Schlüssel auf OVHcloud KMS mit BYOK importieren und exportieren

Ziel

Bring Your Own Key (BYOK) ermöglicht Ihnen, kryptografisches Schlüsselmaterial mit dem OVHcloud Key Management Service (KMS) zu importieren und zu exportieren, ohne es im Klartext zu übertragen. Ein RSA-Transportschlüsselpaar schützt das Material während der Übertragung: Der öffentliche Schlüssel umschließt es, und nur der Inhaber des privaten Schlüssels kann die Umschließung wieder aufheben.

Diese Anleitung erklärt, wie Sie einen Schlüssel mit OVHcloud KMS mittels asymmetrischer RSA-Umschließung (BYOK) importieren und exportieren.

Voraussetzungen

• Sie verfügen über einen OVHcloud Kunden-Account.
• Sie haben ein OVHcloud KMS bestellt.
• Sie haben für die OKMS-Datenebene eine Authentifizierungsmethode konfiguriert (Personal Access Token, Service-Account oder Zugriffszertifikat).
• Sie können eine IAM-Richtlinie auf Ihre OKMS-Domain anwenden; die erforderlichen BYOK-Aktionen sind unter IAM für BYOK konfigurieren aufgeführt.
• Optional: Sie haben die OKMS CLI (Version 0.6.0 oder höher) oder das Go SDK für die Beispiele in den Tabs installiert.

In der praktischen Anwendung

Die Zeremonie der RSA-Umschließung verstehen

An der Zeremonie sind zwei Umgebungen und ein Operator beteiligt:

• Ziel (Dst): Ihre OKMS-Domain, in der der importierte Schlüssel gespeichert wird.
• Quelle (Src): das System, das derzeit das Schlüsselmaterial hält (ein anderes KMS, eine Anwendung oder ein Werkzeug wie OpenSSL).
• Operator: die Entität mit den Berechtigungen, sowohl auf die OKMS-Domain als auch auf die Quelle des zu importierenden Schlüssels zuzugreifen. Dies kann eine Person sein, die die OKMS CLI verwendet, oder ein Dienst, der über die API arbeitet.

1. Erzeugen Sie ein RSA-Transportschlüsselpaar auf dem OVHcloud KMS mit den Operationen wrapKey und unwrapKey.
2. Exportieren Sie den öffentlichen Transportschlüssel aus dem OVHcloud KMS.
3. Importieren Sie den öffentlichen Transportschlüssel in die Quellumgebung.
4. Exportieren Sie auf der Quelle das Schlüsselmaterial umschlossen (verschlüsselt) mit dem Transportschlüssel mittels RSA-OAEP oder RSA-OAEP-256.
5. Importieren Sie auf dem Ziel den umschlossenen Schlüssel mit POST /api/{okmsId}/v1/servicekey und einer wrappedKeys-Nutzlast. Das KMS hebt die Umschließung des Ciphertexts mit dem privaten Transportschlüssel auf und speichert den resultierenden Serviceschlüssel.

Bei so importierten Schlüsseln ist never_extractable auf false gesetzt, weil das Material vor dem Import außerhalb des KMS existierte. Um einen Schlüssel später in umschlossener Form zu extrahieren, importieren Sie ihn mit extractable auf true (dies kann nachträglich nicht aktiviert werden) und folgen Sie Einen umschlossenen Schlüssel exportieren. Die vollständige Attributliste finden Sie unter Sensitivitätsattribute von Serviceschlüsseln.

IAM für BYOK konfigurieren

Wenden Sie eine Richtlinie auf die Ressource Ihrer OKMS-Domain an. Deren URN wird im Tab Allgemeine Informationen im Dashboard Ihrer OKMS-Domain angezeigt. Ersetzen Sie <identity_urn> und <okms_urn> durch Ihre Werte. Erstellen Sie Richtlinien über das OVHcloud Kundencenter oder die OVHcloud API.

BYOK-Import — Serviceschlüssel lesen, erstellen oder importieren und mit einem Transportschlüssel die Umschließung aufheben:

{
  "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"
  ]
}

BYOK-Export — einen öffentlichen Transportschlüssel importieren, die Extrahierbarkeit aktualisieren und einen Schlüssel für den Export umschließen:

{
  "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"
  ]
}

Den RSA-Transportschlüssel auf dem Ziel-KMS erstellen

Erstellen Sie einen RSA-Schlüssel, der ausschließlich der Umschließung dient. Setzen Sie für die Import-Zeremonie auf diesem Schlüssel sowohl wrapKey als auch unwrapKey; sie schließen sich mit sign und verify gegenseitig aus.

Unterstützte RSA-Schlüsselgrößen: 2048, 3072 oder 4096 Bit.

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": 2048,
    "operations": ["wrapKey", "unwrapKey"]
  }'

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

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

Speichern Sie die zurückgegebene Schlüssel-id — Sie benötigen sie beim Import als wrappingKeyId.

Den öffentlichen Transportschlüssel abrufen

Exportieren Sie den öffentlichen Teil des Transportschlüssels und stellen Sie ihn der Quellumgebung zur Verfügung. Geben Sie den privaten Schlüssel niemals weiter — er verbleibt im Ziel-KMS.

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 ist ein crypto.PublicKey (*rsa.PublicKey für einen RSA-Transportschlüssel)

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

Das Quell-Schlüsselmaterial umschließen

Verschlüsseln Sie in der Quellumgebung das Schlüsselmaterial mit dem öffentlichen RSA-Zielschlüssel.

Dieser Schritt erfolgt außerhalb von OVHcloud KMS: Verwenden Sie in der Quellumgebung eine JOSE-Bibliothek.

Unterstützte Algorithmen für die Umschließung (RFC 7518):

keyFormatType beschreibt das Format des Klartext-Schlüsselmaterials vor der Umschließung und nach dem Aufheben der Umschließung. Der Ciphertext ist stets eine JWE Compact Serialization-Zeichenkette (der Algorithmus der Umschließung steht im JWE-Header).

Nach dem Umschließen mit dem öffentlichen Zielschlüssel senden Sie den entstandenen JWE-Compact-Serialization-ciphertext in der Importanfrage. Ein Go-Beispiel für diesen Umschließungsschritt finden Sie unter End-to-End-Beispiel in Go.

Den umschlossenen Schlüssel importieren

Rufen Sie POST /api/{okmsId}/v1/servicekey mit einem wrappedKeys-Array anstelle von Klartext-keys auf.

Jeder wrappedKeys-Eintrag:

Sie können einen öffentlichen Schlüssel allein importieren (class wird zu PUBLIC_KEY) oder einen privaten Schlüssel (das KMS rekonstruiert den öffentlichen Teil; class wird zu KEY_PAIR). Symmetrisches Material wird als SECRET_KEY gespeichert.

IAM-Aktionen bei diesem Aufruf: okms:apikms:serviceKey/create, okms:apikms:serviceKey/import und okms:apikms:serviceKey/unwrapKey auf dem Transportschlüssel.

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

Den importierten Schlüssel prüfen

Bestätigen Sie, dass der Schlüssel existiert und dem erwarteten Typ sowie den erwarteten Operationen entspricht.

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
}

Prüfen Sie Folgendes:

• der state des Schlüssels ist active (oder aktivieren Sie ihn, falls Ihr Workflow dies erfordert).
• type, size und operations entsprechen Ihren Absichten.
• die Sensitivitätsattribute unter attributes spiegeln einen importierten Schlüssel wider (never_extractable ist false).

Anschließend können Sie den Schlüssel für encrypt, decrypt, sign oder verify verwenden, wie in OVHcloud Key Management Service (KMS) verwenden beschrieben.

Einen umschlossenen Schlüssel exportieren

Der sichere Export ist die Umkehrung des Imports: OVHcloud KMS verschlüsselt das Schlüsselmaterial mit einem RSA-Transportschlüssel und liefert nur einen JWE-Ciphertext zurück. Der private Transportschlüssel muss in der Ziel-Umgebung liegen — hier das externe System, das den Schlüssel empfängt, nicht OVHcloud KMS —, damit nur diese Umgebung die Umschließung des Materials aufheben kann.

