Importar y exportar claves en OVHcloud KMS con BYOK

Objetivo

Bring Your Own Key (BYOK) le permite importar y exportar material de clave criptográfico con OVHcloud Key Management Service (KMS) sin enviarlo en claro. Un par de claves RSA de transporte protege el material en tránsito: la clave pública lo encapsula y solo el titular de la clave privada puede desencapsularlo.

Esta guía le explica cómo importar y exportar una clave con OVHcloud KMS utilizando el encapsulado de clave RSA asimétrico (BYOK).

Requisitos

• Disponer de una cuenta de cliente de OVHcloud.
• Haber contratado un KMS de OVHcloud.
• Haber configurado un método de autenticación para el plano de datos OKMS (token de acceso personal, cuenta de servicio o certificado de acceso).
• Poder aplicar una política IAM en su dominio OKMS; las acciones BYOK necesarias se enumeran en Configurar IAM para el BYOK.
• Opcional: la CLI OKMS o el SDK Go instalados para los ejemplos en pestañas.

Procedimiento

Comprender la ceremonia de encapsulado RSA

La ceremonia implica dos entornos y un operador:

• Destino (Dst): su dominio OKMS, donde se almacenará la clave importada.
• Origen (Src): el sistema que actualmente posee el material de clave (otro KMS, una aplicación o una herramienta como OpenSSL).
• Operator: la entidad que dispone de los permisos necesarios para acceder tanto al dominio OKMS como al origen de la clave que se va a importar. Puede ser una persona que utiliza el CLI OKMS o un servicio que actúa a través de la API.

1. Genere un par de claves RSA de transporte en el KMS de OVHcloud con las operaciones wrapKey y unwrapKey.
2. Exporte la clave de transporte pública desde el KMS de OVHcloud.
3. Importe la clave de transporte pública en el entorno de origen.
4. En el origen, exporte el material de clave encapsulado (cifrado) con la clave de transporte utilizando RSA-OAEP o RSA-OAEP-256.
5. En el destino, importe la clave encapsulada con POST /api/{okmsId}/v1/servicekey y una carga útil wrappedKeys. El KMS desencapsula el ciphertext con la clave de transporte privada y almacena la clave de servicio resultante.

Las claves así importadas tienen never_extractable definido en false, porque el material existía fuera del KMS antes de la importación. Para extraer posteriormente una clave en forma encapsulada, defina extractable en true y siga Exportar una clave encapsulada. Consulte Atributos de sensibilidad de las claves de servicio para la lista completa de atributos.

Configurar IAM para el BYOK

Aplique una política sobre el recurso de su dominio OKMS. Su URN se muestra en la pestaña Información general del dashboard de su dominio OKMS. Sustituya <identity_urn> y <okms_urn> por sus valores. Cree las políticas a través del área de cliente de OVHcloud o de la API de OVHcloud.

Importación BYOK — leer, crear o importar claves de servicio y desencapsular con una clave de transporte:

{
  "name": "okms-byok-import",
  "description": "Import wrapped keys into an OKMS domain using RSA BYOK",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apikms:serviceKey/get",
    "okms:apikms:serviceKey/create",
    "okms:apikms:serviceKey/unwrapKey",
    "okms:apikms:serviceKey/import"
  ]
}

Exportación BYOK — importar una clave de transporte pública, actualizar la extraibilidad y encapsular una clave para la exportación:

{
  "name": "okms-byok-export",
  "description": "Export wrapped keys from an OKMS domain using RSA BYOK",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apikms:serviceKey/get",
    "okms:apikms:serviceKey/create",
    "okms:apikms:serviceKey/import",
    "okms:apikms:serviceKey/update",
    "okms:apikms:serviceKey/wrapKey"
  ]
}

Crear la clave de transporte RSA en el KMS de destino

Cree una clave RSA dedicada al encapsulado. Para la ceremonia de importación, defina tanto wrapKey como unwrapKey en esta clave; son mutuamente excluyentes con sign y verify.

Tamaños de clave RSA admitidos: 2048, 3072 o 4096 bits.

curl -X POST "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "byok-transport-rsa",
    "type": "RSA",
    "size": 4096,
    "operations": ["wrapKey", "unwrapKey"]
  }'

okms keys generate byok-transport-rsa \
  --type rsa \
  --size 4096 \
  --usage wrapKey,unwrapKey

resp, err := okmsClient.GenerateRSAKeyPair(
  ctx,
  okmsId,
  types.N4096,
  "byok-transport-rsa",
  types.SOFTWARE,
  "",
  []types.CryptographicUsages{types.WrapKey, types.UnwrapKey},
)
if err != nil {
  return err
}
transportKeyID := resp.Id

Conserve el id de la clave devuelta: lo necesitará como wrappingKeyId durante la importación.

