Bereiten Sie sich vor, indem Sie wichtige Änderungen berücksichtigen Migrieren Sie zum Client SDK 5 Verwandte Themen

Migrieren Sie Ihren JCE-Anbieter von AWS CloudHSM Client SDK 3 auf Client SDK 5

Verwenden Sie dieses Thema, um Ihren JCE-Anbieter von AWS CloudHSM Client SDK 3 auf Client SDK 5 zu migrieren. Informationen zu den Vorteilen der Migration finden Sie unter. Vorteile von AWS CloudHSM Client SDK 5

In AWS CloudHSM führen Kundenanwendungen mithilfe des AWS CloudHSM Client Software Development Kit (SDK) kryptografische Operationen durch. Das Client SDK 5 ist das primäre SDK, das weiterhin um neue Funktionen und Plattformunterstützung erweitert wird.

Der Client SDK 3-JCE-Anbieter verwendet benutzerdefinierte Klassen APIs , die nicht Teil der Standard-JCE-Spezifikation sind. Das Client-SDK 5 für den JCE-Anbieter entspricht der JCE-Spezifikation und ist in bestimmten Bereichen abwärtsinkompatibel mit dem Client SDK 3. Kundenanwendungen müssen im Rahmen der Migration zum Client-SDK 5 möglicherweise geändert werden. In diesem Abschnitt werden die Änderungen beschrieben, die für eine erfolgreiche Migration erforderlich sind.

Die Migrationsanweisungen für alle Anbieter finden Sie unterMigration von AWS CloudHSM Client SDK 3 zu Client SDK 5.

Themen

Bereiten Sie sich vor, indem Sie wichtige Änderungen berücksichtigen
Migrieren Sie zum Client SDK 5
Verwandte Themen

Bereiten Sie sich vor, indem Sie wichtige Änderungen berücksichtigen

Überprüfen Sie diese grundlegenden Änderungen und aktualisieren Sie Ihre Anwendung in Ihrer Entwicklungsumgebung entsprechend.

Die Provider-Klasse und der Name haben sich geändert

Was hat sich geändert	Was es in Client SDK 3 war	Was ist es in Client SDK 5	Beispiel
Klasse und Name des Anbieters	Die JCE-Providerklasse im Client SDK 3 wird aufgerufen `CaviumProvider` und hat den Provider-Namen`Cavium`.	In Client SDK 5 wird die Provider-Klasse aufgerufen `CloudHsmProvider` und hat den Provider-Namen`CloudHSM`.	Ein Beispiel für die Initialisierung des `CloudHsmProvider` Objekts ist im AWS CloudHSM GitHub Beispiel-Repository verfügbar.

Die explizite Anmeldung hat sich geändert, die implizite nicht

Was hat sich geändert	Was es in Client SDK 3 war	Was ist es in Client SDK 5	Beispiel
Explizite Anmeldung	Das Client-SDK 3 verwendet die `LoginManager` Klasse für die explizite Anmeldung ¹.	Im Client-SDK 5 implementiert der `CloudHSM` Anbieter `AuthProvider` die explizite Anmeldung. `AuthProvider`ist eine Standard-Java-Klasse und folgt der idiomatischen Methode von Java, sich bei einem Provider anzumelden. Dank der verbesserten Verwaltung des Anmeldestatus im Client SDK 5 müssen Anwendungen die Anmeldung bei erneuten ²Verbindungen nicht mehr überwachen und durchführen.	Ein Beispiel für die Verwendung der expliziten Anmeldung mit Client SDK 5 finden Sie im LoginRunner Beispiel im AWS CloudHSM GitHub CloudHSM-Beispiel-Repository.
Implizite Anmeldung	Für die implizite Anmeldung sind keine Änderungen erforderlich. Dieselbe Eigenschaftendatei und alle Umgebungsvariablen funktionieren weiterhin für die implizite Anmeldung, wenn von Client SDK 3 auf Client SDK 5 migriert wird.		Ein Beispiel für die Verwendung der impliziten Anmeldung mit dem Client SDK 5 finden Sie im LoginRunner Beispiel im AWS CloudHSM GitHub Beispiel-Repository.

[1] Codeausschnitt für das Client-SDK 3:


LoginManager lm = LoginManager.getInstance();
                       
lm.login(partition, user, pass);

[2] Codeausschnitt für das Client-SDK 5:


// Construct or get the existing provider object 
AuthProvider provider = new CloudHsmProvider();
                       
