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

Objectif

Bring Your Own Key (BYOK) vous permet d'importer et d'exporter du matériel cryptographique avec OVHcloud Key Management Service (KMS) sans l'envoyer en clair. Une paire de clés RSA de transport protège le matériel en transit : la clé publique l'encapsule et seul le détenteur de la clé privée peut le désencapsuler.

Ce guide vous explique comment importer et exporter une clé avec OVHcloud KMS en utilisant l'encapsulation de clé RSA asymétrique (BYOK).

Prérequis

• Disposer d'un compte client OVHcloud.
• Avoir commandé un OVHcloud KMS.
• 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).
• Pouvoir appliquer une politique IAM sur votre domaine OKMS ; les actions BYOK requises sont listées dans la section « Configurer IAM pour le BYOK ».
• Optionnel : avoir installé la CLI OKMS ou le SDK Go pour les exemples en onglets.

En pratique

Comprendre la cérémonie d'encapsulation RSA

La cérémonie implique deux environnements et un opérateur :

• Destination (Dst) : votre domaine OKMS, où la clé importée est stockée.
• Source (Src) : le système qui détient actuellement le matériel de clé (un autre KMS, une application ou un outil tel qu'OpenSSL).
• Operator : l'entité disposant des autorisations nécessaires pour accéder à la fois au domaine OKMS et à la source de la clé à importer. Il peut s'agir d'une personne utilisant le CLI OKMS ou d'un service passant par l'API.

1. Générez une paire de clés RSA de transport sur OVHcloud KMS avec les opérations wrapKey et unwrapKey.
2. Exportez la clé de transport publique depuis OVHcloud KMS.
3. Importez la clé de transport publique dans l'environnement source.
4. Sur la source, exportez le matériel de clé encapsulé (chiffré) avec la clé de transport en utilisant RSA-OAEP ou RSA-OAEP-256.
5. Sur la destination, importez la clé encapsulée avec POST /api/{okmsId}/v1/servicekey et une charge utile wrappedKeys. Le KMS désencapsule le ciphertext avec la clé de transport privée et stocke la clé de service résultante.

Les clés ainsi importées ont never_extractable défini à false, car le matériel existait en dehors du KMS avant l'import. Pour extraire ultérieurement une clé sous forme encapsulée, définissez extractable à true et suivez la section « Exporter une clé encapsulée ». Consultez la section « Attributs de sensibilité des clés de service » pour obtenir la liste complète des attributs.

Configurer IAM pour le BYOK

Appliquez une politique à la ressource de votre domaine OKMS. Son URN est affiché dans l'onglet Informations générales du dashboard de votre domaine OKMS. Remplacez <identity_urn> et <okms_urn> par vos valeurs. Créez les politiques via l'espace client OVHcloud ou l'API OVHcloud.

Import BYOK — lire, créer ou importer des clés de service et désencapsuler avec une clé de transport :

{
  "name": "okms-byok-import",
  "description": "Import wrapped keys into an OKMS domain using RSA BYOK",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apikms:serviceKey/get",
    "okms:apikms:serviceKey/create",
    "okms:apikms:serviceKey/unwrapKey",
    "okms:apikms:serviceKey/import"
  ]
}

Export BYOK — importer une clé de transport publique, mettre à jour l'extractibilité et encapsuler une clé pour l'export :

{
  "name": "okms-byok-export",
  "description": "Export wrapped keys from an OKMS domain using RSA BYOK",
  "identities": ["<identity_urn>"],
  "resources": [{ "urn": "<okms_urn>" }],
  "action": [
    "okms:apikms:serviceKey/get",
    "okms:apikms:serviceKey/create",
    "okms:apikms:serviceKey/import",
    "okms:apikms:serviceKey/update",
    "okms:apikms:serviceKey/wrapKey"
  ]
}

Créer la clé de transport RSA sur le KMS de destination

Créez une clé RSA dédiée à l'encapsulation. Pour la cérémonie d'import, définissez à la fois wrapKey et unwrapKey sur cette clé ; elles sont mutuellement exclusives avec sign et verify.

Tailles de clé RSA prises en charge : 2048, 3072 ou 4096 bits.

curl -X POST "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "byok-transport-rsa",
    "type": "RSA",
    "size": 4096,
    "operations": ["wrapKey", "unwrapKey"]
  }'

okms keys generate byok-transport-rsa \
  --type rsa \
  --size 4096 \
  --usage wrapKey,unwrapKey

resp, err := okmsClient.GenerateRSAKeyPair(
  ctx,
  okmsId,
  types.N4096,
  "byok-transport-rsa",
  types.SOFTWARE,
  "",
  []types.CryptographicUsages{types.WrapKey, types.UnwrapKey},
)
if err != nil {
  return err
}
transportKeyID := resp.Id

Conservez l'id de la clé renvoyée — vous en avez besoin comme wrappingKeyId lors de l'import.

