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

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

Verwenden Sie dieses Thema, um Ihren JCE-Anbieter von Client SDK 3 auf Client SDK 5 zu migrieren. Informationen zu den Vorteilen der Migration finden Sie unter. Vorteile von 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 und 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 Client-SDK 3 zu Client-SDK 5.

Themen

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

Bereiten Sie sich darauf 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-Anbieterklasse im Client SDK 3 wird aufgerufen `CaviumProvider` und hat den Anbieternamen`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-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 verwenden um Schlüssel anhand von Labels zu finden. Verwenden Sie with, um Schlüssel anhand des Handles AWS CloudHSM `KeyStoreWithAttributes` zu finden AWS CloudHSM `KeyRefereneSpec`.
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.	Mit dem 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 key set-attribute 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.
Finde 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 Verwalten Sie Schlüssel in Ihrer Anwendung effektiv. 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 CloudHSM Github-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 Verschlüsselungs-, Entschlüsselungs- und Umschließungsvorgänge mit Chiffrierung sind keine Änderungen erforderlich.

Bei Unwrap-Vorgängen muss die CaviumUnwrapParameterSpec Klasse Client SDK 3 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 und verwenden Sie den AWS CloudHSM JCE-Anbieter für 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.