// Call login method on the CloudHsmProvider object
// Here loginHandler is a CallbackHandler
provider.login(null, loginHandler);

Ein Beispiel für die Verwendung der expliziten Anmeldung mit dem Client SDK 5 finden Sie im LoginRunner Beispiel im AWS CloudHSM GitHub Beispiel-Repository.

Weniger anzeigen

Die Schlüsselgenerierung hat sich geändert

Was hat sich geändert	Was es in Client SDK 3 war	Was ist es in Client SDK 5	Beispiel
Schlüsselgenerierung	Wird im Client SDK 3 zur Angabe von Schlüsselgenerierungsparametern verwendet. `Cavium[Key-type]AlgorithmParameterSpec` Einen Codeausschnitt finden Sie in der Fußnote. 1	Wird im Client SDK 5 zur Angabe von `KeyAttributesMap` Schlüsselgenerierungsattributen verwendet. Einen Codeausschnitt finden Sie in der Fußnote. 2	Ein Beispiel `KeyAttributesMap` zur Generierung eines symmetrischen Schlüssels finden Sie im Beispiel im AWS CloudHSM SymmetricKeys GitHub CloudHSM-Beispiel-Repository.
Generierung von Schlüsselpaaren	Wird im Client SDK 3 verwendet, `Cavium[Key-type]AlgorithmparameterSpec` um Parameter für die Schlüsselpaargenerierung anzugeben. Einen Codeausschnitt finden Sie in der Fußnote. 3	Wird im Client SDK 5 verwendet, `KeyPairAttributesMap` um diese Parameter anzugeben. Einen Codeausschnitt finden Sie in der Fußnote. 4	Ein Beispiel `KeyAttributesMap` zur Generierung eines asymmetrischen Schlüssels finden Sie im AsymmetricKeys Beispiel im Beispiel-Repository. AWS CloudHSM GitHub

[1] Codeausschnitt zur Schlüsselgenerierung des Client-SDK 3:


KeyGenerator keyGen = KeyGenerator.getInstance("AES", "Cavium");
CaviumAESKeyGenParameterSpec aesSpec = new CaviumAESKeyGenParameterSpec(
keySizeInBits,
keyLabel,
isExtractable,
isPersistent);
keyGen.init(aesSpec);
SecretKey aesKey = keyGen.generateKey();

[2] Codeausschnitt zur Schlüsselgenerierung des Client-SDK 5:


KeyGenerator keyGen = KeyGenerator.getInstance("AES",
CloudHsmProvider.PROVIDER_NAME);
                    
final KeyAttributesMap aesSpec = new KeyAttributesMap();
aesSpec.put(KeyAttribute.LABEL, keyLabel);
aesSpec.put(KeyAttribute.SIZE, keySizeInBits);
aesSpec.put(KeyAttribute.EXTRACTABLE, isExtractable);
aesSpec.put(KeyAttribute.TOKEN, isPersistent);
                    
keyGen.init(aesSpec);
SecretKey aesKey = keyGen.generateKey();

[3] Codeausschnitt zur Generierung von key pair für das Client-SDK 3:


KeyPairGenerator keyPairGen = KeyPairGenerator.getInstance("rsa", "Cavium");
CaviumRSAKeyGenParameterSpec spec = new CaviumRSAKeyGenParameterSpec(
keySizeInBits,
new BigInteger("65537"),
label + ":public",
label + ":private",
isExtractable,
isPersistent);
                    
keyPairGen.initialize(spec);
                    
keyPairGen.generateKeyPair();

[4] Codeausschnitt zur Generierung von key pair für das Client-SDK 5:


KeyPairGenerator keyPairGen =
KeyPairGenerator.getInstance("RSA", providerName);
                    
// Set attributes for RSA public key
final KeyAttributesMap publicKeyAttrsMap = new KeyAttributesMap();
publicKeyAttrsMap.putAll(additionalPublicKeyAttributes);
publicKeyAttrsMap.put(KeyAttribute.LABEL, label + ":Public");
publicKeyAttrsMap.put(KeyAttribute.MODULUS_BITS, keySizeInBits);
publicKeyAttrsMap.put(KeyAttribute.PUBLIC_EXPONENT,
new BigInteger("65537").toByteArray());
                    
// Set attributes for RSA private key
final KeyAttributesMap privateKeyAttrsMap = new KeyAttributesMap();
privateKeyAttrsMap.putAll(additionalPrivateKeyAttributes);
privateKeyAttrsMap.put(KeyAttribute.LABEL, label + ":Private");
                    
