Création et importation de clés de chiffrement

Découvrez comment créer, chiffrer et importer vos clés de chiffrement sur le cloud à l'aide d'Hyper Protect Crypto Services.

Objectifs

Ce tutoriel vous explique comment créer et importer en toute sécurité des clés de chiffrement dans le service Hyper Protect Crypto Services. Il est destiné aux utilisateurs qui découvrent la fonction de gestion de clés d'Hyper Protect Crypto Services, mais qui connaissent les systèmes de gestion des clés. Les étapes suivantes doivent prendre environ 20 minutes.

Configuration de l'API de service de gestion de clés
Préparation de votre instance de service Hyper Protect Crypto Services pour commencer l'importation de clés
Création et chiffrement de clés à l'aide du kit d'outils de chiffrement OpenSSL
Importation d'une clé chiffrée dans votre instance de service Hyper Protect Crypto Services

Aucun frais n'est prélevé sur votre compte IBM Cloud pour ce tutoriel.

Flux de tâches

Le diagramme suivant donne un aperçu de la façon de créer et d'importer des clés de chiffrement. Vous pouvez cliquer sur chaque étape du graphique pour afficher les détails de l'étape.

Cliquez sur chaque étape pour obtenir plus de détails sur le flux — Flux de tâches de création et d'importation d'une clé de chiffrement

Avant de commencer

Pour commencer, vous avez besoin de l'interface de ligne de commande d'IBM Cloud pour pouvoir interagir avec les services que vous mettez à disposition sur IBM Cloud. Les packages openssl et jq doivent également être installés en local sur votre poste de travail.

Créez un compteIBM Cloud.
Téléchargez et installez l'interface de ligne de commande IBM Cloud pour votre système d'exploitation.
Téléchargez et installez le IBM Key Protect plug-in de l'interface de ligne de commande de version 0.6.3 ou d'une version ultérieure, et configurez-le pour l'utiliser dans Hyper Protect Crypto Services. Assurez-vous de mettre à jour la variable KP_PRIVATE_ADDR sur l'URL de noeud final de gestion des clés de l'instance actuelle.

Pour vérifier votre version de plug-in d'interface de ligne de commande IBM Key Protect :
```
ibmcloud plugin show key-protect
```
Pour mettre à jour votre plug-in d'interface de ligne de commande IBM Key Protect vers la version la plus récente :
```
ibmcloud plugin update key-protect -r 'IBM Cloud'
```
Téléchargez et installez la bibliothèque de cryptographieOpenSSL.

Vous pouvez utiliser les commandes openssl pour créer des clés de chiffrement sur votre poste de travail local si vous essayez Hyper Protect Crypto Services pour la première fois. Ce tutoriel requiert OpenSSL version 1.0.2r ou une version ultérieure.

Si vous utilisez un Mac, vous pouvez rapidement être opérationnel avec OpenSSL en utilisant Homebrew. Exécutez brew install openssl si vous installez le package pour la première fois ou brew upgrade openssl pour mettre à niveau votre package existant vers la dernière version.
Téléchargez et installez jq.

jqq vous aide à diviser les données JSON. Vous allez utiliser jq dans ce tutoriel pour saisir et utiliser des données spécifiques renvoyées lorsque vous appelez l'API de service de gestion de clés Hyper Protect Crypto Services.
Créez une instance de service Hyper Protect Crypto Services.
Initialisez l'instance de service Hyper Protect Crypto Services.
Configuration de l'API de service de gestion de clés Hyper Protect Crypto Services.

Créer un jeton d'importation

Avec vos données d'identification de service, vous pouvez commencer à interagir avec l'API de service de gestion de clés pour créer et apporter vos clés de chiffrement au service.

Dans l'étape suivante, vous allez créer un Jeton d'importation pour votre instance de service Hyper Protect Crypto Services. En créant un jeton d'importation basé sur une règle que vous spécifiez, vous activez la sécurité supplémentaire pour votre clé de chiffrement lors de sa transmission au service.

