Skip to main content

Getting started with OVHcloud Key Management Service (KMS)

Stephanie R.
Updated

Learn the steps you need to take to set up your first Key Management Service (KMS) and to create a key and access certificate.

 

Requirements

 

Instructions

Ordering your KMS

Each KMS is associated with a region, so the keys stored there are guaranteed to stay there. You can order multiple KMSs, in different regions or the same region.

Since the billing for a KMS is based on the number of keys stored on it, ordering a KMS does not generate billing until keys are created.

You can order a KMS from the OVHcloud Control Panel by going to one of the following menus:

  1. In the top navigation bar, choose either Bare Metal Cloud or Hosted Private Cloud.
  2. In the left-hand menu, select Identity, Security & Operations, and then Key Management Service.
  3. Click Order.

manage_KMS_quickstart01**.png

Choose a region for your KMS.

manage_KMS_quickstart02*.png

You can then finalize the order in another tab. If it has not opened automatically, the URL is displayed:

manage_KMS_quickstart03*.png

After a few seconds, the KMS will be available in your OVHcloud Control Panel.

manage_KMS_quickstart04*.png

 

Creating an encryption key

Click each tab across the top to view all content.

You can create an encryption key from the OVHcloud Control Panel by selecting the KMS service you just created, choosing the Encryption keys tab, and clicking the + Create a key button.

manage_KMS_quickstart05*.png

A form allows you to configure the key and select its type, size, and usage. Click Confirm when you have made your selections.

manage_KMS_quickstart06*.png

Once the key is created, click on it to access its details. The dashboard displays the cryptographic properties of the key and the actions for renaming, disabling, or deleting it.

To reduce the risk of unwanted deletion, it is required to disable the key before deleting it.

NOTE: A deleted key is not recoverable and results in the loss of any data encrypted with it. Deletions should be performed with great caution.

manage_KMS_quickstart07**.png

You can create (or import) a key using the following API:

POST /okms/resource/{okmsId}/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
 

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
  • EC:
    • size: do not specify
    • curve: P-256, P-384, P-521
    • operations: sign, verify

 

Creating an access certificate

Click each tab across the top to view all content.

To communicate with your KMS, you will need to create an access certificate. This will be used for any interaction with the KMS, either to create encryption keys or to carry out operations with them.

It is possible to create this certificate from the OVHcloud Control Panel by selecting the Access certificates tab and clicking + Generate an access certificate.

manage_KMS_quickstart08*.png

 

Without providing a private key

If you do not provide a CSR, OVHcloud will generate the access certificate along with a private key.

On the next screen, provide a name for your certificate, choose a validity period, select a generation method (via OVHcloud or your own), and click Add user IDs.

manage_KMS_quickstart09*.png

The second part of the form allows you to indicate the OVHcloud identities associated to this certificate that will be used to calculate access rights via the OVHcloud IAM. It is possible to add the root identity to the certificate so not to be constrained by the OVHcloud IAM.

Add your users, groups, and/or service accounts, then click Generate access certificate.

manage_KMS_quickstart11*.png

On the next screen, be sure to Download private key and confirm by checking ☑ the box. Then click Finish.

NOTE: The private key will no longer be accessible at a later stage. If you lose it, you will need to regenerate a certificate.

manage_KMS_quickstart12*.png

Finally, you can download the public key of the certificate from the dashboard by clicking the more options ... button and selecting Download.

 

With a CSR

If you have your own private key, it is possible to use it by providing a CSR.

Then you will be able to select the associated users, as shown above.

manage_KMS_quickstart10*.png

To communicate with your KMS, you will need to create an access certificate. This will be used for any interaction with the KMS, either to create encryption keys or to carry out operations with them.

Each certificate contains an OVHcloud identity used to calculate access rights via the OVHcloud IAM.

You can generate this certificate by letting OVHcloud generate the private key, or by providing your Certificate Signing Request (CSR) in case you have your own private key.

Without providing a private key

You can generate a certificate via the following API:

POST /okms/resource/{okmsId}/credential

The following information is required:

  • name: the name of the certificate
  • identityURNs: list of OVHcloud identities in URN format that will be provided to the IAM for calculating access rights
  • description: certificate description (optional)
  • validity: certificate validity duration in days - 365 days by default (optional)

For the ACCOUNT_NIC, the following API call will retrieve that information. It is in the format "az123-ovh" and is listed in the "account" line of the API response:

GET /auth/details

Example of certificate creation with root account:

{
  "description": "My root access credential",
  "identityURNs": [
    "urn:v1:us:identity:account:<ACCOUNT_NIC>"
  ],
  "name": "root",
  "validity": 30
}

Example of certificate creation with local user:

NOTE: A user policy with the correct permissions for accessing the KMS should be created and applied to the user.

{
  "description": "My access credential",
  "identityURNs": [
    "urn:v1:us:identity:user:<ACCOUNT_NIC>/<IAM_USER>",
    "urn:v1:us:identity:group:<ACCOUNT_NIC>/<IAM_GROUP>"
  ],
  "name": "John Smith",
  "validity": 30
}

The API then returns the certificate creation status:

{
  "id": "f18b5e0d-75b8-40a3-9b0e-XXXXXX",
  "name": "John Smith",
  "description": "My access credential",
  "identityURNs": [
    "urn:v1:us:identity:user:xxxxx-ovh/john.smith",
    "urn:v1:us:identity:group:xxxxx-ovh/my_group"
  ],
  "status": "CREATING",
  "fromCSR": false,
  "privateKeyPEM": "-----BEGIN EC PRIVATE KEY-----\nMHcCAQEEIDOfWuMVQxl5quoURzThF4zTI9YYTmylSaPjneLBwP+2oAoGCCqGSM49\nAwEHoUQDQgAERd1eMw0YdAD+E9oSymGc4bCL1mfJl0EZwoM2ya/uKFFVFnGMnckg\nXXXXXXXXXXXXXXX==\n-----END EC PRIVATE KEY-----\n",
  "createdAt": "2024-04-04T12:26:28.856619+02:00",
  "expiredAt": "2025-04-04T12:26:28.856616+02:00"
}

Copy the value of the privateKeyPEM field to a domain.key file

WARNING: The private key will no longer be accessible at a later stage. If you lose it, you will need to regenerate a certificate.

NOTE: The privateKeyPEM field will need to be edited so that all instances of \n are replaced by carriage returns.

Then copy the certificate ID and access its details via the API:

GET /okms/resource/{okmsId}/credential/{credentialId}

The API returns the certificate in PEM:

{
  "id": "f18b5e0d-75b8-40a3-9b0e-XXXXXX",
  "name": "John Smith",
  "description": "My access credential",
  "identityURNs": [
    "urn:v1:us:identity:user:xxxxx-ovh/john.smith",
    "urn:v1:us:identity:group:xxxxx-ovh/my_group"
  ],
  "status": "READY",
  "fromCSR": false,
  "certificatePEM": "-----BEGIN CERTIFICATE-----\nMIIBqTCCAVCgAwIBAgIRAPGLXg11uECjmw5x/+X/A8swCgYIKoZIzj0EAwIwFTET\nMBEGA1UEAxMKQ0NNVXNlcnNDQTAeFw0yNDA0MDQxMDI2MjhaFw0yNTA0MDQxMDI2\nMjhaMC8xLTArBgNVBAMTJGU5MGM1ODQxLWYzOWUtNDk4My04NTk2LTYyZmYwYzUz\nOGI2YjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABEXdXjMNGHQA/hPaEsphnOGw\ni9ZnyZdBGcKDNsmv7ihRVRZxjJ3JICEusleqD4lE27DAAdzbRdqAhpCqsTks+sSj\nZzBlME4GA1UdEQEB/wREMEKgQAYKKwYBBAGCNxQCA6AyDDBva21zLmRvbWFpbjpl\nOTBjNTg0MS1mMzllLTQ5ODMtODU5Ni02MmZmMGM1MzhiNmIwEwYDVR0lBAwwCgYI\nKwYBBQUHAwIwCgYIKoZIzj0EAwIDRwAwRAIgdWGYm1UQMg0sTIgROFH5mWiAh/lk\nDlyP5HhrWyFB9BICIDl5wtUWgCmo6TjOqXXXXXXXXXXXXXX\n-----END CERTIFICATE-----",
  "createdAt": "2024-04-04T12:26:28.856619+02:00",
  "expiredAt": "2025-04-04T12:26:28.856616+02:00"
}

Copy the value of the certificatePEM field to a client.cert file.

NOTE: The certificatePEM field will need to be edited so that all instances of \n are replaced by carriage returns.

 

With a CSR

If you have your own private key, it is possible to use it by providing a CSR.

You can generate a certificate via the following API:

POST /okms/resource/{okmsId}/credential

The following information is required:

  • name: the name of the certificate
  • identityURNs: list of OVHcloud identities in URN format that will be provided to the IAM for calculating access rights
  • description: certificate description (optional)
  • validity: certificate validity duration in days - 365 days by default (optional)
  • csr: the content of the CSR

    NOTE: The CSR needs to be in JSON format. The CSR file will need to be edited so that there are no carriage returns; rather, \n will have to be inserted where the line breaks were previously. You can see this in practice in the example below. If you need assistance, there are third-party tools available online to adjust content into the correct JSON format.

Example of certificate creation:

