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.

# Importer une clé symétrique en texte brut à l'aide de KMU AWS CloudHSM
<a name="key_mgmt_util-imSymKey"></a>

Utilisez la **imSymKey** commande de l'outil AWS CloudHSM key\_mgmt\_util pour importer une copie en texte brut d'une clé symétrique depuis un fichier dans le module de sécurité matériel (HSM). Vous pouvez l'utiliser pour importer des clés générées par n'importe quelle méthode en dehors du HSM et des clés exportées depuis un HSM, telles que les clés que la [exSymKey](key_mgmt_util-exSymKey.md)commande écrit dans un fichier. 

Pendant le processus d'importation, **imSymKey** utilise une clé AES que vous sélectionnez (la *clé d'encapsulage*) pour *encapsuler* (chiffrer), puis *désencapsuler* (déchiffrer) la clé à importer. Cependant, **imSymKey** fonctionne uniquement sur les fichiers qui contiennent des clés en texte brut. Pour exporter et importer des clés chiffrées, utilisez le [WrapKey](key_mgmt_util-wrapKey.md) et [unWrapKey](key_mgmt_util-unwrapKey.md)les commandes. 

De plus, la commande **imSymKey** importe uniquement les clés symétriques. Pour importer les clés publiques, utilisez [importPubKey](key_mgmt_util-importPubKey.md). Pour importer des clés privées, utilisez [importPrivateKey](key_mgmt_util-importPrivateKey.md)ou [WrapKey](key_mgmt_util-wrapKey.md). 

**Note**  
Vous ne pouvez pas importer une clé PEM protégée par mot de passe à l'aide d'une clé symétrique ou privée.

Le fonctionnement des clés importées est très similaire à celui des clés générées dans le HSM. Toutefois, la valeur de l'[attribut OBJ\_ATTR\_LOCAL](key-attribute-table.md) est zéro, ce qui indique qu'il n'a pas été généré en local. Vous pouvez utiliser la commande suivante pour partager une clé symétrique que vous importez. Vous pouvez utiliser la commande `shareKey` dans [cloudhsm\_mgmt\_util](cloudhsm_mgmt_util.md) pour partager la clé après qu'elle a été importée. 

```
imSymKey -l aesShared -t 31 -f kms.key -w 3296 -u 5
```

Après avoir importé une clé, n'oubliez pas de marquer ou de supprimer le fichier de clé. Cette commande ne vous empêche pas d'importer plusieurs fois les mêmes éléments de clés. Le résultat, plusieurs clés avec des handles de clé distincts et les mêmes éléments de clé, complique le suivi de l'utilisation des éléments de clé et évite un dépassement des limites de chiffrement. 

Avant d'exécuter une commande key\_mgmt\_util, vous devez [démarrer key\_mgmt\_util](key_mgmt_util-setup.md#key_mgmt_util-start) et vous [connecter](key_mgmt_util-log-in.md) au HSM en tant qu'utilisateur de chiffrement (CU). 

## Syntaxe
<a name="imSymKey-syntax"></a>

```
imSymKey -h

imSymKey -f <key-file>
         -w <wrapping-key-handle>  
         -t <key-type>
         -l <label>
         [-id <key-ID>]
         [-sess]
         [-wk <wrapping-key-file> ]
         [-attest]
         [-min_srv <minimum-number-of-servers>]
         [-timeout <number-of-seconds> ]
         [-u <user-ids>]
```

## Exemples
<a name="imSymKey-examples"></a>

Ces exemples montrent comment importer **imSymKey** des clés symétriques dans votre HSMs.

**Example : Importation d'une clé symétrique AES**  
Cet exemple permet d'**imSymKey**importer une clé symétrique AES dans le HSMs.   
La première commande utilise OpenSSL pour générer une clé symétrique AES 256 bits aléatoire. Elle enregistre la clé dans le fichier `aes256.key`.  

```
$  openssl rand -out aes256.key 32
```
La deuxième commande permet **imSymKey** d'importer la clé AES du `aes256.key` fichier dans le HSMs. Elle utilise la clé 20, clé AES du HSM, comme clé d'encapsulage et spécifie l'étiquette `imported`. Contrairement à l'ID, l'étiquette n'a pas besoin d'être unique dans le cluster. La valeur du paramètre `-t` (type) est `31`, qui correspond à AES.   
La sortie indique que la clé du fichier a été encapsulée et désencapsulée, puis importée dans le HSM, où le handle de clé 262180 lui a été attribué.  

```
Command:  imSymKey -f aes256.key -w 20 -t 31 -l imported

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 262180

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
```
La commande suivante utilise [getAttribute](key_mgmt_util-getAttribute.md) pour obtenir l'attribut OBJ\_ATTR\_LOCAL ([attribut 355](key-attribute-table.md)) de la clé nouvellement importée et l'écrit dans le fichier `attr_262180`.  