A partir de la ligne de commande, accédez à un nouveau répertoire hs-crypto-test.
```
mkdir hs-crypto-test && cd hs-crypto-test
```
Vous allez utiliser ce répertoire afin de stocker les fichiers que vous allez créer ultérieurement.
Vous pouvez créer un jeton d'importation pour votre instance de service Hyper Protect Crypto Services à l'aide de API de service de gestion des clés ou à l'aide de CLI, puis enregistrer la réponse dans un fichier JSON.
- Utilisation de l'API
```
curl -X POST $HPCS_API_URL/api/v2/import_token \
    -H "Accept: application/vnd.ibm.collection+json" \
    -H "Authorization: $ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Bluemix-Instance: $INSTANCE_ID" \
    -d '{
        "expiration": 1200,
        "maxAllowedRetrievals": 1
      }' > createImportTokenResponse.json
```
  Dans le corps de la requête, vous pouvez spécifier une règle sur le jeton d'importation qui limite l'utilisation en fonction du temps et du nombre d'utilisations. Dans cet exemple, vous définissez le délai d'expiration du jeton d'importation sur 1 200 secondes (20 minutes) et n'autorisez qu'une extraction de ce jeton pendant ce délai d'expiration.
- Utilisez l'interface de ligne de commande IBM Key Protect
```
ibmcloud kp import-token create --instance-id $INSTANCE_ID --max-retrievals=1 --expiration=1200 -o json > createImportTokenResponse.json
```
Affichez les détails du jeton d'importation.
```
jq '.' createImportTokenResponse.json
```
La sortie affiche les métadonnées associées à votre jeton d'importation, telles que la date de création et les détails de la règle. Le fragment ci-après montre un exemple de sortie.
```
{
  "creationDate": "2020-06-08T16:58:29Z",
  "expirationDate": "2020-06-08T17:18:29Z",
  "maxAllowedRetrievals": 1,
  "remainingRetrievals": 1
}
```

Extraction du jeton d'importation

A l'étape précédente, vous avez créé un jeton d'importation et avez consulté les métadonnées associées.

Dans cette étape, vous allez extraire la clé publique et la valeur nonce qui sont associées au jeton d'importation. Vous aurez besoin de la clé publique pour chiffrer les données au cours d'une étape ultérieure et de la valeur nonce pour vérifier votre demande d'importation sécurisée vers le service Hyper Protect Crypto Services.

Pour extraire le contenu du jeton d'importation :

Extrayez le jeton d'importation que vous avez généré à l'étape précédente, puis sauvegardez la réponse dans un fichier JSON.

Utilisation de l'API

curl -X GET $HPCS_API_URL/api/v2/import_token \
    -H "Accept: application/vnd.ibm.collection+json" \
    -H "Authorization: $ACCESS_TOKEN" \
    -H "Bluemix-Instance: $INSTANCE_ID" > getImportTokenResponse.json

Utilisez l'interface de ligne de commande IBM Key Protect

ibmcloud kp import-token show -o json > getImportTokenResponse.json

Facultatif : examinez le contenu du jeton d'importation.
```
jq '.' getImportTokenResponse.json
```
La sortie affiche des informations détaillées sur le jeton d'importation. Le fragment ci-après montre un exemple de sortie avec des valeurs tronquées.
```
{
  "creationDate": "2020-06-08T16:58:29Z",
  "expirationDate": "2020-06-08T17:18:29Z",
  "maxAllowedRetrievals": 1,
  "remainingRetrievals": 0,
  "payload": "MIICIjANBgkqhkiG...",
  "nonce": "8zJE9pKVdXVe/nLb"
}
```
La valeur payload représente la clé publique associée au jeton d'importation. Cette valeur est codée en base64. Pour plus de sécurité, Hyper Protect Crypto Services fournit une valeur nonce permettant de vérifier l'originalité d'une demande vers le service. Vous devrez chiffrer et fournir cette valeur lorsque vous importerez votre clé de chiffrement.
Décoder et enregistrer la clé publique dans un fichier appelé PublicKey.pem et extraire les valeurs en variables à utiliser ultérieurement.
```
jq -r '.payload' getImportTokenResponse.json | openssl enc -base64 -A -d -out PublicKey.pem
```
```
HPCS_PUBKEY="$(jq -r '.payload' getImportTokenResponse.json)"
NONCE="$(jq -r '.nonce' getImportTokenResponse.json)"
```
La clé publique est maintenant téléchargée sur votre poste de travail au format PEM. Passez à l'étape suivante.

Création d'une clé de chiffrement

Avec Hyper Protect Crypto Services, vous pouvez activer les avantages de sécurité de Keep Your Own Key (KYOK) en créant et en téléchargeant vos propres clés de chiffrement à utiliser sous IBM Cloud.

