Recuperación de una lista de las claves raíz o de las claves estándar

Para obtener una vista de alto nivel, puede examinar las claves raíz o las claves estándar que se gestionan en su instancia suministrada de Hyper Protect Crypto Services haciendo una llamada GET al siguiente punto final.

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

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

2. Vea las características generales sobre las claves ejecutando el siguiente mandato cURL.

   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>' \
   

   Sustituya las variables de la solicitud de ejemplo de acuerdo con la siguiente tabla.

   Tabla 2. Describe las variables necesarias para ver claves con la API

   Variable	Descripción
   region	La abreviatura de región, como us-south o au-syd, que representa el área geográfica donde reside su instancia de servicio de Hyper Protect Crypto Services. Para obtener más información, consulte Puntos finales de servicio regional.
   port	Obligatorio. El número de puerto del punto final de API.
   IAM_token	Su señal de acceso de IBM Cloud. Incluya el contenido completo de la señal IAM, incluido el valor de Bearer, en la solicitud cURL. Para obtener más información, consulte Recuperación de una señal de acceso.
   instance_ID	El identificador exclusivo que está asignado a su instancia de servicio de Hyper Protect Crypto Services. Para obtener más información, consulte Recuperación de un ID de instancia.
   key_ring_ID	Opcional. El identificador exclusivo del conjunto de claves al que pertenece la clave. Si no se especifica, Hyper Protect Crypto Services buscará la clave en cada conjunto de claves asociado a la instancia especificada. Por lo tanto, se recomienda especificar el ID del conjunto de claves para una solicitud más optimizada. Nota: El ID del conjunto de claves que se ha creado sin una cabecera x-kms-key-ring es: default. Para obtener más información, consulte Gestionar conjuntos de claves.
   correlation_ID	Opcional. El identificador exclusivo que se ha utilizado para rastrear y correlacionar transacciones.

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

   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 tenga que utilizar limit y offset o póngase en contacto con el administrador para asegurarse de que tiene asignado el acceso de nivel correcto a las claves de la 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 3000 claves totales almacenadas en su instancia de servicio de Hyper Protect Crypto Services, 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://<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>'

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

Para obtener notas de uso, compruebe los ejemplos siguientes para configurar los parámetros de consulta limit y offset.

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 servicio 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 de estado toma una lista de enteros de 0 a 5 delimitados por comas sin espacios en blanco o comas finales. Los estados válidos se basan en NIST SP 800-57. Para obtener más información sobre los estados de las claves, consulte Estados y transiciones de claves.

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

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>'

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.