Share via

Azure Managed HSM TLS オフロード ライブラリ

  • [アーティクル]

Azure Managed HSM には、PKCS#11 バージョン 2.40 に準拠した TLS オフロード ライブラリが用意されています。 Azure Managed HSM で、PKCS#11 仕様に記載されているすべての機能がサポートされているのではありません。そうではなく、TLS オフロード ライブラリを使用することで、主に TLS サーバー証明書キーの生成と TLS ハンドシェイク中のデジタル署名の生成を行うために、F5 (BigIP) と Nginx を使用した SSL/TLS オフロードの限られたメカニズムとインターフェイス機能のセットがサポートされます。

詳細については、Azure Managed HSM TLS オフロード ライブラリの GitHub を参照してください。

TLS オフロード ライブラリを使用すると、Azure Key Vault REST API を内部的に使用して Azure Managed HSM を操作できます。

作業の開始

PKCS#11 の属性

PKCS#11 と適切に連携するには、(C_GenerateKeyPair による) キーの生成と、(C_FindObjectsInit/C_FindObjects による) キー オブジェクトの検索のために、Azure Key Vault キー オブジェクトに PKCS#11 属性を保存するためのソリューションが必要です。 TLS オフロード ライブラリを使用すると、必要なこれらの PKCS#11 属性を Azure Key Vault タグに変換できます。

これらの "属性タグ" には、特別なプレフィックスが付いています。

  • p11_pri_{P11 属性名} - 秘密キー属性
  • p11_pub_{P11 属性名} - 公開キー属性

TLS オフロード ライブラリを使用すると、Azure Key Vault キー操作とキー有効期間の属性を適切に設定し、生成されたキーに対してこれらの制限をサービスで適切に適用できます。 これらの属性は、クエリ機能をサポートするために、他の PKCS#11 属性と同様にタグとして保存されます。

TLS オフロード ライブラリを使用するアプリケーションで 1 つ以上の PKCS#11 属性を使って、キー オブジェクトを検索して使用します。

警告

TLS オフロード ライブラリとそのタグによって生成されたキーには、Azure Key Vault REST API を使ってアクセスできます。 Azure Key Vault REST API を使用してこれらの P11 属性タグを操作すると、TLS オフロード ライブラリ アプリケーションが中断される可能性があります。

キーの生成

TLS オフロード ライブラリには、キー作成ツールである mhsm_p11_create_key が含まれています。 コマンド ライン引数を指定せずにツールを実行すると、ツールの正しい使用方法が表示されます。

キー作成ツールを使用するにはサービス プリンシパルが必要です。これは "/keys" をスコープとして "Managed HSM 暗号化ユーザー" ロールに割り当てられます。

キー作成ツールによって、環境変数 MHSM_CLIENT_ID および MHSM_CLIENT_SECRET からサービス プリンシパルの資格情報が読み取られます。

  • MHSM_CLIENT_ID – サービス プリンシパルのアプリケーション (クライアント) ID に設定する必要があります
  • MHSM_CLIENT_SECRET – サービス プリンシパルのパスワード (クライアント シークレット) に設定する必要があります

マネージド ID の場合、上記の環境変数は必要ありません。

  • --identity 引数を使用して、mhsm_p11_create_key ツールでマネージド ID を有効にします。
  • ユーザー割り当てマネージド ID の client_id は、MHSM 構成ファイル (mhsm-pkcs11.conf) で引用される必要があります。 ユーザー割り当てマネージド ID の client_id が指定されていない場合は、システム割り当てマネージド ID と見なされます。

キーの名前は作成時にキー作成ツールでランダムに生成されます。 作業を容易にするために、完全な Azure Key Vault キー ID とキー名がコンソールに出力されます。

MHSM_CLIENT_ID="<service-principal-application-id>" \
MHSM_CLIENT_SECRET="<service-principal-password>" \
mhsm_p11_create_key --RSA 4K --label tlsKey

Key is generated successfully. \
Managed HSM Key ID: https://myhsm.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f

