OVHcloud Key Management Service (KMS) verwenden

Verschlüsseln oder signieren Sie Ihre Daten mit der regionalen REST-API des OVHcloud Key Management Service (KMS)

Ziel

Ziel dieser Anleitung ist es, Ihnen die Schritte zur Interaktion mit dem OVHcloud KMS zu zeigen, um Ihre Daten zu verschlüsseln oder zu signieren.

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

In der praktischen Anwendung

Mit dem KMS kommunizieren

Die Kommunikation mit dem KMS für Verschlüsselungs- und Signaturvorgänge erfolgt über APIs.

Da das KMS regionalisiert ist, greifen Sie direkt in seiner Region auf die API zu: https://my-region.okms.ovh.net.

Zum Beispiel für ein KMS, das in der Region eu-west-rbx erstellt wurde: https://eu-west-rbx.okms.ovh.net.

Sie können mit dem KMS wie folgt kommunizieren:

Die Swagger-Benutzeroberfläche
Die OKMS CLI: https://github.com/ovh/okms-cli
Das Golang SDK: https://pkg.go.dev/github.com/ovh/okms-sdk-go

Authentifizieren Sie sich mit einem Personal Access Token, einem Service-Account oder einem Zugriffszertifikat. Für die Nutzung der REST-API werden ein PAT oder ein Service-Account empfohlen. Zugriffszertifikate sind für KMIP-Integrationen erforderlich.

Um API-Aufrufe interaktiv zu testen, verwenden Sie die OKMS Swagger UI unter https://<region>.okms.ovh.net/swagger/.

Einen Verschlüsselungsschlüssel über die API erstellen

Die Erstellung eines Schlüssels kann entweder über die oder über die spezifische OVHcloud KMS API erfolgen. Das Ergebnis unterscheidet sich je nach Erstellungsmethode nicht.

Info

Die folgenden Routen erwarten die Kennung Ihrer OKMS-Domain. Sie wird vom folgenden API-Aufruf zurückgegeben:

GET/okms/resource

Sie erscheint zusammen mit dem regionalen Endpoint auch im Tab Allgemeine Informationen im .

Im Fall der spezifischen OVHcloud KMS API erstellen Sie einen Schlüssel über die folgende API:

Methode	Pfad	Beschreibung
POST	/api/{okmsId}/v1/servicekey	Einen CMK erstellen oder importieren

Die API erwartet die folgenden Werte:

Feld	Wert	Beschreibung
name	string	Name des Schlüssels
context	string	Zusätzliche Identifikationsdaten zur Überprüfung der Authentizität des Schlüssels
type	oct, RSA, EC	Schlüsseltyp: Byte-Sequenz (oct) für symmetrische Schlüssel, RSA (RSA), Elliptic Curve (EC)
size	Integer	Schlüsselgröße – siehe Tabelle unten
operations	Array	Schlüsselverwendung – siehe Tabelle unten
curve	P-256, P-384, P-521	(optional) Kryptografische Kurve für Schlüssel vom Typ EC
extractable	boolean	(optional) Gibt an, ob das Schlüsselmaterial später exportiert werden kann – siehe Abschnitt Sensitivitätsattribute von Serviceschlüsseln weiter unten

Beispiel für die Erstellung eines symmetrischen Schlüssels:

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

Beispiel für die Erstellung eines asymmetrischen Schlüssels:

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

Beispiel für die Erstellung eines EC-Schlüssels:

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

Je nach Schlüsseltyp sind die möglichen Größen und Operationen die folgenden:

Oct:
- Größe: 128, 192, 256
- Operationen:
  - encrypt, decrypt
  - wrapKey, unwrapKey
RSA:
- Größe: 2048, 3072, 4096
- Operationen:
  - sign, verify
  - wrapKey, unwrapKey
EC:
- Größe: nicht angeben
- curve: P-256, P-384, P-521
- Operationen: sign, verify

Info

Bei RSA-Schlüsseln schließen sich wrapKey / unwrapKey und sign / verify gegenseitig aus.

Einen Verschlüsselungsschlüssel importieren

Beim Erstellen eines Schlüssels können Sie einen vorhandenen Schlüssel im Klartext als JWK importieren.

Warning

Der Import von Schlüsselmaterial im Klartext wird für Schlüssel, die vertrauenswürdig bleiben müssen, nicht empfohlen. Bevorzugen Sie sicheres BYOK mit asymmetrischer RSA-Umschließung.

Fügen Sie dazu ein zusätzliches Feld keys in den Body der Anfrage ein:

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

