Préparez-vous en faisant face aux changements les plus importants Migrer vers le SDK client 5 Rubriques en relation

Migrez votre fournisseur JCE du SDK client 3 vers le SDK client 5

Utilisez cette rubrique pour migrer votre fournisseur JCE du SDK client 3 vers le SDK client 5. Pour connaître les avantages de la migration, voirAvantages du SDK client 5.

Dans AWS CloudHSM, les applications client exécutent des opérations cryptographiques à l'aide du kit de développement logiciel (SDK) AWS CloudHSM client. Le SDK client 5 est le SDK principal auquel de nouvelles fonctionnalités et un support de plateforme continuent d'être ajoutés.

Le fournisseur JCE du SDK client 3 utilise des classes personnalisées et des API qui ne font pas partie de la spécification JCE standard. Le SDK client 5 pour le fournisseur JCE est conforme à la spécification JCE et est rétroincompatible avec le SDK client 3 dans certains domaines. Les applications du client peuvent nécessiter des modifications dans le cadre de la migration vers le SDK client 5. Cette section décrit les modifications requises pour une migration réussie.

Pour consulter les instructions de migration pour tous les fournisseurs, voirMigration du SDK client 3 vers le SDK client 5.

Rubriques

Préparez-vous en faisant face aux changements les plus importants
Migrer vers le SDK client 5
Rubriques en relation

Préparez-vous en faisant face aux changements les plus importants

Passez en revue ces modifications majeures et mettez à jour votre application dans votre environnement de développement en conséquence.

La classe et le nom du fournisseur ont changé

Qu'est-ce qui a changé	Ce que c'était dans le SDK client 3	Qu'est-ce que c'est dans le SDK client 5	Exemple
Classe et nom du fournisseur	La classe de fournisseur JCE du SDK client 3 est appelée `CaviumProvider` et porte le nom du fournisseur. `Cavium`	Dans le SDK client 5, la classe Provider est appelée `CloudHsmProvider` et porte le nom `CloudHSM` du fournisseur.	Un exemple d'initialisation de l'`CloudHsmProvider`objet est disponible dans le référentiel AWS CloudHSM GitHub d'exemples.

La connexion explicite a changé, la connexion implicite n'a pas changé

Qu'est-ce qui a changé	Ce que c'était dans le SDK client 3	Qu'est-ce que c'est dans le SDK client 5	Exemple
Login explicite	Le SDK client 3 utilise la `LoginManager` classe pour une connexion ¹explicite.	Dans le SDK client 5, le `CloudHSM` fournisseur implémente `AuthProvider` une connexion explicite. `AuthProvider`est une classe Java standard qui suit la méthode idiomatique de Java pour se connecter à un fournisseur. Grâce à la gestion améliorée de l'état de connexion dans le SDK client 5, les applications n'ont plus besoin de surveiller et d'effectuer des connexions lors des ²reconnexions.	Pour un exemple d'utilisation de la connexion explicite avec le SDK client 5, consultez l' LoginRunner exemple dans le référentiel d'exemples GitHub AWS CloudHSM.
Login implicite	Aucune modification n'est requise pour la connexion implicite. Le même fichier de propriétés et toutes les variables d'environnement continueront de fonctionner pour la connexion implicite lors de la migration du SDK client 3 vers le SDK client 5.		Pour un exemple d'utilisation de la connexion implicite avec le SDK client 5, consultez l'LoginRunner exemple dans le référentiel AWS CloudHSM GitHub d'exemples.

[1] Extrait de code du SDK client 3 :


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

[2] Extrait de code du SDK client 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);

Pour un exemple d'utilisation de la connexion explicite avec le SDK client 5, consultez l'LoginRunner exemple dans le référentiel AWS CloudHSM GitHub d'exemples.

Afficher plus

Afficher moins

La génération de clés a changé

Qu'est-ce qui a changé	Ce que c'était dans le SDK client 3	Qu'est-ce que c'est dans le SDK client 5	Exemple
Génération de clés	Dans le SDK client 3, `Cavium[Key-type]AlgorithmParameterSpec` est utilisé pour spécifier les paramètres de génération de clés. Pour un extrait de code, voir note de bas de page. 1	Dans le SDK client 5, `KeyAttributesMap` est utilisé pour spécifier les attributs de génération de clés. Pour un extrait de code, voir note de bas de page. 2	Pour un exemple expliquant comment `KeyAttributesMap` générer une clé symétrique, consultez l'exemple dans le référentiel SymmetricKeys d'exemples AWS CloudHSM Github.
Génération de paires de clés	Dans le SDK client 3, `Cavium[Key-type]AlgorithmparameterSpec` est utilisé pour spécifier les paramètres de génération de paires de clés. Pour un extrait de code, voir note de bas de page. 3	Dans le SDK client 5, `KeyPairAttributesMap` est utilisé pour spécifier ces paramètres. Pour un extrait de code, voir note de bas de page. 4	Pour un exemple sur la façon de `KeyAttributesMap` générer une clé asymétrique, consultez l'AsymmetricKeys exemple dans le référentiel AWS CloudHSM GitHub d'échantillons.

[1] Extrait de code de génération de clé du SDK client 3 :


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

[2] Extrait de code de génération de clé du SDK client 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] Extrait de code de génération de paires de clés du SDK client 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] Extrait de code de génération de 5 paires de clés du SDK client :


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();

Afficher plus

Afficher moins

La recherche, la suppression et le référencement des clés ont changé

Trouver une clé déjà générée AWS CloudHSM implique d'utiliser le KeyStore. Le SDK client 3 est de deux KeyStore types : Cavium etCloudHSM. Le SDK client 5 n'a qu'un seul KeyStore type :CloudHSM.

