Objectifs

Ce tutoriel vous explique comment créer et importer en toute sécurité des clés de chiffrement dans le service Key Protect. Il est destiné aux utilisateurs débutant avec Key Protect, mais qui sont éventuellement familiarisés avec les principaux systèmes de gestion. Les étapes qui suivent durent environ 20 minutes.

• Configuration de l'interface de ligne de commande Key Protect

• Préparation de votre instance de service Key Protect 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 sur votre instance Key Protect

Ce tutoriel n'entraînera pas de frais pour votre compte IBM Cloud compte.

Avant de commencer

Pour commencer, vous avez besoin de l'interface de ligne de commande 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 ordinateur.

1. Créez un Compte IBM Cloud.

2. Téléchargez et installez Interface de ligne de commande de baseIBM Cloud pour votre système d'exploitation.

3. Configurez et configurez le Key Protect pour démarrer la gestion des clés. Si vous avez déjà effectué les deux premières étapes répertoriées précédemment, commencez par l'étape numéro 3 sur le lien avant de revenir à ce tutoriel.

4. Téléchargez et installez la bibliothèque cryptographique OpenSSL.

   Vous pouvez utiliser les commandes openssl pour générer des clés de chiffrement sur votre ordinateur local si vous essayez Key Protect pour la première fois. Ce tutoriel nécessite OpenSSL version 1.0.2r ou une version ultérieure.

   Si vous utilisez un Mac, vous pouvez télécharger OpenSSL à l'aide de 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.

5. Téléchargez et installez jq.

   jqq vous aide à diviser les données JSON. Vous utilisez jq dans ce tutoriel pour capturer des données spécifiques renvoyées lorsque vous appelez l'API Key Protect.

Etape 1. Créer une instance de « Key Protect »

Après avoir configuré un compte IBM Cloud, procédez comme suit pour fournir une instance Key Protect .

1. Dans une fenêtre de terminal, exécutez la commande suivante pour vous connecter à IBM Cloud avec Interface de ligne de commandeIBM Cloud.

   ibmcloud login
   

   Si la connexion échoue, exécutez la commande ibmcloud login --sso pour réessayer. Le paramètre --sso est requis lorsque vous vous connectez avec un ID fédéré. Si cette option est utilisée, allez sur le lien répertorié dans la sortie d'interface de ligne de commande pour générer un code d'accès unique.

2. Sélectionnez le compte et le groupe de ressources dans lesquels vous souhaitez créer une instance Key Protect.

   Dans ce tutoriel, vous interagissez avec la région Washington DC. Si vous êtes connecté à une autre région, veillez à définir Washington DC comme région cible en exécutant la commande ci-après.

   ibmcloud target -r us-east
   

3. Mettez à disposition une instance de Key Protect dans ce compte et ce groupe de ressources.

   Tout d'abord, spécifiez le groupe de ressources pour l'instance en exécutant la commande suivante:

   ibmcloud target -g <your-resource-group>
   

   Exemple: ibmcloud target -g Default

   Vous pouvez ensuite créer l'instance en exécutant la commande suivante:

   ibmcloud resource service-instance-create "import-keys-demo" kms tiered-pricing us-east
   

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

4. Facultatif : vérifiez que l'instance Key Protect a été créée en répertoriant vos instances Key Protect disponibles.

   ibmcloud resource service-instances
   

   Réussite ! L'instance Key Protect dans laquelle vous pouvez stocker et gérer vos clés de chiffrement est maintenant prête. Passez à l'étape suivante.

Étape 2. Configurez l'API Key Protect

Maintenant que vous avez mis à disposition une instance de Key Protect, vous êtes prêt à utiliser l'API.

Key Protect fournit une interface graphique et une API REST pour créer, suivre et gérer des clés de chiffrement. :NONE. L'API Key Protect requiert une valeur valide Le jeton IAM IBM Cloud et un ID d'instance pour s'authentifier auprès du service.

