EP11 接続の 2 番目の認証層の有効化-標準プランのみ

暗号操作の実行に対する排他制御を確保するために、Hyper Protect Crypto Services Certificate Manager CLI を使用して、EP11 (GREP11 または PKCS#11 API) 接続の認証の第 2 層を有効にすることができます。この機能を有効にして、Identity and Access Management (IAM) トークンに加えてさらにアクセス権限制御のレイヤーを EP11 アプリケーションに追加します。相互 TLS 接続が確立されて、有効なクライアント証明書を持つ EP11 アプリケーションのみが EP11 操作を実行できるようになります。

EP11 接続の認証の第 2 層は、現在 Hyper Protect Crypto Services 標準プランでのみサポートされています。

相互 TLS 認証を有効にするためのセキュリティーと可用性のベスト・プラクティス

EP11 にアクセスするための認証の第 2 層として相互 TLS を使用する場合は、セキュリティーと可用性に関する以下の考慮事項に留意する必要があります。

特定のユーザーが EP11 にアクセスできないようにする必要がある場合は、サービス・ユーザーから証明書管理者を切り離します。クライアント証明書を管理するユーザーにのみ _「Certificate Manager」ロールを割り当て、運用の使用目的に対応するロールを他のサービス・ユーザーに割り当てることによって、アクセス権限を制御します。ユーザー・アクセス権限を管理するには、アカウント管理アクセス権限を持つ「管理者」_ロールが割り当てられている必要があります。
無効なクライアント証明書を使用している場合や、使用不可の秘密鍵を使用してクライアント証明書に署名している場合は、EP11 API にアクセスできません。可用性を確保するには、複数のユーザーに _「Certificate Manager」_ロールをバックアップとして割り当てます。証明書管理者は、各自の固有の管理者秘密鍵を安全に保持する必要があります。証明書管理者は、例えば IBM Cloud Secrets Managerを使用して、 Hyper Protect Crypto Services インスタンスの外部にあるすべてのクライアント証明書のバックアップを維持する必要もあります。証明書の有効期限をモニターすることも推奨されます。

開始前に

GREP11 または PKCS#11 API 接続向け認証の第 2 層を有効にする前に、以下の前提条件を満たしていることを確認してください。

対応するアクションを実行するための 「Certificate Manager」 IAM ロールが割り当てられます。 IAM 役割の割り当てについて詳しくは、ユーザーのアクセス権限の管理およびリソースに対するアクセス権限の管理を参照してください。
TLS 認証に使用されるクライアント証明書がご使用のワークステーション上に準備されていること。 IBM Cloud Secrets Manager を使用して、アプリケーションおよびサービスの SSL/TLS 証明書を管理することをお勧めします。この証明書マネージャーは無料であり、証明書用の永続ストレージを提供します。
IBM Cloud CLI をインストールします。
以下のコマンドを使用して、最新の Certificate Manager CLI プラグインをインストールします。
```
ibmcloud plugin install hpcs-cert-mgr
```
CLI を使用して IBM Cloud にログインします。複数のアカウントがある場合は、サービス・インスタンスを作成するアカウントを選択します。以下のコマンドを使用して、サービス・インスタンスが配置されている正しいリージョンとリソース・グループにログインしていることを確認します。
```
ibmcloud target -r <region> -g <resource_group>
```

ステップ 1: 管理者署名鍵の構成

認証の第 2 層を有効にするには、まず管理者の署名鍵を構成する必要があります。署名キーは、Certificate Manager CLI コマンドを処理するインスタンス Certificate Manager サーバーに接続するために使用されます。

以下のコマンドを使用して、署名キー・ペアを生成します。
```
ibmcloud hpcs-cert-mgr adminkey set --crn HPCS_CRN [--private]
```
HPCS_CRN 変数を、ご使用の Hyper Protect Crypto Services インスタンスのクラウド・リソース名 (CRN) に置き換えます。 ibmcloud resource service-instances --long コマンドを使用して、CRN を取得できます。 --private パラメーターはオプションです。このパラメーターを使用する場合は、証明書マネージャー・サーバーの URL はプライベート・エンドポイントを指すため、ユーザーはプライベート・ネットワークを使用してサービス・インスタンスに接続する必要があります。

このコマンドを実行すると、公開鍵と秘密鍵のペアが生成され、ローカル・ワークステーションに保管されます。デフォルトのファイル・パスは /Users/<username>/.hpcs-cert-mgr-cfg/ です。署名鍵は、パスワードで保護するなどして安全に保管してください。パブリック・キーは、署名検査のためにインスタンス Certificate Manager サーバーに自動的にアップロードされます。

署名鍵をリフレッシュおよび更新するには、ibmcloud hpcs-cert-mgr adminkey update コマンドを使用します。 CLI の使用法について詳しくは、Hyper Protect Crypto Services Certificate Manager CLI のリファレンスを参照してください。
(オプション) 以下のコマンドを使用して、公開鍵がサーバーにアップロードされているかどうかを確認します。
```
ibmcloud hpcs-cert-mgr adminkey get --crn HPCS_CRN [--private]
```
このコマンドによって公開鍵の値が返される場合は、公開鍵は正常にアップロードされています。

ステップ 2: 認証のためのクライアント CA 証明書のセットアップ

管理者署名鍵を構成した後、TLS クライアント認証のためにクライアント認証局(CA)A trusted third-party organization or company that issues the digital certificates. The certificate authority typically verifies the identity of the individuals who are granted the unique certificate. 証明書をインスタンス証明書マネージャー・サーバーにアップロードする必要があります。

クライアント CA 証明書をセットアップすると、UI を介して EP11 鍵ストアおよび EP11 鍵にアクセスできなくなります。

(オプション) CA 証明書およびクライアント証明書の準備

OpenSSL ユーティリティーを使用して、GREP11 インフラストラクチャーの CA 証明書を生成できます。

証明書の生成に使用できるワークステーションには、必ず OpenSSL をインストールしてください。ワークステーションで以下の手順を実行します。
1. 以下のコマンドを実行して、CA キーを生成します。
```
openssl genrsa -out ca.key 2048
```
2. 以下のコマンドを実行して、CA 証明書を作成します。
```
openssl req -new -x509 -key ca.key -days 730 -out ca.pem
```
3. 以下のコマンドを実行して、クライアント・キーを作成します。
```
openssl genrsa -out client-key.pem 2048
```
4. 以下のコマンドを実行して、クライアント証明書署名要求を作成します。
```
openssl req -new -key client-key.pem -out client.csr
```
5. 以下のコマンドを実行して、クライアント証明書を作成します。
```
openssl x509 -req -days 730 -in client.csr -CA ca.pem -CAcreateserial -CAkey ca.key -out client.pem
```

以下のコマンドを使用して、クライアント CA 証明書をサーバーにアップロードします。

クライアント証明書が証明書チェーンの中間 CA 証明書によって署名されている場合は、その中間 CA 証明書をアップロードする必要があります。

ibmcloud hpcs-cert-mgr cert set --crn HPCS_CRN --admin-priv-key ADMIN_PRIV_KEY --cert-id CERT_ID --cert CERT_FILE [--private]

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

表 1. TLS 証明書をアップロードするために必要な変数について説明します。
変数	説明
`HPCS_CRN`	必須。ご使用の Hyper Protect Crypto Services インスタンスのクラウド・リソース名 (CRN)。 `ibmcloud resource service-instances --long` コマンドを使用して、CRN を取得できます。
`ADMIN_PRIV_KEY`	必須。ステップ 1で生成または更新するローカル・ワークステーションの現行のプライベート・キーのファイル・パス。この秘密鍵を使用して、インスタンス証明書マネージャー・サーバーに対してこのコマンド・アクションが署名されます。
`CERT_ID`	必須。識別を容易にする目的でクライアント CA 証明書に割り当てる文字列 ID。
`CERT_FILE`	必須。ローカル・ワークステーションのクライアント CA 証明書のファイル・パス。

--private パラメーターはオプションです。このパラメーターを使用する場合は、証明書マネージャー・サーバーの URL はプライベート・エンドポイントを指すため、ユーザーはプライベート・ネットワークを使用してサービス・インスタンスに接続する必要があります。

(オプション) 以下のコマンドを使用して、クライアント CA 証明書がサーバーにアップロードされているかどうかを確認します。
```
ibmcloud hpcs-cert-mgr cert list --crn HPCS_CRN [--private]
```
このコマンドは、サーバー上でユーザーによって管理されている使用可能なすべてのクライアント CA 証明書をリストします。以前にアップロードされた証明書がリストに含まれている場合は、アクションが正常に完了したことを意味します。

ステップ 3: EP11 アプリケーション向けの相互 TLS 接続の確立

管理者署名キーとクライアント CA 証明書をセットアップすると、EP11 ユーザーは GREP11 または PKCS #11 API を使用するアプリケーションに対して相互 TLS 接続を確立できます。その前に EP11 ユーザーは、クライアント証明書を使用して GREP11 または PKCS#11 アプリケーションを構成する必要があります。

GREP11 または PKCS#11 API を使用するには、EP11 操作を実行するための適切な IAM 役割が EP11 ユーザーに割り当てられている必要があります。詳しくは、IAM サービス・アクセス役割の「HSM API」タブを参照してください。

GREP11 アプリケーションの構成

GREP11 アプリケーションに使用するプログラミング言語に応じて、対応する gRPC パッケージに基づいて構成方法は異なります。以下に、Golang と JavaScript の例を示します。
- Golang のサンプル・コード・スニペット
```
cert, _ := tls.LoadX509KeyPair("client.pem", "client-key.pem")
var callOpts = []grpc.DialOption{
  grpc.WithTransportCredentials(credentials.NewTLS(&tls.Config{Certificates: []tls.Certificate{cert}}))
}
```
  tls.Config{} は、 Config 型構造体に基づいて適切に定義する必要があります。少なくとも Certificates フィールドを設定する必要があります。クライアント・キーとクライアント証明書を必ず使用してください。完全な Golang サンプル・コードについては、 The sample GitHub repository for Golangを参照してください。
- JavaScript のサンプル・コード・スニペット
```
credentials.push(grpc.credentials.createSsl());
```
  関数およびパラメーターについて詳しくは、資格情報モジュールの資料を参照してください。 private_key 関数の cert_chain パラメーターと createSsl() パラメーターを設定する必要があります。完全な JavaScript サンプル・コードについては、 The sample GitHub repository for JavaScriptを参照してください。

PKCS #11 アプリケーションの構成

PKCS #11 の構成ファイル内で相互 TLS が扱われます。以下の例に従って tls フィールドを更新します。

tls:
  enabled: true
  mutual: true
  cacert:
  certfile: "<client_certificate>"
  keyfile: "<client_certificate_private_key>"

次の表に基づいて、例内の変数を置き換えてください。

表 3. PKCS #11 アプリケーションの構成に必要な変数について説明します。
変数	説明
`client_certificate`	必須。証明書管理者によってサーバーにアップロードされるクライアント証明書のファイル・パス。
`client_certificate_private_key`	必須。証明書を署名するために使用されるクライアント証明書の秘密鍵のファイル・パス。

構成後に、アプリケーションが GREP11 または PKCS#11 API を使用して暗号操作を実行すると、相互 TLS 接続が確立されて、追加の認証層に対してクライアント証明書が検証されます。

(オプション) 相互 TLS 接続の無効化

認証の第 2 層が不要になった場合は、サーバー上のすべてのクライアント CA 証明書を削除すると、この機能を無効にできます。

以下のコマンドを使用して、CA 証明書を削除します。このステップを繰り返して、サーバー上の使用可能なすべての証明書を削除し、EP11 アプリケーションからの TLS 接続を無効にします。

ibmcloud hpcs-cert-mgr cert delete --crn HPCS_CRN --admin-priv-key ADMIN_PRIV_KEY --cert-id CERT_ID [--private]

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

表 2. CA 証明書を削除するために必要な変数について説明します。
変数	説明
`HPCS_CRN`	必須。ご使用の Hyper Protect Crypto Services インスタンスのクラウド・リソース名 (CRN)。 `ibmcloud resource service-instances --long` コマンドを使用して、CRN を取得できます。
`ADMIN_PRIV_KEY`	必須。ローカル・ワークステーションに保管されている現在の秘密鍵のファイル・パス。この秘密鍵を使用して、インスタンス証明書マネージャー・サーバーに対してこのコマンド・アクションが署名されます。
`CERT_ID`	必須。削除したい CA 証明書の文字列 ID。最初に `ibmcloud hpcs-cert-mgr cert list --crn HPCS_CRN` コマンドを使用して、すべての証明書とそれらの ID をリストできます。

サービス・インスタンスに複数の証明書管理者がセットアップされている場合は、これらの管理者のもとにあるすべての CA 証明書を必ず削除してください。

Certificate Manager サーバーから CA 証明書を削除すると、この CA 証明書によって発行されたクライアント証明書を使用するすべてのアプリケーションは、相互 TLS 接続を介して GREP11 インスタンスにアクセスできなくなります。

Certificate Manager サーバーからすべての CA 証明書を削除すると、GREP11 インスタンスの相互 TLS 認証は無効になります。アプリケーションは今後は、GREP11 インスタンスに接続するために相互 TLS 接続を必要としなくなります。

(オプション) 以下のコマンドを使用して、すべての CA 証明書が削除されたかを確認します。
```
ibmcloud hpcs-cert-mgr cert list --crn HPCS_CRN [--private]
```
証明書が返されない場合は、サービス・インスタンスのすべての証明書が削除されたことを意味します。
(オプション) GREP11 アプリケーションまたは PKCS #11 アプリケーションを更新して、証明書構成を削除し、アプリケーションが今後の API 接続でその証明書を使用しないようにします。

次の作業

Certificate Manager CLI コマンドの詳細なリファレンスについては、Hyper Protect Crypto Services の Certificate Manager CLI プラグインを参照してください。
GREP11 API と PKCS #11 API のリファレンスについては、暗号操作: GREP11 API および暗号操作: PKCS #11 の API を参照してください。