インスタンス、認証情報、マスターキーを作成し、専用 Key Protect を初期化する

Dedicated Key Protect を機能させるには、まずインスタンスをプロビジョニングし、次に暗号ユニットを操作するために使用する管理者認証情報を生成し、 Key Protect がお客様に代わって暗号ユニットに対して暗号処理を実行することを許可するマスターキーを作成およびロードする必要があります。

専用 Key Protect サービスの主要コンセプトの詳細については、スタンダードと専用 Key Protect についてをご覧ください。

このトピックでは、Mac/ Linux 用、Windows Powershell 用、Windows コマンドプロンプト（CMD）用の3種類のコマンドを紹介します。お使いのシステムに対応するコマンドを使用していることを確認してください。

開始前に

IBM Cloud CLIの最新バージョンがない場合、インスタンスを初期化できないことがあります。 CLIプラグインを最新バージョンにアップデートして、初期化を確実に成功させましょう。

コンソールを使用してインスタンスをデプロイする場合でも、CLIの最新バージョンを使用して初期化を完了する必要があります。 KP CLIプラグインの最新バージョンのインストール中に - Unable to obtain plug-in's metadata エラーが発生した場合は、トラブルシューティング手順を参照してください。

コンソールでインスタンスをプロビジョニングする

コンソールでインスタンスをプロビジョニングするには、こちらの手順に従って、カタログの「Dedicated」タイルを選択します。プロビジョニング処理には数分かかる。

インスタンスのプロビジョニングが完了したら、管理者認証情報を生成し、暗号ユニットを請求する準備が整います。

crypto unitの数を指定しない場合、インスタンスは2つでプロビジョニングされる。ドロップダウンを使用して、3つの暗号化ユニットを指定することもできる。 2つまたは3つの暗号化ユニットを指定する場合でも、値は後で変更できないことに注意。

CLIでインスタンスをプロビジョニングする

cryptoユニットを作成し、インスタンスを初期化する前に、インスタンスを作成する必要がある。まず、対象とするリソースグループを設定する：

ibmcloud target -c <resource-group>

自分のリソース・グループがわからない場合は、発行すればわかる：

ibmcloud resource groups

リソースグループを設定したら、次のコマンドを実行してインスタンスを作成する：

ibmcloud resource service-instance-create <INSTANCE_NAME> kms dedicated us-south

ここで、

<INSTANCE_NAME> はインスタンスにつける名前だ。

このコマンドのデフォルトは2つの暗号化ユニットであることに注意。を発行することで、3つの暗号ユニットを指定できる：

ibmcloud resource service-instance-create <INSTANCE_NAME> kms dedicated us-south -p '{"crypto_units": 3}'

2 、 3 以外の cryptoユニット数を指定すると、エラーが返される。暗号化ユニットの数を後で変更することはできない。

Dedicatedインスタンスのプロビジョニングには数分かかります。を発行することで、インスタンスのステータスをチェックすることができる：

ibmcloud resource service-instance <INSTANCE_NAME>

ここで、

<INSTANCE_NAME> は前のステップでインスタンスにつけた名前です。

インスタンスは2つの状態、 アクティブまたは進行中のいずれかを持つことができる。 アクティブなインスタンスはまだ初期化されていないことに注意してください。インスタンスを初期化するまでは、IDがマスターキーを作成する暗号ユニットにまだ構成されていないため、使用できない。

エンドポイントの取得

インスタンスがアクティブになったら、エンドポイントとGUIDを取得する：

ibmcloud resource service-instance <INSTANCE_NAME> -o json

ここで、

<INSTANCE_NAME> は前のステップでインスタンスにつけた名前です。

エンドポイントは、上記のjson出力の endpoints スタンザにある public パラメータ値である。 https://<instance-id>.api.<region>.kms.appdomain.cloud. GUIDは、上記の出力における GUID パラメータ値である。 UUID.

ibmcloud resource service-instance <\kp-instance-id\> --output json | jq -r '.[].extensions.endpoints'.

サポートされている3つのオペレーティングシステムのうち1つで、2つのコマンドを実行して、完全なエンドポイントを環境変数として保存する。

に対して macOS:

export KP_TARGET_ADDR=<ST_INSTANCE_ENDPOINT>

そして

export KP_INSTANCE_ID=<GUID>

Windows Powershellの場合：

$Env:KP_INSTANCE_ID = <GUID>

そして

$Env:KP_TARGET_ADDR = <ST_INSTANCE_ENDPOINT>

[Windows の]場合{: tag-windows} CMD：

set KP_INSTANCE_ID=<GUID>