Die Export-Zeremonie verstehen

1. Erzeugen Sie ein RSA-Transportschlüsselpaar in der Ziel-Umgebung (ein anderes KMS oder ein Werkzeug, das den Schlüssel empfängt).
2. Importieren Sie den öffentlichen Ziel-Transportschlüssel in OVHcloud KMS mit der Operation wrapKey. Dieser Schlüssel ist die beim Export verwendete wrappingKeyId.
3. Exportieren Sie auf OVHcloud KMS den Serviceschlüssel umschlossen durch diesen Transportschlüssel. Der Schlüssel muss mit extractable auf true erstellt oder importiert worden sein. Setzen Sie extractable danach nach Möglichkeit auf false.
4. Übertragen Sie den Ciphertext an das Ziel und heben Sie seine Umschließung mit dem privaten Ziel-Transportschlüssel auf.

Der über wrappingKeyId referenzierte Transportschlüssel muss ein RSA-Schlüssel in derselben OKMS-Domain mit der Verwendung wrapKey sein. Informationen zum Export eines im HSM gespeicherten Schlüssels finden Sie unter BYOK mit HSM-Schlüsseln verwenden. Sensible Schlüssel (AES/oct sowie privates RSA/EC-Material) können nur nach der Umschließung extrahiert werden — die Extraktion im Klartext wird für diese Schlüssel nicht unterstützt.

Den öffentlichen Ziel-Transportschlüssel in OVHcloud KMS importieren

Registrieren Sie den öffentlichen Zielschlüssel, damit OVHcloud KMS den exportierten Schlüssel damit umschließen kann. Importieren Sie ihn als rein öffentlichen RSA-Schlüssel mit wrapKey (ohne privates Material).

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

destKey, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
  return err
}
resp, err := okmsClient.ImportKey(
  ctx,
  okmsId,
  &destKey.PublicKey,
  "byok-export-transport-pub",
  "",
  []types.CryptographicUsages{types.WrapKey},
)
if err != nil {
  return err
}
wrappingKeyID := resp.Id

Speichern Sie die zurückgegebene Schlüssel-id als wrappingKeyId.

Extraktion aktivieren

Der zu exportierende Schlüssel muss extrahierbar sein, und dies wird bei der Erstellung oder beim Import des Schlüssels festgelegt. Danach kann extractable nur noch von true auf false geändert werden: Einmal auf false gesetzt, kann es nie wieder auf true gesetzt werden. Ein Schlüssel, der ohne extractable auf true erstellt oder importiert wurde, kann daher nie exportiert werden. Diese Regel gilt für SOFTWARE- und HSM-Schlüssel gleichermaßen.

Setzen Sie extractable bei der Erstellung des Schlüssels auf true:

curl -X POST "https://<region>.okms.ovh.net/api/<okmsId>/v1/servicekey" \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "aes-to-migrate",
    "type": "oct",
    "size": 256,
    "operations": ["encrypt", "decrypt"],
    "extractable": true
  }'

okms keys generate aes-to-migrate \
  --type oct \
  --size 256 \
  --usage encrypt,decrypt \
  --extractable

resp, err := okmsClient.GenerateSymmetricKey(
  ctx,
  okmsId,
  types.N256,
  "aes-to-migrate",
  types.SOFTWARE,
  "",
  []types.CryptographicUsages{types.Encrypt, types.Decrypt},
  okms.WithExtractable(true),
)
if err != nil {
  return err
}
keyID := resp.Id

Setzen Sie bei einem Import "extractable": true im Anfragetext (REST-API), fügen Sie --extractable hinzu (OKMS CLI) oder übergeben Sie okms.WithExtractable(true) (Go SDK).