```
Command:  getAttribute -o 262180 -a 355 -out attributes/attr_262180
Attributes dumped into attributes/attr_262180_imported file

        Cfm3GetAttribute returned: 0x00 : HSM Return: SUCCESS
```
Lorsque vous examinez le fichier d'attribut, vous pouvez voir que l'attribut `OBJ_ATTR_LOCAL` a pour valeur zéro, ce qui indique que les clés n'ont pas été générées dans le HSM.   

```
$  cat attributes/attr_262180_local
OBJ_ATTR_LOCAL
0x00000000
```

**Example  : Déplacement d'une clé symétrique entre les clusters**  
Cet exemple montre comment utiliser [exSymKey](key_mgmt_util-exSymKey.md) et **imSymKey** pour déplacer une clé AES en texte brut entre les clusters. Vous pouvez utiliser un processus comme celui-ci pour créer un encapsulage AES existant sur les HSMs deux clusters. Une fois que la clé d'encapsulation partagée est en place, vous pouvez utiliser [WrapKey [unWrapKey](key_mgmt_util-unwrapKey.md)](key_mgmt_util-wrapKey.md)pour déplacer les clés chiffrées entre les clusters.  
L'utilisateur du CU qui effectue cette opération doit être autorisé à se connecter HSMs aux deux clusters.  
La première commande utilise [exSymKey](key_mgmt_util-exSymKey.md) pour exporter la clé 14, clé AES 32 bits, depuis le cluster 1 vers le fichier `aes.key`. Il utilise la touche 6, une clé AES du HSMs cluster 1, comme clé d'encapsulation.   

```
Command: exSymKey -k 14 -w 6 -out aes.key

        Cfm3WrapKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapHostKey returned: 0x00 : HSM Return: SUCCESS


Wrapped Symmetric Key written to file "aes.key"
```
L'utilisateur se connecte ensuite à key\_mgmt\_util du cluster 2 et exécute une **imSymKey** commande pour importer la clé du `aes.key` fichier dans le cluster 2. HSMs Cette commande utilise la clé 252152, une touche AES du HSMs cluster 2, comme clé d'encapsulation.   
Comme les clés d'encapsulage utilisées par [exSymKey](key_mgmt_util-exSymKey.md) et **imSymKey** encapsulent et désencapsulent immédiatement les clés cibles, les clés d'encapsulage des différents clusters n'ont pas besoin d'être identiques.   
La sortie montre que la clé a été importée avec succès dans le cluster 2 et que le handle de clé 21 lui a été attribué.   

```
Command:  imSymKey -f aes.key -w 262152 -t 31 -l xcluster

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 21

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 2 and err state 0x00000000 : HSM Return: SUCCESS
```
Pour prouver que la clé 14 du cluster 1 et la clé 21 du cluster 2 ont les mêmes éléments de clé, recherchez la valeur de contrôle de clé (KCV) de chaque clé. Si les valeurs KCV sont identiques, les éléments de clé sont les mêmes.  
La commande suivante utilise [getAttribute](key_mgmt_util-getAttribute.md) du cluster 1 pour écrire la valeur de l'attribut KCV (attribut 371) de la clé 14 dans le fichier `attr_14_kcv`. Elle utilise ensuite une commande **cat** pour obtenir le contenu du fichier `attr_14_kcv`.  

```
Command:  getAttribute -o 14 -a 371 -out attr_14_kcv
Attributes dumped into attr_14_kcv file

$  cat attr_14_kcv
OBJ_ATTR_KCV
0xc33cbd
```
Cette commande similaire utilise [getAttribute](key_mgmt_util-getAttribute.md) du cluster 2 pour écrire la valeur de l'attribut KCV (attribut 371) de la clé 21 dans le fichier `attr_21_kcv`. Elle utilise ensuite une commande **cat** pour obtenir le contenu du fichier `attr_21_kcv`.  

```
Command:  getAttribute -o 21 -a 371 -out attr_21_kcv
Attributes dumped into attr_21_kcv file

$  cat attr_21_kcv
OBJ_ATTR_KCV
0xc33cbd
```
La sortie montre que les valeurs KCV des deux clés sont identiques, ce qui prouve que les éléments de clé sont les mêmes.  
Étant donné que le même contenu clé existe dans les HSMs deux clusters, vous pouvez désormais partager des clés chiffrées entre les clusters sans jamais exposer la clé en texte clair. Par exemple, vous pouvez utiliser la commande `wrapKey` avec la clé d'encapsulage 14 pour exporter une clé chiffrée depuis le cluster 1, puis utiliser `unWrapKey` avec la clé d'encapsulage 21 pour importer la clé chiffrée dans le cluster 2.