そして

set KP_TARGET_ADDR=<ST_INSTANCE_ENDPOINT>

ここで、

<ST_INSTANCE_ENDPOINT> はインスタンスの完全なエンドポイントで、 https://<instance-id>.api.<region>.kms.appdomain.cloud.
<GUID> は上記の出力にあるインスタンスIDである。

これで管理者認証情報を生成する準備ができました。

プロビジョニング後、暗号ユニットが使用可能になるまで数分間待つ必要がある場合があります。

クリプト・ユニットの状態の詳細については、クリプト・ユニットの状態を参照のこと。

管理者認証情報の生成と暗号ユニットの請求

暗号ユニットは管理者または管理者によって管理されるため、利用可能なIDを用意するか、IDを作成する必要がある。管理者IDが適切にフォーマットされていれば（ RSA-2048 を使用した対称256ビットAES鍵）、マスター鍵の作成までスキップできます。

管理者認証情報の生成

管理者クレデンシャルを作成する必要がある場合は、発行してください：

ibmcloud kp crypto-unit sig-key generate --file <ADMIN_KEY_FILE> --passphrase <PWD> --algo RSA-2048

ここで、

<ADMIN_KEY_FILE> は、ID が作成されるマシン上の場所です（たとえば、 admin-keyfile.key ）。
<PWD> はオプションのパスワードまたはパスフレーズで、静止時にファイルを暗号化するために使用される。パスフレーズを入力するプロンプトが表示される場合は、"-"を指定する。

このキーファイルのコピーを保存し、パスフレーズを覚えておく。これは、暗号化ユニットと対話するときのすべての認証コマンドに必要である。

ibmcloud kp crypto-unit コマンドがエラーコード e00bad05 を返した場合は、トラブルシューティングの手順を参照してください。

暗号ユニットの請求

クリプト・ユニットの状態の詳細については、クリプト・ユニットの状態を参照のこと。

ユーザーに割り当てられた暗号ユニットは、クリアされた状態で開始する。 1 つのサービス・インスタンスに属するすべての暗号装置は、同じ構成内容にする必要があります。インスタンスが配置されているリージョン内の 1 つのアベイラビリティー・ゾーンにアクセスできない場合に、運用暗号装置を交互に使用できるので、ロード・バランシングや高可用性に役立ちます。

単一のサービスインスタンス内のすべての暗号化ユニットにおけるマスターキーは、すべて同じに設定する必要があります。すべての暗号化ユニットに同じ管理者グループを追加する必要があり、すべての暗号化ユニットは同時に初期化されなければなりません。

現在のユーザー・アカウントに属するターゲット・リソース・グループに含まれるサービス・インスタンスと暗号装置を表示するには、次のコマンドを使用します。

ibmcloud kp crypto-units

以下の出力は、表示される内容の例です。出力テーブルの「ID」列は、KP CLIプラグインによって後で発行される管理コマンドの対象となる暗号資産単位を識別するものです。

*******************************************************  
Id                                     InstanceID                             State  
6e0aead3-9d44-4c92-a4c4-f7a1ab415420   c28a8939-3980-4697-a80c-50b1f8bbf160   reserved  
3bb363fc-b1f9-4237-b37b-2c9e07784e3c   c28a8939-3980-4697-a80c-50b1f8bbf160   reserved  
*******************************************************

RSA鍵ペアの公開鍵は、対象の暗号ユニットにインストールされる証明書に格納され、これにより暗号ユニットの管理者が定義されます。 cryptoユニットのデフォルト管理者としてアップロードするには、claimコマンドを使用する：

ibmcloud kp crypto-unit claim --credential <ADMIN_KEY_FILE>

ここで、

<ADMIN_KEY_FILE> はIDが保存されたファイルである。

すべての crypto-unit コマンドは、すべての cryptoユニットに適用される。事実上、互いにクローンである。

マスターキーの生成とインポート

マスターキーの認証情報をインポートしているため、 Key Protect、そのキーにアクセスしたりバックアップを取ったりすることはできません。マスターキーの記録は安全な場所に保管してください。

インスタンスと管理者IDを作成したので、これらを使用してマスター・キーを作成できます。マスター鍵 (HSM マスター鍵とも呼ばれます) とは、鍵ストレージ用のサービス・インスタンスを暗号化するために使用するものです。これは対称 256 ビット AES 鍵です。マスターキーを使用することで、クラウドHSMの所有権を取得し、キー管理キーストア内のルートキーや標準キーを含む、暗号化キーの階層全体を暗号化する「信頼のルート」を所有することになります。 1 つのサービス・インスタンスで設定できるマスター鍵は 1 つだけです。サービス・インスタンスのマスター鍵を削除すると、そのサービスで管理されている鍵で暗号化されたすべてのデータの暗号破棄作業を効率的に行うことができます。

