Wrapping für Schlüssel mit der API durchführen

Sie können einen bestimmten Datenverschlüsselungsschlüssel (DEK) mit einem Rootschlüssel schützen, den Sie in Hyper Protect Crypto Services verwalten.

Wenn Sie einen Rootschlüssel für das Wrapping angeben, stellen Sie sicher, dass der Rootschlüssel 128, 192 oder 256 Bit lang ist, damit der Wrapping-Aufruf erfolgreich ist. Wenn Sie einen Rootschlüssel im Service erstellen, generiert Hyper Protect Crypto Services einen 256-Bit-Schlüssel aus den HSMs (unterstützt durch den AES-CBC-Algorithmus).

Nach der Angabe eines Rootschlüssels im Service können Sie einen DEK mit der erweiterten Verschlüsselung mithilfe eines POST-Aufrufs an den folgenden Endpunkt einschließen.

https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/<key_ID>/actions/wrap

1. Rufen Sie Ihre Service- und Authentifizierungsnachweise zur Arbeit mit den Schlüsseln im Service ab.

2. Kopieren Sie die Schlüsselinformationen, die Sie verwalten und schützen möchten.

   Wenn Sie über Manager- oder Writer-Berechtigungen für Ihre Hyper Protect Crypto Services-Serviceinstanz verfügen, können Sie das Schlüsselmaterial für einen bestimmten Schlüssel abrufen, indem Sie eine GET /v2/keys/<key_ID>-Anfrage stellen.

3. Kopieren Sie die ID des Rootschlüssels, den Sie für das Wrapping verwenden möchten.

4. Führen Sie den folgenden cURL-Befehl aus, um den Schlüssel mit einer Wrapping-Operation zu schützen.

   curl -X POST \
     'https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys/<key_ID>/actions/wrap' \
     -H 'accept: application/vnd.ibm.kms.key_action+json' \
     -H 'authorization: Bearer <IAM_token>' \
     -H 'bluemix-instance: <instance_ID>' \
     -H 'content-type: application/vnd.ibm.kms.key_action+json' \
     -H 'x-kms-key-ring: <key_ring_ID>' \
     -H 'correlation-id: <correlation_ID>' \
     -d '{
     "plaintext": "<data_key>"
   }'
   

   Ersetzen Sie die Variablen in der Beispielanforderung entsprechend der folgenden Tabelle.

   Tabelle 1. Beschreibt die Variablen, die zum Wrapping eines angegebenen Schlüssels erforderlich sind.

   Variabel	Beschreibung
   region	Erforderlich. Die Regionsabkürzung, z. B. us-south oder au-syd, die das geografische Gebiet darstellt, in dem sich Ihre Hyper Protect Crypto Services-Serviceinstanz befindet. Weitere Informationen finden Sie unter Regionale Serviceendpunkte.
   port	Erforderlich. Die Portnummer des API-Endpunkts.
   key_ID	Erforderlich. Die eindeutige ID für den Rootschlüssel, der für das Wrapping verwendet werden soll.
   IAM_token	Erforderlich. Ihr IBM Cloud-Zugriffstoken. Nehmen Sie den vollständigen Inhalt des IAM-Tokens einschließlich des Werts für Bearer in die cURL-Anforderung auf. Weitere Informationen finden Sie unter Zugriffstoken abrufen.
   instance_ID	Erforderlich. Die eindeutige ID, die Ihrer Hyper Protect Crypto Services-Serviceinstanz zugewiesen ist. Weitere Informationen finden Sie unter Instanz-ID abrufen.
   key_ring_ID	Optional. Die eindeutige ID des Schlüsselrings, zu dem der Schlüssel gehört. Wenn diese Option nicht angegeben wird, sucht Hyper Protect Crypto Services nach dem Schlüssel in jedem Schlüsselring, der der angegebenen Instanz zugeordnet ist. Daher wird empfohlen, die Schlüsselring-ID für eine optimierte Anforderung anzugeben. Hinweis: Die Schlüsselring-ID der Schlüssel, die ohne den Header x-kms-key-ring erstellt werden, lautet wie folgt: default. Weitere Informationen finden Sie im Abschnitt zum Verwalten von Schlüsselringen.
   correlation_ID	Optional. Die eindeutige ID, die zum Überwachen und Korrelieren von Transaktionen verwendet wird.
   data_key	Die Schlüsselinformationen des DEK, den Sie verwalten und schützen wollen. Der Wert plaintext muss base64 codiert sein. Um einen neuen DEK zu generieren, lassen Sie das Attribut plaintext weg. Der Service generiert einen zufälligen Klartext (32 Byte), bricht diesen Wert um und gibt dann sowohl die generierten als auch die eingeschlossenen Werte in der Antwort zurück. Der generierte Wert und der Wert mit dem Wrapping liegen in Base64-Codierung vor, sodass Sie sie decodieren müssen, um die Schlüssel zu entschlüsseln.

   Der Datenverschlüsselungsschlüssel nach dem Wrapping, der die mit Base64-Codierung verschlüsselte Schlüsselinformationen enthält, wird im Entitätshauptteil der Antwort zurückgegeben. Der Antworthauptteil enthält auch die ID der Schlüsselversion, die verwendet wurde, um den bereitgestellten Klartext einzuschließen. Das folgende JSON-Objekt zeigt ein Beispiel für einen zurückgegebenen Wert.

   {
     "ciphertext": "eyJjaXBoZXJ0ZXh0IjoiYmFzZTY0LWtleS1nb2VzLWhlcmUiLCJpdiI6IjRCSDlKREVmYU1RM3NHTGkiLCJ2ZXJzaW9uIjoiNC4wLjAiLCJoYW5kbGUiOiJ1dWlkLWdvZXMtaGVyZSJ9",
     "keyVersion": {
       "id": "02fd6835-6001-4482-a892-13bd2085f75d"
     }
   }
   

   Wenn bei der Wrapping-Anforderung das Attribut plaintext nicht angegeben wird, gibt der Service sowohl den generierten Datenverschlüsselungsschlüssel (DEK) als auch den DEK nach dem Wrapping im Format mit Base64-Codierung zurück.

   {
     "plaintext": "Rm91ciBzY29yZSBhbmQgc2V2ZW4geWVhcnMgYWdv",
     "ciphertext": "eyJjaXBoZXJ0ZXh0IjoiYmFzZTY0LWtleS1nb2VzLWhlcmUiLCJpdiI6IjRCSDlKREVmYU1RM3NHTGkiLCJ2ZXJzaW9uIjoiNC4wLjAiLCJoYW5kbGUiOiJ1dWlkLWdvZXMtaGVyZSJ9",
     "keyVersion": {
       "id": "12e8c9c2-a162-472d-b7d6-8b9a86b815a6"
     }
   }
   

   Der Wert für plaintext stellt den DEK ohne Wrapping dar und der Wert für ciphertext stellt den DEK mit dem Wrapping dar, und zwar beide Werte in Base64-Codierung. Der Wert für keyVersion.id stellt die Version des Rootschlüssels dar, der für das Wrapping verwendet wurde.

   Wenn Hyper Protect Crypto Services einen neuen Datenverschlüsselungsschlüssel (DEK) generieren soll, können Sie auch einen leeren Hauptteil in einer Wrapping-Anforderung übergeben. Der generierte DEK, der die mit Base64-Codierung verschlüsselten Schlüsselinformationen enthält, wird im Entitätshauptteil der Antwort zusammen mit dem DEK nach dem Wrapping zurückgegeben.