Obtenir la clé de transport publique

Exportez la partie publique de la clé de transport et transmettez-la à l'environnement source. Ne partagez jamais la clé privée — elle reste à l'intérieur du KMS de destination.

curl -X GET "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<transport-key-id>?format=jwk" \
  -H "Authorization: Bearer <token>"

okms keys export <transport-key-id> --format jwk

pub, err := okmsClient.ExportPublicKey(ctx, okmsId, transportKeyID)
if err != nil {
  return err
}
// pub est un crypto.PublicKey (*rsa.PublicKey pour une clé de transport RSA)

jwk, err := okmsClient.ExportJwkPublicKey(ctx, okmsId, transportKeyID)
if err != nil {
  return err
}

Encapsuler le matériel de clé source

Sur l'environnement source, chiffrez le matériel de clé avec la clé RSA publique de destination.

Cette étape se déroule en dehors d'OVHcloud KMS : utilisez une bibliothèque JOSE sur l'environnement source.

Algorithmes d'encapsulation pris en charge (RFC 7518) :

keyFormatType décrit le format du matériel de clé en clair avant encapsulation et après désencapsulation. Le ciphertext est toujours une chaîne JWE Compact Serialization (l'algorithme d'encapsulation est porté dans l'en-tête JWE).

Après encapsulation avec la clé publique de destination, envoyez le ciphertext JWE Compact Serialization obtenu dans la requête d'import.

Importer la clé encapsulée

Appelez POST /api/{okmsId}/v1/servicekey avec un tableau wrappedKeys au lieu de keys en clair.

Chaque entrée de wrappedKeys :

Vous pouvez importer une clé uniquement publique (class devient PUBLIC_KEY) ou une clé privée (le KMS reconstruit la partie publique ; class devient KEY_PAIR). Le matériel symétrique est stocké comme SECRET_KEY.

Actions IAM sur cet appel : okms:apikms:serviceKey/create, okms:apikms:serviceKey/import et okms:apikms:serviceKey/unwrapKey sur la clé de transport.

curl -X POST "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "imported-aes-byok",
    "operations": ["encrypt", "decrypt"],
    "wrappedKeys": [
      {
        "keyFormatType": "JWK",
        "wrappingKeyId": "<transport-key-id>",
        "ciphertext": "<jwe-compact-serialization>"
      }
    ]
  }'

okms keys import --usage encrypt,decrypt \
  --wrapping-key-id <transport-key-id> \
  --wrapped-key-format JWK \
  imported-aes-byok @wrapped.jwe

resp, err := okmsClient.ImportWrappedServiceKey(
  ctx,
  okmsId,
  transportKeyID,
  jweCompact,
  types.JWK,
  "imported-aes-byok",
  "",
  []types.CryptographicUsages{types.Encrypt, types.Decrypt},
)
if err != nil {
  return err
}
importedKeyID := resp.Id

Vérifier la clé importée

Confirmez que la clé existe et correspond au type et aux opérations attendus.

curl -X GET "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<imported-key-id>" \
  -H "Authorization: Bearer <token>"

okms keys get <imported-key-id>

key, err := okmsClient.GetServiceKey(ctx, okmsId, importedKeyID, nil)
if err != nil {
  return err
}

Vérifiez que :

• l'état (state) de la clé est active (ou activez-la si votre workflow l'exige).
• type, size et operations correspondent à ce que vous attendez.
• les attributs de sensibilité sous attributes reflètent une clé importée (never_extractable vaut false).

Vous pouvez ensuite utiliser la clé pour encrypt, decrypt, sign ou verify, comme documenté dans le guide « Utiliser votre OVHcloud Key Management Service (KMS) ».

Exporter une clé encapsulée

L'export sécurisé est l'inverse de l'import : OVHcloud KMS chiffre le matériel de clé avec une clé de transport RSA et ne renvoie qu'un ciphertext JWE. La clé de transport privée doit résider dans l'environnement de destination — ici le système externe qui reçoit la clé, et non OVHcloud KMS — afin que seul cet environnement puisse désencapsuler le matériel.

Comprendre la cérémonie d'export

1. Générez une paire de clés RSA de transport sur l'environnement de destination (un autre KMS ou un outil qui recevra la clé).
2. Importez la clé de transport publique de destination dans OVHcloud KMS avec l'opération wrapKey (niveau de protection SOFTWARE). Cette clé est le wrappingKeyId utilisé au moment de l'export.
3. Sur OVHcloud KMS, définissez extractable à true sur la clé de service juste avant l'export, puis exportez-la encapsulée par cette clé de transport. Remettez ensuite extractable à false lorsque c'est possible.
4. Transférez le ciphertext vers la destination et désencapsulez-le avec la clé de transport privée de destination.