キー作成ツールの --label 引数で、生成される秘密キーと公開キーに必要な CKA_LABEL を指定します。 通常、これらの属性は、サポートされている TLS オフロード ソリューション (nginx SSL 構成設定 'ssl_certificate_key' など) を構成するために必要です。

キー名は、Azure CLI でのロールの割り当て変更のために必要です。

アクセス制御

TLS オフロード ライブラリを使用すると、C_FindObjectsInit が Azure Key Vault REST API 呼び出しに変換されます。これは /keys スコープで動作します。 MHSM サービスで、キー作成ツールを使用して作成されたキーの検索操作を TLS オフロード ライブラリ ユーザーが承認するには、このスコープの読み取りアクセス許可が必要です。

Azure Managed HSM のローカル RBAC の詳細については、以下を参照してください。

次のセクションでは、TLS オフロード ライブラリ サービス プリンシパルとマネージド ID のアクセス制御を実装するためのさまざまな方法について説明します。

TLS オフロード サービス プリンシパル

TLS オフロード サービス プリンシパルは、TLS オフロード ライブラリを使用してキーにアクセスするアプリケーションによって使用され、ロールの割り当てを通して少なくとも次のアクセス許可が与えられている必要があります。

  • マネージド HSM 内のすべてのキーに対する KeyRead アクセス許可
  • TLS オフロードに必要なキーに対する KeySign アクセス許可

管理者ユーザー

管理者ユーザーは、カスタム ロール定義とロールの割り当てを作成します。 そのため、管理者ユーザーは、"/" をスコープとして次のいずれかの組み込みロールに割り当てられている必要があります。

  • Managed HSM 暗号化担当者
  • Managed HSM ポリシー管理者
  • Managed HSM 管理者

キー生成サービス プリンシパル

キー生成サービス プリンシパルは、TLS オフロード キーを生成するためにキー作成ツール (mhsm_p11_create_key) で使用されます。 このサービス プリンシパルは、"/keys" をスコープとして "Managed HSM 暗号化ユーザー" ロールに割り当てられている必要があります。

Azure CLI

Azure CLI を使用して、ロールの割り当てなどのタスクを実行できます。

制限の少ないアプローチ

制限の少ないアプローチは比較的シンプルであり、Azure Managed HSM を TLS オフロードのためだけに使用する場合に適しています。

"/keys" をスコープとして暗号化ユーザー ロールを TLS オフロード サービス プリンシパルに割り当てます。 これにより、TLS オフロード サービス プリンシパルに、TLS オフロード用のキーの生成および検索のアクセス許可が付与されます。

az keyvault role assignment create --hsm-name ContosoMHSM \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys

マネージド ID の場合は、次のようにコマンド引数を指定します。

az keyvault role assignment create --hsm-name ContosoMHSM \
      --role "Managed HSM Crypto User"  \
       --assignee-object-id <object_id>  \
       --assignee-principal-type MSI \
       --scope /keys

詳細なアプローチ

詳細なアプローチでは、きめ細かいアクセス制御を実装します。 そのためには、2 つのサービス プリンシパル (TLS オフロード サービス プリンシパルとキー生成サービス プリンシパル) と管理者ユーザーが必要です。

目的は、TLS オフロードに必要な最小限のアクセス許可をサポートするように TLS オフロード サービス プリンシパルのアクセス許可を制限することです。 ライブラリの C_FindObject* 関数をサポートするには、ユーザーに他のキーの読み取りアクセス許可が必要です。

TLS オフロード ライブラリ ユーザー読み取りロール

詳細なアプローチを実装する最初の手順は、カスタム ロールを作成することです。 この操作は一度実行するだけで済みます。

管理者ユーザー (Managed HSM 暗号化責任者または Managed HSM 管理者または Managed HSM ポリシー管理者ロールを持つ) は、カスタムの "TLS ライブラリ ユーザー読み取りロール" のロール定義を作成します。

