Extraction des clés par état

En filtrant sur l'état des clés spécifiques de votre instance Key Protect, vous pouvez extraire les clés qui se trouvent dans les états que vous indiquez.

Par exemple, vous pouvez avoir des clés dans votre instance Key Protect qui se trouvent dans les états Actif, Interrompu et Détruit, mais vous souhaitez uniquement extraire des clés à l'état Actif lorsque vous consultez une liste de clés.

Pour plus d'informations sur les états de clé, voir Etats et transitions de clés.

Après avoir créé ou importé vos clés existantes dans le service, vous disposez de deux options pour afficher vos clés. La première option, Afficher les clés à travers la liste des ressources, fonctionne pour toutes les clés, à l'exception de celles dont l'accès est très fin. Pour plus d'informations sur l'affichage des clés avec un accès à grain fin, voir Visualisation des clés d'accès à grain fin IAM.

Extraction d'une liste de clés

Pour obtenir une vue globale, vous pouvez parcourir les clés qui sont gérées dans votre instance Key Protect mise à disposition en soumettant une demande GET au noeud final suivant.

https://<region>.kms.cloud.ibm.com/api/v2/keys

1. Extrayez vos données d'authentification 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://<region>.kms.cloud.ibm.com/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 dans l'exemple de demande en fonction des informations du tableau 1. Pour plus d'informations sur les paramètres facultatifs disponibles lors de l'affichage des collections de clés, y compris la possibilité de rechercher vos clés, voir la documentation de l'API concernant la méthode List keys.

Une demande GET api/v2/keys qui aboutit renvoie une collection des clés disponibles dans votre instance de service Key Protect.

{
    "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:kms: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": "Deprecated"
            },
            "extractable": false,
            "imported": true,
            "algorithmMode": "Deprecated",
            "algorithmBitSize": 256,
            "dualAuthDelete": {
                "enabled": false
            }
        },
        {
            "id": "2291e4ae-a14c-4af9-88f0-27c0cb2739e2",
            "type": "application/vnd.ibm.kms.key+json",
            "name": "Standard-key",
            "state": 1,
            "expirationDate": "2020-03-14T03:50:12Z",
            "crn": "crn:v1:bluemix:public:kms: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": "Deprecated"
            },
            "extractable": true,
            "imported": false,
            "algorithmMode": "Deprecated",
            "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 consulter les pages limit et offset ou vous adresser à votre administrateur pour vous assurer que le niveau d'accès aux clés qui vous a été attribué dans votre instance est bien le bon. 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 3 000 clés stockées dans votre instance Key Protect, 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://<region>.kms.cloud.ibm.com/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 :

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 Key Protect 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 accueille une liste d'entiers compris entre 0 et 5 délimitée par des virgules, sans espace ni virgule de fin. Pour plus d'informations sur les états de clé, 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://<region>.kms.cloud.ibm.com/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.

Extraction des clés par valeur du paramètre extractable

L'indication du paramètre extractable au moment de la demande vous permet d'extraire les clés dont le matériel peut quitter le service.

Par exemple, vous pouvez avoir à la fois des clés standard et des clés racine dans votre instance Key Protect, mais ne souhaiter extraire que des clés avec du matériel de clé extractible lorsque vous effectuez une demande GET /keys.

Le paramètre de demande extractible prend une valeur booléenne.

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

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?extractable=<extractable>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"

Remplacez la variable extractable 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 extractable.

Trier une liste de clés

L'utilisation du paramètre sort dans la chaîne de requête trie la liste des clés renvoyées en fonction d'une ou de plusieurs propriétés de clé. Pour trier une propriété par ordre décroissant, préfixez le terme par "-". Pour trier sur plusieurs propriétés clés, utilisez une virgule pour séparer chaque propriété. La première propriété de la liste séparée par des virgules est évaluée avant la suivante.

$ curl -X GET \
    "https://<region>.kms.cloud.ibm.com/api/v2/keys?sort=<sort-value>" \
    -H "accept: application/vnd.ibm.collection+json" \
    -H "authorization: Bearer <IAM_token>" \
    -H "bluemix-instance: <instance_ID>"