Lors de l'étape suivante, vous allez créer une clé symétrique AES de 256 bits sur votre poste de travail en local.

Ce tutoriel utilise le kit d'outils de chiffrement OpenSSL pour générer une clé pseudo-aléatoire, mais vous pouvez explorer d'autres options afin de générer des clés plus fortes en fonction de vos besoins en matière de sécurité. Par exemple, vous pouvez utiliser le système interne de gestion des clés de votre organisation qui repose sur un module de sécurité matériel pour créer et exporter des clés.

Si vous souhaitez créer une clé symétrique AES 256 bits à partir de la ligne de commande, exécutez la commande openssl suivante :

openssl rand 32 > PlainTextKey.bin

Vous pouvez ignorer cette étape si vous utilisez votre propre clé dans ce tutoriel.

Réussite ! Votre clé de chiffrement est maintenant sauvegardée dans un fichier intitulé PlainTextKey.bin. Passez à l'étape suivante.

Définition de la clé de chiffrement en tant que variable d'environnement

Si vous créez la clé en suivant étape 3, pour coder la clé et définir la valeur codée en tant que variable d'environnement, exécutez la commande suivante. Vous pouvez ignorer cette étape si vous utilisez votre propre clé dans ce tutoriel :

KEY_MATERIAL=$(openssl enc -base64 -A -in PlainTextKey.bin)

Chiffrer le nonce avec la clé de chiffrement

Pour une sécurité supplémentaire, Hyper Protect Crypto Services requiert une vérification nonce lorsque vous importez une clé de chiffrement au service.

En cryptographie, la valeur nonce fait office de jeton de session qui vérifie l'originalité d'une demande de protection contre les attaques malveillantes et les appels non autorisés. En utilisant la valeur nonce distribuée par Hyper Protect Crypto Services, vous vous assurez que la demande de téléchargement d'une clé est valide. La valeur nonce doit être chiffrée à l'aide de la clé que vous souhaitez importer dans le service.

Pour chiffrer la valeur nonce :

Si vous prévoyez d'utiliser l'API pour effectuer les étapes supplémentaires, procédez comme suit :

Vous n'avez pas besoin d'effectuer cette étape si vous prévoyez d'utiliser l'interface de ligne de commande IBM Key Protect.
1. Téléchargez l'exemple de fichier kms-encrypt-nonce binaire compatible avec votre système d'exploitation. Extrayez le fichier, puis déplacez-le vers le répertoire hs-crypto-test.
  
  Le fichier binaire contient un script que vous pouvez utiliser pour exécuter le chiffrement AES-CBC sur la valeur nonce à l'aide de la clé que vous avez générée dans étape 2. Pour en savoir plus sur le script, consultez le fichier source sur GitHub.
2. Si vous utilisez Linux, marquez le fichier comme exécutable en exécutant la commande chmod suivante. Vous pouvez ignorer cette étape si vous utilisez Windows.
```
chmod +x ./kms-encrypt-nonce
```
3. Exécutez le script pour chiffrer la valeur nonce avec la clé que vous avez générée dans étape 2.

Sauvegardez le nonce chiffré dans un fichier appelé EncryptedValues.json.

Utilisation de l'API

./kms-encrypt-nonce -key $KEY_MATERIAL -nonce $NONCE -alg "CBC" > EncryptedValues.json

Utilisez l'interface de ligne de commande IBM Key Protect

ibmcloud kp import-token nonce-encrypt --key "$KEY_MATERIAL" --nonce "$NONCE" --cbc -o json > EncryptedValues.json

Facultatif : examinez le contenu du fichier JSON.
```
jq '.' EncryptedValues.json
```
La sortie affiche les valeurs que vous devrez fournir lors de l'étape suivante. Le fragment ci-après montre un exemple de sortie avec des valeurs tronquées.
```
{
  "encryptedNonce": "DVy/Dbk37X8gSVwRA5U6vrHdWQy8T2ej+riIVw==",
  "iv": "puQrzDX7gU1TcTTx"
}
```
La valeur encryptedNonce représente le nonce d'origine qui est encapsulé (ou chiffré) par la clé que vous avez générée à l'aide d'OpenSSL. La valeur iv correspond au vecteur d'initialisation créé par l'algorithme AES-CBC ; elle sera requise par la suite pour permettre à Hyper Protect Crypto Services de déchiffrer la valeur nonce.

