Utilizar su OVHcloud Key Management Service (KMS)

Cifre o firme sus datos con la API REST regional del Key Management Service (KMS) de OVHcloud

Objetivo

El objetivo de esta guía es presentar las diferentes etapas para interactuar con el KMS de OVHcloud con el fin de cifrar o firmar sus datos.

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).

Procedimiento

Comunicar con el KMS

La comunicación con el KMS para las acciones de cifrado y de firma se realiza a través de las API.

Como el KMS está regionalizado, el acceso a la API se realiza directamente en su región: https://my-region.okms.ovh.net.

Por ejemplo, para un KMS creado en la región eu-west-rbx: https://eu-west-rbx.okms.ovh.net

Es posible comunicarse con el KMS utilizando:

La interfaz de usuario Swagger
La CLI OKMS: https://github.com/ovh/okms-cli
El SDK Golang: https://pkg.go.dev/github.com/ovh/okms-sdk-go

Autentíquese mediante un token de acceso personal, una cuenta de servicio o un certificado de acceso. Para el uso de la API REST, se recomienda un token de acceso personal (PAT) o una cuenta de servicio. Los certificados de acceso son obligatorios para las integraciones KMIP.

Para probar las llamadas a la API de forma interactiva, utilice la interfaz Swagger de OKMS en la dirección https://<region>.okms.ovh.net/swagger/.

Crear una clave de cifrado mediante API

La creación de una clave puede realizarse a través de la o de las API específicas del KMS de OVHcloud. No hay ninguna diferencia en el resultado según el método de creación.

Info

Las rutas siguientes utilizan el identificador de su dominio OKMS. Se obtiene mediante la siguiente llamada a la API:

GET/okms/resource

También aparece, junto con el endpoint regional, en la pestaña Información general del .

En el caso de las API específicas del KMS de OVHcloud, la creación de una clave se realiza mediante la siguiente API:

Método	Ruta	Descripción
POST	/api/{okmsId}/v1/servicekey	Crear o importar una CMK

La API espera los siguientes valores:

Campo	Valor	Descripción
name	string	Nombre de la clave
context	string	Dato de identificación complementario que permite verificar la autenticidad de la clave
type	oct, RSA, EC	Tipo de la clave: secuencia de bytes (oct) para claves simétricas, RSA (RSA), Elliptic Curve (EC)
size	Integer	Tamaño de la clave - véase la tabla de correspondencia siguiente
operations	Array	Uso de la clave - véase la tabla de correspondencia siguiente
curve	P-256, P-384, P-521	(opcional) Curva criptográfica para las claves de tipo EC
extractable	boolean	(opcional) Indica si el material de la clave podrá exportarse - consulte la sección Atributos de sensibilidad de las claves de servicio más abajo

Ejemplo de creación de una clave simétrica:

{
  "name": "My first AES key",
  "context": "project A",
  "type": "oct",
  "size": 256,
  "operations": [
    "encrypt",
    "decrypt"
  ]
}

Ejemplo de creación de una clave asimétrica:

{
  "name": "My first RSA key",
  "context": "project A",
  "type": "RSA",
  "size": 4096,
  "operations": [
    "sign",
    "verify"
  ]
}

Ejemplo de creación de una clave EC:

{
  "name": "My first EC key",
  "context": "project A",
  "type": "EC",
  "operations": [
    "sign",
    "verify"
  ],
  "curve": "P-256"
}

Los tamaños y las operaciones posibles en función del tipo de clave son los siguientes:

oct:
- tamaño: 128, 192, 256
- operaciones:
  - encrypt, decrypt
  - wrapKey, unwrapKey
RSA:
- tamaño: 2048, 3072, 4096
- operaciones:
  - sign, verify
  - wrapKey, unwrapKey
EC:
- tamaño: no especificar
- curve: P-256, P-384, P-521
- operaciones: sign, verify

Info

En las claves RSA, wrapKey / unwrapKey son mutuamente excluyentes con sign / verify.

Importar una clave de cifrado

Al crear una clave, es posible importar una clave existente en claro en formato JWK.

Warning

La importación de material de clave en claro no está recomendada para las claves que deben seguir siendo de confianza. Prefiera el BYOK seguro con encapsulado RSA asimétrico.

Para ello, puede añadir un campo complementario keys en el cuerpo de la solicitud:

{
  "name": "My imported key",
  "keys": [
    {
      "kid": "string",
      "use": "string",
      "key_ops": [
        "string"
      ],
      "alg": "string",
      "kty": "oct",
      "n": "string",
      "e": "string",
      "k": "string",
      "crv": "string",
      "x": "string",
      "y": "string",
      "d": "string",
      "dp": "string",
      "dq": "string",
      "p": "string",
      "q": "string",
      "qi": "string"
    }
  ]
}

