API を使用した鍵のラッピング

Hyper Protect Crypto Services 内で管理するルート鍵を使用して、 指定されたデータ暗号化鍵 (DEK) を保護することができます。

ラッピングのためにルート鍵を提供する場合、ラップ呼び出しが成功できるように、ルート鍵が 128 ビット、192 ビット、または 256 ビットであることを確認してください。 サービスでルート鍵を作成する場合は、Hyper Protect Crypto Services が、HSM で 256 ビットの鍵 (AES-CBC アルゴリズムでサポートされるもの) を生成します。

サービス内でルート鍵を指定した後、以下のエンドポイントへの POST 呼び出しを行うことにより、拡張暗号化を使用して DEK をラップできます。

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

1. サービス内で鍵の処理を行うために、サービスおよび認証の資格情報を取得します。

2. 管理および保護する DEK の鍵の素材をコピーします。

   Hyper Protect Crypto Services サービス・インスタンスに対する「マネージャー」権限または「ライター」権限がある場合は、GET /v2/keys/<key_ID> 要求を行うと、特定のキーのキー素材をリトリーブできます。

3. ラッピングに使用するルート鍵の ID をコピーします。

4. 以下の cURL コマンドを実行し、ラップ操作を使用して鍵を保護します。

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

   次の表に従って、例の要求内の変数を置き換えてください。

   変数	説明
   region	必須。 Hyper Protect Crypto Services サービス・インスタンスを置く地理的領域を表す、地域の省略形 (us-south、au-syd など)。 詳細については、リージョナル・サービス・エンドポイントを参照してください。
   port	必須。 API エンドポイントのポート番号。
   key_ID	必須。 ラッピングに使用するルート鍵の固有 ID。
   IAM_token	必須。 IBM Cloud アクセス・トークン。 Bearer 値を含む、IAM トークンの全コンテンツを cURL 要求に組み込みます。 詳細については、アクセス・トークンのリトリーブを参照してください。
   instance_ID	必須。 Hyper Protect Crypto Services サービス・インスタンスに割り当てられた固有 ID。 詳細については、インスタンス ID のリトリーブを参照してください。
   key_ring_ID	オプション。 鍵が属する鍵リングの固有 ID。 指定しないと、Hyper Protect Crypto Services は、指定されたインスタンスに関連付けられているすべての鍵リングで鍵を検索します。 このため、鍵リング ID を指定して、より最適化された要求を行うことをお勧めします。 注: x-kms-key-ring ヘッダーを指定せずに作成した鍵の鍵リング ID は「default」になります。 詳しくは、鍵リングの管理を参照してください。
   correlation_ID	オプション。 トランザクションを追跡し、相互に関連付けるために使用される固有 ID。
   data_key	管理および保護する DEK の鍵の素材。 の plaintext 値はbase64エンコードされました。 新しいDEKを生成するには、plaintext 属性。 サービスはランダムなプレーンテキスト (32 バイト) を生成し、その値をラップして、生成された値とラップされた値の両方を応答で返します。 生成された値とラップされた値は base64 でエンコードされており、

           鍵を復号するためにはそれらをデコードする必要があります。 |
   

   ラップされたデータ暗号鍵 (base64 エンコードの鍵素材を含む) が、応答のエンティティー本体で返されます。 レスポンス本文には、提供されたプレーンテキストをラップするために使用されたキー バージョンの ID も含まれます。 以下の JSON オブジェクトは、返された値の例を示しています。

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

   ラップ要求を行う際に plaintext 属性を省略した場合、サービスは、生成されたデータ暗号鍵 (DEK) とラップされた DEK の両方を Base64 エンコード形式で返します。

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

   plaintext の値はアンラップされた DEK を表し、ciphertext の値は ラップされた DEK を表します。これらの値は両方とも base64 でエンコードされています。 keyVersion.id の値は、ラッピングに使用されたルート鍵のバージョンを表します。

   Hyper Protect Crypto Services がユーザーの代わりに新規データ暗号鍵 (DEK) を生成するようにする場合、ラップ要求で空の本体を渡すこともできます。 Base64 エンコードの鍵素材が含まれている生成された DEK が、ラップされた DEK とともに応答のエンティティー本体で返されます。