鍵管理サービスのHyper Protect Crypto Services（以下HPCS）をオーダーして初期セットアップをするまでの記録です。
全体の流れは下記に従います。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started
インスタンス作成
カタログからHPCSを選択します。
暗号化ユニット数は、最小が2です。
オーダーすると数分でサービスのプロビジョニングが完了します。
HPCS初期化
HPCSのプロビジョニング直後は下記の状態になっており、初期化の操作が必要です。
初期化の流れは下記となります。
STEP2では3通りの方法が用意されています。今回は3つ目の「Initializing service instances using key part files」の方法で行います。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started#initialize-crypto
3つ目の方法の詳細はこちらです。順に実施していきます。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm
（準備）ibmcloud CLIを用意してログイン
作業環境を準備します。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm-prerequisite
今回の操作はTKE（Trusted Key Entry）のプラグインが必要なので入っていない場合、追加します。
$ ibmcloud plugin install tke
リポジトリー 'IBM Cloud' から 'tke' を検索しています...
プラグイン 'tke 1.3.0' がリポジトリー 'IBM Cloud' 内で見つかりました
バイナリー・ファイルをダウンロードしようとしています...
12.16 MiB / 12.16 MiB [=====================================================================] 100.00% 4s
12746640 バイトがダウンロードされました
バイナリーをインストールしています...
OK
プラグイン 'tke 1.3.0' は /Users/tama/.bluemix/plugins/tke に正常にインストールされました。 'ibmcloud plugin show tke' を使用して詳細を表示してください。
$
ログインし、ターゲットとなるリージョンやリソースグループを指定します。
$ ibmcloud login
$ ibmcloud target -r us-south
$ ibmcloud target -g Default
暗号化ユニットを表示
このステップに沿って操作を進めます。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm&locale=en#identify_crypto_units
まず、下記のコマンドで、存在する暗号化ユニットを表示します。
初期は、SELECTEDの列は全てfalseになっています。（後続の手順で選択し、操作対象とします。）
$ ibmcloud tke cryptounits
（略）
SERVICE INSTANCE: 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
CRYPTO UNIT NUM SELECTED TYPE LOCATION
5 false OPERATIONAL [us-south].[AZ3-CS9].[00].[26]
6 false OPERATIONAL [us-south].[AZ1-CS1].[00].[17]
7 false RECOVERY [us-south].[AZ2-CS2].[03].[13]
8 false RECOVERY [us-east].[AZ2-CS2].[01].[09]
（略）
暗号化ユニットを選択
次のコマンドで、これから操作対象とする暗号化ユニットを選択します。
基本的に、同じサービスインスタンス内の暗号化ユニットは同じ状態にしておく必要があるため、全て選びます。
In general, either all crypto units or none of the crypto units in a service instance are selected.
他にもう1つHPCSがある環境で試したので1,2,3,4はそちらで使われており、この後の例では、暗号化ユニットの番号が5,6,7,8になっています。
RECOVERY UNITがあるのはDallas(us-south)とWashington DC(us-east)のみとDocsに書かれているので、東京リージョンのHPCSで表示される暗号化ユニットはTYPE=OPERATIONALの2つである可能性があります。
$ ibmcloud tke cryptounit-add
（略）
SERVICE INSTANCE: 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
CRYPTO UNIT NUM SELECTED TYPE LOCATION
5 false OPERATIONAL [us-south].[AZ3-CS9].[00].[26]
6 false OPERATIONAL [us-south].[AZ1-CS1].[00].[17]
7 false RECOVERY [us-south].[AZ2-CS2].[03].[13]
8 false RECOVERY [us-east].[AZ2-CS2].[01].[09]
Note: all operational crypto units in a service instance must be configured the same.
Use 'ibmcloud tke cryptounit-compare' to check how crypto units are configured.
Enter a list of CRYPTO UNIT NUM to add, separated by spaces:
> 5 6 7 8
OK
（略）
SERVICE INSTANCE: 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
CRYPTO UNIT NUM SELECTED TYPE LOCATION
5 true OPERATIONAL [us-south].[AZ3-CS9].[00].[26]
6 true OPERATIONAL [us-south].[AZ1-CS1].[00].[17]
7 true RECOVERY [us-south].[AZ2-CS2].[03].[13]
8 true RECOVERY [us-east].[AZ2-CS2].[01].[09]
Note: all operational crypto units in a service instance must be configured the same.
Use 'ibmcloud tke cryptounit-compare' to check how crypto units are configured.
$
自分のサービスインスタンスにある暗号化ユニットが全てSELECTED=trueになりました。
サービスインスタンス内の全ての暗号化ユニットの設定は一致している必要があります。
下記コマンドでSELECTED=trueになっている暗号化ユニットの設定内容を比較します。
$ ibmcloud tke cryptounit-compare
SIGNATURE THRESHOLDS
SERVICE INSTANCE: 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
CRYPTO UNIT NUM SIGNATURE THRESHOLD REVOCATION THRESHOLD
5 0 0
6 0 0
7* 0 0
8* 0 0
* Indicates a recovery crypto unit used only to hold a backup master key value.
==> Crypto units with a signature threshold of 0 are in IMPRINT MODE. <==
CRYPTO UNIT ADMINISTRATORS
SERVICE INSTANCE: 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
CRYPTO UNIT NUM ADMIN NAME SUBJECT KEY IDENTIFIER
5 No administrators
6 No administrators
7* No administrators
8* No administrators
* Indicates a recovery crypto unit used only to hold a backup master key value.
NEW MASTER KEY REGISTER
SERVICE INSTANCE: 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
CRYPTO UNIT NUM STATUS VERIFICATION PATTERN
5 Empty 00000000000000000000000000000000
00000000000000000000000000000000
6 Empty 00000000000000000000000000000000
00000000000000000000000000000000
7* Empty 00000000000000000000000000000000
00000000000000000000000000000000
8* Empty 00000000000000000000000000000000
00000000000000000000000000000000
CURRENT MASTER KEY REGISTER
SERVICE INSTANCE: 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
CRYPTO UNIT NUM STATUS VERIFICATION PATTERN
5 Empty 00000000000000000000000000000000
00000000000000000000000000000000
6 Empty 00000000000000000000000000000000
00000000000000000000000000000000
7* Empty 00000000000000000000000000000000
00000000000000000000000000000000
8* Empty 00000000000000000000000000000000
00000000000000000000000000000000
* Indicates a recovery crypto unit used only to hold a backup master key value.
CONTROL POINTS
SERVICE INSTANCE: 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
CRYPTO UNIT NUM XCP_CPB_ALG_EC_25519 XCP_CPB_BTC XCP_CPB_ECDSA_OTHER
5 Set Set Set
6 Set Set Set
7* Set Set Set
8* Set Set Set
* Indicates a recovery crypto unit used only to hold a backup master key value.
==> All crypto units are configured the same. <==
$
マスターキーのロード
下記の手順に沿ってマスターキーをロードを行います。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm&locale=en#load-master-keys
Step1 signature keyの作成
まずPC端末でsignature keyを作成します。これは、HPCSに対しコマンドを発行する際にsignature keyで署名することで、コマンド実行者が正当な権限を持っていることを保証するための鍵です。
$ ibmcloud tke sigkeys
No files containing a signature key were found.
To create a file containing a signature key, use the 'ibmcloud tke sigkey-add' command.
$ ibmcloud tke sigkey-add
Enter an administrator name to be associated with the signature key:
> tama
Enter a password to protect the signature key:
>
Re-enter the password to confirm:
>
OK
A signature key was created.
The available signature keys on this workstation are:
KEYNUM DESCRIPTION SUBJECT KEY IDENTIFIER
1 tama b93e8cbc8d92d613c7cd2acb037b52...
No KEYNUM are selected as current signature keys.
$
signature key作成直後は選択されていない状態なので、選択します。
$ ibmcloud tke sigkey-sel
KEYNUM DESCRIPTION SUBJECT KEY IDENTIFIER
1 tama b93e8cbc8d92d613c7cd2acb037b52...
No KEYNUM are selected as current signature keys.
Enter the KEYNUM values to select as current signature keys, separated by spaces:
> 1
Enter the password for KEYNUM 1:
>
OK
KEYNUM 1 has been made the current signature key.
$
これで、HPCSに対しコマンドを打つ時、作成したsignature keyが使われることになります。
HPCSの初期状態はコマンド実行時にsignature keyを必要としないimprint modeで動いています。このモードはセキュアで無いため、実行できるコマンドに制限があります。この後の手順でimprint modeを抜け、登録したsignature keyでサインしたコマンドのみ受け付ける状態にします。
Step2 暗号化ユニットにadministratorを追加
前手順で作成したsignature keyを登録します。このsignature keyを持っているユーザーがadministratorとみなされます。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm&locale=en#step2-load-admin
$ ibmcloud tke cryptounit-admins
No crypto unit administrators for service instance 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
$
$ ibmcloud tke cryptounit-admin-add
KEYNUM DESCRIPTION SUBJECT KEY IDENTIFIER
1 tama b93e8cbc8d92d613c7cd2acb037b52...
KEYNUM 1 is selected as the current signature key.
Enter the KEYNUM of the administrator signature key you wish to load:
> 1
Enter the password for the administrator signature key file:
>
OK
The crypto unit administrator was added to the selected crypto units.
$
Step3 閾値の設定
次に閾値を設定することで、「コマンドを実行するのに何人のadministratorが必要か？」を設定する事ができます。1〜8まで選べます。
ここで複数を選ぶと、コマンドによっては複数名のadministratorが合意することで初めて実行できる状態（Quorum authentication）にでき、重要なコマンドについては、仮に1人のadministratorが悪意を持っても単独では実行できないようにできます。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm&locale=en#step3-exit-imprint-mode
Quorum authenticationについて。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-understand-concepts#quorum-authenticaion-concept
今回は閾値に1を指定します。このコマンドにより、imprint modeを抜けた事になります。
$ ibmcloud tke cryptounit-thrhld-set
Enter the new signature threshold value:
> 1
Enter the new revocation signature threshold value:
> 1
Enter the password for the signature key identified by:
tama (b93e8cbc8d92d613c7cd2acb037b52...)
>
OK
New signature threshold values have been set in the selected crypto units.
SIGNATURE THRESHOLDS
SERVICE INSTANCE: 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
CRYPTO UNIT NUM SIGNATURE THRESHOLD REVOCATION THRESHOLD
5 1 1
6 1 1
7* 1 1
8* 1 1
* Indicates a recovery crypto unit used only to hold a backup master key value.
==> Crypto units with a signature threshold of 0 are in IMPRINT MODE. <==
$
imprint modeを抜けたことにより、主に更新系のコマンドは、signature keyファイルがローカルに無かったり、signature keyのパスワードを正しく入れないとコマンドを実行できなくなります。
Enter the password for the signature key identified by:
tama (b93e8cbc8d92d613c7cd2acb037b52...)
>
FAILED
Invalid password.
Step4 マスターキーパーツの作成
2つまたは3つのキーパーツを作ります。下記では2つ作成しています。
$ ibmcloud tke mk-add --random
Enter a description for the key part:
> masterkey01
Enter a password to protect the key part:
>
Re-enter the password to confirm:
>
OK
A key part was created.
The available EP11 master key parts on this workstation are:
KEYNUM DESCRIPTION VERIFICATION PATTERN
1 masterkey01 d2963553a8286d3b1a6ba7eb90b6f9be
501161a7dcf6dabc1ad9ef515f1f1575
$
$ ibmcloud tke mk-add --random
Enter a description for the key part:
> masterkey02
Enter a password to protect the key part:
>
Re-enter the password to confirm:
>
OK
A key part was created.
The available EP11 master key parts on this workstation are:
KEYNUM DESCRIPTION VERIFICATION PATTERN
1 masterkey01 d2963553a8286d3b1a6ba7eb90b6f9be
501161a7dcf6dabc1ad9ef515f1f1575
2 masterkey02 23a95d689179fbccb794f64d52b31e4e
56f04da4a88bfc190edeb3120ab8a7a3
$
Step5 master keyのアップロード
作成したmaster keyを暗号化ユニットにアップロードします。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm&locale=en#step5-load-master-key
アップロード直後はFull Uncommittedのステータスになっています。
この後のcommitやactivateのコマンドにより、master keyのステータスは下記のように遷移します。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-introduce-service#understand-key-ceremony
$ ibmcloud tke cryptounit-mk-load
KEYNUM DESCRIPTION VERIFICATION PATTERN
1 masterkey01 d2963553a8286d3b1a6ba7eb90b6f9be
501161a7dcf6dabc1ad9ef515f1f1575
2 masterkey02 23a95d689179fbccb794f64d52b31e4e
56f04da4a88bfc190edeb3120ab8a7a3
Enter the KEYNUM values of the master key parts you wish to load.
2 or 3 values must be specified, separated by spaces.
> 1 2
Enter the password for the signature key identified by:
tama (b93e8cbc8d92d613c7cd2acb037b52...)
>
Enter the password for key file 1
>
Enter the password for key file 2
>
OK
The new master key register has been loaded in the selected crypto units.
NEW MASTER KEY REGISTER
SERVICE INSTANCE: 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
CRYPTO UNIT NUM STATUS VERIFICATION PATTERN
5 Full Uncommitted 10ca6697582392616441b65de14b69d0
b59110f497b7531839204d6fd7e592a2
6 Full Uncommitted 10ca6697582392616441b65de14b69d0
b59110f497b7531839204d6fd7e592a2
7* Full Uncommitted 10ca6697582392616441b65de14b69d0
b59110f497b7531839204d6fd7e592a2
8* Full Uncommitted 10ca6697582392616441b65de14b69d0
b59110f497b7531839204d6fd7e592a2
* Indicates a recovery crypto unit used only to hold a backup master key value.
$
Step6 master keyのコミット
コミットします。ステータスがFull Committedになります。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm&locale=en#step6-commit-master-key
$ ibmcloud tke cryptounit-mk-commit
Enter the password for the signature key identified by:
tama (b93e8cbc8d92d613c7cd2acb037b52...)
>
OK
The new master key register has been committed in the selected crypto units.
NEW MASTER KEY REGISTER
SERVICE INSTANCE: 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
CRYPTO UNIT NUM STATUS VERIFICATION PATTERN
5 Full Committed 10ca6697582392616441b65de14b69d0
b59110f497b7531839204d6fd7e592a2
6 Full Committed 10ca6697582392616441b65de14b69d0
b59110f497b7531839204d6fd7e592a2
7* Full Committed 10ca6697582392616441b65de14b69d0
b59110f497b7531839204d6fd7e592a2
8* Full Committed 10ca6697582392616441b65de14b69d0
b59110f497b7531839204d6fd7e592a2
* Indicates a recovery crypto unit used only to hold a backup master key value.
$
Step7 master keyのactivate
activateします。NEW MASTER KEY REGISTERの欄に記載されていたmaster keyの情報がCURRENT MASTER KEY REGISTERの欄に反映され、NEWの欄は空になります。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm&locale=en#step7-activate-master-key
$ ibmcloud tke cryptounit-mk-setimm
Warning! Any key storage associated with the targeted service instance must be prepared to accept the new master key value before running this command. Otherwise, key storage may become unusable.
Do you want to continue?
Answer [y/N]:
> y
Enter the password for the signature key identified by:
tama (b93e8cbc8d92d613c7cd2acb037b52...)
>
OK
Set immediate completed successfully in the selected crypto units.
NEW MASTER KEY REGISTER
SERVICE INSTANCE: 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
CRYPTO UNIT NUM STATUS VERIFICATION PATTERN
5 Empty 00000000000000000000000000000000
00000000000000000000000000000000
6 Empty 00000000000000000000000000000000
00000000000000000000000000000000
7* Empty 00000000000000000000000000000000
00000000000000000000000000000000
8* Empty 00000000000000000000000000000000
00000000000000000000000000000000
CURRENT MASTER KEY REGISTER
SERVICE INSTANCE: 7a092c6d-ce27-4b8a-8c5e-69310ed329cb
CRYPTO UNIT NUM STATUS VERIFICATION PATTERN
5 Valid 10ca6697582392616441b65de14b69d0
b59110f497b7531839204d6fd7e592a2
6 Valid 10ca6697582392616441b65de14b69d0
b59110f497b7531839204d6fd7e592a2
7* Valid 10ca6697582392616441b65de14b69d0
b59110f497b7531839204d6fd7e592a2
8* Valid 10ca6697582392616441b65de14b69d0
b59110f497b7531839204d6fd7e592a2
* Indicates a recovery crypto unit used only to hold a backup master key value.
$
以上の操作でHPCSの初期化が完了します。
