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 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, setzen Sie extractable auf true 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": 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

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.

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 (Schutzstufe SOFTWARE). Dieser Schlüssel ist die beim Export verwendete wrappingKeyId.
3. Setzen Sie auf OVHcloud KMS extractable unmittelbar vor dem Export auf dem Serviceschlüssel auf true, und exportieren Sie ihn anschließend umschlossen durch diesen Transportschlüssel. Setzen Sie extractable danach nach Möglichkeit wieder 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 SOFTWARE-RSA-Schlüssel in derselben OKMS-Domain mit der Verwendung wrapKey sein. 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

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

Extraktion aktivieren

Der zu exportierende Schlüssel muss extrahierbar sein. Setzen Sie extractable idealerweise nur für den Exportvorgang auf true (via PATCH) und danach wieder auf false. Lassen Sie Schlüssel bei der Erstellung nach Möglichkeit nicht extrahierbar: Wenn Sie einen Schlüssel extrahierbar machen, wird never_extractable dauerhaft auf false gesetzt.

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": 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
}

Deaktivieren Sie die Extraktion nach einem erfolgreichen umschlossenen Export (siehe Den mit dem Transportschlüssel umschlossenen Schlüssel exportieren) erneut:

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

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.

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.