Using OVHcloud Key Management Service (KMS)

Learn the steps to interact with the OVHcloud KMS to encrypt or sign your data.

Requirements

• an OVHcloud customer account
• an OVHcloud KMS ordered and an access certificate created

Instructions

Contact 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.us.

For example, for a KMS created in the us-east-vin region: https://us-east-vin.okms.ovh.us.

It is possible to communicate with the KMS using:

• The Swagger UI
• The OKMS CLI
• The Golong SDK

Using the KMS API via the Swagger UI

You can access the swagger for your KMS by clicking on the link in the OVHcloud Control Panel in your KMS dashboard.

You will land on the non-authenticated version of the Swagger UI that is meant for API documentation purposes. If you want to use the Swagger UI to make requests on your own KMS, you will need to switch to the authenticated version, whose link is in the description section:

The next steps will guide you on how to authenticate.

Importing your KMS credentials into the browser

To access the authenticated Swagger UI, you need to load your KMS access certificate into the browser Certificate Manager.

For that, it is required to convert it to PKCS#12 format. PKCS#12 is a binary format for storing a certificate chain and private key in a single, encrypted file. It is commonly used for importing and exporting certificates and private keys, especially in environments that require secure transport of these items, such as web servers and client applications.

To convert your KMS credentials (assuming you saved them into files named ID_certificate.pem and ID_privatekey.pem) to PKCS#12 with the OpenSSL Command Line Interface, use the following command:

openssl pkcs12 -export -in ID_certificate.pem  -inkey ID_privatekey.pem -out client.p12

You will be prompted to enter a password that will be used for the symmetrical encryption of the file content. Then, you need to import it into your web browser.

Accessing the authenticated Swagger UI

Once your certificate is loaded into your browser, you can go to the authenticated Swagger UI.

You will be prompted to identify yourself with a certificate. Select the previously imported PKCS#12 certificate in the drop-down list.

In Firefox

In Chrome/Chromium

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 in the result.

For the OVHcloud KMS API, you can create a key using the following API:

POST /v1/serviceKey

The API expects the following values:

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

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

{
  "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
• 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.

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",
      "curve": "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

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.

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:

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

You can generate a DK using the following API:

The API expects the following values:

{
  "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 which 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.

Sign 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 from the KMS, the signature can only be done directly with the KMS.

The API expects the following values:

{
  "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:

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

The API will then return the result of the verification:

{
  "result": true
}

Go further

For more information and tutorials, please see our other Manage & Operate support guides or explore the guides for other OVHcloud products and services.