Extraction d'une liste de vos clés racine ou de vos clés standard

Pour obtenir une vue globale, vous pouvez parcourir les clés racine ou les clés standard qui sont gérées dans votre instance Hyper Protect Crypto Services mise à disposition en soumettant un appel GET au noeud final suivant.

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

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

2. Affichez les caractéristiques générales de vos clés en exécutant la commande cURL suivante :

   curl -X GET \
   "https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys" \
   -H 'accept: application/vnd.ibm.collection+json' \
   -H 'authorization: Bearer <IAM_token>' \
   -H 'bluemix-instance: <instance_ID>' \
   -H 'x-kms-key-ring: <key_ring_ID>' \
   -H 'correlation-id: <correlation_ID>' \
   

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

   Tableau 2. Décrit les variables nécessaires pour afficher les clés avec l'API

   Variables	Description
   region	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 Nœuds finaux de service régional.
   port	Obligatoire. Numéro de port du noeud final d'API.
   IAM_token	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	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.

   Une demande GET /v2/keys réussie renvoie une collection des clés qui sont disponibles dans votre instance Hyper Protect Crypto Services.

   {
     "metadata": {
       "collectionType": "application/vnd.ibm.kms.key+json",
       "collectionTotal": 2
     },
     "resources": [
       {
         "id": "02fd6835-6001-4482-a892-13bd2085f75d",
         "type": "application/vnd.ibm.kms.key+json",
         "name": "Root-key",
         "state": 1,
         "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:12e8c9c2-a162-472d-b7d6-8b9a86b815a6:key:02fd6835-6001-4482-a892-13bd2085f75d",
         "createdBy": "...",
         "creationDate": "2020-03-11T16:30:06Z",
         "lastUpdateDate": "2020-03-11T16:30:06Z",
         "algorithmMetadata": {
           "bitLength": "256",
           "mode": "CBC_PAD"
         },
         "extractable": false,
         "imported": true,
         "algorithmMode": "CBC_PAD",
         "algorithmBitSize": 256,
         "dualAuthDelete": {
           "enabled": false
         }
       },
       {
         "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
         "type": "application/vnd.ibm.kms.key+json",
         "name": "Standard-key",
         "state": 1,
         "crn": "crn:v1:bluemix:public:hs-crypto:us-south:a/f047b55a3362ac06afad8a3f2f5586ea:30372f20-d9f1-40b3-b486-a709e1932c9c:key:2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
         "createdBy": "...",
         "creationDate": "2020-03-12T03:50:12Z",
         "lastUpdateDate": "2020-03-12T03:50:12Z",
         "algorithmMetadata": {
           "bitLength": "256",
           "mode": "CBC_PAD"
         },
         "extractable": true,
         "imported": false,
         "algorithmMode": "CBC_PAD",
         "algorithmBitSize": 256,
         "dualAuthDelete": {
           "enabled": false
         }
       }
     ]
   }
   

   Par défaut, GET api/v2/keys renvoie vos 200 premières clés, mais vous pouvez ajuster cette limite à l'aide du paramètre limit au moment de la demande. Pour en savoir plus sur limit et offset, voir Extraction d'un sous-ensemble de clés.

   Vous ne voyez pas la liste complète des clés ? Vous devrez peut-être utiliser limit et offset ou vérifiez auprès de votre administrateur pour vous assurer que le niveau d'accès correct aux clés de votre instance vous est attribué. Pour en savoir plus, reportez-vous à la rubrique Impossible d'afficher ou de répertorier les clés.

Extraction d'un sous-ensemble de clés

En spécifiant les paramètres limit et offset lors de l'interrogation, vous pouvez extraire un sous-ensemble de vos clés, à partir de la valeur offset que vous spécifiez.

Par exemple, vous pouvez avoir un total de 3000 clés stockées dans votre instance de service Hyper Protect Crypto Services, mais vous souhaitez extraire les clés 200 à 300 lorsque vous effectuez une demande GET /keys.

Vous pouvez utiliser l'exemple de demande suivant pour extraire un autre ensemble de clés :

curl -X GET \
  'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys?offset=<offset>&limit=<limit>' \
  -H 'accept: application/vnd.ibm.collection+json' \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>'

Remplacez les variables limit et offset dans votre demande conformément au tableau suivant :

Pour les remarques d'utilisation, reportez-vous aux exemples suivants relatifs à la configuration de vos paramètres de requête limit et offset.

Le paramètre offset correspond à l'emplacement d'une clé spécifique dans un jeu de données. La valeur offset est basée sur zéro, ce qui signifie que la 10ème clé de chiffrement dans un jeu de données se situe à l'emplacement 9.

Extraction des clés par état

En spécifiant le paramètre state lors de la requête, vous pouvez extraire des clés qui sont à l'état que vous spécifiez.

Par exemple, vous pouvez avoir des clés dans votre instance de service qui sont à l'état actif, interrompu ou détruit, mais vous souhaitez extraire uniquement les clés à l'état actif lorsque vous effectuez une demande GET /keys.

Le paramètre de requête d'état prend une liste d'entiers 0-5 délimités par des virgules, sans virgules ni virgules. Les états valides sont basés sur NIST SP 800-57. Pour plus d'informations sur les états des clés, voir Etats et transitions de clés.

Vous pouvez utiliser l'exemple de demande suivant pour extraire un autre ensemble de clés :

curl -X GET \
  'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys?state=<state_integers>' \
  -H 'accept: application/vnd.ibm.collection+json' \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>'

Remplacez la variable state dans votre demande conformément au tableau suivant :

Pour les remarques d'utilisation, reportez-vous aux exemples ci-après relatifs à la configuration de votre paramètre de requête state.