Encapsulage de clés à l'aide de l'API

Vous pouvez protéger la clé DEK indiquée avec une clé racine que vous gérez dans Hyper Protect Crypto Services.

Quand vous fournissez une clé racine pour l'encapsulage, vérifiez qu'il s'agit d'une clé racine de 128, 192 ou 256 bits pour que l'opération aboutisse. Si vous créez une clé racine dans le service, Hyper Protect Crypto Services génère une clé 256 bits à partir des HSM, prise en charge par l'algorithme AES-CBC.

Après avoir désigné une clé racine dans le service, vous pouvez encapsuler une clé DEK avec un chiffrement avancé en soumettant un appel POST au noeud final suivant.

https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/<key_ID>/actions/wrap

1. Extrayez vos données d'authentification et de service afin d'utiliser les clés dans le service.

2. Copiez les informations de clé DEK que vous voulez gérer et protéger.

   Si vous disposez des privilèges de gestionnaire ou d'éditeur pour votre instance de service Hyper Protect Crypto Services, vous pouvez extraire le matériau de clé d'une clé spécifique en effectuant une demande GET /v2/keys/<key_ID>.

3. Copiez l'ID de la clé racine que vous voulez utiliser pour l'encapsulage.

4. Exécutez la commande cURL suivante pour protéger la clé avec une opération d'encapsulage :

   curl -X POST \
     'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/<key_ID>/actions/wrap' \
     -H 'accept: application/vnd.ibm.kms.key_action+json' \
     -H 'authorization: Bearer <IAM_token>' \
     -H 'bluemix-instance: <instance_ID>' \
     -H 'content-type: application/vnd.ibm.kms.key_action+json' \
     -H 'x-kms-key-ring: <key_ring_ID>' \
     -H 'correlation-id: <correlation_ID>' \
     -d '{
     "plaintext": "<data_key>"
   }'
   

   Remplacez les variables de l'exemple de demande conformément au tableau suivant :

   Tableau 1. Décrit les variables requises pour encapsuler une clé spécifiée

   Variables	Description
   region	Obligatoire. Abréviation de la région, comme us-south ou au-syd, représentant la zone géographique dans laquelle votre instance de service Hyper Protect Crypto Services réside. Pour plus d'informations, voir Noeuds finaux de service régional.
   port	Obligatoire. Numéro de port du noeud final d'API.
   key_ID	Obligatoire. ID unique de la clé racine que vous souhaitez utiliser pour l'encapsulage.
   IAM_token	Obligatoire. Votre jeton d'accès IBM Cloud. Incluez l'ensemble du contenu du jeton IAM, y compris la valeur Bearer, dans la demande cURL. Pour plus d'informations, voir Extraction d'un jeton d'accès.
   instance_ID	Obligatoire. Identificateur unique affecté à votre instance de service Hyper Protect Crypto Services. Pour plus d'informations, voir Extraction d'un ID d'instance.
   key_ring_ID	Facultatif. Identificateur unique du fichier de clés auquel appartient la clé. S'il n'est pas spécifié, Hyper Protect Crypto Services recherche la clé dans chaque fichier de clés associé à l'instance spécifiée. Par conséquent, il est conseillé de spécifier l'ID du fichier de clés pour une demande plus optimisée. Remarque : les clés créées sans en-tête x-kms-key-ring ont l'ID de fichier de clé "default". Pour plus d'informations, voir Gestion des fichiers de clés.
   correlation_ID	Facultatif. Identificateur unique qui est utilisé pour suivre et corréler des transactions.
   data_key	Informations de clé de la clé de chiffrement de données que vous voulez gérer et protéger. La valeur plaintext doit être codée en base64. Pour générer une nouvelle clé DEK, omettez l'attribut plaintext. Le service génère un texte brut aléatoire (32 octets), encapsule cette valeur, puis renvoie les valeurs générées et encapsulées dans la réponse. Les valeurs générées et encapsulées sont codées en base64 et vous devrez les décoder pour pouvoir déchiffrer les clés.

   La clé de chiffrement de données encapsulée, qui contient le matériel de clé codé en base64, est renvoyée dans la section entity-body de la réponse. Le corps de la réponse contient également l'ID de la version de clé utilisée pour encapsuler le texte en clair fourni. L'objet JSON suivant illustre un exemple de valeur renvoyée :

   {
     "ciphertext": "eyJjaXBoZXJ0ZXh0IjoiYmFzZTY0LWtleS1nb2VzLWhlcmUiLCJpdiI6IjRCSDlKREVmYU1RM3NHTGkiLCJ2ZXJzaW9uIjoiNC4wLjAiLCJoYW5kbGUiOiJ1dWlkLWdvZXMtaGVyZSJ9",
     "keyVersion": {
       "id": "02fd6835-6001-4482-a892-13bd2085f75d"
     }
   }
   

   Si vous omettez l'attribut plaintext dans votre demande d'encapsulage, le service renvoie à la fois la clé de chiffrement de données (DEK) générée et la clé de chiffrement de données encapsulée codées en base64.

   {
     "plaintext": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv",
     "ciphertext": "eyJjaXBoZXJ0ZXh0IjoiYmFzZTY0LWtleS1nb2VzLWhlcmUiLCJpdiI6IjRCSDlKREVmYU1RM3NHTGkiLCJ2ZXJzaW9uIjoiNC4wLjAiLCJoYW5kbGUiOiJ1dWlkLWdvZXMtaGVyZSJ9",
     "keyVersion": {
       "id": "12e8c9c2-a162-472d-b7d6-8b9a86b815a6"
     }
   }
   

   La valeur plaintext représente la clé de chiffrement de données désencapsulée et la valeur ciphertext représente la clé de chiffrement de données encapsulée et les deux sont codées en base64. La valeur keyVersion.id représente la version de la clé racine qui a été utilisée pour l'encapsulage.

   Si vous voulez que Hyper Protect Crypto Services génère pour vous une nouvelle clé de chiffrement de données (DEK), vous pouvez également transmettre une section body vide dans votre demande d'encapsulage. La clé de chiffrement de données générée, qui contient le matériel de clé codé en base64, est renvoyée dans la section entity-body de la réponse, avec la clé de chiffrement de données encapsulée.