Au cours de cette étape, vous utilisez l'interface de ligne de commande IBM Cloud pour collecter les données d'authentification dont vous avez besoin pour commencer à interagir avec les API Key Protect. Pour extraire et préparer vos données d'identification en vue des étapes ultérieures, vous définissez également les données d'identification en tant que variables d'environnement dans votre terminal.

1. Dans votre fenêtre de terminal, définissez l'API de nœud final Key Protect en tant que variable d'environnement.

   export KP_API_URL=https://<region>.kms.cloud.ibm.com
   

2. Générez un jeton d'accès IBM Cloud à l'aide du plug-in de l'interface de ligne de commande Key Protect, et définissez-le en tant que variable d'environnement.

   La variable d'environnement doit commencer par le type d'autorisation, Bearer. La commande de l'interface de ligne de commande, comme indiqué dans l'exemple, inclura automatiquement le bon type.

   export ACCESS_TOKEN=`ibmcloud iam oauth-tokens | grep IAM | cut -d \: -f 2 | sed 's/^ *//'`
   

   Les jetons d'accès IBM Cloud sont valides pendant une heure, mais vous pouvez les régénérer si besoin. Pour générer un nouveau jeton d'accès, exécutez le commande ibmcloud iam oauth-tokens. Pour en savoir plus sur l'extraction des jetons d'accès IBM Cloud, voirExtraction d'un jeton d'accès.

3. Extrayez l'identificateur associé à votre instance Key Protect, puis définissez la valeur en tant que variable d'environnement.

   export INSTANCE_ID=`ibmcloud resource service-instance "import-keys-demo" --output json | jq -r '.[].guid'`
   

4. Facultatif : vérifiez que les variables d'environnement sont correctement définies en les imprimant sur votre écran de terminal.

   $ echo $KP_API_URL
   https://us-east.kms.cloud.ibm.com
   $ echo $ACCESS_TOKEN
   Bearer eyJraWQiOiIyM...
   $ echo $INSTANCE_ID
   c1cf624b-6bed-4d4d-bd54-8e2534258a88
   

   Réussite ! Les données d'identification du service dont vous avez besoin pour vous authentifier auprès de l'API Key Protect sont maintenant prêtes. Passez à l'étape suivante.

Étape 3. Créer un jeton d'importation

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

Lors de l'étape suivante, vous créez un jeton d'importation pour votre instance Key Protect. En créant un jeton d'importation basé sur une politique que vous définissez, vous renforcez la sécurité de votre clé de chiffrement pendant son transfert vers le service.

1. A l'aide de votre session de terminal, accédez à un nouveau répertoire key-protect-test.

   mkdir key-protect-test && cd key-protect-test
   

   Utilisez ce répertoire afin de stocker les fichiers pour les étapes ultérieures.

2. Créez un jeton d'importation pour votre instance Key Protect, puis enregistrez la réponse dans un fichier JSON.

   $ curl -X POST \
       "$KP_API_URL/api/v2/import_token" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: $ACCESS_TOKEN" \
       -H "bluemix-instance: $INSTANCE_ID" \
       -H "content-type: application/json" \
       -d '{
               "expiration": 1200,
               "maxAllowedRetrievals": 1
           }' > createImportTokenResponse.json
   

   Dans le corps de la demande, vous pouvez spécifier une règle sur le jeton d'importation qui en 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.

3. 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 sa date de création et les détails de la règle. Le fragment ci-après montre un exemple de sortie.

   {
       "creationDate": "2019-04-08T16:58:29Z",
       "expirationDate": "2019-04-08T17:18:29Z",
       "maxAllowedRetrievals": 1,
       "remainingRetrievals": 1
   }
   

Étape 4. 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.

{
    "creationDate": "2019-04-08T16:58:29Z",
    "expirationDate": "2019-04-08T17:18:29Z",
    "maxAllowedRetrievals": 1,
    "remainingRetrievals": 1
}

Au cours de cette étape, vous extrayez la clé de chiffrement publique et la valeur nonce associées au jeton d'importation. Vous avez besoin de la clé publique pour chiffrer les données dans une étape ultérieure, et du nonce pour vérifier votre demande d'importation sécurisée envoyée au du service Key Protect.