La clave debe estar en formato JSON Web Key (JWK). El valor de los campos contenidos en la tabla sigue la documentación de la RFC 7518.

Gestionar las claves de cifrado

Para gestionar las claves de cifrado, hay varias API disponibles:

Método	Ruta	Descripción
GET	/api/{okmsId}/v1/servicekey	Enumera las claves de cifrado disponibles
DELETE	/api/{okmsId}/v1/servicekey/{keyId}	Elimina una clave de cifrado
POST	/api/{okmsId}/v1/servicekey/{keyId}/activate	Activa una clave de cifrado
POST	/api/{okmsId}/v1/servicekey/{keyId}/deactivate	Desactiva una clave de cifrado

La desactivación de una clave de cifrado implica que esta ya no podrá utilizarse, aunque la clave permanezca presente en el KMS.

La eliminación de una clave de cifrado solo es posible en una clave previamente desactivada.

Warning

La eliminación de una clave de cifrado es definitiva. Todos los datos cifrados con ella quedarán definitivamente inaccesibles.

Atributos de sensibilidad de las claves de servicio

Cuando crea o recupera una clave de servicio, los indicadores de sensibilidad y extraibilidad se devuelven en el objeto attributes de la respuesta GET (junto con otros metadatos como state). Solo extractable es modificable por el usuario (en la creación o mediante PATCH). Los demás indicadores los establece el KMS. Definir extractable en true fija definitivamente never_extractable en false.

Atributo	¿Modificable por el usuario?	Descripción
`extractable`	Sí (creación / PATCH)	Si es `true`, el material de la clave puede exportarse (en claro o encapsulado, según la clase de clave). Por defecto: `false` — salvo las claves solo públicas, cuyo valor por defecto es `true`.
`never_extractable`	No	`true` si la clave nunca ha sido extraíble desde su creación en el KMS. Las claves importadas con BYOK o mediante importación en claro tienen `never_extractable` definido en `false`, porque el material existía fuera del KMS antes de la importación. Activar la extracción también borra este indicador de forma permanente.
`sensitive`	No	`true` cuando la clave solo puede extraerse tras encapsularse (lo que también requiere que `extractable` sea `true`). Las claves secretas y privadas (material AES/`oct` y RSA/EC privado) se consideran siempre sensibles.
`always_sensitive`	No	`true` si la clave ha sido siempre sensible desde su creación.

Ejemplo de respuesta GET (campos abreviados):

{
  "id": "<key-id>",
  "name": "aes-to-export",
  "type": "oct",
  "attributes": {
    "state": "active",
    "extractable": true,
    "never_extractable": false,
    "sensitive": true,
    "always_sensitive": true
  }
}

Para extraer una clave de forma segura, defina extractable en true únicamente para la operación de exportación, expórtela con encapsulado RSA y vuelva a ponerlo en false. Consulte Exportar una clave encapsulada.

Cifrar un dato con el KMS

Cifrado en el KMS

El KMS de OVHcloud dispone de una API de cifrado dedicada para el cifrado de pequeños volúmenes de datos (menos de 4 kB).

Se trata del método más sencillo, pero que no ofrece el mejor rendimiento.

Método	Ruta	Descripción
POST	/api/{okmsId}/v1/servicekey/{keyId}/encrypt	Cifrado de datos con una CMK

La API espera los siguientes valores:

Campo	Valor	Descripción
plaintext	string	Dato a cifrar
context	string	Dato de identificación complementario que permite verificar la autenticidad del dato

Ejemplo de cifrado

{
  "plaintext": "My secret data",
  "context": "Project A"
}

La API devuelve a continuación el dato cifrado en un campo ciphertext:

{
  "ciphertext": "Encrypted data",
}

El descifrado del dato se realiza a la inversa mediante la API:

Método	Ruta	Descripción
POST	/api/{okmsId}/v1/servicekey/{keyId}/decrypt	Descifrado de datos con una CMK

La API espera los siguientes valores:

Campo	Valor	Descripción
ciphertext	string	Dato a descifrar
context	string	Dato de identificación complementario que permite verificar la autenticidad del dato

El campo context debe tener el mismo valor que el indicado durante el cifrado.

Cifrado con una Data Key (DK)

Para obtener un mejor rendimiento, es posible generar una Data Key (DK) a partir de una clave simétrica (AES) para utilizarla desde su aplicación. La clave AES utilizada debe haberse generado con las operaciones wrapKey y unwrapKey.