Le passage du Cavium KeyStore à CloudHSM KeyStore nécessite un changement de KeyStore type. En outre, le SDK client 3 utilise des poignées de touches pour référencer les clés, tandis que le SDK client 5 utilise des étiquettes de touches. Les modifications de comportement qui en résultent sont répertoriées ci-dessous.

Qu'est-ce qui a changé	Ce que c'était dans le SDK client 3	Qu'est-ce que c'est dans le SDK client 5	Exemple
Principales références	Avec le SDK client 3, les applications utilisent des libellés ou des descripteurs de touches pour référencer les clés dans le HSM. Ils utilisent des étiquettes KeyStore pour trouver une clé, ou ils utilisent des poignées pour créer des `CaviumKey` objets.	Dans le SDK client 5, les applications peuvent utiliser le Utilisation de la classe AWS CloudHSM KeyStore Java pour rechercher des clés par étiquette. Pour rechercher les clés par poignée, utilisez la touche AWS CloudHSM `KeyStoreWithAttributes` avec AWS CloudHSM `KeyRefereneSpec`.
Recherche de plusieurs entrées	Lorsque vous recherchez une clé à l'aide de `getEntrygetKey`, ou `getCertificate` dans des scénarios où plusieurs éléments répondant aux mêmes critères existent dans le `Cavium` KeyStore, seule la première entrée trouvée sera renvoyée.	Avec le AWS CloudHSM `KeyStore` et`KeyStoreWithAttributes`, ce même scénario entraînera le lancement d'une exception. Pour résoudre ce problème, il est recommandé de définir des étiquettes uniques pour les clés à l'aide de la clé set-attribute commande de la CLI CloudHSM. Ou `KeyStoreWithAttributes#getKeys` utilisez-le pour renvoyer toutes les clés correspondant aux critères.
Trouvez toutes les clés	Dans le SDK client 3, il est possible de trouver toutes les clés du HSM à l'aide de. `Util.findAllKeys()`	Le SDK client 5 simplifie et rend la recherche de clés plus efficace en utilisant la `KeyStoreWithAttributes` classe. Dans la mesure du possible, mettez vos clés en cache pour minimiser le temps de latence. Pour plus d’informations, consultez Gérez efficacement les clés de votre application. Lorsque vous devez récupérer toutes les clés du HSM, utilisez-les `KeyStoreWithAttributes#getKeys` avec une clé vide. `KeyAttributesMap`	Un exemple utilisant la `KeyStoreWithAttributes` classe pour trouver une clé est disponible dans le référentiel d'exemples AWS CloudHSM Github et un extrait de code est affiché dans. 1
Suppression de la clé	Le SDK client 3 est utilisé `Util.deleteKey()` pour supprimer une clé.	L'`Key`objet du SDK client 5 implémente l'`Destroyable`interface qui permet de supprimer des clés à l'aide de la `destroy()` méthode de cette interface.	Un exemple de code illustrant la fonctionnalité de suppression de la clé se trouve dans le référentiel d'exemples de CloudHSM Github. Un exemple d'extrait de code pour chaque SDK est présenté dans. 2

[1] un extrait est affiché ci-dessous :


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] Suppression d'une clé dans le SDK client 3 :
```
Util.deleteKey(key);
```
Suppression d'une clé dans le SDK client 5 :
```
((Destroyable) key).destroy();
```

Afficher plus

Afficher moins

Les opérations de décompression du chiffrement ont changé, les autres opérations de chiffrement n'ont pas changé

Note

Aucune modification n'est requise pour les opérations de chiffrement/déchiffrement/encapsulation par chiffrement.

Les opérations de désencapsulage nécessitent le remplacement de la CaviumUnwrapParameterSpec classe du SDK client 3 par l'une des classes suivantes, spécifique aux opérations cryptographiques répertoriées.

GCMUnwrapKeySpecpour AES/GCM/NoPadding déballer
IvUnwrapKeySpecpour AESWrap unwrap et AES/CBC/NoPadding unwrap
OAEPUnwrapKeySpec pour RSA OAEP unwrap

Exemple d'extrait pour : 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);

Afficher plus

Afficher moins

Les opérations de signature n'ont pas changé

Aucune modification n'est requise pour les opérations de signature.

Migrer vers le SDK client 5

Suivez les instructions de cette section pour migrer du SDK client 3 vers le SDK client 5.

Note

Amazon Linux, Ubuntu 16.04, Ubuntu 18.04, CentOS 6, CentOS 8 et RHEL 6 ne sont actuellement pas pris en charge avec le SDK client 5. Si vous utilisez actuellement l'une de ces plateformes avec le SDK client 3, vous devrez en choisir une autre lors de la migration vers le SDK client 5.

Désinstallez le fournisseur JCE pour le SDK client 3.

Désinstallez le démon client pour le SDK client 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
```
Note
Les configurations personnalisées doivent être réactivées.
Installez le fournisseur JCE du SDK client en suivant les étapes décrites dans. Installation et utilisation du fournisseur AWS CloudHSM JCE pour le SDK client 5
Le SDK client 5 introduit un nouveau format de fichier de configuration et un outil d'amorçage en ligne de commande. Pour démarrer votre fournisseur Client SDK 5 JCE, suivez les instructions répertoriées dans le guide de l'utilisateur ci-dessous. Amorcez le SDK client
Dans votre environnement de développement, testez votre application. Mettez à jour votre code existant pour corriger les modifications importantes avant votre migration finale.

Rubriques en relation

Les meilleures pratiques pour AWS CloudHSM

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

CloudHSM KeyStore

Configurations avancées