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.

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

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
EC:
- tamaño: no especificar
- curve: P-256, P-384, P-521
- operaciones: sign, verify

Importar una clave de cifrado

Al crear una clave, es posible importar una clave existente.

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	/v1/servicekey	Enumera las claves de cifrado disponibles
DELETE	/v1/servicekey/{keyId}/delete	Elimina una clave de cifrado
POST	/v1/servicekey/{keyId}/activate	Activa una clave de cifrado
POST	/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.

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	/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	/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, unwrapKey".

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

Método	Ruta	Descripción
POST	/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	/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 del KMS, la firma solo puede realizarse directamente en el KMS.

Método	Ruta	Descripción
POST	/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	/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

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?