Key Protect 専用版では、「鍵分割」という手法を採用しています。これは、暗号鍵を複数の部分に分割することで、セキュリティを強化するものです。最低でも 2 「キーシェア」を作成しなければならないが、ユースケースによってはそれ以上でもよい。

マスター・キーをローカルに生成するには、サポートされている3つのオペレーティング・システムのいずれかでコマンドを実行する。

に対して macOS:

ibmcloud kp crypto-unit master-key generate --keyshare-files '["<KEYSHARE_FILE_1>#<PASSWORD1>", "<KEYSHARE_FILE_2>#<PASSWORD2>"]' --keyshare-minimum 2 --algo AES-256 --key-name <KEY_NAME> --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PASSOWRD3>"}]'

Windows Powershellの場合：

ibmcloud kp crypto-unit master-key generate --keyshare-files '["""<KEYSHARE_FILE_1>#<PASSWORD1>""","""<KEYSHARE_FILE_2>#<PASSWORD2>"""]' --keyshare-minimum 2 --algo AES-256 --key-name <KEY_NAME> --auth '[{"""ADMIN""": """<ADMIN_KEY_FILE>#<PASSOWRD3>"""}]'

[Windows の]場合{: tag-windows} CMD：

ibmcloud kp crypto-unit master-key generate --keyshare-files"[\"<KEYSHARE_FILE_1>#<PASSWORD1>\", \"<KEYSHARE_FILE_2>#<PASSWORD2>\"]" --keyshare-minimum 2 --algo AES-256 --key-name <KEY_NAME> --auth "[{\"ADMIN\": \"<ADMIN_KEY_FILE>#<PASSOWRD3>\"}]"

ここで、

<KEYSHARE_FILE_1>#<PASSWORD1> は、作成されるファイルのパスフレーズとともに、鍵共有の1つの場所である。パスフレーズは必須で、6～255文字でなければならない。パスフレーズを入力するプロンプトを表示するには、 #<PASSWORD1> を省略する。
<KEYSHARE_FILE_2>#<PASSWORD2> は、作成されるファイルのパスフレーズとともに、別の鍵共有の場所である。パスフレーズは必須で、6～255文字でなければならない。パスフレーズを入力するプロンプトを表示するには、 #<PASSWORD2> を省略する。パスフレーズを入力するプロンプトを表示するには、 #<PASSWORD2> を省略する。
<KEY_NAME> はマスターキーの名前である。
<ADMIN_KEY_FILE>#<PASSOWRD3> は、管理者の場所と、先ほど生成したパスフレーズです（自分のIDを持参しない場合）。パスフレーズを入力するプロンプトを表示するには、 #<PASSWORD3> を省略する。

keyshare-minimum （デフォルトでは 2 に設定されているが、増やすことも可能）は、指定しなければならない最小のキーシェア数（位置別）を示していることに注意。

マスターキーをインスタンスのcryptoユニットにアップロードするには、サポートされている3つのオペレーティングシステムのいずれかでコマンドを実行する。

に対して macOS:

ibmcloud kp crypto-unit master-key import --keyshare-files '["<KEYSHARE_FILE_1>#<PASSWORD1>", "<KEYSHARE_FILE_2>#<PASSWORD2"]' --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PASSWORD3>"}]'

[ウィンドウズ]用{: tag-windows} PowerShell:

ibmcloud kp crypto-unit master-key import --keyshare-files '["""<KEYSHARE_FILE_1>#<PASSWORD1>""","""<KEYSHARE_FILE_2>#<PASSWORD2>"""]' --auth '[{"""ADMIN""": """<ADMIN_KEY_FILE>#<PASSWORD3>"""}]'

[Windows の]場合{: tag-windows} CMD：

ibmcloud kp crypto-unit master-key import --keyshare-files "[\"<KEYSHARE_FILE_1>#<PASSWORD1>\", \"<KEYSHARE_FILE_2>#<PASSWORD2\"]" --auth "[{\"ADMIN\": \"<ADMIN_KEY_FILE>#<PASSWORD3>\"}]"

ここで、