Sobald der Schlüssel nicht mehr exportiert werden muss, zum Beispiel nach einem erfolgreichen umschlossenen Export (siehe Den mit dem Transportschlüssel umschlossenen Schlüssel exportieren), deaktivieren Sie die Extraktion. Dies kann nicht rückgängig gemacht werden. IAM-Aktion: 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": 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
}

Den mit dem Transportschlüssel umschlossenen Schlüssel exportieren

Rufen Sie GET /api/{okmsId}/v1/servicekey/{keyId} mit den unten stehenden Abfrageparametern für die Umschließung auf. Sind diese Parameter vorhanden, liefert die API wrappedKeys statt Klartext-keys.

IAM-Aktionen: okms:apikms:serviceKey/get auf dem exportierten Schlüssel und okms:apikms:serviceKey/wrapKey auf dem Transportschlüssel.

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

Die Umschließung des Ciphertexts am Ziel aufheben

Übertragen Sie den ciphertext in die Zielumgebung. Heben Sie seine Umschließung mit dem privaten Ziel-Transportschlüssel auf (dem Gegenstück des öffentlichen Schlüssels, den Sie in OVHcloud KMS importiert haben).

• Ist das Ziel eine andere OKMS-Domain, importieren Sie das umschlossene Material dort mit wrappedKeys wie unter Den umschlossenen Schlüssel importieren, und verwenden Sie die ID des Transportschlüssels dieser Domain als wrappingKeyId.
• Ist das Ziel ein externes System, nutzen Sie dessen native API zum Aufheben der Umschließung bzw. zum Import mit dem privaten Transportschlüssel, demselben keyFormatType und demselben Algorithmus für die Umschließung wie beim Export.

BYOK mit HSM-Schlüsseln verwenden

Mit der Schutzstufe HSM wird das Schlüsselmaterial innerhalb des HSM umschlossen und ausgepackt: Es erscheint in OVHcloud KMS nie im Klartext. Das JWE-Format ist dasselbe wie für SOFTWARE-Schlüssel (RSA-OAEP oder RSA-OAEP-256 mit A256GCM).

Der Transportschlüssel muss im HSM gespeichert sein, sobald der importierte oder exportierte Schlüssel dort gespeichert ist, wie in der folgenden Tabelle zusammengefasst:

Die nachfolgend beschriebenen Importe in das HSM werden nur für die REST-API gezeigt.

Einen HSM-Transportschlüssel erstellen

Um einen Schlüssel in das HSM zu importieren, erstellen Sie den Transportschlüssel mit der Schutzstufe HSM:

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-hsm",
    "type": "RSA",
    "size": 2048,
    "operations": ["wrapKey", "unwrapKey"],
    "protectionLevel": "HSM"
  }'

okms keys generate byok-transport-rsa-hsm \
  --type rsa \
  --size 2048 \
  --usage wrapKey,unwrapKey \
  --protectionLevel hsm

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

Exportieren Sie anschließend seinen öffentlichen Schlüssel und umschließen Sie das Schlüsselmaterial an der Quelle, wie unter Den öffentlichen Transportschlüssel abrufen und Das Quell-Schlüsselmaterial umschließen beschrieben.

Einen Schlüssel in das HSM importieren

Da das HSM das ausgepackte Material nie preisgibt, kann OVHcloud KMS den Schlüsseltyp nicht ableiten. Die Importanfrage unterscheidet sich von einem SOFTWARE-Import:

• Setzen Sie protectionLevel auf HSM. Der Transportschlüssel muss ebenfalls ein HSM-Schlüssel sein.
• Geben Sie type an: oct, RSA oder EC. Setzen Sie für RSA und EC weder size noch curve: Das HSM liest sie aus dem Schlüssel. Für oct ist size optional (128, 192 oder 256).
• Setzen Sie in wrappedKeys kein keyFormatType. Der im JWE umschlossene Klartext muss für einen oct-Schlüssel aus den Rohbytes des Schlüssels bestehen und für einen RSA- oder EC-Schlüssel aus dem privaten Schlüssel in PKCS#8 (DER).
• Unterstützte Schlüssel: AES mit 128, 192 oder 256 Bit, RSA mit 2048, 3072 oder 4096 Bit, EC P-256, P-384 oder P-521. Ein öffentlicher Schlüssel allein kann nicht umschlossen in das HSM importiert werden; nur ein Klartext-Import ist möglich.

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-hsm",
    "type": "oct",
    "operations": ["encrypt", "decrypt"],
    "protectionLevel": "HSM",
    "wrappedKeys": [
      {
        "wrappingKeyId": "<hsm-transport-key-id>",
        "ciphertext": "<jwe-compact-serialization>"
      }
    ]
  }'

