Utiliser votre OVHcloud Key Management Service (KMS)

Chiffrez ou signez vos données avec l'API REST régionale du Key Management Service (KMS) OVHcloud

Objectif

L'objectif de ce guide est de présenter les différentes étapes pour interagir avec le KMS OVHcloud pour chiffrer ou signer vos données.

Prérequis

Disposer d'un compte client OVHcloud.
Avoir commandé un KMS OVHcloud.
Avoir configuré une méthode d'authentification pour le plan de données OKMS (jeton d'accès personnel, compte de service ou certificat d'accès).

En pratique

Communiquer avec le KMS

La communication avec le KMS pour les actions de chiffrement et de signature se fait au travers des APIs.

Le KMS étant régionalisé, l'accès à l'API se fait directement sur la région de celui-ci : https://my-region.okms.ovh.net.

Par exemple, pour un KMS créé sur la région eu-west-rbx : https://eu-west-rbx.okms.ovh.net

Il est possible de communiquer avec le KMS en utilisant :

L'interface utilisateur Swagger
La CLI OKMS : https://github.com/ovh/okms-cli
Le SDK Golang : https://pkg.go.dev/github.com/ovh/okms-sdk-go

Authentifiez-vous à l'aide d'un jeton d'accès personnel, d'un compte de service ou d'un certificat d'accès. Pour l'utilisation de l'API REST, un jeton d'accès personnel (PAT) ou un compte de service est recommandé. Les certificats d'accès sont obligatoires pour les intégrations KMIP.

Pour tester les appels API de manière interactive, utilisez l'interface Swagger OKMS à l'adresse https://<region>.okms.ovh.net/swagger/.

Créer une clé de chiffrement par API

La création d'une clé peut être faite soit à travers les soit sur les API spécifiques au KMS OVHcloud. Il n'y a pas de différences sur le résultat selon la méthode de création.

Info

Les routes ci-dessous prennent l'identifiant de votre domaine OKMS. Il est renvoyé par l'appel API suivant :

GET/okms/resource

Il figure également, avec l'endpoint régional, dans l'onglet Informations générales du .

Dans le cas des API spécifiques au KMS OVHcloud, la création d'une clé se fait par l'API suivante :

Méthode	Chemin	Description
POST	/api/{okmsId}/v1/servicekey	Créer ou importer une CMK

L'API attend les valeurs suivantes :

Champ	Valeur	Description
name	string	Nom de la clé
context	string	Donnée d'identification complémentaire permettant de vérifier l'authenticité de la clé
type	oct, RSA, EC	Type de la clé : séquence d'octets (oct) pour les clés symétriques, RSA (RSA), Elliptic Curve (EC)
size	Integer	Taille de la clé - voir table de correspondance ci-dessous
operations	Array	Usage de la clé - voir table de correspondance ci-dessous
curve	P-256, P-384, P-521	(optionnel) Courbe cryptographique pour les clés de type EC
extractable	boolean	(optionnel) Indique si le matériel de clé pourra être exporté - voir la section « Attributs de sensibilité des clés de service » ci-dessous

Exemple de création de clé symétrique :

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

Exemple de création de clé asymétrique :

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

Exemple de création de clé EC :

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

Les tailles et opérations possibles en fonction du type de clé sont les suivantes :

oct :
- taille : 128, 192, 256
- opérations :
  - encrypt, decrypt
  - wrapKey, unwrapKey
RSA :
- taille : 2048, 3072, 4096
- opérations :
  - sign, verify
  - wrapKey, unwrapKey
EC :
- taille : ne pas spécifier
- curve : P-256, P-384, P-521
- opérations : sign, verify

Info

Pour les clés RSA, wrapKey / unwrapKey sont mutuellement exclusives avec sign / verify.

Importer une clé de chiffrement

Lorsque vous créez une clé, vous pouvez importer une clé existante en clair au format JWK.

Warning

L'import de matériel de clé en clair est déconseillé pour les clés qui doivent rester dignes de confiance. Préférez le BYOK sécurisé par encapsulation RSA asymétrique.