Der Schlüssel muss im Format JSON Web Key (JWK) vorliegen. Die Werte der in der Tabelle enthaltenen Felder folgen der Dokumentation der RFC 7518.

Verschlüsselungsschlüssel verwalten

Zur Verwaltung der Verschlüsselungsschlüssel stehen mehrere APIs zur Verfügung:

Methode	Pfad	Beschreibung
GET	/api/{okmsId}/v1/servicekey	Listet die verfügbaren Verschlüsselungsschlüssel auf
DELETE	/api/{okmsId}/v1/servicekey/{keyId}	Löscht einen Verschlüsselungsschlüssel
POST	/api/{okmsId}/v1/servicekey/{keyId}/activate	Aktiviert einen Verschlüsselungsschlüssel
POST	/api/{okmsId}/v1/servicekey/{keyId}/deactivate	Deaktiviert einen Verschlüsselungsschlüssel

Die Deaktivierung eines Verschlüsselungsschlüssels bedeutet, dass dieser nicht mehr verwendbar ist, obwohl der Schlüssel im KMS erhalten bleibt.

Das Löschen eines Verschlüsselungsschlüssels ist nur bei einem zuvor deaktivierten Schlüssel möglich.

Warning

Das Löschen eines Verschlüsselungsschlüssels ist endgültig. Alle damit verschlüsselten Daten werden dauerhaft unzugänglich.

Sensitivitätsattribute von Serviceschlüsseln

Wenn Sie einen Serviceschlüssel erstellen oder abrufen, werden die Flags für Sensitivität und Extrahierbarkeit im Objekt attributes der GET-Antwort zurückgegeben (neben anderen Metadaten wie state). Nur extractable ist vom Benutzer setzbar (bei der Erstellung oder per PATCH). Die anderen Flags werden vom KMS gesetzt. Das Setzen von extractable auf true setzt never_extractable dauerhaft auf false.

Attribut	Vom Benutzer setzbar?	Beschreibung
`extractable`	Ja (Erstellung / PATCH)	Wenn `true`, kann das Schlüsselmaterial exportiert werden (im Klartext oder umschlossen, je nach Schlüsselklasse). Standard: `false` — mit Ausnahme rein öffentlicher Schlüssel, die standardmäßig `true` sind.
`never_extractable`	Nein	`true`, wenn der Schlüssel seit seiner Erstellung im KMS nie extrahierbar war. Bei Schlüsseln, die mit BYOK importiert oder per Klartextimport übernommen wurden, ist `never_extractable` auf `false` gesetzt, weil das Material vor dem Import außerhalb des KMS existierte. Das Aktivieren der Extraktion löscht dieses Flag ebenfalls dauerhaft.
`sensitive`	Nein	`true`, wenn der Schlüssel nur nach Umschließung extrahiert werden kann (wozu auch `extractable` auf `true` gesetzt sein muss). Geheime und private Schlüssel (AES/`oct` sowie privates RSA/EC-Material) gelten stets als sensibel.
`always_sensitive`	Nein	`true`, wenn der Schlüssel seit seiner Erstellung stets sensibel war.

Beispiel einer GET-Antwort (Felder gekürzt):

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

Um einen Schlüssel sicher zu extrahieren, setzen Sie extractable nur für den Exportvorgang auf true, exportieren Sie ihn mit RSA-Umschließung und setzen Sie es anschließend wieder auf false. Siehe Einen umschlossenen Schlüssel exportieren.

Daten mit dem KMS verschlüsseln

Verschlüsselung über das KMS

Das OVHcloud KMS verfügt über eine dedizierte Verschlüsselungs-API für die Verschlüsselung kleiner Datenmengen (weniger als 4 kB).

Dies ist die einfachste Methode, sie bietet jedoch nicht die beste Performance.

Methode	Pfad	Beschreibung
POST	/api/{okmsId}/v1/servicekey/{keyId}/encrypt	Datenverschlüsselung mit einem CMK

Die API erwartet die folgenden Werte:

Feld	Wert	Beschreibung
plaintext	string	Zu verschlüsselnde Daten
context	string	Zusätzliche Identifikationsdaten zur Überprüfung der Authentizität der Daten

Beispiel für die Verschlüsselung

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

Die API gibt die verschlüsselten Daten anschließend in einem Feld ciphertext zurück:

{
  "ciphertext": "Encrypted data",
}

Die Entschlüsselung der Daten erfolgt umgekehrt über die API:

Methode	Pfad	Beschreibung
POST	/api/{okmsId}/v1/servicekey/{keyId}/decrypt	Datenentschlüsselung mit einem CMK