Ein HSM-Transportschlüssel kann auch die Umschließung eines SOFTWARE-Schlüssels aufheben: Folgen Sie in diesem Fall Den umschlossenen Schlüssel importieren mit keyFormatType.

Einen Schlüssel aus dem HSM exportieren

Nur symmetrische (oct) Schlüssel können aus dem HSM exportiert werden: Das HSM gibt private RSA- oder EC-Schlüssel nie heraus. Wie bei einem SOFTWARE-Schlüssel muss der Schlüssel mit extractable auf true erstellt oder importiert worden sein, was nachträglich nicht aktiviert werden kann (siehe Extraktion aktivieren).

Der Transportschlüssel muss im HSM gespeichert sein. Importieren Sie den öffentlichen Ziel-Transportschlüssel mit der Schutzstufe HSM:

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-hsm",
    "type": "RSA",
    "operations": ["wrapKey"],
    "protectionLevel": "HSM",
    "keys": [
      {
        "kty": "RSA",
        "n": "<base64url-modulus>",
        "e": "<base64url-exponent>",
        "key_ops": ["wrapKey"]
      }
    ]
  }'

Exportieren Sie anschließend den Schlüssel und setzen Sie dabei wrappedKeyFormat auf RAW: Das HSM umschließt immer die Rohbytes des Schlüssels, daher ist die entschlüsselte JWE-Nutzlast der AES-Schlüssel selbst (32 Bytes für einen 256-Bit-Schlüssel).

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

okms keys export <hsm-key-id> \
  --wrapping-key-id <hsm-wrapping-key-id> \
  --wrapped-key-format RAW \
  --wrapping-algorithm RSA-OAEP-256

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

Entschlüsseln Sie am Ziel das JWE mit dem privaten Transportschlüssel, wie unter Die Umschließung des Ciphertexts am Ziel aufheben beschrieben.

End-to-End-Beispiel in Go

Die folgenden Beispiele führen beide Zeremonien mit einem RSA-Schlüsselpaar durch. Sie verwenden das Go SDK für die Aufrufe an OVHcloud KMS und go-jose für die JWE-Operationen außerhalb von OVHcloud KMS. Beide Beispiele kodieren das Schlüsselmaterial in PKCS#8 (DER), was dem keyFormatType-Wert PKCS8 entspricht.

Einen lokal erzeugten Schlüssel importieren

Das Programm erzeugt den Schlüssel mit der Go-Standardbibliothek, umschließt ihn lokal mit dem öffentlichen Transportschlüssel und importiert ihn anschließend. Der Schlüssel erreicht OVHcloud KMS nie im Klartext.

// 1. Erzeugen Sie den Transportschlüssel auf OVHcloud KMS und rufen Sie seinen öffentlichen Teil ab.
transportKey, err := okmsClient.GenerateRSAKeyPair(
  ctx,
  okmsId,
  types.N2048,
  "byok-transport-rsa",
  types.SOFTWARE,
  "",
  []types.CryptographicUsages{types.WrapKey, types.UnwrapKey},
)
if err != nil {
  return err
}
transportPub, err := okmsClient.ExportPublicKey(ctx, okmsId, transportKey.Id)
if err != nil {
  return err
}

// 2. Erzeugen Sie den zu importierenden Schlüssel und kodieren Sie ihn in PKCS#8 (DER).
srcKey, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
  return err
}
plaintext, err := x509.MarshalPKCS8PrivateKey(srcKey)
if err != nil {
  return err
}