Obtener la clave de transporte pública

Exporte la parte pública de la clave de transporte y proporciónela al entorno de origen. No comparta nunca la clave privada: permanece dentro del KMS de destino.

curl -X GET "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<transport-key-id>?format=jwk" \
  -H "Authorization: Bearer <token>"

okms keys export <transport-key-id> --format jwk

pub, err := okmsClient.ExportPublicKey(ctx, okmsId, transportKeyID)
if err != nil {
  return err
}
// pub es un crypto.PublicKey (*rsa.PublicKey para una clave de transporte RSA)

jwk, err := okmsClient.ExportJwkPublicKey(ctx, okmsId, transportKeyID)
if err != nil {
  return err
}

Encapsular el material de clave de origen

En el entorno de origen, cifre el material de clave con la clave RSA pública de destino.

Este paso se realiza fuera de OVHcloud KMS: utilice una biblioteca JOSE en el entorno de origen.

Algoritmos de encapsulado admitidos (RFC 7518):

keyFormatType describe el formato del material de clave en claro antes del encapsulado y después del desencapsulado. El ciphertext es siempre una cadena JWE Compact Serialization (el algoritmo de encapsulado va en el encabezado JWE).

Tras el encapsulado con la clave pública de destino, envíe el ciphertext JWE Compact Serialization resultante en la solicitud de importación.

Importar la clave encapsulada

Llame a POST /api/{okmsId}/v1/servicekey con un array wrappedKeys en lugar de keys en claro.

Cada entrada de wrappedKeys:

Puede importar una clave solo pública (class se convierte en PUBLIC_KEY) o una clave privada (el KMS reconstruye la parte pública; class se convierte en KEY_PAIR). El material simétrico se almacena como SECRET_KEY.

Acciones IAM en esta llamada: okms:apikms:serviceKey/create, okms:apikms:serviceKey/import, y okms:apikms:serviceKey/unwrapKey sobre la clave de transporte.

curl -X POST "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "imported-aes-byok",
    "operations": ["encrypt", "decrypt"],
    "wrappedKeys": [
      {
        "keyFormatType": "JWK",
        "wrappingKeyId": "<transport-key-id>",
        "ciphertext": "<jwe-compact-serialization>"
      }
    ]
  }'

okms keys import --usage encrypt,decrypt \
  --wrapping-key-id <transport-key-id> \
  --wrapped-key-format JWK \
  imported-aes-byok @wrapped.jwe

resp, err := okmsClient.ImportWrappedServiceKey(
  ctx,
  okmsId,
  transportKeyID,
  jweCompact,
  types.JWK,
  "imported-aes-byok",
  "",
  []types.CryptographicUsages{types.Encrypt, types.Decrypt},
)
if err != nil {
  return err
}
importedKeyID := resp.Id

Verificar la clave importada

Confirme que la clave existe y corresponde al tipo y a las operaciones esperados.

curl -X GET "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<imported-key-id>" \
  -H "Authorization: Bearer <token>"

okms keys get <imported-key-id>

key, err := okmsClient.GetServiceKey(ctx, okmsId, importedKeyID, nil)
if err != nil {
  return err
}

Verifique que:

• el state de la clave es active (o actívela si su flujo de trabajo lo exige).
• type, size y operations coinciden con lo esperado.
• los atributos de sensibilidad bajo attributes reflejan una clave importada (never_extractable vale false).

A continuación puede utilizar la clave para encrypt, decrypt, sign o verify, como se documenta en Utilizar su OVHcloud Key Management Service (KMS).

Exportar una clave encapsulada

La exportación segura es la inversa de la importación: OVHcloud KMS cifra el material de clave con una clave de transporte RSA y solo devuelve un ciphertext JWE. La clave de transporte privada debe residir en el entorno de destino — aquí el sistema externo que recibe la clave, no OVHcloud KMS — para que solo ese entorno pueda desencapsular el material.

Comprender la ceremonia de exportación

1. Genere un par de claves RSA de transporte en el entorno de destino (otro KMS o una herramienta que recibirá la clave).
2. Importe la clave de transporte pública de destino en OVHcloud KMS con la operación wrapKey (nivel de protección SOFTWARE). Esta clave es el wrappingKeyId utilizado en el momento de la exportación.
3. En OVHcloud KMS, defina extractable en true sobre la clave de servicio justo antes de la exportación, luego expórtela encapsulada por esta clave de transporte. Vuelva a poner después extractable en false cuando sea posible.
4. Transfiera el ciphertext al destino y desencapsúlelo con la clave de transporte privada de destino.

La clave de transporte referenciada por wrappingKeyId debe ser una clave RSA SOFTWARE en el mismo dominio OKMS, con el uso wrapKey. Las claves sensibles (material AES/oct y RSA/EC privado) solo pueden extraerse después del encapsulado: la extracción en claro no está admitida para estas claves.

