Envolvimiento de claves utilizando la API

Proteja una clave de cifrado de datos (DEK) específica con una clave raíz que gestionará en Hyper Protect Crypto Services.

Cuando proporcione una clave raíz para el envolvimiento, asegúrese de que la clave raíz es de 128, 192 o 256 bits para que la llamada de envolvimiento sea satisfactoria. Si crea una clave raíz en el servicio, Hyper Protect Crypto Services genera una clave de 256 bits desde los HSM, soportados por el algoritmo AES-CBC.

Después de designar una clave raíz en el servicio, puede envolver una DEK con cifrado avanzado realizando una llamada POST al siguiente punto final.

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

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

2. Copie el material de la clave de la DEK que desea gestionar y proteger.

   Si tiene privilegios de gestor o escritor para la instancia de servicio de Hyper Protect Crypto Services, puede recuperar el material de clave para una clave específica realizando una solicitud GET /v2/keys/<key_ID>.

3. Copie el ID de la clave raíz que desea utilizar para envolver.

4. Ejecute el siguiente mandato cURL para proteger la clave con una operación de envolvimiento.

   curl -X POST \
     'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/<key_ID>/actions/wrap' \
     -H 'accept: application/vnd.ibm.kms.key_action+json' \
     -H 'authorization: Bearer <IAM_token>' \
     -H 'bluemix-instance: <instance_ID>' \
     -H 'content-type: application/vnd.ibm.kms.key_action+json' \
     -H 'x-kms-key-ring: <key_ring_ID>' \
     -H 'correlation-id: <correlation_ID>' \
     -d '{
     "plaintext": "<data_key>"
   }'
   

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

   Tabla 1. Describe las variables necesarias para envolver una clave especificada

   Variable	Descripción
   region	Obligatorio. 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.
   key_ID	Obligatorio. Identificador exclusivo para la clave raíz que desea utilizar para envolver.
   IAM_token	Obligatorio. 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	Obligatorio. 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.
   data_key	El material de la clave de la DEK que desea gestionar y proteger. El valor plaintext debe estar codificado en base64. Para generar una nueva DEK, omita el atributo plaintext. El servicio genera un texto sin formato aleatorio (32 bytes), envuelve ese valor y, a continuación, devuelve los valores generados y envueltos en la respuesta. Los valores generado y envuelto están codificados en base64 y deberá descodificarlos para poder descifrar las claves.

   La clave de cifrado de datos envuelta, con el material de la clave codificado en base64, se devuelve en el cuerpo de entidad de la respuesta. El cuerpo de respuesta también contiene el ID de la versión de clave que se ha utilizado para envolver el texto sin formato proporcionado. El siguiente objeto JSON muestra un valor devuelto de ejemplo.

   {
     "ciphertext": "eyJjaXBoZXJ0ZXh0IjoiYmFzZTY0LWtleS1nb2VzLWhlcmUiLCJpdiI6IjRCSDlKREVmYU1RM3NHTGkiLCJ2ZXJzaW9uIjoiNC4wLjAiLCJoYW5kbGUiOiJ1dWlkLWdvZXMtaGVyZSJ9",
     "keyVersion": {
       "id": "02fd6835-6001-4482-a892-13bd2085f75d"
     }
   }
   

   Si omite el atributo plaintext cuando realice la solicitud de envolvimiento, el servicio devolverá tanto la clave de cifrado de datos (DEK) generada como la DEK envuelta en formato con codificación base64.

   {
     "plaintext": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv",
     "ciphertext": "eyJjaXBoZXJ0ZXh0IjoiYmFzZTY0LWtleS1nb2VzLWhlcmUiLCJpdiI6IjRCSDlKREVmYU1RM3NHTGkiLCJ2ZXJzaW9uIjoiNC4wLjAiLCJoYW5kbGUiOiJ1dWlkLWdvZXMtaGVyZSJ9",
     "keyVersion": {
       "id": "12e8c9c2-a162-472d-b7d6-8b9a86b815a6"
     }
   }
   

   El valor plaintext representa la DEK desenvuelta y el valor ciphertext representa la DEK envuelta; ambos están codificados en base64. El valor keyVersion.id representa la versión de la clave raíz utilizada para envolver.

   Si desea que Hyper Protect Crypto Services genere una nueva clave de cifrado de datos (DEK) por usted, también puede pasar un cuerpo vacío en una solicitud de envolvimiento. La DEK generada, que contiene el material de claves con codificación base64, se devolverá en la respuesta de cuerpo de entidad, junto con la DEK empaquetada.