Die API erwartet die folgenden Werte:

Feld	Wert	Beschreibung
ciphertext	string	Zu entschlüsselnde Daten
context	string	Zusätzliche Identifikationsdaten zur Überprüfung der Authentizität der Daten

Das Feld context muss denselben Wert haben wie der bei der Verschlüsselung angegebene.

Verschlüsselung mit einem Data Key (DK)

Für eine bessere Performance können Sie einen Data Key (DK) aus einem symmetrischen Schlüssel (AES) generieren, um ihn in Ihrer Anwendung zu verwenden. Der verwendete AES-Schlüssel muss mit den Operationen wrapKey und unwrapKey generiert worden sein.

Sie können einen DK über die folgende API generieren:

Methode	Pfad	Beschreibung
POST	/api/{okmsId}/v1/servicekey/{keyId}/datakey	Generiert einen von einem CMK abgeleiteten DK

Die API erwartet die folgenden Werte:

Feld	Wert	Beschreibung
name	string	Name des Schlüssels
size	Integer	Schlüsselgröße (64-4096)

Beispiel für die Generierung eines Data Key:

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

Die API gibt anschließend den Data Key zurück:

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

key: verschlüsselter, in base64 codierter Schlüssel. Diese Information muss mit den verschlüsselten Daten gespeichert werden und wird vom KMS für die Entschlüsselung verwendet.
plaintext: Schlüssel im Klartext, in base64 codiert. Diese Information muss nach Abschluss der Verschlüsselung gelöscht werden und darf nicht gesichert werden.

Die Verwendung des Data Key erfolgt anschließend über Verschlüsselungsalgorithmen wie AES-GCM. Dies wird in dieser Dokumentation nicht behandelt.

Umgekehrt können Sie die entschlüsselte Version eines Data Key über die folgende API abrufen:

Methode	Pfad	Beschreibung
POST	/api/{okmsId}/v1/servicekey/{keyId}/datakey/decrypt	Entschlüsselung eines DK

Die API erwartet die folgenden Werte:

Feld	Wert	Beschreibung
key	string	Verschlüsselter Data Key

Und sie gibt den entschlüsselten Data Key in einem Feld plaintext zurück.

Mit dem KMS signieren

Die Signatur einer Datei erfolgt mit dem privaten Schlüssel eines asymmetrischen Schlüsselpaars.

Unterstützte Algorithmen

Das OVHcloud KMS unterstützt die folgende Liste von Signaturalgorithmen:

RSASSA-PKCS1 v1.5

Name	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

Gemäß der Dokumentation der RFC 7518.

ECDSA

Name	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

Gemäß der Dokumentation der RFC 7518.

RSASSA-PSS

Name	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

Gemäß der Dokumentation der RFC 7518.

Signatur einer Nachricht

Da der private Schlüssel nicht im Klartext aus dem KMS extrahiert werden kann, kann die Signatur nur direkt über das KMS erfolgen.

Methode	Pfad	Beschreibung
POST	/api/{okmsId}/v1/servicekey/{keyId}/sign	Signatur einer Datei

Die API erwartet die folgenden Werte:

Feld	Wert	Beschreibung
message	string	Zu signierende Nachricht im base64-Format
alg	string	Signaturalgorithmus
isdigest	boolean	Gibt an, ob die Nachricht bereits gehasht ist

Beispiel für eine Signatur:

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

Die API gibt anschließend die Signatur der Datei zurück:

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

Eine Datei überprüfen

Sie können eine Datei entweder direkt über das KMS oder mithilfe des öffentlichen Schlüssels überprüfen.

Über das KMS können Sie die folgende API verwenden:

Methode	Pfad	Beschreibung
POST	/api/{okmsId}/v1/servicekey/{keyId}/verify	Überprüfung einer Signatur

Die API erwartet die folgenden Werte:

Feld	Wert	Beschreibung
message	string	Zu signierende Nachricht
signature	string	Der Nachricht zugeordnete Signatur
alg	string	Signaturalgorithmus
isdigest	boolean	Gibt an, ob die Nachricht bereits gehasht ist

Beispiel für eine Überprüfung

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

Die API gibt anschließend das Ergebnis der Überprüfung zurück:

{
  "result": true
}

Weiterführende Informationen

Schlüssel auf OVHcloud KMS mit BYOK importieren und exportieren

OKMS-Authentifizierungsmethoden

Anleitung zum Verbinden eines kompatiblen Produkts über das KMIP-Protokoll

Treten Sie unserer User Community bei.

War diese Seite hilfreich?