Hyper Protect Crypto Servicesを使ってみた　その１（初期化）

鍵管理サービスのHyper Protect Crypto Services（以下HPCS）をオーダーして初期セットアップをするまでの記録です。

全体の流れは下記に従います。
https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-get-started

#インスタンス作成
カタログからHPCSを選択します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/59627/21bba8f5-ea77-79c2-acf6-0f2fb071540b.png)

暗号化ユニット数は、最小が2です。
![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/59627/a5aef4f7-bb24-0099-f9a7-3ec61f6340f0.png)

オーダーすると数分でサービスのプロビジョニングが完了します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/59627/1ff04050-df20-1fee-2d02-f19564223105.png)


#HPCS初期化
HPCSのプロビジョニング直後は下記の状態になっており、初期化の操作が必要です。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/59627/f15c604c-d72e-b43e-5019-c9e8c5423592.png)

初期化の流れは下記となります。
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.

:::note info
他にもう1つHPCSがある環境で試したので1,2,3,4はそちらで使われており、この後の例では、暗号化ユニットの番号が5,6,7,8になっています。
:::

:::note info
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が使われることになります。

:::note info
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 マスターキーパーツの作成

https://cloud.ibm.com/docs/hs-crypto?topic=hs-crypto-initialize-hsm&locale=en#step4-create-master-key

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の初期化が完了します。

![image.png](https://qiita-image-store.s3.ap-northeast-1.amazonaws.com/0/59627/ba4b5aa9-a247-e0f9-26c2-d08812274141.png)