**Example : Importation d'une clé de session**  
Cette commande utilise les paramètres `-sess` de **imSymKey** pour importer une clé DES triple 192 bits, valable uniquement pendant la session en cours.   
La commande utilise le paramètre `-f` pour spécifier le fichier contenant la clé à importer, le paramètre `-t` pour spécifier le type de clé et le paramètre `-w` pour spécifier la clé d'encapsulage. Elle utilise le paramètre `-l` pour spécifier une étiquette qui catégorise la clé et le paramètre `-id` pour créer un identifiant descriptif, mais unique, de la clé. Elle utilise également le paramètre `-attest` pour vérifier le microprogramme qui importe la clé.   
La sortie montre que la clé a été encapsulée et désencapsulée avec succès, puis importée dans le HSM ; enfin, le handle de clé 37 lui a été attribué. De plus, le contrôle d'attestation a été passé avec succès, ce qui indique que le microprogramme n'a pas été falsifié.  

```
Command:  imSymKey -f 3des192.key -w 6 -t 21 -l temp -id test01 -sess -attest

        Cfm3WrapHostKey returned: 0x00 : HSM Return: SUCCESS

        Cfm3CreateUnwrapTemplate returned: 0x00 : HSM Return: SUCCESS

        Cfm3UnWrapKey returned: 0x00 : HSM Return: SUCCESS

        Symmetric Key Unwrapped.  Key Handle: 37

        Attestation Check : [PASS]

        Cluster Error Status
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
```
Ensuite, vous pouvez utiliser les commandes [getAttribute](key_mgmt_util-getAttribute.md) ou [findKey](key_mgmt_util-findKey.md) pour vérifier les attributs de la clé nouvellement importée. La commande suivante utilise **findKey** pour vérifier que la clé 37 a le type, l'étiquette et l'ID spécifiés par la commande, et qu'il s'agit d'une clé de session. Comme affiché sur la ligne 5 de la sortie, **findKey** rapporte que la seule clé qui correspond à tous les attributs est la clé 37.   

```
Command:  findKey -t 21 -l temp -id test01 -sess 1
Total number of keys present 1

 number of keys matched from start index 0::0
37

        Cluster Error Status
        Node id 1 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 0 and err state 0x00000000 : HSM Return: SUCCESS
        Node id 2 and err state 0x00000000 : HSM Return: SUCCESS

        Cfm3FindKey returned: 0x00 : HSM Return: SUCCESS
```

## Parameters
<a name="imSymKey-params"></a>

**-attest**  
Exécute un contrôle d'intégrité qui vérifie que le microprogramme sur lequel le cluster est exécuté n'a pas été altéré.  
Par défaut : aucune vérification d'attestation.  
Obligatoire : non

**-f**  
Spécifie le fichier qui contient la clé à importer.  
Le fichier doit contenir une copie en texte brut d'une clé AES ou Triple DES de la longueur spécifiée. RC4 et les touches DES ne sont pas valides en mode FIPS HSMs.  
+ **AES** : 16, 24 ou 32 octets
+ **Triple DES (3DES)** : 24 octets
Obligatoire : oui

**-h**  
Affiche l'aide concernant la commande.   
Obligatoire : oui

**-id**  
Spécifie un identifiant défini par l'utilisateur pour la clé. Saisissez une chaîne unique dans le cluster. La valeur par défaut est une chaîne vide.   
Valeur par défaut : pas de valeur d'ID.  
Obligatoire : non

**-l**  
Spécifie l'étiquette définie par l'utilisateur pour la clé. Saisissez une chaîne.  
Vous pouvez utiliser n'importe quelle phrase qui vous aide à identifier la clé. Comme il n'est pas nécessaire que l'étiquette soit unique, vous pouvez l'utiliser pour regrouper et classer des clés.   
Obligatoire : oui

**-min\_srv**  
Spécifie le nombre minimum HSMs sur lequel la clé est synchronisée avant l'expiration de la valeur du `-timeout` paramètre. Si la clé n'est pas synchronisée sur le nombre spécifié de serveurs dans le temps imparti, elle n'est pas créée.  
AWS CloudHSM synchronise automatiquement chaque clé avec chaque HSM du cluster. Pour accélérer votre processus, réglez la valeur de sur une valeur inférieure `min_srv` au nombre de HSMs dans le cluster et définissez une valeur de délai d'expiration faible. Toutefois, notez que certaines demandes peuvent ne pas générer une clé.  
Valeur par défaut : 1  
Obligatoire : non

**-sess**  
Crée une clé qui existe uniquement dans la session en cours. La clé ne peut pas être récupérée une fois la session terminée.  
Utilisez ce paramètre lorsque vous n'avez besoin que brièvement d'une clé, par exemple une clé d'encapsulage qui chiffre, puis déchiffre rapidement, une autre clé. N'utilisez pas de clé de session pour chiffrer les données que vous pourriez avoir besoin de déchiffrer après la fin de la session.  
Pour remplacer une clé de session par une clé persistante (jeton), utilisez [setAttribute](key_mgmt_util-setAttribute.md).  
Par défaut : la clé est persistante.   
Obligatoire : non

