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

[アーティクル]
08/08/2024

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 オフロードライブラリを使用する

キーを生成する

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

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

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

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

キーのない TLS を実装する

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

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

TLS オフロードライブラリのサービスプリンシパルを作成します (たとえば、TLSOffload ServicePrincipal)

"/keys" をスコープとして TLS オフロードサービスプリンシパルに "Managed HSM 暗号化ユーザー" ロールを割り当てます。

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

「TLS オフロードライブラリを使用してキーを生成する方法」の手順に従って、必要なラベルを付けてキーを生成します。
Managed HSM TLS オフロードライブラリを PKCS#11 インターフェイスライブラリとして使用するように TLS サーバーを構成します
キーラベルと TLS オフロードサービスプリンシパルの資格情報を使用して TLS サーバー (nginx SSL 構成設定 'ssl_certificate_key' など) を構成します

詳細なアプローチ

次のロールを持つ管理者ユーザー (TLSOffloadAdminUser など) を作成します。
- "/" スコープの "Managed HSM 暗号化責任者" ロール
TLS オフロードキー生成用のキー生成サービスプリンシパル (TLSOffloadKeyGenServicePrincipal など) を作成し、次のロールを割り当てます。
- "/keys" スコープの "Managed HSM 暗号化ユーザー" ロール。
TLS オフロード用のサービスプリンシパルを作成します (たとえば、TLSOffload ServicePrincipal)

管理者ユーザーは、次のカスタムロール定義を作成します。

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": []
}'

「TLS オフロードライブラリを使用してキーを生成する方法」に従って、必要なラベルを付けてキーを生成します。キーの生成中に、キー生成サービスプリンシパル (TLSOffloadKeyGenServicePrincipal など) を使用します。キーラベルとキー名をメモします。例:
- キーラベル: tlsKey
- キー名: p11-6a2155dc40c94367a0f97ab452dc216f

管理者ユーザーは、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

Azure Managed HSM TLS オフロードライブラリを PKCS#11 インターフェイスライブラリとして使用するように TLS サーバーを構成します
キーラベルと TLS オフロードサービスプリンシパルの資格情報を使用して TLS サーバー (nginx SSL 構成設定 'ssl_certificate_key' など) を構成します

次の方法で共有

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

作業の開始

PKCS#11 の属性

キーの生成

アクセス制御

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

管理者ユーザー

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

Azure CLI

制限の少ないアプローチ

詳細なアプローチ

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

キーを生成する

アクセス許可を付与する

接続のキャッシュ

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

キーを生成する

キーのない TLS を実装する

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

詳細なアプローチ

次のステップ

フィードバック

その他のリソース

次の方法で共有

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

作業の開始

PKCS#11 の属性

キーの生成

アクセス制御

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

管理者ユーザー

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

Azure CLI

制限の少ないアプローチ

詳細なアプローチ

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

キーを生成する

アクセス許可を付与する

接続のキャッシュ

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

キーを生成する

キーのない TLS を実装する

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

詳細なアプローチ

次のステップ

フィードバック

その他のリソース

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

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

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

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

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