Importar la clave de transporte pública de destino en OVHcloud KMS

Registre la clave pública de destino para que OVHcloud KMS pueda encapsular con ella la clave exportada. Impórtela como clave RSA solo pública con wrapKey (sin material privado).

curl -X POST "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "byok-export-transport-pub",
    "type": "RSA",
    "operations": ["wrapKey"],
    "keys": [
      {
        "kty": "RSA",
        "n": "<base64url-modulus>",
        "e": "<base64url-exponent>",
        "key_ops": ["wrapKey"]
      }
    ]
  }'

okms keys import byok-export-transport-pub @destination-transport-public.pem \
  --usage wrapKey

pemBytes, err := os.ReadFile("destination-transport-public.pem")
if err != nil {
  return err
}
resp, err := okmsClient.ImportKeyPairPEM(
  ctx,
  okmsId,
  pemBytes,
  "byok-export-transport-pub",
  "",
  []types.CryptographicUsages{types.WrapKey},
)
if err != nil {
  return err
}
wrappingKeyID := resp.Id

Conserve el id de la clave devuelta como wrappingKeyId.

Activar la extracción

La clave que exporta debe ser extraíble. Prefiera definir extractable en true únicamente para la operación de exportación (mediante PATCH), y luego volver a ponerlo en false. Deje las claves no extraíbles en la creación siempre que sea posible: hacer una clave extraíble fija definitivamente never_extractable en false.

Acción IAM: okms:apikms:serviceKey/update.

curl -X PATCH "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<key-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "extractable": true
  }'

okms keys update <key-id> --extractable=true

extractable := true
_, err := okmsClient.UpdateServiceKey(ctx, okmsId, keyID, types.PatchServiceKeyRequest{
  Extractable: &extractable,
})
if err != nil {
  return err
}

Tras una exportación encapsulada correcta (consulte Exportar la clave encapsulada por la clave de transporte), desactive de nuevo la extracción:

curl -X PATCH "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<key-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "extractable": false
  }'

okms keys update <key-id> --extractable=false

extractable := false
_, err := okmsClient.UpdateServiceKey(ctx, okmsId, keyID, types.PatchServiceKeyRequest{
  Extractable: &extractable,
})
if err != nil {
  return err
}

Exportar la clave encapsulada por la clave de transporte

Llame a GET /api/{okmsId}/v1/servicekey/{keyId} con los parámetros de consulta de encapsulado siguientes. Cuando estos parámetros están presentes, la API devuelve wrappedKeys en lugar de keys en claro.

Acciones IAM: okms:apikms:serviceKey/get sobre la clave exportada, y okms:apikms:serviceKey/wrapKey sobre la clave de transporte.

curl -X GET "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<key-id>?wrappingKeyId=<wrapping-key-id>&wrappedKeyFormat=JWK&wrappingAlgorithm=RSA-OAEP-256" \
  -H "Authorization: Bearer <token>"

{
  "id": "<key-id>",
  "name": "imported-aes-byok",
  "type": "oct",
  "class": "SECRET_KEY",
  "size": 256,
  "operations": ["encrypt", "decrypt"],
  "wrappedKeys": [
    {
      "keyFormatType": "JWK",
      "wrappingKeyId": "<wrapping-key-id>",
      "ciphertext": "<jwe-compact-serialization>"
    }
  ]
}

okms keys get <key-id> \
  --wrapping-key-id <wrapping-key-id> \
  --wrapped-key-format JWK \
  --wrapping-algorithm RSA-OAEP-256

wrapped, err := okmsClient.GetWrappedServiceKey(
  ctx,
  okmsId,
  keyID,
  wrappingKeyID,
  types.JWK,
  types.RSAOAEP256,
)
if err != nil {
  return err
}
ciphertext := wrapped[0].Ciphertext

Desencapsular el ciphertext en el destino

Transfiera el ciphertext al entorno de destino. Desencapsúlelo con la clave de transporte privada de destino (la contraparte de la clave pública que importó en OVHcloud KMS).

• Si el destino es otro dominio OKMS, importe allí el material encapsulado con wrappedKeys como en Importar la clave encapsulada, utilizando el identificador de la clave de transporte de ese dominio como wrappingKeyId.
• Si el destino es un sistema externo, utilice su API nativa de desencapsulado / importación con la clave de transporte privada y el mismo keyFormatType / algoritmo de encapsulado que durante la exportación.

Más información

Utilizar su OVHcloud Key Management Service (KMS)

Métodos de autenticación de OKMS

Primeros pasos con OVHcloud Key Management Service (KMS)

Interactúe con nuestra comunidad de usuarios.