Chiffrer la clé de chiffrement créée

Ensuite, utilisez la clé publique qui a été distribuée par Hyper Protect Crypto Services dans étape 2 pour chiffrer la clé de chiffrement que vous avez créée à l'aide d'OpenSSL.

Chiffrez la clé de chiffrement créée avec l'API et affectez la clé à la variable d'environnement :
```
openssl pkeyutl \
  -encrypt \
  -pubin \
  -keyform PEM \
  -inkey PublicKey.pem \
  -pkeyopt rsa_padding_mode:oaep \
  -pkeyopt rsa_oaep_md:sha1 \
  -in PlainTextKey.bin \
  -out EncryptedKey.bin
```
```
ENCRYPTED_KEY=$(openssl enc -base64 -A -in EncryptedKey.bin)
```
Si vous rencontrez une erreur de paramètre lorsque vous exécutez la commande openssl sous Mac OSX, vous devrez peut-être vous assurer qu'OpenSSL est correctement configuré pour votre environnement. Si vous avez installé OpenSSL à l'aide de Homebrew, exécutez la commande brew update, puis la commande brew install openssl, pour obtenir la dernière version. Exécutez ensuite export PATH="/usr/local/opt/openssl/bin:$PATH"' >> ~/.bash_profile pour lier symboliquement le package. A partir de la ligne de commande, exécutez which openssl && openssl version pour vérifier que la version la plus récente d'OpenSSL est disponible sous /usr/local/. Si vous continuez de rencontrer des erreurs, veillez à utiliser uniquement les paramètres répertoriés dans cet exemple.
Chiffrez la clé de chiffrement créée avec l'interface de ligne de commande IBM Key Protect :
```
ibmcloud kp import-token key-encrypt -k "$KEY_MATERIAL" -p "$HPCS_PUBKEY" --hash SHA1 -o json > EncryptedKey.json
ENCRYPTED_KEY=$(jq -r '.encryptedKey' EncryptedKey.json)
```
Réussite ! Vous êtes prêt à télécharger votre clé chiffrée dans Hyper Protect Crypto Services. Passez à l'étape suivante.

Importer la clé chiffrée

Vous pouvez désormais importer la clé chiffrée à l'aide de l'API de service de gestion de clés.

Pour importer la clé chiffrée :

Collectez la valeur nonce et la valeur de vecteur d'initialisation chiffrées.

ENCRYPTED_NONCE=$(jq -r '.encryptedNonce' EncryptedValues.json)

IV=$(jq -r '.iv' EncryptedValues.json)

Stockez la clé chiffrée dans votre instance de service Hyper Protect Crypto Services.
- Utilisation de l'API
```
curl -X POST  $HPCS_API_URL/api/v2/keys \
    -H "Accept: application/vnd.ibm.collection+json" \
    -H "Authorization: $ACCESS_TOKEN" \
    -H "Content-Type: application/json" \
    -H "Bluemix-Instance: $INSTANCE_ID" \
    -d '{
      "metadata": {
        "collectionType": "application/vnd.ibm.kms.key+json",
        "collectionTotal": 1
      },
      "resources": [
      {
        "name": "encrypted-root-key",
        "type": "application/vnd.ibm.kms.key+json",
        "payload": "'"$ENCRYPTED_KEY"'",
        "extractable": false,
        "encryptionAlgorithm": "RSAES_OAEP_SHA_1",
        "encryptedNonce": "'"$ENCRYPTED_NONCE"'",
        "iv": "'"$IV"'"
      }
    ]
  }' > createRootKeyResponse.json
```
  Dans le corps de la demande, vous fournissez la clé de chiffrement que vous avez préparée à l'étape précédente. Vous fournissez également la valeur nonce chiffrée et les valeurs de vecteur d'initialisation requises pour vérifier la demande. Enfin, la valeur extractable définie sur false désigne votre nouvelle clé comme clé racine dans le service que vous pouvez utiliser pour le chiffrement d'enveloppe.
  
  Si la demande d'API échoue car en raison de l'expiration du jeton d'importation, retournez à l'étape 1 pour créer un nouveau jeton d'importation. N'oubliez pas que les jetons d'importation et leurs clés publiques associées arrivent à expiration en fonction de la règle que vous spécifiez lors de la phase de création.