<KEYSHARE_FILE_1>#<PASSWORD1> は、作成されるファイルのパスフレーズとともに、鍵共有の1つの場所である。パスフレーズは必須で、6～255文字でなければならない。パスフレーズを入力するプロンプトを表示するには、 #<PASSWORD1> を省略する。
<KEYSHARE_FILE_2>#<PASSWORD2> は、別の鍵共有の場所と、作成されるファイルのパスフレーズである。パスフレーズは必須で、6～255文字でなければならない。パスフレーズを入力するプロンプトを表示するには、 #<PASSWORD2> を省略する。
<ADMIN_KEY_FILE>#<PASSWORD3> は、管理者の場所と、先ほど生成したパスフレーズです（自分のIDを持参しない場合）。パスフレーズを入力するプロンプトを表示するには、 #<PASSWORD3> を省略する。

マスター・キーが作成されたので、 Key Protect サービスが暗号化ユニットに対してアクションを実行できるようにする必要がある（たとえば、キーの作成など）。なお、 Key Protect に付与される権限のレベルは、管理者よりも低いことにご留意ください。サポートされている3つのオペレーティング・システムのいずれかを使用してコマンドを実行する。

に対して macOS:

ibmcloud kp crypto-unit user add --type kmsCryptoUser --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PASSWORD>"}]'

[ウィンドウズ]用{: tag-windows} PowerShell:

ibmcloud kp crypto-unit user add --type kmsCryptoUser --auth '[{"""ADMIN""": """<ADMIN_KEY_FILE>#<PASSWORD>"""}]'

[Windows の]場合{: tag-windows} CMD：

ibmcloud kp crypto-unit user add --type kmsCryptoUser --auth "[{\"ADMIN\": \"<ADMIN_KEY_FILE>#<PASSWORD>\"}]"

ここで、

<ADMIN_KEY_FILE>#<PASSWORD> は、管理キーファイルの場所と、先ほど生成したパスフレーズです（自分のIDを持参しない場合）。パスフレーズを入力するプロンプトを表示するには、 #<PASSWORD> を省略する。

このコマンドは、 --type admin を作成し、所有する管理者IDを指す --name と --file を追加することで、暗号ユニットに管理者を追加するためにも使用できる。 kmsCryptoUser を追加する際には、 --name や --file を追加しないこと。以下に例を示します。

ibmcloud kp crypto-unit user add --type admin --name <USERNAME> --credential "<USERNAME_KEY_FILE>" --auth '[{"ADMIN": "<ADMIN_KEY_FILE>#<PWD>"}]'

ここで、

<USERNAME> は、追加する管理者IDの名前です。
<USERNAME_KEY_FILE> は、新しいユーザーに関連付けるクレデンシャルのファイル・パスです。
<ADMIN_KEY_FILE>#<PWD> は、既存の管理者の場所と、先ほど生成したパスフレーズです（自分のIDを持参しない場合）。パスフレーズを入力するプロンプトを表示するには、 #<PWD> を省略する。

管理者として kmsCryptoUser を追加する際、 --name または --file を追加しないでください。

おめでとうございます。インスタンスは完全に初期化されました。

インスタンスが利用可能になるまで、最大で5～10分ほどかかる場合があります。

次のステップ

インスタンスが作成され、それを操作するために使用できる管理者IDがあり、マスターキーを作成し、インスタンス上でアクションを実行するための Key Protect ：

ルート鍵を作成します。 Destroyed を含め、どのような状態のルート鍵または標準鍵も最大500個まで持つことができる。
キーホルダーを作る。 1つのサービス・インスタンスにつき最大50個のキー・リングを持つことができる。
ローテーションの方針を決める。

インポートトークンは Key Protect Dedicated ではサポートされていません。

サポートされない機能

インポートトークンの作成
セキュア・インポート・キーをインポートトークンとする。
allowed_network policy.
インスタンスを us-south 以外の場所にデプロイする。
PKCS#11 キーストア
暗号ユニットのフェイルオーバー。

トラブルシューティング

`Unable to obtain plug-in's metadata` KP CLI プラグインのインストールまたはアップグレード中にエラーが発生しました

IBM Key Protect CLI プラグインをインストールする際に以下のエラーが発生した場合：

Installing binary...
FAILED
Unable to obtain plug-in's metadata. Error: exit status 1

Linux 環境

ディストリビューションのパッケージ・マネージャーから、 libstdc++ システム・ライブラリを GLIBCXX バージョン 3.4.26 以降でインストールまたは更新する。以下のインストール・コマンドの例を使用する：

Ubuntu/Debian: apt-get update && apt-get install libstdc++6
RHEL/Fedora/CentOS: yum install libstdc++
Alpine: apk add --no-cache gcompat libstdc++

それでもエラーが解消されない場合は、 Key Protect のサポートまでお問い合わせください。

Windows または macOS 環境