Pour extraire le contenu du jeton d'importation :

1. 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.

   $ curl -X GET \
       "$KP_API_URL/api/v2/import_token" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: $ACCESS_TOKEN" \
       -H "bluemix-instance: $INSTANCE_ID" > getImportTokenResponse.json
   

2. 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": "2019-04-08T16:58:29Z",
       "expirationDate": "2019-04-08T17:18:29Z",
       "maxAllowedRetrievals": 1,
       "remainingRetrievals": 0,
       "payload": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv...",
       "nonce": "8zJE9pKVdXVe/nLb"
   }
   

   La valeur payload représente la clé publique associée au jeton d'importation. Cette valeur est codée en base64. La valeur nonce est utilisée pour vérifier l'originalité d'une demande au service. Vous devez chiffrer et fournir cette valeur lorsque vous importez votre clé de chiffrement à une étape ultérieure.

3. Décodez et sauvegardez la clé publique dans un fichier appelé PublicKey.pem.

   jq -r '.payload' getImportTokenResponse.json | base64 --decode -o PublicKey.pem
   

   La clé publique est maintenant téléchargée sur votre ordinateur au format PEM. Passez à l'étape suivante.

Étape 5. Création d'une clé de chiffrement

Avec Key Protect, vous pouvez bénéficier des avantages du mécanisme BYOK (Bring Your Own Key) en créant et téléchargeant vos propres clés à utiliser sur IBM Cloud.

Lors de l'étape suivante, vous créez une clé symétrique AES de 256 bits sur votre ordinateur 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.

1. Dans une fenêtre de terminal, exécutez la commande openssl ci-après pour créer une clé de chiffrement de 256 bits.

   openssl rand 32 > PlainTextKey.bin
   

   Réussite ! Votre clé de chiffrement est désormais enregistrée dans un fichier nommé PlainTextKey.bin. Passez à l'étape suivante.

Étape 6. Chiffrement de la valeur nonce

Pour vérifier que les bits que nous recevons sont exactement les mêmes que les bits que vous envoyez dans le cadre d'une demande, Key Protect nécessite une vérification du nonce lorsque vous téléchargez la clé symétrique sur le 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 le même nonce qui a été distribué par Key Protect, vous contribuez à vérifier que votre 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 :

1. Codez la clé générée à l'étape précédente et définissez la valeur codée en tant que variable d'environnement.

   KEY_MATERIAL=$(base64 PlainTextKey.bin)
   

2. Collectez la valeur nonce que vous avez extraite à l'étape 4.

   NONCE=$(jq -r '.nonce' getImportTokenResponse.json)
   

3. Exécutez la commande suivante pour chiffrer la valeur du nonce avec la clé de chiffrement que vous avez générée à l'étape 5. Ensuite, enregistrez la réponse dans un fichier nommé EncryptedValues.json.

   ibmcloud kp import-token nonce-encrypt -k $KEY_MATERIAL -n $NONCE --output json > EncryptedValues.json
   

4. Facultatif : Examinez le contenu du fichier JSON en utilisant jq comme indiqué.

   jq '.' EncryptedValues.json
   

   La sortie affiche les valeurs à fournir pour 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 la valeur nonce d'origine encapsulée (ou chiffrée) par la clé de chiffrement que vous avez générée à l'aide d'OpenSSL. :NONE. iv Cette valeur correspond au vecteur d'initialisation (IV) généré par l'algorithme AES- GCM, et elle sera nécessaire ultérieurement afin que Key Protect puisse déchiffrer le nonce.

Etape 7. Chiffrement de la clé

Ensuite, utilisez la clé publique distribuée par Key Protect pour chiffrer la clé symétrique que vous avez générée à l'aide d'OpenSSL.