- Utilisez l'interface de ligne de commande IBM Key Protect
```
ibmcloud kp key create new-imported-key --key-material "$ENCRYPTED_KEY" --encrypted-nonce "$ENCRYPTED_NONCE" --iv "$IV" --sha1 -o json > createRootKeyResponse.json
```
  En arrière-plan, Hyper Protect Crypto Services reçoit votre paquet chiffré via une connexion TLS 1.2. Dans un module HSM, le système utilise la clé privée pour déchiffrer la clé symétrique. Enfin, le système utilise la clé symétrique et le vecteur d'initialisation pour déchiffrer la valeur nonce et vérifier la demande. Votre clé est maintenant stockée dans un module HSM inviolable certifié FIPS 140-2 Level 4.
Affichez les détails de la clé.
```
jq '.' createRootKeyResponse.json
```
Le fragment ci-après est un exemple de sortie.
```
{
  "metadata": {
    "collectionType": "application/vnd.ibm.kms.key+json",
    "collectionTotal": 1
  },
  "resources": [
    {
      "id": "644cba65-e240-471f-8b84-14115447d2ae",
      "type": "application/vnd.ibm.kms.key+json",
      "name": "encrypted-root-key",
      "state": 1,
      "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:346d9f67-4bb2-481e-a3e1-3c2c646aa886:key:644cba65-e240-471f-8b84-14115447d2ae",
      "extractable": false,
      "imported": true
    }
  ]
}
```
- La valeur id est un identificateur unique qui est affecté à votre clé et qui est utilisé pour les appels ultérieurs à l'API de service de gestion de clés.
- La valeur state définie sur 1 indique que votre clé est maintenant à l'état de clé active.
- La valeur crn fournit le chemin d'accès complet à la clé qui indique l'emplacement de la ressource dans IBM Cloud.
- Enfin, les valeurs extractable et imported décrivent cette ressource comme clé racine que vous avez importée dans le service. Lorsque vous définissez l'attribut extractable sur true, le service désigne la clé comme étant une clé standard que vous pouvez stocker dans vos applications ou services. Sinon, lorsque vous définissez l'attribut extractable sur false, le service désigne la clé comme étant une clé racine.
Facultatif : accédez au tableau de bord Hyper Protect Crypto Services pour afficher et gérer votre clé.

Vous pouvez parcourir les caractéristiques générales de vos clés dans la page Détails de l'application. Choisissez dans la liste une option de gestion de votre clé, telle que rotation de la clé ou suppression de la clé.

Nettoyer

Collectez l'identificateur de la clé de chiffrement que vous avez importée à l'étape précédente.
```
ROOT_KEY_ID=$(jq -r '.resources[].id' createRootKeyResponse.json)
```

Supprimez la clé de chiffrement de votre instance de service Hyper Protect Crypto Services.

Utilisation de l'API

curl -X DELETE $HPCS_API_URL/api/v2/keys/$ROOT_KEY_ID \
  -H "Accept: application/vnd.ibm.collection+json" \
  -H "Authorization: $ACCESS_TOKEN" \
  -H "Bluemix-Instance: $INSTANCE_ID" | jq .

Utilisez l'interface de ligne de commande IBM Key Protect
```
ibmcloud kp key delete {ROOT_KEY_ID}
```

Retirez tous les fichiers locaux associés à ce tutoriel.
```
rm kms-encrypt-nonce *.json *.bin *.pem
```
Supprimez le répertoire de test que vous avez créé pour ce tutoriel.
```
cd .. && rm -r hs-crypto-test
```
Facultatif : supprimez votre instance de service Hyper Protect Crypto Services.
```
ibmcloud resource service-instance-delete import-keys-demo
```
Si vous avez créé plusieurs clés de test dans votre instance de service, veillez à supprimer toutes les clés de chiffrement de votre instance de service avant de mettre à disposition l'instance.

Etapes suivantes

Dans ce tutoriel, vous avez appris à configurer l'API de service de gestion des clés Hyper Protect Crypto Services , à créer une clé de chiffrement et à importer en toute sécurité une clé chiffrée dans votre instance de service Hyper Protect Crypto Services.

En savoir plus sur l'utilisation de votre clé racine pour protéger les données au repos.
Déployer votre clé racine sur les services de cloud pris en charge.
En savoir plus sur API de service de gestion des clés.