---
title: "Using OVHcloud Key Management Service (KMS)"
description: "Learn the steps to interact with the OVHcloud KMS to encrypt or sign your data."
url: https://docs.us.ovhcloud.com/en/manage-and-operate/kms/use-key-management-service
lang: en
---
> For AI agents: the complete documentation index is available at https://docs.us.ovhcloud.com/en/llms.txt, the full documentation bundle is available at https://docs.us.ovhcloud.com/en/llms-full.txt.

# 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](https://docs.us.ovhcloud.com/en/account/account-information/create-account.md)
- an [OVHcloud KMS ordered and an access certificate created](https://docs.us.ovhcloud.com/en/manage-and-operate/kms/quick-start.md)

 

## 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](https://us-east-vin.okms.ovh.us).

It is possible to communicate with the KMS using:

- The Swagger UI
- The [OKMS CLI](https://github.com/ovh/okms-cli)
- The [Golong SDK](https://pkg.go.dev/github.com/ovh/okms-sdk-go)

 

### 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](https://manager.us.ovhcloud.com/) 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:

**Warning:**

**NOTE:** If you created your original access certificate with a CSR and in the OVHcloud Control Panel, the `ID_privatekey.pem` is the one you created in our [Getting Started with KMS](https://docs.us.ovhcloud.com/en/manage-and-operate/kms/quick-start.md#creating-an-access-certificate) guide.

```bash
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.

**Note:**

The examples below are based on a Linux environment. The appearance and steps may be different if you are using another operating system.

**Tip:**

Click the tab for your browser.

##### Firefox

- Type `about:preferences#privacy` into the address bar.
- Scroll down until you reach a section named **Certificates**.
- Click on `View Certificates...` to open the Certificate Manager.

- Go to the tab named `Your Certificates`, then `Import...` and select the location of your `client.p12` file.

- You will be prompted to enter the password you used during the PKCS#12 file creation.
- After entering the password, your certificate will be imported and ready for use.

**Warning:** **NOTE:** The browser session will remember the certificate selected for the site. To use a new certificate, clear the existing certificate from the "Authentication Decisions" tab.

##### Chrome/Chromium

- Type `chrome://settings/certificates` into the address bar.
- Go to the `Your certificates` tab. Click on `Import` and select your `client.p12` file.

- You will be prompted to enter the password you used during the PKCS#12 file creation.
- After entering the password, your certificate will be imported and ready for use.

 

#### Accessing the authenticated Swagger UI

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

**Warning:**

**NOTE:** If the authenticated Swagger UI does not load after you select the correct certificate, refresh the page.

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

**Warning:**

**NOTE:** From this point forward, all API calls are for the Swagger API interface (also called OVHcloud KMS REST API or just OVHcloud KMS API).

Key creation can be performed either through the [OVHcloud API](https://api.us.ovhcloud.com/console/?section=%2Fokms\&branch=v2) 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:

| **Field**  | **Value**           | **Description**                                                                  |
| ---------- | ------------------- | -------------------------------------------------------------------------------- |
| name       | string              | Key name                                                                         |
| context    | string              | Additional credential to verify key authenticity                                 |
| type       | oct, RSA, EC        | Key type: Byte sequence (oct) for symmetric keys, RSA (RSA), Elliptic Curve (EC) |
| size       | Integer             | Key size - see lookup below                                                      |
| operations | Array               | Key Usage - see lookup below                                                     |
| curve      | P-256, P-384, P-521 | (optional) Cryptographic curve for EC type keys                                  |

**Tip:**

Click each tab across the top to view all content.

#### Example of symmetric key creation:

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

#### Example of asymmetric key creation:

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

#### Example of EC key creation:

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

```json
{
  "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](https://www.rfc-editor.org/rfc/rfc7518.html).

 

#### Managing encryption keys

To manage encryption keys, several APIs are available:

| **API Call**                         | **Description**                     |
| ------------------------------------ | ----------------------------------- |
| GET /v1/servicekey                   | Lists the available encryption keys |
| DELETE /v1/servicekey/\{id}          | Deletes an encryption key           |
| POST /v1/servicekey/\{id}/activate   | Activates an encryption key         |
| POST /v1/servicekey/\{id}/deactivate | Deactivates an encryption key       |

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.

**Warning:**

**NOTE:** Deleting an encryption key is permanent. All data encrypted using it will be permanently inaccessible.

 

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

| **API Call**                      | **Description**            |
| --------------------------------- | -------------------------- |
| POST /v1/servicekey/\{id}/encrypt | Data encryption with a CMK |

The API expects the following values:

| **Field** | **Value** | **Description**                                            |
| --------- | --------- | ---------------------------------------------------------- |
| plaintext | string    | Data to encrypt                                            |
| context   | string    | Additional identification data to verify data authenticity |

##### Encryption example:

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

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

```json
{
  "ciphertext": "Encrypted data",
}
```

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

| **API Call**                      | **Description**            |
| --------------------------------- | -------------------------- |
| POST /v1/servicekey/\{id}/decrypt | Decrypting data with a CMK |

The API expects the following values:

| **Field**  | **Value** | **Description**                                            |
| ---------- | --------- | ---------------------------------------------------------- |
| ciphertext | string    | Data to decrypt                                            |
| context    | string    | Additional identification data to verify data authenticity |

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:

| **API Call**                      | **Description**                  |
| --------------------------------- | -------------------------------- |
| POST /v1/servicekey/\{id}/datakey | Generate a DK derived from a CMK |

The API expects the following values:

| **Field** | **Value** | **Description**    |
| --------- | --------- | ------------------ |
| name      | string    | Key name           |
| size      | Integer   | Key Size (64-4096) |

##### Data Key generation example:

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

The API will then return the Data Key:

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

| **API Call**                              | **Description** |
| ----------------------------------------- | --------------- |
| POST /v1/servicekey/\{id}/datakey/decrypt | Decrypting a DK |

The API expects the following values:

| **Field** | **Value** | **Description**    |
| --------- | --------- | ------------------ |
| key       | string    | Encrypted Data Key |

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

| **Name** | **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 |

Following the documentation in [RFC 7518](https://www.rfc-editor.org/rfc/rfc7518#section-3.3).

- **ECDSA**

| **Name** | **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   |

Following the documentation in [RFC 7518](https://www.rfc-editor.org/rfc/rfc7518#section-3.4).

- **RSASSA-PSS**

| **Name** | **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 |

Following the documentation in [RFC 7518](https://www.rfc-editor.org/rfc/rfc7518#section-3.5).

 

#### Message signature

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

| **API Call**                   | **Description** |
| ------------------------------ | --------------- |
| POST /v1/servicekey/\{id}/sign | File signature  |

The API expects the following values:

| **Field** | **Value** | **Description**                       |
| --------- | --------- | ------------------------------------- |
| message   | string    | Message to sign in base64 format      |
| alg       | string    | Signature algorithm                   |
| isdigest  | boolean   | Whether the message is already hashed |

##### Signature example:

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

The API will then return the file signature:

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

| **API Call**                     | **Description**       |
| -------------------------------- | --------------------- |
| POST /v1/servicekey/\{id}/verify | Verifying a signature |

The API expects the following values:

| **Field** | **Value** | **Description**                       |
| --------- | --------- | ------------------------------------- |
| message   | string    | Message to sign                       |
| signature | string    | Signature associated with message     |
| alg       | string    | Signature algorithm                   |
| isdigest  | boolean   | Whether the message is already hashed |

##### Verification example:

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

The API will then return the result of the verification:

```json
{
  "result": true
}
```

 

## Go further

Browse all the [Key Management Service (KMS) guides](https://docs.us.ovhcloud.com/en/manage-and-operate/kms/landing-page-kms.md).

Browse the rest of the [OVHcloud US documentation](https://docs.us.ovhcloud.com/en/index.md) for guides on our other products and services.

Learn more about [Key Management Service](https://us.ovhcloud.com/identity-security-operations/key-management-service/) on the OVHcloud US website.