La clé de transport référencée par wrappingKeyId doit être une clé RSA SOFTWARE dans le même domaine OKMS, avec l'usage wrapKey. Les clés sensibles (matériel AES/oct et RSA/EC privé) ne peuvent être extraites qu'après encapsulation — l'extraction en clair n'est pas prise en charge pour ces clés.

Importer la clé de transport publique de destination dans OVHcloud KMS

Enregistrez la clé publique de destination pour qu'OVHcloud KMS puisse encapsuler la clé exportée avec elle. Importez-la comme clé RSA uniquement publique avec wrapKey (sans matériel privé).

curl -X POST "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "byok-export-transport-pub",
    "type": "RSA",
    "operations": ["wrapKey"],
    "keys": [
      {
        "kty": "RSA",
        "n": "<base64url-modulus>",
        "e": "<base64url-exponent>",
        "key_ops": ["wrapKey"]
      }
    ]
  }'

okms keys import byok-export-transport-pub @destination-transport-public.pem \
  --usage wrapKey

pemBytes, err := os.ReadFile("destination-transport-public.pem")
if err != nil {
  return err
}
resp, err := okmsClient.ImportKeyPairPEM(
  ctx,
  okmsId,
  pemBytes,
  "byok-export-transport-pub",
  "",
  []types.CryptographicUsages{types.WrapKey},
)
if err != nil {
  return err
}
wrappingKeyID := resp.Id

Conservez l'id de la clé renvoyée comme wrappingKeyId.

Activer l'extraction

La clé que vous exportez doit être extractible. Préférez définir extractable à true uniquement pour l'opération d'export (via PATCH), puis le remettre à false ensuite. Gardez les clés non extractibles à la création autant que possible : rendre une clé extractible fixe définitivement never_extractable à false.

Action IAM : okms:apikms:serviceKey/update.

curl -X PATCH "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<key-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "extractable": true
  }'

okms keys update <key-id> --extractable=true

extractable := true
_, err := okmsClient.UpdateServiceKey(ctx, okmsId, keyID, types.PatchServiceKeyRequest{
  Extractable: &extractable,
})
if err != nil {
  return err
}

Après un export encapsulé réussi (voir la section « Exporter la clé encapsulée par la clé de transport »), désactivez à nouveau l'extraction :

curl -X PATCH "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<key-id>" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "extractable": false
  }'

okms keys update <key-id> --extractable=false

extractable := false
_, err := okmsClient.UpdateServiceKey(ctx, okmsId, keyID, types.PatchServiceKeyRequest{
  Extractable: &extractable,
})
if err != nil {
  return err
}

Exporter la clé encapsulée par la clé de transport

Appelez GET /api/{okmsId}/v1/servicekey/{keyId} avec les paramètres de requête d'encapsulation ci-dessous. Lorsque ces paramètres sont présents, l'API renvoie wrappedKeys au lieu de keys en clair.

Actions IAM : okms:apikms:serviceKey/get sur la clé exportée, et okms:apikms:serviceKey/wrapKey sur la clé de transport.

curl -X GET "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey/<key-id>?wrappingKeyId=<wrapping-key-id>&wrappedKeyFormat=JWK&wrappingAlgorithm=RSA-OAEP-256" \
  -H "Authorization: Bearer <token>"

{
  "id": "<key-id>",
  "name": "imported-aes-byok",
  "type": "oct",
  "class": "SECRET_KEY",
  "size": 256,
  "operations": ["encrypt", "decrypt"],
  "wrappedKeys": [
    {
      "keyFormatType": "JWK",
      "wrappingKeyId": "<wrapping-key-id>",
      "ciphertext": "<jwe-compact-serialization>"
    }
  ]
}

okms keys get <key-id> \
  --wrapping-key-id <wrapping-key-id> \
  --wrapped-key-format JWK \
  --wrapping-algorithm RSA-OAEP-256

wrapped, err := okmsClient.GetWrappedServiceKey(
  ctx,
  okmsId,
  keyID,
  wrappingKeyID,
  types.JWK,
  types.RSAOAEP256,
)
if err != nil {
  return err
}
ciphertext := wrapped[0].Ciphertext

Désencapsuler le ciphertext sur la destination

Transférez le ciphertext vers l'environnement de destination. Désencapsulez-le avec la clé de transport privée de destination (la contrepartie de la clé publique que vous avez importée dans OVHcloud KMS).

• Si la destination est un autre domaine OKMS, importez-y le matériel encapsulé avec wrappedKeys comme dans la section « Importer la clé encapsulée », en utilisant l'identifiant de la clé de transport de ce domaine comme wrappingKeyId.
• Si la destination est un système externe, utilisez son API native de désencapsulation ou d'import, avec la clé de transport privée, le même keyFormatType et le même algorithme d'encapsulation qu'à l'export.

Aller plus loin

Utiliser votre OVHcloud Key Management Service (KMS)

Méthodes d'authentification OKMS

Premiers pas avec OVHcloud Key Management Service (KMS)

Échangez avec notre communauté d'utilisateurs.