az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{ \
"roleName": "TLS Library User Read Role", \
"description": "Grant Read access to keys", \
"actions": [], \
"notActions": [], \
"dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \
"notDataActions": [] \
}'

キーを生成する

キーは、キー作成ツール (mhsm_p11_create_key) でキー生成サービス プリンシパルを使用して生成できます。

アクセス許可を付与する

管理者ユーザーは、TLS オフロード サービス プリンシパルに次のロールを割り当てます。

  • "/keys" スコープの "TLS ライブラリ ユーザー読み取りロール" ロールを割り当てる
  • "/keys/{キー名}" スコープの "Managed HSM 暗号化ユーザー" ロールを割り当てる

次の例では、キー名は "p11-6a2155dc40c94367a0f97ab452dc216f" です。

az keyvault role assignment create --hsm-name ContosoMHSM  \
--role "TLS Library User Read Role"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys

az keyvault role assignment create --hsm-name ContosoMHSM  \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f

接続のキャッシュ

Managed HSM サービスへの Sign 呼び出しのパフォーマンスを向上させるために、TLS オフロード ライブラリによって Managed HSM サービス サーバーへの TLS 接続がキャッシュされます。 既定では、TLS オフロード ライブラリにより、最大 20 個の TLS 接続がキャッシュされます。 接続のキャッシュは、MHSM 構成ファイル (mhsm-pkcs11.conf) を使用して制御できます。

"ConnectionCache": {
        "Disable": false, 
        "MaxConnections": 20
}

無効化

この値が true の場合、接続のキャッシュは無効になります。 共有メモリ プロトコルは既定で有効になっています。

MaxConnections

キャッシュする接続の最大数を指定します。 最大接続制限は、アプリケーションで使用されている同時 PKCS11 セッションの数に基づいて構成する必要があります。 アプリケーションは通常、PKCS11 セッションのプールを作成し、それらをスレッドのプールから使用して、署名要求を並列で生成します。 MaxConnections は、アプリケーションによって生成される同時署名要求の数と一致する必要があります。

署名要求数/秒 (RPS) は、同時要求の数とキャッシュされた接続の数によって異なります。 大きい数または既定の制限を指定しても、同時 PKCS11 署名要求の数がこの制限より少ない場合、署名 RPS は改善されません。 Standard B1 HSM プールのバースト モードを実現するためのコンカレント接続の最大数は、インスタンスの種類に応じて約 30 個です。 ただし、最適なコンカレント接続数を算出するには、さまざまな数値で試してみる必要があります。

アプリケーションでの PKCS11 ライブラリの使用方法に関する詳細については、アプリケーションのドキュメントを参照するか、アプリケーション ベンダーにお問い合わせください。

TLS オフロード ライブラリを使用する

キーを生成する

TLS オフロード ライブラリには、キー作成ツールである mhsm_p11_create_key が含まれています。 コマンド ライン引数を指定せずにツールを実行すると、ツールの正しい使用方法が表示されます。

キー作成ツールを使用するにはサービス プリンシパルが必要です。これは "/keys" をスコープとして "Managed HSM 暗号化ユーザー" ロールに割り当てられます。

環境変数 MHSM_CLIENT_ID および MHSM_CLIENT_SECRET からキー作成ツールによってサービス プリンシパルの資格情報が読み取られます。

  • MHSM_CLIENT_ID – サービス プリンシパルのアプリケーション (クライアント) ID に設定する必要があります
  • MHSM_CLIENT_SECRET – サービス プリンシパルのパスワード (クライアント シークレット) に設定する必要があります

キーの名前は作成時にキー作成ツールでランダムに生成されます。 作業を容易にするために、完全な Azure Key Vault キー ID とキー名がコンソールに出力されます。

MHSM_CLIENT_ID="<service-principal-application-id>" \
MHSM_CLIENT_SECRET="<service-principal-password>" \
mhsm_p11_create_key --RSA 4K --label tlsKey

Key is generated successfully.
Managed HSM Key ID: https://myhsm.managedhsm.azure.net/keys/p11-6a2155dc40c94367a0f97ab452dc216f/92f8aa2f1e2f4dc1be334c09a2639908 \
Key Name: p11-6a2155dc40c94367a0f97ab452dc216f

キー作成ツールの --label 引数で、生成される秘密キーと公開キーに必要な CKA_LABEL を指定します。 通常、これらの属性は、サポートされている TLS オフロード ソリューション (nginx SSL 構成設定 'ssl_certificate_key' など) を構成するために必要です。

キーに対する詳細なアクセスを実装することを予定している場合は、キー名が必要です。

キーのない TLS を実装する

キーを生成し、キーのない TLS 用にキーを使用するには、2 つの方法があります。よりシンプルで、より制限の少ないアプローチと、より優れたセキュリティを提供する詳細なアプローチです。 アプローチは、実装作業とセキュリティの適用方法によって異なります。

よりシンプルなアプローチ

  1. TLS オフロード ライブラリのサービス プリンシパルを作成します (たとえば、TLSOffload ServicePrincipal)
  2. "/keys" をスコープとして TLS オフロード サービス プリンシパルに "Managed HSM 暗号化ユーザー" ロールを割り当てます。 
    az keyvault role assignment create --hsm-name ContosoMHSM \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys
  3. 「TLS オフロード ライブラリを使用してキーを生成する方法」の手順に従って、必要なラベルを付けてキーを生成します。
  4. Managed HSM TLS オフロード ライブラリを PKCS#11 インターフェイス ライブラリとして使用するように TLS サーバーを構成します
  5. キー ラベルと TLS オフロード サービス プリンシパルの資格情報を使用して TLS サーバー (nginx SSL 構成設定 'ssl_certificate_key' など) を構成します

詳細なアプローチ

  1. 次のロールを持つ管理者ユーザー (TLSOffloadAdminUser など) を作成します。
    • "/" スコープの "Managed HSM 暗号化責任者" ロール
  2. TLS オフロード キー生成用のキー生成サービス プリンシパル (TLSOffloadKeyGenServicePrincipal など) を作成し、次のロールを割り当てます。
    • "/keys" スコープの "Managed HSM 暗号化ユーザー" ロール。
  3. TLS オフロード用のサービス プリンシパルを作成します (たとえば、TLSOffload ServicePrincipal)
  4. 管理者ユーザーは、次のカスタム ロール定義を作成します。
    az keyvault role definition create --hsm-name ContosoMHSM --role-definition '{ \
"roleName": "TLS Library User Read Role", \
"description": "Grant Read access to keys", \ 
"actions": [], \
"notActions": [], \
"dataActions": ["Microsoft.KeyVault/managedHsm/keys/read/action"], \
"notDataActions": []
}'
  5. 「TLS オフロード ライブラリを使用してキーを生成する方法」に従って、必要なラベルを付けてキーを生成します。 キーの生成中に、キー生成サービス プリンシパル (TLSOffloadKeyGenServicePrincipal など) を使用します。 キー ラベルとキー名をメモします。 次に例を示します。
    • キー ラベル: tlsKey
    • キー名: p11-6a2155dc40c94367a0f97ab452dc216f
  6. 管理者ユーザーは、TLS オフロード サービス プリンシパルに次のロールを割り当てます
    • "/keys" スコープの "TLS ライブラリ ユーザー読み取りロール" ロール
    • "/keys/{キー名}" スコープの "Managed HSM 暗号化ユーザー" ロール
    az keyvault role assignment create --hsm-name ContosoMHSM  \
--role " TLS Library User Read Role"  \
--assignee TLSOffloadServicePrincipal @contoso.com  \
--scope /keys

az keyvault role assignment create --hsm-name ContosoMHSM  \
--role "Managed HSM Crypto User"  \
--assignee TLSOffloadServicePrincipal@contoso.com  \
--scope /keys/p11-6a2155dc40c94367a0f97ab452dc216f
  7. Azure Managed HSM TLS オフロード ライブラリを PKCS#11 インターフェイス ライブラリとして使用するように TLS サーバーを構成します
  8. キー ラベルと TLS オフロード サービス プリンシパルの資格情報を使用して TLS サーバー (nginx SSL 構成設定 'ssl_certificate_key' など) を構成します

次のステップ