使用根金鑰包裝資料加密金鑰

如果您是特許使用者，則可以使用 IBM Cloud® Hyper Protect Crypto Services 金鑰管理服務 API，以根金鑰A symmetric wrapping key that is used for encrypting and decrypting other keys that are stored in a data service. 來管理及保護加密金鑰。

當您使用根金鑰包裝資料加密金鑰(DEK)A cryptographic key used to encrypt data that is stored in an application. 時，Hyper Protect Crypto Services 會結合多個演算法的強度，以保護已加密資料的隱私權和完整性。

若要瞭解金鑰包裝如何協助您控制雲端中靜置資料的安全，請參閱封套加密。

使用 API 包裝金鑰

您可以使用您在 Hyper Protect Crypto Services 中管理的根金鑰來保護指定的資料加密金鑰 (DEK)。

當您提供用於包裝的根金鑰時，請確定根金鑰是 128、192 或 256 位元，wrap 呼叫才能成功。如果您在服務中建立根金鑰，Hyper Protect Crypto Services 會從 AES-CBC 演算法支援的 HSM 產生 256 位元金鑰。

在服務中指定根金鑰之後，即可對下列端點發出 POST 呼叫，以使用進階加密來包裝 DEK。

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

擷取服務及鑑別認證以使用服務中的金鑰。
複製您要管理及保護之 DEK 的金鑰資料。

如果您具有 Hyper Protect Crypto Services 服務實例的管理員或撰寫者專用權，您可以提出 GET /v2/keys/<key_ID> 要求來擷取特定金鑰的金鑰資料。
複製您要用於包裝之根金鑰的 ID。

執行下列 cURL 指令，以使用 wrap 作業來保護金鑰。

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

根據下表取代範例要求中的變數。

表 1. 說明包裝指定金鑰所需的變數
變數	說明
`region`	必要。代表 Hyper Protect Crypto Services 服務實例所在地理區域的地區縮寫，例如 `us-south` 或 `au-syd`。如需相關資訊，請參閱地區服務端點。
`port`	必要。 API 端點的埠號。
`key_ID`	必要。您要用於包裝之根金鑰的唯一 ID。
`IAM_token`	必要。您的 IBM Cloud 存取記號。請在 cURL 要求中包含 `IAM` 記號的完整內容，包括 Bearer 值。如需相關資訊，請參閱擷取存取記號。
`instance_ID`	必要。指派給您 Hyper Protect Crypto Services 服務實例的唯一 ID。如需相關資訊，請參閱擷取實例 ID。
`key_ring_ID`	選用。金鑰所屬金鑰環的唯一 ID。如果未指定，Hyper Protect Crypto Services 將在與指定實例相關聯的每個金鑰環中搜尋金鑰。因此，建議為更最佳化的要求指定金鑰環 ID。附註: 在沒有 `x-kms-key-ring` 標頭的情況下建立之金鑰的金鑰環 ID 為: 預設值。如需相關資訊，請參閱管理金鑰環。
`correlation_ID`	選用。用來追蹤及關聯交易的唯一 ID。
`data_key`	您要管理及保護之 DEK 的金鑰資料。 `plaintext` 值必須以 base64 編碼。若要產生新的 DEK，請省略 `plaintext` 屬性。服務會產生隨機純文字 (32 個位元組)，將該值折行，然後在回應中同時傳回產生及折行的值。產生的值和包裝的值會以 base64 編碼，您必須將它們解碼，才能將金鑰解密。

已包裝資料加密金鑰（包含以 base64 編碼的金鑰資料）會在回應實體內文中傳回。回應內文也包含用來包裝所提供之純文字的金鑰版本 ID。下列 JSON 物件顯示回覆值範例。

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

如果您在提出 wrap 要求時省略 plaintext 屬性，則服務會以 base64 編碼格式傳回產生的資料加密金鑰 (DEK) 和已包裝 DEK。

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

plaintext 值代表未包裝的 DEK，ciphertext 值代表已包裝的 DEK，且兩者都是 base64 編碼。 keyVersion.id 值代表用於包裝的根金鑰版本。

如果您想要 Hyper Protect Crypto Services 代表您產生新的資料加密金鑰 (DEK)，您也可以在 wrap 要求傳入空的內文。所產生的 DEK（包含以 base64 編碼的金鑰資料）會在回應實體內文中傳回，並且隨附已包裝的 DEK。