{
  "csr": "-----BEGIN CERTIFICATE REQUEST-----\nMIICvDCCAaQCAQAwdzELMAkGA1UEBhMCVVMxDTALBgNVBAgMBFV0YWgxDzANBgNV\nBAcMBkxpbmRvbjEWMBQGA1UECgwNRGlnaUNlcnQgSW5jLjERMA8GA1UECwwIRGln\naUNlcnQxHTAbBgNVBAMMFGV4YW1wbGUuZGlnaWNlcnQuY29tMIIBIjANBgkqhkiG\n9w0BAQEFAAOCAQ8AMIIBCgKCAQEA8+To7d+2kPWeBv/orU3LVbJwDrSQbeKamCmo\nwp5bqDxIwV20zqRb7APUOKYoVEFFOEQs6T6gImnIolhbiH6m4zgZ/CPvWBOkZc+c\n1Po2EmvBz+AD5sBdT5kzGQA6NbWyZGldxRthNLOs1efOhdnWFuhI162qmcflgpiI\nWDuwq4C9f+YkeJhNn9dF5+owm8cOQmDrV8NNdiTqin8q3qYAHHJRW28glJUCZkTZ\nwIaSR6crBQ8TbYNE0dc+Caa3DOIkz1EOsHWzTx+n0zKfqcbgXi4DJx+C1bjptYPR\nBPZL8DAeWuA8ebudVT44yEp82G96/Ggcf7F33xMxe0yc+Xa6owIDAQABoAAwDQYJ\nKoZIhvcNAQEFBQADggEBAB0kcrFccSmFDmxox0Ne01UIqSsDqHgL+XmHTXJwre6D\nhJSZwbvEtOK0G3+dr4Fs11WuUNt5qcLsx5a8uk4G6AKHMzuhLsJ7XZjgmQXGECpY\nQ4mC3yT3ZoCGpIXbw+iP3lmEEXgaQL0Tx5LFl/okKbKYwIqNiyKWOMj7ZR/wxWg/\nZDGRs55xuoeLDJ/ZRFf9bI+IaCUd1YrfYcHIl3G87Av+r49YVwqRDT0VDV7uLgqn\n29XI1PpVUNCPQGn9p/eX6Qo7vpDaPybRtA2R7XLKjQaF9oXWeCUqy1hvJac9QFO2\n97Ob1alpHPoZ7mWiEXXXXXXXXXXXXX\n-----END CERTIFICATE REQUEST-----",
  "description": "My access credential",
  "identityURNs": [
    "urn:v1:us:identity:user:xxxxx-ovh/john.smith",
    "urn:v1:us:identity:group:xxxxx-ovh/my_group"
  ],
  "name": "John Smith",
  "validity": 30
}

The API then returns the certificate creation status:

{
  "id": "f18b5e0d-75b8-40a3-9b0e-XXXXXX",
  "name": "John Smith",
  "description": "My access credential",
  "identityURNs": [
    "urn:v1:us:identity:user:xxxxx-ovh/john.smith",
    "urn:v1:us:identity:group:xxxxx-ovh/my_group"
  ],
  "status": "CREATING",
  "fromCSR": true,
  "createdAt": "2024-04-04T12:26:28.856619+02:00",
  "expiredAt": "2025-04-04T12:26:28.856616+02:00"
}

Copy the ID of the certificate and access its details via the API:

GET /okms/resource/{okmsId}/credential/{credentialId}

The API returns the certificate in PEM:

{
  "id": "f18b5e0d-75b8-40a3-9b0e-XXXXXX",
  "name": "John Smith",
  "description": "My access credential",
  "identityURNs": [
    "urn:v1:us:identity:user:xxxxx-ovh/john.smith",
    "urn:v1:us:identity:group:xxxxx-ovh/my_group"
  ],
  "status": "READY",
  "fromCSR": true,
  "certificatePEM": "-----BEGIN CERTIFICATE-----\nMIIBqTCCAVCgAwIBAgIRAPGLXg11uECjmw5x/+X/A8swCgYIKoZIzj0EAwIwFTET\nMBEGA1UEAxMKQ0NNVXNlcnNDQTAeFw0yNDA0MDQxMDI2MjhaFw0yNTA0MDQxMDI2\nMjhaMC8xLTArBgNVBAMTJGU5MGM1ODQxLWYzOWUtNDk4My04NTk2LTYyZmYwYzUz\nOGI2YjBZMBMGByqGSM49AgEGCCqGSM49AwEHA0IABEXdXjMNGHQA/hPaEsphnOGw\ni9ZnyZdBGcKDNsmv7ihRVRZxjJ3JICEusleqD4lE27DAAdzbRdqAhpCqsTks+sSj\nZzBlME4GA1UdEQEB/wREMEKgQAYKKwYBBAGCNxQCA6AyDDBva21zLmRvbWFpbjpl\nOTBjNTg0MS1mMzllLTQ5ODMtODU5Ni02MmZmMGM1MzhiNmIwEwYDVR0lBAwwCgYI\nKwYBBQUHAwIwCgYIKoZIzj0EAwIDRwAwRAIgdWGYm1UQMg0sTIgROFH5mWiAh/lk\nDlyP5HhrWyFB9BICIDl5wtUWgCmo6TjOqXXXXXXXXXXXXXX\n-----END CERTIFICATE-----",
  "createdAt": "2024-04-04T12:26:28.856619+02:00",
  "expiredAt": "2025-04-04T12:26:28.856616+02:00"
}

Copy the value of the certificatePEM field to a client.cert file.

 

Use the OVHcloud KMS

Once your OVHcloud KMS is set up, there are two different ways to use it:

  • Using the Rest API, if you want to manually use the API to encrypt or sign your data.
  • Using the KMIP protocol, if you want to connect any KMIP compatible product with your OVHcloud KMS.

 

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.

Related articles