Key Protect サポートまでご連絡ください。

`command failed with error code: e00bad05` エラー

ibmcloud kp crypto-unit コマンドが以下のエラーを返した場合：

FAILED
command failed with error code: e00bad05

このエラーは、お使いのシステムが ibmcloud kp crypto-unit 機能に対応していないことを示している可能性があります。推奨システム要件は以下の通り：

Windows: AMD64 (Windows 10 以降)
Linux: AMD64 (Debian, Ubuntu, Red Hat)
macOS: ARM64 （アップルシリコン）

このリスト以外のシステムでも、 ibmcloud kp crypto-unit 機能と互換性がある場合があります。特定のシステムとの互換性を確認したい場合、または推奨されるシステム要件を満たしているにもかかわらず e00bad05 エラーが発生する場合は、 Key Protect サポートにお問い合わせください。

HTTP 503 `no healthy upstream` エラー

Key Protect 操作の呼び出しが、 no healthy upstream: no crypto units are in kms-initialized state at this time というメッセージとともに HTTP 503 を返す場合、以下の原因が考えられる：

あなたはまだ専用初期化ステップを完了していない。
専用の初期化手順は完了したが、 Key Protect が新しく kms-initialized 暗号ユニットを認識するまで、数分待つ必要がある。
kms-initialized 、そのクリプトユニットはメンテナンスのためダウンしている。
不一致のマスターキーマテリアルを1つまたは複数の暗号ユニットにアップロードした。

`context deadline exceeded` エラー

CLIコマンドがエラー context deadline exceeded (Client.Timeout exceeded while awaiting headers) を返す場合、プライベート・エンドポイントの要件を満たしていないシステムからプライベート・エンドポイントに KP_TARGET_ADDR。

このエラーを解決するには、以下のようにします。

エンドポイントを取得するステップからパブリック・エンドポイントを使用します。
プライベート・エンドポイントを使用する場合、プライベート・エンドポイントへの呼び出しについては、プライベート・エンドポイントを参照のこと。

暗号ユニットコマンドがすべての暗号ユニットに適用されない

crypto-unit claim、 crypto-unit master-key import、 crypto-unit user add --type kmsCryptoUser コマンドがすべての暗号化ユニットに適用できない場合、次の例のような出力が表示されることがある：

Executing operation Generate Master Key against CryptoUnit with ID fadedbee-0000-0000-0000-1234567890ab
OK
Executing operation Generate Master Key against CryptoUnit with ID addedace-0000-0000-0000-1234567890ab
FAILED

この問題を解決するには:

デフォルトでは、 claim、 master-key import、 user add の各コマンドは、すべての暗号化ユニットに適用しようとする。これらのコマンドが部分的にしか成功しない場合(インスタンス内のcryptoユニットのサブセットのみに適用される)、失敗を返したcryptoユニットに対してのみ、コマンドを再試行する。これらの各コマンドは、特定の暗号ユニットをターゲットに設定できる。特定のcryptoユニットをターゲットにする方法を確認するには、 crypto-unit コマンドに -h を追加してヘルプテキストを表示するか、 CLIリファレンスを参照する。
CLIリファレンスの kp crypto-units コマンドを実行し、すべての cryptoユニットが同じ状態であることを確認する。
- 暗号化ユニットの状態が不一致の場合は、「暗号化ユニットの状態」を参照。
- いずれかのcryptoユニットが maintenance 状態の場合、 kp crypto-unit コマンドを後で再試行する。

インスタンス、認証情報、マスターキーを作成し、専用 Key Protect を初期化する

インスタンス、認証情報、マスターキーを作成し、専用 Key Protect を初期化する

開始前に

コンソールでインスタンスをプロビジョニングする

CLIでインスタンスをプロビジョニングする

エンドポイントの取得

管理者認証情報の生成と暗号ユニットの請求

管理者認証情報の生成

暗号ユニットの請求

マスターキーの生成とインポート

次のステップ

サポートされない機能

トラブルシューティング

Unable to obtain plug-in's metadata KP CLI プラグインのインストールまたはアップグレード中にエラーが発生しました

Linux 環境

Windows または macOS 環境

command failed with error code: e00bad05 エラー

HTTP 503 no healthy upstream エラー

context deadline exceeded エラー

暗号ユニットコマンドがすべての暗号ユニットに適用されない

`Unable to obtain plug-in's metadata` KP CLI プラグインのインストールまたはアップグレード中にエラーが発生しました

`command failed with error code: e00bad05` エラー

HTTP 503 `no healthy upstream` エラー

`context deadline exceeded` エラー