標準鍵のインポート

既存の暗号鍵は、UI を使用して追加することも、 Hyper Protect Crypto Services 鍵管理サービス API を使用してプログラマチックに追加することもできます。

UI を使用した標準鍵のインポート

サービスのインスタンスを作成した後、以下の手順を実行して、Hyper Protect Crypto Services GUI で既存の標準鍵を入力します。

UI にログインします。
「メニュー」>**「リソース・リスト」**に移動し、リソースのリストを表示します。
IBM Cloud リソース・リストで、Hyper Protect Crypto Services のプロビジョン済みインスタンスを選択します。
鍵をインポートするには、サイド・メニューの**「KMS 鍵 (KMS keys)」**タブを選択します。

**「鍵」テーブルで「鍵の追加」をクリックし、「鍵のインポート」**を選択します。

キーの詳細を以下のように指定します。

表 1. 標準鍵をインポートするための設定について説明します。
設定	説明
キー・タイプ	Hyper Protect Crypto Services で管理する鍵のタイプ。キー・タイプのリストから、「標準キー」を選択します。
キーの名前	鍵を簡単に識別するための、人間が理解できる固有の別名。プライバシーを保護するため、鍵の名前には、個人の名前や場所などの個人情報 (PII) を含めないように注意してください。
キー・エイリアス	(オプション) 鍵を認識しやすくするために鍵に割り当てる (人間が理解できる) 1 つ以上の固有の別名。別名の長さは 2 文字から 90 文字です。最大 5 つの別名を (コンマ区切りにして) 鍵に設定することができます。注: 各別名は、大/小文字の区別がある英数字でなければならず、スペースやダッシュ (-) や下線 (_) 以外の特殊文字を含めることはできません。別名は、バージョン 4 の UUID であってはならず、 Hyper Protect Crypto Services の予約名 ( `allowed_ip`、 `key`、 `keys`、 `metadata`、 `policy`、 `policies`、 `registration`、 `registrations`、 `ring`、 `rings`、 `rotate`、 `wrap`、 `unwrap`、 `rewrap`、 `version`、 `versions`) であってはなりません。
鍵リング ID	既存の鍵リングのリストから鍵リングを選択します。鍵リングを割り当てない場合は、`default` の鍵リングに鍵が追加されます。鍵リングについて詳しくは、鍵リングの管理を参照してください。
キー素材	サービスで管理する、Base64 エンコード鍵の素材 (対称鍵など)。詳細については、キー素材の Base64 エンコードを参照してください。鍵素材が以下の要件を満たしていることを確認してください。鍵は最大 7,500 バイトです。鍵は base64 エンコードでなければなりません。
有効期限の日付	(オプション) 鍵の有効期限が切れる日時を設定します。有効期限が切れると、鍵は「非アクティブ化」状態に移行します。鍵の状態について詳しくは、暗号鍵のライフサイクルのモニターを参照してください。
説明	(オプション) 鍵の詳しい説明を追加します。長さは 2 から 240 文字でなければなりません。

鍵の詳細の記入が完了したら、**「鍵のインポート (Import key)」**をクリックして確認します。

API を使用した標準鍵のインポート

以下のエンドポイントへの POST 呼び出しを行うことにより、標準鍵をインポートします。

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

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

以下の cURL コマンドを使用して、 Hyper Protect Crypto Services 鍵管理サービス API を呼び出します。

curl -X POST \
  https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'content-type: application/vnd.ibm.kms.key+json' \
  -H 'correlation-id: <correlation_ID>' \
  -H 'prefer: <return_preference>' \
  -d '{
 "metadata": {
   "collectionType": "application/vnd.ibm.kms.key+json",
   "collectionTotal": 1
 },
 "resources": [
   {
   "type": "application/vnd.ibm.kms.key+json",
   "name": "<key_alias>",
   "description": "<key_description>",
   "expirationDate": "<YYYY-MM-DDTHH:MM:SS.SSZ>",
   "payload": "<key_material>",
   "extractable": <key_type>
   }
 ]
}'

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