// 3. Umschließen Sie das Schlüsselmaterial als JWE: Schlüsselumschließung mit RSA-OAEP-256, Inhaltsverschlüsselung mit A256GCM.
encrypter, err := jose.NewEncrypter(
  jose.A256GCM,
  jose.Recipient{Algorithm: jose.RSA_OAEP_256, Key: transportPub},
  nil,
)
if err != nil {
  return err
}
jwe, err := encrypter.Encrypt(plaintext)
if err != nil {
  return err
}
ciphertext, err := jwe.CompactSerialize()
if err != nil {
  return err
}

// 4. Importieren Sie den umschlossenen Schlüssel. Das KMS hebt die Umschließung auf und leitet Typ und Größe aus dem Material ab.
// Er wird als extrahierbar importiert, damit das nächste Beispiel ihn exportieren kann: Dies kann nachträglich nicht aktiviert werden.
imported, err := okmsClient.ImportWrappedServiceKey(
  ctx,
  okmsId,
  transportKey.Id,
  ciphertext,
  types.PKCS8,
  "imported-rsa-byok",
  "",
  []types.CryptographicUsages{types.Sign, types.Verify},
  okms.WithExtractable(true),
)
if err != nil {
  return err
}
keyID := imported.Id

Der Algorithmus für die JWE-Inhaltsverschlüsselung (enc) muss A256GCM sein.

Einen Schlüssel exportieren und das JWE entschlüsseln

Das Ziel (hier das lokale Programm) erzeugt das Transportschlüsselpaar, importiert nur dessen öffentlichen Teil in OVHcloud KMS und entschlüsselt anschließend das exportierte JWE mit dem privaten Teil.

// ID des zu exportierenden Serviceschlüssels, zum Beispiel des im vorherigen Beispiel importierten Schlüssels.
keyID := uuid.MustParse("<key-id>")

// 1. Erzeugen Sie das Transportschlüsselpaar am Ziel.
destKey, err := rsa.GenerateKey(rand.Reader, 2048)
if err != nil {
  return err
}

// 2. Importieren Sie nur seinen öffentlichen Teil in OVHcloud KMS, mit der Verwendung wrapKey.
wrappingKey, err := okmsClient.ImportKey(
  ctx,
  okmsId,
  &destKey.PublicKey,
  "byok-export-transport-pub",
  "",
  []types.CryptographicUsages{types.WrapKey},
)
if err != nil {
  return err
}

// 3. Exportieren Sie den Schlüssel umschlossen durch den öffentlichen Zielschlüssel. Der Schlüssel muss als
// extrahierbar erstellt oder importiert worden sein. Nach dem Export wird die Extraktion endgültig deaktiviert.
defer func() {
  extractable := false
  _, _ = okmsClient.UpdateServiceKey(ctx, okmsId, keyID, types.PatchServiceKeyRequest{Extractable: &extractable})
}()
wrapped, err := okmsClient.GetWrappedServiceKey(
  ctx,
  okmsId,
  keyID,
  wrappingKey.Id,
  types.PKCS8,
  types.RSAOAEP256,
)
if err != nil {
  return err
}

// 4. Entschlüsseln Sie das JWE mit dem privaten Zielschlüssel und parsen Sie das PKCS#8-Material.
jwe, err := jose.ParseEncrypted(
  wrapped[0].Ciphertext,
  []jose.KeyAlgorithm{jose.RSA_OAEP_256},
  []jose.ContentEncryption{jose.A256GCM},
)
if err != nil {
  return err
}
plaintext, err := jwe.Decrypt(destKey)
if err != nil {
  return err
}

exportedKey, err := x509.ParsePKCS8PrivateKey(plaintext)
if err != nil {
  return err
}
// exportedKey enthält das exportierte Schlüsselmaterial, das im weiteren Programm verwendet wird.

Weiterführende Informationen

OVHcloud Key Management Service (KMS) verwenden

OKMS-Authentifizierungsmethoden

Erste Schritte mit OVHcloud Key Management Service (KMS)

Treten Sie unserer User Community bei.