// Create KeyPairAttributesMap and use that to initialize the 
// keyPair generator
KeyPairAttributesMap keyPairSpec =
new KeyPairAttributesMapBuilder()
.withPublic(publicKeyAttrsMap)
.withPrivate(privateKeyAttrsMap)
.build();
                    
keyPairGen.initialize(keyPairSpec);
keyPairGen.generateKeyPair();

Weniger anzeigen

Das Suchen, Löschen und Referenzieren von Schlüsseln hat sich geändert

Um einen bereits generierten Schlüssel mit zu finden, AWS CloudHSM müssen Sie den KeyStore verwenden. Das Client-SDK 3 hat zwei KeyStore Typen: Cavium undCloudHSM. Das Client-SDK 5 hat nur einen KeyStore Typ:CloudHSM.

Der Wechsel von A Cavium KeyStore nach CloudHSM KeyStore erfordert eine Änderung des KeyStore Typs. Darüber hinaus verwendet das Client-SDK 3 Schlüsselnamen, um auf Schlüssel zu verweisen, während das Client-SDK 5 Tastenbezeichnungen verwendet. Die daraus resultierenden Verhaltensänderungen sind unten aufgeführt.

Was hat sich geändert	Was es in Client SDK 3 war	Was ist es in Client SDK 5	Beispiel
Wichtige Referenzen	Mit Client SDK 3 verwenden Anwendungen entweder Tastenbezeichnungen oder Schlüsselhandles, um auf Schlüssel im HSM zu verweisen. Sie verwenden Labels mit KeyStore , um einen Schlüssel zu finden, oder sie verwenden Griffe und erstellen `CaviumKey` Objekte.	Im Client SDK 5 können Anwendungen die verwenden, AWS CloudHSM KeyStore Java-Klasse für Client SDK 5 um Schlüssel anhand von Labels zu finden. Verwenden Sie with, um Schlüssel anhand des Handles AWS CloudHSM `KeyStoreWithAttributes` zu finden AWS CloudHSM `KeyReferenceSpec`.
Suche nach mehreren Einträgen	Bei der Suche nach einem Schlüssel mithilfe von `getEntrygetKey`, oder `getCertificate` in Szenarien, in denen mehrere Elemente mit denselben Kriterien existieren `Cavium` KeyStore, wird nur der erste gefundene Eintrag zurückgegeben.	Bei Verwendung von AWS CloudHSM `KeyStore` und führt dasselbe Szenario dazu`KeyStoreWithAttributes`, dass eine Ausnahme ausgelöst wird. Um dieses Problem zu beheben, wird empfohlen, mithilfe des Legen Sie die Attribute von Schlüsseln mit der CloudHSM-CLI fest Befehls in der CloudHSM-CLI eindeutige Bezeichnungen für Schlüssel festzulegen. Oder verwenden Sie diese `KeyStoreWithAttributes#getKeys` Option, um alle Schlüssel zurückzugeben, die den Kriterien entsprechen.
Findet alle Schlüssel	Im Client SDK 3 ist es möglich, alle Schlüssel im HSM mithilfe von `Util.findAllKeys()` zu finden.	Das Client SDK 5 macht das Auffinden von Schlüsseln mithilfe der `KeyStoreWithAttributes` Klasse einfacher und effizienter. Wenn möglich, speichern Sie Ihre Schlüssel im Cache, um die Latenz zu minimieren. Weitere Informationen finden Sie unter Effektives Verwalten von Schlüsseln in Ihrer Anwendung. Wenn Sie alle Schlüssel aus dem HSM abrufen müssen, verwenden Sie es `KeyStoreWithAttributes#getKeys` mit einem leeren `KeyAttributesMap` Schlüssel.	Ein Beispiel, das die `KeyStoreWithAttributes` Klasse verwendet, um einen Schlüssel zu finden, ist im AWS CloudHSM GitHub Beispiel-Repository verfügbar. Ein Codeausschnitt ist unter zu finden. 1
Löschen von Schlüsseln	Client SDK 3 verwendet`Util.deleteKey()`, um einen Schlüssel zu löschen.	Das `Key` Objekt in Client SDK 5 implementiert die `Destroyable` Schnittstelle, die das Löschen von Schlüsseln mithilfe der `destroy()` Methode dieser Schnittstelle ermöglicht.	Ein Beispielcode, der die Funktion zum Löschen von Schlüsseln zeigt, finden Sie im GitHub CloudHSM-Beispiel-Repository. Ein Beispielausschnitt für jedes SDK finden Sie unter. 2

