Les traductions sont fournies par des outils de traduction automatique. En cas de conflit entre le contenu d'une traduction et celui de la version originale en anglais, la version anglaise prévaudra. # Migrez votre fournisseur JCE du SDK AWS CloudHSM client 3 vers le SDK client 5 Utilisez cette rubrique pour migrer votre [fournisseur JCE](java-library.md) du SDK AWS CloudHSM client 3 vers le SDK client 5. Pour connaître les avantages de la migration, voir[Avantages du SDK AWS CloudHSM client 5](client-sdk-5-benefits.md). 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 APIs 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, voir[Migration du SDK AWS CloudHSM client 3 vers le SDK client 5](client-sdk-migration.md). **Topics** + [Préparez-vous en faisant face aux changements les plus importants](#jce-migration-preparation-sdk5) + [Migrer vers le SDK client 5](#w2aac25c19c21c15) + [Rubriques en relation](#java-lib-migrate_to_sdk5-seealso) ## 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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AESGCMEncryptDecryptRunner.java#L43-L50). | ### 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 [1](#explicit_login_sdk3_note)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 [2](#explicit_login_sdk5_note)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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141). | | 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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L143-L202) 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](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/LoginRunner.java#L109C5-L141) dans le référentiel AWS CloudHSM GitHub d'exemples. ### 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](#key_generation_sdk3_note) | 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](#key_generation_sdk5_note) | Pour un exemple expliquant comment l'utiliser `KeyAttributesMap` pour générer une clé symétrique, consultez l'[SymmetricKeys exemple dans le référentiel d'exemples](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/SymmetricKeys.java) GitHub AWS CloudHSM. | | 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](#key_pair_generation_sdk3_note) | 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](#key_pair_generation_sdk5_note) | Pour un exemple sur la façon de `KeyAttributesMap` générer une clé asymétrique, consultez l'[AsymmetricKeys exemple](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/AsymmetricKeys.java) 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(); ``` ### La recherche, la suppression et le référencement des clés ont changé Pour trouver une clé déjà générée, AWS CloudHSM il faut utiliser le KeyStore. Le SDK client 3 est de deux KeyStore types : `Cavium` et`CloudHSM`. 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 libellés 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 [AWS CloudHSM KeyStore Classe Java pour le SDK client 5](alternative-keystore_5.md) pour rechercher des clés par étiquette. Pour rechercher les clés par poignée, utilisez la touche AWS CloudHSM `KeyStoreWithAttributes` avec AWS CloudHSM `KeyReferenceSpec`. | | | Recherche de plusieurs entrées | Lorsque vous recherchez une clé à l'aide de `getEntry``getKey`, 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 [Définissez les attributs des clés à l'aide de la CLI CloudHSM](cloudhsm_cli-key-set-attribute.md) 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 de plus amples informations, veuillez consulter [Gérez efficacement les clés de votre application](bp-application-integration.md#bp-manage-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 AWS CloudHSM GitHub d'exemples](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L205-L223) et un extrait de code est affiché dans. [1](#using_keystore_att_note) | | 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 [ GitHub CloudHSM](https://github.com/aws-samples/aws-cloudhsm-jce-examples/blob/sdk5/src/main/java/com/amazonaws/cloudhsm/examples/KeyUtilitiesRunner.java#L229-L234). Un exemple d'extrait de code pour chaque SDK est présenté dans. [2](#delete_key_note) | + [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(); ``` ### 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 encrypt/decrypt/wrap opérations de chiffrement. Les opérations de désencapsulage nécessitent que la `CaviumUnwrapParameterSpec` classe du SDK client 3 soit remplacée par l'une des classes suivantes, spécifique aux opérations cryptographiques répertoriées. + `GCMUnwrapKeySpec`pour `AES/GCM/NoPadding` déballer + `IvUnwrapKeySpec`pour `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); ``` ### 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. 1. Désinstallez le fournisseur JCE pour le SDK client 3. ------ #### [ Amazon Linux 2 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ CentOS 7 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ RHEL 7 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ RHEL 8 ] ``` $ sudo yum remove cloudhsm-client-jce ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client-jce ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client-jce ``` ------ 1. Arrêtez le démon client pour le SDK client 3. ------ #### [ Amazon Linux 2 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ CentOS 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 7 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ RHEL 8 ] ``` $ sudo service cloudhsm-client stop ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo systemctl stop cloudhsm-client ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo systemctl stop cloudhsm-client ``` ------ 1. 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 ``` ------ #### [ Ubuntu 16.04 LTS ] ``` $ sudo apt remove cloudhsm-client ``` ------ #### [ Ubuntu 18.04 LTS ] ``` $ sudo apt remove cloudhsm-client ``` ------ **Note** Les configurations personnalisées doivent être réactivées. 1. Installez le fournisseur JCE du SDK client en suivant les étapes décrites dans. [Installation du fournisseur JCE pour le SDK AWS CloudHSM client 5](java-library-install_5.md) 1. 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](cluster-connect.md#connect-how-to) 1. 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](best-practices.md)