1. Chiffrez la clé générée à l'aide de la clé publique que vous avez extraite à l'étape 4.

   openssl pkeyutl \
       -encrypt \
       -pubin \
       -keyform PEM \
       -inkey PublicKey.pem \
       -pkeyopt rsa_padding_mode:oaep \
       -pkeyopt rsa_oaep_md:sha256 \
       -in PlainTextKey.bin \
       -out EncryptedKey.bin
   

   Si vous rencontrez une erreur de paramètres lorsque vous exécutez la openssl commande sous Mac OS X, vous devrez peut-être vous assurer que 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. Ensuite, exécutez export PATH="/usr/local/opt/openssl/bin:$PATH" >> ~/.bash_profile pour créer un lien symbolique vers le paquet. Ouvrez une nouvelle session de terminal, puis exécutez which openssl && openssl version pour vérifier que la dernière version de OpenSSL est disponible à l'adresse /usr/local/. Si vous continuez de rencontrer des erreurs, veillez à utiliser uniquement les paramètres répertoriés dans cet exemple.

   Réussite ! Votre clé chiffrée est désormais enregistrée dans un fichier nommé EncryptedKey.bin. Vous êtes maintenant prêt à télécharger votre clé chiffrée dans Key Protect. Passez à l'étape suivante.

Étape 8. Importation de la clé

Vous pouvez désormais importer la clé chiffrée à l'aide de l'API Key Protect.

Pour importer la clé :

1. Collectez les valeurs de la clé chiffrée, de la valeur nonce chiffrée et du vecteur d'initialisation.

   ENCRYPTED_KEY=$(openssl enc -base64 -A -in EncryptedKey.bin)
   

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

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

2. Stockez la clé chiffrée dans votre Instance Key Protect en exécutant la commande curl suivante.

   $ curl -X POST \
       "$KP_API_URL/api/v2/keys" \
       -H "accept: application/vnd.ibm.collection+json" \
       -H "authorization: $ACCESS_TOKEN" \
       -H "bluemix-instance: $INSTANCE_ID" \
       -H "content-type: application/json" \
       -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_256",
                       "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 est définie sur false définit votre nouvelle clé comme clé racine dans le service; vous pouvez l'utiliser pour le chiffrement des enveloppes.

   Key Protect reçoit votre paquet chiffré via le protocole TLS 1.2 ou 1.3. 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.

   Si la demande d'API échoue car le délai d'expiration du jeton d'importation est dépassé, retournez à l'étape 3 pour créer un autre 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.

3. Affichez les détails de la clé de chiffrement.

   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": "02fd6835-6001-4482-a892-13bd2085f75d",
               "type": "application/vnd.ibm.kms.key+json",
               "name": "encrypted-root-key",
               "state": 1,
               "crn": "crn:v1:bluemix:public:kms:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
               "extractable": false,
               "imported": true
           }
       ]
   }
   

   La valeur id est un identificateur unique qui est affecté à votre clé et qui est utilisé pour les appels suivants à l'API Key Protect. La valeur de l' state, réglée sur 1, indique que votre clé de chiffrement se trouve désormais dans le fichier « Actif état clé ». 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.

4. Facultatif : Accédez au Tableau de bord Key Protect pour afficher et gérer votre clé de chiffrement.

   

   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é.

Étape 9. Nettoyer

1. 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)
   

2. Supprimez la clé de chiffrement de votre instance Key Protect.

   $ curl -X DELETE \
       "$KP_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 .
   

3. Supprimez tous les fichiers locaux associés à ce tutoriel.

   rm *.json *.bin *.pem
   

4. Supprimez le répertoire de test que vous avez créé pour ce tutoriel.

   cd .. && rm -r key-protect-test
   

5. Facultatif : supprimez votre instance de service Key Protect.

   ibmcloud resource service-instance-delete import-keys-demo
   

   Si vous avez créé d'autres clés de test dans votre instance Key Protect, veillez à supprimer toutes les clés de chiffrement de votre instance avant de supprimer l'instance ou d'annuler sa mise à disposition.

Etapes suivantes

Dans ce tutoriel, vous avez appris à configurer l'API Key Protect, à créer une clé de chiffrement et à importer de façon sécurisée une clé chiffrée dans votre instance Key Protect.

• 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 APIKey Protect.