[1] Ein Ausschnitt ist unten dargestellt:


KeyAttributesMap findSpec = new KeyAttributesMap();
findSpec.put(KeyAttribute.LABEL, label);
findSpec.put(KeyAttribute.KEY_TYPE, keyType);
KeyStoreWithAttributes keyStore = KeyStoreWithAttributes.getInstance("CloudHSM");
                    
keyStore.load(null, null);
keyStore.getKey(findSpec);

[2] Löschen eines Schlüssels im Client SDK 3:
```
Util.deleteKey(key);
```
Löschen eines Schlüssels im Client-SDK 5:
```
((Destroyable) key).destroy();
```

Weniger anzeigen

Operationen zum Entpacken von Chiffren haben sich geändert, andere Verschlüsselungsoperationen nicht

Anmerkung

Für Chiffrieroperationen sind keine Änderungen erforderlich. encrypt/decrypt/wrap

Bei Unwrap-Vorgängen muss die Client SDK CaviumUnwrapParameterSpec 3-Klasse durch eine der folgenden Klassen ersetzt werden, die für die aufgeführten kryptografischen Operationen spezifisch sind.

GCMUnwrapKeySpeczum Auspacken AES/GCM/NoPadding
IvUnwrapKeySpecfür und AESWrap unwrap AES/CBC/NoPadding unwrap
OAEPUnwrapKeySpec für RSA OAEP unwrap

Beispielausschnitt für: OAEPUnwrapkeySpec


OAEPParameterSpec oaepParameterSpec =
new OAEPParameterSpec(
        "SHA-256",
        "MGF1",
        MGF1ParameterSpec.SHA256,
        PSpecified.DEFAULT);

KeyAttributesMap keyAttributesMap =
        new KeyAttributesMap(KeyAttributePermissiveProfile.KEY_CREATION);
keyAttributesMap.put(KeyAttribute.TOKEN, true);
keyAttributesMap.put(KeyAttribute.EXTRACTABLE, false);

OAEPUnwrapKeySpec spec = new OAEPUnwrapKeySpec(oaepParameterSpec,
        keyAttributesMap);

Cipher hsmCipher =
        Cipher.getInstance(
                "RSA/ECB/OAEPPadding",
                CloudHsmProvider.PROVIDER_NAME);
hsmCipher.init(Cipher.UNWRAP_MODE, key, spec);

Weniger anzeigen

Die Signaturoperationen haben sich nicht geändert

Für Signaturoperationen sind keine Änderungen erforderlich.

Migrieren Sie zum Client SDK 5

Folgen Sie den Anweisungen in diesem Abschnitt, um von Client SDK 3 auf Client SDK 5 zu migrieren.

Anmerkung

Amazon Linux, Ubuntu 16.04, Ubuntu 18.04, CentOS 6, CentOS 8 und RHEL 6 werden derzeit nicht mit Client SDK 5 unterstützt. Wenn Sie derzeit eine dieser Plattformen mit Client SDK 3 verwenden, müssen Sie bei der Migration zu Client SDK 5 eine andere Plattform wählen.

Deinstallieren Sie den JCE-Anbieter für Client SDK 3.

Deinstallieren Sie den Client Daemon für Client SDK 3.
Amazon Linux 2
```
$ sudo yum remove cloudhsm-client
```
CentOS 7
```
$ sudo yum remove cloudhsm-client
```
RHEL 7
```
$ sudo yum remove cloudhsm-client
```
RHEL 8
```
$ sudo yum remove cloudhsm-client
```
Anmerkung
Benutzerdefinierte Konfigurationen müssen erneut aktiviert werden.
Installieren Sie den Client SDK JCE Provider, indem Sie die Schritte unter befolgen. Installieren Sie den JCE-Anbieter für AWS CloudHSM Client SDK 5
Das Client SDK 5 führt ein neues Konfigurationsdateiformat und ein Befehlszeilen-Bootstrapping-Tool ein. Folgen Sie den Anweisungen im Benutzerhandbuch unter, um Ihren Client SDK 5 JCE-Anbieter zu booten. Bootstrap für das Client-SDK
Testen Sie Ihre Anwendung in Ihrer Entwicklungsumgebung. Nehmen Sie vor der endgültigen Migration Aktualisierungen an Ihrem vorhandenen Code vor, um Ihre wichtigsten Änderungen zu beheben.