Pour cela, vous pouvez ajouter un champ complémentaire keys dans le corps de la requête :

{
  "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 clé doit être au format JSON Web Key (JWK). La valeur des champs contenus dans le tableau suit la documentation de la RFC 7518.

Gérer les clés de chiffrement

Afin de gérer les clés de chiffrement, plusieurs API sont disponibles :

Méthode	Chemin	Description
GET	/api/{okmsId}/v1/servicekey	Liste les clés de chiffrement disponibles
DELETE	/api/{okmsId}/v1/servicekey/{keyId}	Supprime une clé de chiffrement
POST	/api/{okmsId}/v1/servicekey/{keyId}/activate	Active une clé de chiffrement
POST	/api/{okmsId}/v1/servicekey/{keyId}/deactivate	Désactive une clé de chiffrement

La désactivation d'une clé de chiffrement implique que celle-ci ne sera plus utilisable, bien que la clé reste présente dans le KMS.

La suppression d'une clé de chiffrement n'est possible que sur une clé préalablement désactivée.

Warning

La suppression d'une clé de chiffrement est définitive. Toutes les données chiffrées à l'aide de celle-ci seront définitivement inaccessibles.

Attributs de sensibilité des clés de service

Lorsque vous créez ou récupérez une clé de service, les indicateurs de sensibilité et d'extractibilité sont renvoyés dans l'objet attributes de la réponse GET (aux côtés d'autres métadonnées telles que state). Seul extractable est modifiable par l'utilisateur (à la création ou via PATCH). Les autres indicateurs sont définis par le KMS. Définir extractable à true fixe définitivement never_extractable à false.

Attribut	Modifiable par l'utilisateur ?	Description
`extractable`	Oui (création / PATCH)	Si `true`, le matériel de clé peut être exporté (en clair ou encapsulé, selon la classe de clé). Par défaut : `false` — sauf les clés uniquement publiques, dont la valeur par défaut est `true`.
`never_extractable`	Non	`true` si la clé n'a jamais été extractible depuis sa création dans le KMS. Les clés importées via BYOK ou via un import en clair ont `never_extractable` défini à `false`, car le matériel existait en dehors du KMS avant l'import. Activer l'extraction efface également cet indicateur de façon permanente.
`sensitive`	Non	`true` lorsque la clé ne peut être extraite qu'une fois encapsulée (ce qui nécessite également que `extractable` soit `true`). Les clés secrètes et privées (matériel AES/`oct` et RSA/EC privé) sont toujours considérées comme sensibles.
`always_sensitive`	Non	`true` si la clé a toujours été sensible depuis sa création.

Exemple de réponse GET (champs abrégés) :

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

Pour extraire une clé en toute sécurité, définissez extractable à true uniquement pour l'opération d'export, exportez la clé avec encapsulation RSA, puis remettez-le à false. Consultez la section « Exporter une clé encapsulée » du guide « Importer et exporter des clés sur OVHcloud KMS avec BYOK ».

Chiffrer une donnée avec le KMS

Chiffrement sur le KMS

Le KMS OVHcloud dispose d'une API de chiffrement dédiée pour le chiffrement de petits volumes de données (moins de 4 kB).

Il s'agit de la méthode la plus simple, mais qui ne présente pas les meilleures performances.

Méthode	Chemin	Description
POST	/api/{okmsId}/v1/servicekey/{keyId}/encrypt	Chiffrement de données avec une CMK

L'API attend les valeurs suivantes :

Champ	Valeur	Description
plaintext	string	Donnée à chiffrer
context	string	Donnée d'identification complémentaire permettant de vérifier l'authenticité de la donnée

Exemple de chiffrement

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

L'API renvoyant ensuite la donnée chiffrée dans un champ ciphertext :

{
  "ciphertext": "Encrypted data",
}

Le déchiffrement de la donnée se faisant à l'inverse via l'API :

Méthode	Chemin	Description
POST	/api/{okmsId}/v1/servicekey/{keyId}/decrypt	Déchiffrement de données avec une CMK

L'API attend les valeurs suivantes :

Champ	Valeur	Description
ciphertext	string	Donnée à déchiffrer
context	string	Donnée d'identification complémentaire permettant de vérifier l'authenticité de la donnée

Le champ context devant avoir la même valeur que celle donnée lors du chiffrement.

Chiffrement avec une Data Key (DK)

Pour plus de performances, il est possible de générer une Data Key (DK) depuis une clé symétrique (AES) pour l'utiliser depuis votre application. La clé AES utilisée doit avoir été générée avec les opérations wrapKey et unwrapKey.

La génération d'une DK se fait via l'API suivante :

Méthode	Chemin	Description
POST	/api/{okmsId}/v1/servicekey/{keyId}/datakey	Générer une DK dérivée d'une CMK

L'API attend les valeurs suivantes :

Champ	Valeur	Description
name	string	Nom de la clé
size	Integer	Taille de la clé (64-4096)

Exemple de génération de Data Key :

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

L'API renverra ensuite la Data Key :

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

key : clé chiffrée encodée en base64. Cette information doit être stockée avec la donnée chiffrée et sera utilisée pour le déchiffrement par le KMS.
plaintext : clé en clair encodée en base64. Cette information doit être supprimée une fois le chiffrement effectué et ne doit pas être sauvegardée.

L'utilisation de la Data Key se fait ensuite à travers des algorithmes de chiffrement comme AES-GCM qui n'est pas couvert par cette documentation.

Inversement, il est possible de récupérer la version déchiffrée d'une Data Key via l'API suivante :

Méthode	Chemin	Description
POST	/api/{okmsId}/v1/servicekey/{keyId}/datakey/decrypt	Déchiffrement d'une DK

L'API attend les valeurs suivantes :

Champ	Valeur	Description
key	string	Data Key chiffrée

Et renvoie la Data Key déchiffrée dans un champ plaintext.

Signer avec le KMS

La signature de fichier se fait à l'aide de la clé privée d'une paire de clés asymétriques.

Algorithmes supportés

Le KMS OVHcloud supporte la liste d'algorithmes de signature suivante :

RSASSA-PKCS1 v1.5

Nom	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

Suivant la documentation de la RFC 7518.

ECDSA

Nom	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

Suivant la documentation de la RFC 7518.

RSASSA-PSS

Nom	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

Suivant la documentation de la RFC 7518.

Signature d'un message

Étant donné que la clé privée ne peut être extraite en clair du KMS, la signature ne peut se faire que directement auprès du KMS.

Méthode	Chemin	Description
POST	/api/{okmsId}/v1/servicekey/{keyId}/sign	Signature d'un ficher

L'API attend les valeurs suivantes :

Champ	Valeur	Description
message	string	Message à signer en format base64
alg	string	Algorithme de signature
isdigest	boolean	Indique si le message est déjà hashé

Exemple de signature :

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

L'API renverra ensuite la signature du fichier :

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

Vérification d'un fichier

La vérification d'un fichier peut se faire soit directement auprès du KMS, soit en utilisant la clé publique.

Auprès du KMS, il est possible d'utiliser l'API suivante :

Méthode	Chemin	Description
POST	/api/{okmsId}/v1/servicekey/{keyId}/verify	Vérification d'une signature

L'API attend les valeurs suivantes :

Champ	Valeur	Description
message	string	Message à signer
signature	string	Signature associée au message
alg	string	Algorithme de signature
isdigest	boolean	Indique si le message est déjà hashé

Exemple de vérification

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

L'API renverra ensuite le résultat de la vérification :

{
  "result": true
}

Aller plus loin

Importer et exporter des clés sur OVHcloud KMS avec BYOK

Méthodes d'authentification OKMS

Comment connecter un produit compatible en utilisant le protocole KMIP

Échangez avec notre communauté d'utilisateurs.

Cette page vous a-t-elle aidé ?