**-timeout**  
Spécifie la durée (en secondes) pendant laquelle la commande attend qu'une touche soit synchronisée avec le nombre de touches HSMs spécifié par le `min_srv` paramètre.   
Ce paramètre n'est valide que lorsque le paramètre `min_srv` est également utilisé dans la commande.  
Par défaut : aucun délai d’expiration. La commande attend indéfiniment et ne renvoie des résultats que lorsque la clé est synchronisée avec le nombre minimum de serveurs.  
Obligatoire : non

**-t**  
Spécifie le type de la clé symétrique. Entrez la constante qui représente le type de clé. Par exemple, pour créer une clé AES, entrez `-t 31`.  
Valeurs valides :   
+ 21 : [Triple DES (3DES)](https://en.wikipedia.org/wiki/Triple_DES).
+ 31 : [AES](https://en.wikipedia.org/wiki/Advanced_Encryption_Standard)
Obligatoire : oui

**-u**  
Partage la clé que vous importez avec les utilisateurs spécifiés. Ce paramètre autorise les autres utilisateurs du chiffrement HSM (CUs) à utiliser cette clé dans des opérations cryptographiques.   
Entrez un identifiant ou une liste d'utilisateurs HSM séparés par des virgules IDs, telle que -u. `5,6` N'incluez pas l'ID utilisateur HSM de l'utilisateur actuel. Pour trouver un ID, vous pouvez utiliser la commande [listUsers](https://docs.aws.amazon.com/cloudhsm/latest/userguide/cloudhsm_mgmt_util-listUsers.html) dans l'outil de ligne de commande cloudhsm\_mgmt\_util ou la commande [listUsers](https://docs.aws.amazon.com/cloudhsm/latest/userguide/key_mgmt_util-listUsers.html) dans l'outil de ligne de commande key\_mgmt\_util.   
Obligatoire : non

**-s, sem**  
Spécifie le handle de clé de la clé d'encapsulage. Ce paramètre est obligatoire. Pour trouver des handles de clé, utilisez la commande [findKey](key_mgmt_util-findKey.md).  
Une *clé d'encapsulage* est une clé du HSM utilisée pour chiffrer (« encapsuler »), puis déchiffrer (« désencapsuler ») la clé pendant le processus d'importation. Seules les clés AES peut être utilisées en tant que clés d'encapsulage.  
Vous pouvez utiliser n'importe quelle clé AES (quelle que soit sa taille) comme clé d'encapsulage. Puisque les clés d'encapsulage encapsulent, puis désencapsulent immédiatement la clé cible, vous pouvez utiliser des clés AES de session unique en tant que clé d'encapsulage. Pour déterminer si une clé peut être utilisée comme clé d'encapsulage, utilisez [getAttribute](key_mgmt_util-getAttribute.md) pour obtenir la valeur de l'attribut `OBJ_ATTR_WRAP` (262). Pour créer une clé d'encapsulage, utilisez [genSymKey](key_mgmt_util-genSymKey.md) pour créer une clé AES (type 31).  
Si vous utilisez le paramètre `-wk` pour spécifier une clé d'encapsulage externe, la clé d'encapsulage `-w` est utilisée pour désencapsuler, mais pas pour encapsuler, la clé importée.  
Clé 4 est une clé interne non prise en charge. Nous vous recommandons d'utiliser une clé AES que vous créez et gérez comme clé d'encapsulage.
Obligatoire : oui

**-wk**  
Utilisez la clé AES du fichier spécifié pour encapsuler la clé en cours d'importation. Entrez le chemin et le nom d'un fichier qui contient une clé AES en texte brut.   
Lorsque vous incluez ce paramètre, **imSymKey** utilise la clé du fichier `-wk` pour encapsuler la clé en cours d'importation, ainsi que la clé du HSM spécifié par le paramètre `-w` pour la désencapsuler. La valeur des paramètres `-w` et `-wk` doivent correspondre à la même clé en texte brut.  
Par défaut : utilisez la clé d'encapsulage sur le HSM pour procéder au désencapsulage.  
Obligatoire : non

## Rubriques en relation
<a name="imSymKey-seealso"></a>
+ [genSymKey](key_mgmt_util-genSymKey.md)
+ [exSymKey](key_mgmt_util-exSymKey.md)
+ [wrapKey](key_mgmt_util-wrapKey.md)
+ [unWrapKey](key_mgmt_util-unwrapKey.md)
+ [exportPrivateKey](key_mgmt_util-exportPrivateKey.md)
+ [exportPubKey](key_mgmt_util-exportPubKey.md)