La generación de una DK se realiza mediante la siguiente API:

Método	Ruta	Descripción
POST	/api/{okmsId}/v1/servicekey/{keyId}/datakey	Generar una DK derivada de una CMK

La API espera los siguientes valores:

Campo	Valor	Descripción
name	string	Nombre de la clave
size	Integer	Tamaño de la clave (64-4096)

Ejemplo de generación de una Data Key:

{
  "name": "My Data Key",
  "size": 4096
}

La API devolverá a continuación la Data Key:

{
  "key": "string",
  "plaintext": "string"
}

key: clave cifrada codificada en base64. Esta información debe almacenarse con el dato cifrado y se utilizará para el descifrado por parte del KMS.
plaintext: clave en claro codificada en base64. Esta información debe eliminarse una vez realizado el cifrado y no debe guardarse.

El uso de la Data Key se realiza a continuación a través de algoritmos de cifrado como AES-GCM, que no se aborda en esta documentación.

A la inversa, es posible recuperar la versión descifrada de una Data Key mediante la siguiente API:

Método	Ruta	Descripción
POST	/api/{okmsId}/v1/servicekey/{keyId}/datakey/decrypt	Descifrado de una DK

La API espera los siguientes valores:

Campo	Valor	Descripción
key	string	Data Key cifrada

Y devuelve la Data Key descifrada en un campo plaintext.

Firmar con el KMS

La firma de un archivo se realiza mediante la clave privada de un par de claves asimétricas.

Algoritmos compatibles

El KMS de OVHcloud admite la siguiente lista de algoritmos de firma:

RSASSA-PKCS1 v1.5

Nombre	Digital Signature Algorithm
RS256	RSASSA-PKCS1-v1_5 using SHA-256
RS384	RSASSA-PKCS1-v1_5 using SHA-384
RS512	RSASSA-PKCS1-v1_5 using SHA-512

Según la documentación de la RFC 7518.

ECDSA

Nombre	Digital Signature Algorithm
ES256	ECDSA using P-256 and SHA-256
ES384	ECDSA using P-384 and SHA-384
ES512	ECDSA using P-521 and SHA-512

Según la documentación de la RFC 7518.

RSASSA-PSS

Nombre	Digital Signature Algorithm
PS256	RSASSA-PSS using SHA-256 and MGF1 with SHA-256
PS384	RSASSA-PSS using SHA-384 and MGF1 with SHA-384
PS512	RSASSA-PSS using SHA-512 and MGF1 with SHA-512

Según la documentación de la RFC 7518.

Firma de un mensaje

Dado que la clave privada no puede extraerse en claro del KMS, la firma solo puede realizarse directamente en el KMS.

Método	Ruta	Descripción
POST	/api/{okmsId}/v1/servicekey/{keyId}/sign	Firma de un archivo

La API espera los siguientes valores:

Campo	Valor	Descripción
message	string	Mensaje a firmar en formato base64
alg	string	Algoritmo de firma
isdigest	boolean	Indica si el mensaje ya está hasheado

Ejemplo de firma:

{
  "message": "SGVsbG8gV29ybGQ=",
  "alg": "RS256",
  "isdigest": false
}

La API devolverá a continuación la firma del archivo:

{
  "signature": "EmUGXC6rsFTWtmFn77y6NS/U6IuhThApVKWTZdXjE7rDMonRPPxbjTo01HQN62J3Dxqyw=="
}

Verificación de un archivo

La verificación de un archivo puede realizarse directamente en el KMS o utilizando la clave pública.

En el KMS, es posible utilizar la siguiente API:

Método	Ruta	Descripción
POST	/api/{okmsId}/v1/servicekey/{keyId}/verify	Verificación de una firma

La API espera los siguientes valores:

Campo	Valor	Descripción
message	string	Mensaje a firmar
signature	string	Firma asociada al mensaje
alg	string	Algoritmo de firma
isdigest	boolean	Indica si el mensaje ya está hasheado

Ejemplo de verificación

{
  "message": "SGVsbG8gV29ybGQ=",
  "signature": "EmUGXC6rsFTWtmFn77y6NS/U6IuhThApVKWTZdXjE7rDMonRPPxbjTo01HQN62J3Dxqyw==",
  "alg": "RS256",
  "isdigest": false
}

La API devolverá a continuación el resultado de la verificación:

{
  "result": true
}

Más información

Importar y exportar claves en OVHcloud KMS con BYOK

Métodos de autenticación OKMS

Cómo conectar un producto compatible utilizando el protocolo KMIP

Interactúe con nuestra comunidad de usuarios.

¿Le ha resultado útil esta página?