表 2. Hyper Protect Crypto Services 鍵管理サービス API を使用して標準鍵を追加するために必要な変数について説明します。
変数	説明
`region`	Hyper Protect Crypto Services サービス・インスタンスを置く地理的領域を表す、地域の省略形 (`us-south`、`au-syd` など)。詳細については、リージョナル・サービス・エンドポイントを参照してください。
`port`	必須。 API エンドポイントのポート番号。
`IAM_token`	IBM Cloud アクセス・トークン。 Bearer 値を含む、`IAM` トークンの全コンテンツを cURL 要求に組み込みます。詳細については、アクセス・トークンのリトリーブを参照してください。
`instance_ID`	Hyper Protect Crypto Services サービス・インスタンスに割り当てられた固有 ID。詳細については、インスタンス ID のリトリーブを参照してください。
`correlation_ID`	トランザクションを追跡し、相互に関連付けるために使用される固有 ID。
`return_preference`	オプション: `POST` および `DELETE` 操作のサーバー動作を変更するヘッダー。 `return_preference` 変数を `return=minimal` に設定すると、サービスは、キー名や ID 値などのキー・メタデータのみを応答のエンティティー本体に返します。変数を `return=representation` に設定すると、サービスは鍵の素材と鍵のメタデータの両方を返します。
`key_alias`	鍵を簡単に識別するための、人間が理解できる固有の名前。重要: プライバシーを保護するため、個人データを鍵のメタデータとして保管しないでください。
`key_description`	オプション: 鍵の詳しい説明。重要: プライバシーを保護するため、個人データを鍵のメタデータとして保管しないでください。
`YYYY-MM-DD` `HH:MM:SS.SS`	オプション: システム内の鍵の有効期限が切れる日時 (RFC 3339 形式)。 `expirationDate` 属性を省略すると、キーの有効期限は切れません。
`key_material`	サービスで管理する、Base64 エンコード鍵の素材 (対称鍵など)。詳しくは、鍵素材のBase64 エンコードを参照してください。鍵素材が以下の要件を満たしていることを確認します。 * 鍵は最大 7,500 バイトにすることができます。 * 鍵は base64 エンコードでなければなりません。
`key_type`	鍵の素材をサービスの外に出すことができるかどうかを決定するブール値。 `extractable` 属性を `true` に設定すると、サービスは、鍵を、アプリまたはサービスに保管できる標準鍵として指定します。

個人データの機密性を保護するため、サービスに鍵を追加するときに、個人の名前や場所などの個人情報 (PII) を入力しないようにしてください。 PII のその他の例については、 NIST Special Publication 800-122のセクション 2.2 を参照してください。

成功した POST /v2/keys 応答は、鍵の ID 値を他のメタデータと共に返します。この ID はキーに割り当てられた固有 ID であり、今後の Hyper Protect Crypto Services キー管理サービス API の呼び出しに使用されます。

オプション: 次の呼び出しを実行して Hyper Protect Crypto Services サービス・インスタンス内の鍵を取得し、鍵が追加されたことを確認します。

curl -X GET \
  https://<instance_ID>.api.<region>.hs-crypto.appdomain.cloud/api/v2/keys \
  -H 'accept: application/vnd.ibm.collection+json' \
  -H 'authorization: Bearer <IAM_token>' \
  -H 'bluemix-instance: <instance_ID>' \
  -H 'correlation-id: <correlation_ID>' \

CLI を使用した標準キーのインポート

Hyper Protect Crypto Servicesに統合されている Key Protect CLI を使用する標準鍵をインポートするには、以下の手順を実行します。

Key Protect CLI をセットアップします。
次のコマンドを使用して標準鍵をインポートします。
```
ibmcloud kp key create
```
このコマンドの他のパラメーターについては、Key Protect CLI リファレンスを参照してください。

鍵素材の Base64 でのエンコード

既存の標準鍵をインポートするときは、サービスで保管および管理する暗号化された鍵素材を含める必要があります。

OpenSSL を使用した既存の鍵素材のエンコード

OpenSSLをダウンロードしてインストールします。

次のコマンドを実行して、Base64 エンコードの鍵素材ストリングをデコードします。

$ openssl base64 -in <infile> -out <outfile>

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

表 3. base64 で鍵素材をエンコードするために必要な変数について説明します。
変数	説明
`infile`	鍵素材ストリングが存在するファイルの名前。
`outfile`	当コマンドが実行されたときに base64 でエンコードされた鍵素材が作成される場所となるファイルの名前。

base64 の素材をファイルではなくコマンド・ラインに直接出力する場合は、コマンド openssl enc -base64 <<< '<key_material_string>' を実行します。ここで、key_material_string は、インポートされたキーのキー素材入力を指します。

OpenSSL を使用した新しい鍵素材の作成とエンコード

OpenSSLをダウンロードしてインストールします。
次のコマンドを実行して、Base64 エンコードの鍵素材ストリングをデコードします。
```
$ openssl rand <byte_length> -base64
```
要求例の byte_length 変数を、キーの長さ (バイト単位で測定) に置き換えます。許容されるバイト数の最大長は 7,500 バイトです。

次の作業

プログラムでの鍵の管理について詳しくは、 Hyper Protect Crypto Services 鍵管理サービスの API リファレンス資料を確認してください。