Recuperación de claves por estado

Al filtrar el estado de claves específicas de la instancia de Key Protect, puede recuperar claves que están en los estados que especifique.

Por ejemplo, es posible que tenga claves en la instancia de Key Protect que están en los estados activo, suspendido y destruido, pero sólo desea recuperar las claves en el estado activo cuando consulte una lista de claves.

Para obtener más información sobre los estados de claves, consulte Estados claves y transiciones.

Tras crear o importar las claves existentes en el servicio, tiene dos opciones para ver las claves. La primera opción, Ver claves a través de la lista de recursos, funciona para todas las claves excepto las de acceso fino. Para obtener información sobre la visualización de teclas con acceso de grano fino, consulte Visualización de claves de acceso de grano fino IAM.

Recuperación de una lista de claves

Para obtener una vista de alto nivel, puede examinar claves que se gestionan en su instancia suministrada de Key Protect haciendo una llamada GET al siguiente punto final.

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

1. Recupere sus credenciales de autenticación para trabajar con claves en el servicio.

2. Visualice las características generales de los conjuntos de claves ejecutando el siguiente mandato curl.

   $ 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>"
   

   Sustituya las variables en la solicitud de ejemplo de acuerdo con la información de la Tabla 1. Para obtener más información sobre los parámetros opcionales disponibles al visualizar colecciones de claves, incluida la posibilidad de buscar las claves, consulte Documentación de API con respecto al método List keys.

Una solicitud satisfactoria de GET api/v2/keys devuelve un conjunto de claves disponibles en su instancia de servicio de 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
            }
        }
    ]
}

De forma predeterminada, GET api/v2/keys devuelve las primeras 200 claves, pero puede ajustar este límite utilizando el parámetro limit al momento. Para obtener más información sobre limit y offset, consulte Recuperación de un subconjunto de claves.

¿No ve la lista completa de claves? Es posible que tengas que consultar limit y offset o ponerte en contacto con tu administrador para asegurarte de que se te ha asignado el nivel de acceso adecuado a las claves de tu instancia. Para obtener más información, consulte No se pueden ver ni listar las claves.

Recuperación de un subconjunto de claves

Al especificar los parámetros limit y offset al momento, puede recuperar un subconjunto de sus claves, empezando por el valor offset que especifique.

Por ejemplo, puede tener un total de 3000 claves almacenadas en su instancia de Key Protect, pero desea recuperar 200 o 300 claves cuando realice una solicitud de GET /keys.

Puede utilizar la solicitud de ejemplo siguiente para recuperar un conjunto distinto de claves.

$ 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>"

Sustituya las variables limit y offset en su solicitud de acuerdo con la tabla siguiente.

El desplazamiento es la ubicación de una clave concreta en un conjunto de datos. El valor offset está basado en cero, lo que significa que la clave de cifrado número 10 en un conjunto de datos, es la 9 en el desplazamiento.

Recuperación de claves por estado

Si especifica el parámetro state en el momento de la consulta, puede recuperar las claves que se encuentran en los estados que especifique.

Por ejemplo, suponga que tiene claves en la instancia de Key Protect en estado activo, suspendido y destruido, pero solo desea recuperar las claves en estado activo cuando realiza la solicitud GET /keys.

El parámetro de consulta state toma una lista de enteros comprendidos entre 0 y 5 delimitados por comas sin espacios ni comas finales. Para obtener más información sobre los estados de claves, consulte Estados claves y transiciones.

Puede utilizar la solicitud de ejemplo siguiente para recuperar un conjunto distinto de claves.

$ 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>"

Sustituya la variable state de la solicitud según la tabla siguiente.

Para ver notas sobre el uso, consulte los siguientes ejemplos de configuración del parámetro de consulta state.

Recuperación de claves por valor del parámetro Extractable

Al especificar el parámetro extractable en el momento de la consulta, puede recuperar claves cuyo material puede dejar el servicio.

Por ejemplo, es posible que tenga tanto claves estándar como raíz en la instancia de Key Protect, pero sólo desea recuperar claves con material de clave extraíble cuando realice una solicitud GET /keys.

El parámetro de consulta extractable toma un valor booleano.

Puede utilizar la solicitud de ejemplo siguiente para recuperar un conjunto distinto de claves.

$ 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>"

Sustituya la variable extractable de la solicitud según la tabla siguiente.

Para ver notas sobre el uso, consulte los siguientes ejemplos de configuración del parámetro de consulta extractable.

Ordenar una lista de claves

Al utilizar el parámetro sort en la serie de consulta ordena la lista de claves devueltas basándose en una o más propiedades clave. Para ordenar una propiedad en orden descendente, preceda el término con "-". Para ordenar en varias propiedades clave, utilice una coma para separar cada propiedad. La primera propiedad de la lista separada por comas se evalúa antes que la siguiente.

$ 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>"