Using OVHcloud Key Management Service (KMS)

Objective

The purpose of this guide is to show you the steps to interact with the OVHcloud KMS to encrypt or sign your data.

Requirements

• An OVHcloud customer account.
• An OVHcloud KMS ordered.
• An authentication method configured for the OKMS data plane (Personal Access Token, service account, or access certificate).

Instructions

Contacting the KMS

Communication with the KMS for encryption and signature actions is available via APIs.

Since the KMS is regionalized, you can access the API directly in its region: https://my-region.okms.ovh.net.

For example, for a KMS created in the eu-west-rbx region: https://eu-west-rbx.okms.ovh.net.

It's possible to communicate with the KMS using:

• The Swagger UI
• The OKMS CLI: https://github.com/ovh/okms-cli
• The Golang SDK: https://pkg.go.dev/github.com/ovh/okms-sdk-go

Authenticate using a Personal Access Token, service account, or access certificate. For REST API usage, a PAT or service account is recommended. Access certificates are required for KMIP integrations.

To test API calls interactively, use the OKMS Swagger UI at https://<region>.okms.ovh.net/swagger/.

Creating an encryption key via API

Key creation can be performed either through the OVHcloud API or on the specific OVHcloud KMS API. There is no difference on the result from the creation method.

In the case of the specific OVHcloud KMS API, you can create a key using the following API:

The API expects the following values:

Example of symmetric key creation:

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

Example of asymmetric key creation:

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

Example of EC key creation:

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

Depending on the key type, the possible sizes and operations are:

• Oct:
  • size: 128, 192, 256
  • operations:
    • encrypt, decrypt
    • wrapKey, unwrapKey
• RSA:
  • size: 2048, 3072, 4096
  • operations:
    • sign, verify
    • wrapKey, unwrapKey
• EC:
  • size: do not specify
  • curve: P-256, P-384, P-521
  • operations: sign, verify

Importing an encryption key

When you create a key, you can import an existing key in plaintext JWK form.

To do this, you can add an additional keys field in the body of the request:

{
  "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"
    }
  ]
}

The key must be in JSON Web Key (JWK) format. The values of the fields contained in the table follow the documentation in RFC 7518.

Managing encryption keys

In order to manage encryption keys, several APIs are available:

Disabling an encryption key means that it will no longer be usable, even though the key remains in the KMS.

Deleting an encryption key is only possible on a key that has been previously disabled.

Service key sensitivity attributes

When you create or retrieve a service key, sensitivity and extractability flags are returned in the attributes object of the GET response (alongside other metadata such as state). Only extractable is user-settable (at creation or via PATCH). The other flags are set by the KMS. Setting extractable to true permanently sets never_extractable to false.

Example GET response shape (fields abbreviated):

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

To extract a key securely, set extractable to true only for the export operation, export with RSA wrapping, then set it back to false. See Export a wrapped key.

Encrypting data with the KMS

KMS encryption

The OVHcloud KMS has a dedicated encryption API for encrypting small volumes of data (less than 4 kB).

This is the easiest method, but it does not have the best performance.

The API expects the following values:

Encryption example

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

The API then returns the encrypted data in a ciphertext field:

{
  "ciphertext": "Encrypted data",
}

The decryption of the data is done in reverse via the API:

The API expects the following values:

The context field must have the same value as the one given during encryption.

Encryption with a Data Key (DK)

For better performance, you can generate a Data Key (DK) from a Symmetric Key (AES) to use from your application. The AES key used must have been generated with the wrapKey and unwrapKey operations.

You can generate a DK using the following API:

The API expects the following values:

Data Key generation example:

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

The API will then return the Data Key:

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

• key : encrypted key encoded in base64. This information must be stored with the encrypted data and will be used for decryption by the KMS.
• plaintext: plain key encoded in base64. This information must be deleted once the encryption is complete and must not be backed up.

The use of the Data Key is then done through encryption algorithms like AES-GCM. This is not covered by this documentation.

Conversely, you can retrieve the decrypted version of a Data Key via the following API:

The API expects the following values:

And it returns the decrypted Data Key in a plaintext field.

Signing with the KMS

File signing is done using the private key of an asymmetric key pair.

Supported algorithms

The OVHcloud KMS supports the following list of signing algorithms:

• RSASSA-PKCS1 v1.5

Following the documentation in RFC 7518.

• ECDSA

Following the documentation in RFC 7518.

• RSASSA-PSS

Following the documentation in RFC 7518.

Message signature

Since the private key cannot be extracted in plaintext from the KMS, the signature can only be done directly with the KMS.

The API expects the following values:

Signature example:

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

The API will then return the file signature:

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

Checking a file

You can check a file either directly with the KMS, or by using the public key.

With the KMS, you can use the following API:

The API expects the following values:

Verification example

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

The API will then return the result of the verification:

{
  "result": true
}

Go further

Import and export keys on OVHcloud KMS using BYOK

OKMS authentication methods

How to connect a compatible product using KMIP protocol

Join our community of users.