Apigee Edge for Private Cloud の下り（南向き）Hardware Security Module 統合ガイド

リリース バージョン: Edge for Private Cloud v4.53.01.02 パッチリリース以降。

このページでは、Entrust nShield® 5c ネットワーク ハードウェア セキュリティ モジュール（HSM） を使用して、下り方向の TLS 接続（Apigee Message Processor からバックエンド ターゲット サービス）を構成する方法について説明します。

第三者のコンテンツに関する免責事項: このページでは、Apigee Edge の統合に関連する Entrust nShield ハードウェアの構成手順について説明します。これらの手順は標準的な統合パターンに基づいており、情報提供のみを目的として提供されています。Entrust の構成は、メーカーによって変更される可能性があります。信頼できる仕様、セキュリティ構成、現在のハードウェア要件については、公式のEntrust ドキュメント ポータルをご覧ください。

概要

ハードウェア セキュリティ モジュール（HSM）は、安全な鍵の保存と暗号化オペレーションのための専用の強化された環境を提供します。Apigee Edge for Private Cloud を Entrust nShield HSM と統合することで、下り方向の TLS と mTLS handshake で使用される秘密鍵を保護できます。

Apigee は、次のコンポーネントを介した下り方向の HTTPS トラフィックに対する HSM 統合をサポートしています。

  • ターゲット エンドポイント
  • ターゲット サーバー
  • Service Callout ポリシー
  • MessageLogging ポリシー
  • JavaScript ポリシー

前提条件

HSM 統合を構成する前に、次の前提条件を満たしていることを確認してください。

1. ソフトウェア バージョンの要件

  • Apigee Edge for Private Cloud クラスタは、バージョン 4.53.01.02 以降 で実行されている必要があります。
  • HSM 統合は、次の RPM バージョン（以降）にネイティブで含まれています。
    • edge-management-server-4.53.01-0.0.60380.noarch.rpm
    • edge-message-processor-4.53.01-0.0.60380.noarch.rpm
    • edge-gateway-4.53.01-0.0.60380.noarch.rpm

2. インフラストラクチャとオペレーティング システムの構成

  • Edge for Private Cloud クラスタをホストする OS で FIPS が無効になっている必要があります。
  • HSM クライアントと Security World は、すべての Message Processor ノードにインストールして構成する必要があります。
  • 重要: これらの手順は、apigee ユーザーが実行する必要があります。

HSM クライアントのインストールが正しく構成され、apigee ユーザーがアクセスできることを確認するには、Entrust nShield の公式ドキュメントに記載されている標準の JCA/JCE CSP インストール テストを実行します。このテストがすべての Message Processor ノードで正常に完了することを確認してください。

サポートされている構成

Apigee を構成して、次の 2 つのモードで HSM を使用できます。

このモードでは、秘密鍵（KeyStore）のみが HSM に保存され、信頼できる証明書（TrustStore）は標準の Apigee ソフトウェア ストアに残ります。

2. フル HSM モード

このモードでは、KeyStore（秘密鍵）と TrustStore（信頼できる証明書）の両方が HSM に保存されます。このモードはサポートされていますが、レイテンシが追加される可能性があります。

ステップ 1: Message Processor で HSM を有効にする

次の手順を各 Message Processor ノードで 1 つずつ 実行します。

1. Message Processor を停止する

apigee-service edge-message-processor stop

2. HSM キーストア データファイルを確認する

HSM キーストア データファイル（HSM に読み込まれた鍵を参照）が Message Processor ノードに存在し、apigee ユーザーが所有していることを確認します。

chown apigee:apigee /opt/apigee/{name_of_the_Keystore_Data_File}

3. HSM 構成ファイルを作成する

/opt/apigee/hsm-config.properties で構成ファイルを作成または更新します。HSM キーストアとトラストストアの場所とパスワードを定義します（トラストストアは省略可）。

構成例（混合 HSM プロキシとフル HSM プロキシの両方をサポート）:

# HSM KeyStore Reference
hsm.property.unique_keystore_ref1.keystore.file.location=/opt/apigee/ks.keystore
hsm.property.unique_keystore_ref1.keystore.password=keystore_password

# HSM TrustStore Reference (Optional, only needed for Full HSM Mode)
hsm.property.unique_truststore_ref1.truststore.file.location=/opt/apigee/ts.truststore
hsm.property.unique_truststore_ref1.truststore.password=truststore_password

正しい権限を設定します。

chown apigee:apigee /opt/apigee/hsm-config.properties
 
chmod 600 /opt/apigee/hsm-config.properties

4. Message Processor のプロパティを構成する

/opt/apigee/customer/application/message-processor.properties を作成または編集して、次を追加します。

# Enable HSM Integration
conf_system_apigee.hsm.enabled=true

# HSM Configuration File Path
conf_system_apigee.hsm.properties.file=/opt/apigee/hsm-config.properties

# Advanced Custom HSM Port Support (Optional, default is 9000/9001)
# conf_system_apigee.hsm.priv_port=9001
# conf_system_apigee.hsm.nonpriv_port=9000

正しい所有権を確認します。

chown apigee:apigee /opt/apigee/customer/application/message-processor.properties

5. 再構成して再起動する

apigee-service edge-message-processor configure
 
apigee-service edge-message-processor restart

6. 初期化を検証する

システムログ /opt/apigee/var/log/edge-message-processor/logs/system.log で、初期化が成功したことを示すメッセージを確認します。

main INFO  SECURITY-CONTEXT - SSLPreEvaluationContext.isHSMConfigEnabled() : HSM_FLOW : HSM config is enabled
main INFO  SECURITY-CONTEXT - SSLPreEvaluationContext.loadProperties() : HSM_FLOW :  HSM config properties loaded from file /opt/apigee/hsm-config.properties

ステップ 2: API プロキシを構成する

API プロキシ構成（TargetEndpoint、ServiceCallout、またはポリシー）の SSLInfo ブロックを更新します。hsmref:// 接頭辞を使用して HSM 管理ストアを参照し、ref://（または標準の参照名）を使用してソフトウェア ストアを参照します。

KeyStore（クライアント認証）に HSM を使用し、TrustStore にソフトウェアを使用します。

<SSLInfo>
    <Enabled>true</Enabled>
    <ClientAuthEnabled>true</ClientAuthEnabled>
    <KeyStore>hsmref://unique_keystore_ref1</KeyStore>
    <TrustStore>ref://mySoftwareTrustStoreRef</TrustStore>
</SSLInfo>

2. フル HSM 構成

KeyStore と TrustStore の両方に HSM を使用します。

<SSLInfo>
    <Enabled>true</Enabled>
    <ClientAuthEnabled>true</ClientAuthEnabled>
    <KeyStore>hsmref://unique_keystore_ref1</KeyStore>
    <TrustStore>hsmref://unique_truststore_ref1</TrustStore>
</SSLInfo>

デプロイ時の検証バイパス

秘密鍵を Apigee の Cassandra データベースにアップロードせずにデプロイできるようにするため、Apigee は、hsmref:// 接頭辞で始まる参照のデプロイ時に、環境キーストア/トラストストアの存在チェックを自動的にバイパスします。

オペレーション: 新しい HSM キーストア/トラストストアを追加する

実行中の既存の環境に新しい HSM キーストアまたはトラストストアを追加するには:

  1. 鍵/証明書を物理 HSM に読み込みます（HSM にキーストア/トラストストアを読み込むをご覧ください）。
  2. 新しいキーストア データファイルを Message Processor ノードにコピーし、所有権を apigee に設定します。
  3. すべての Message Processor ノード で、新しい参照を使用して /opt/apigee/hsm-config.properties を更新します。 
    hsm.property.new_keystore_ref.keystore.file.location=/opt/apigee/new_ks.keystore
hsm.property.new_keystore_ref.keystore.password=new_password
  4. 各ノードで Message Processor を再起動します。 
    apigee-service edge-message-processor restart
  5. 新しい hsmref://new_keystore_ref を使用するように API プロキシ構成を更新してデプロイします。

HSM をグローバルに無効にする

HSM を無効にするには:

  1. hsmref:// を使用するすべてのアクティブなプロキシを更新して、標準のソフトウェア参照（ref://）を使用するようにします。
  2. 各 Message Processor ノードで、/opt/apigee/customer/application/message-processor.properties を編集して、次のように設定します。 
    conf_system_apigee.hsm.enabled=false
  3. Message Processor を再構成して再起動します。 
    apigee-service edge-message-processor configure
     
    apigee-service edge-message-processor restart

制限事項と注意事項

  • サポートされているハードウェア: Entrust nShield 5c ネットワーク HSM に限定されます。
  • メンテナンス: HSM サーバー/クライアントのメンテナンスはお客様の責任となります。
  • レイテンシ: HSM とのネットワーク ネゴシエーションにより、レイテンシが追加されることがあります。HSM 混合モード を使用すると、この問題をある程度軽減できます。
  • HSM の再起動: HSM hardserver が再起動した場合は、接続されている Message Processor ノードで edge-message-processor を再起動する必要があります。

HSM にキーストア/トラストストアを読み込む

PKCS12 キーストアまたは PEM 証明書を HSM にインポートするために必要な正確な keytool コマンドについては、公式の Entrust nShield ドキュメント ポータルをご覧ください。

Apigee との互換性を確保するには、生成された HSM キーストア ファイルが次の要件を満たしている必要があります。

  • ディレクトリ: /opt/apigee/ に保存する必要があります（例: /opt/apigee/hsmks.keystore）。
  • 権限: apigee ユーザーが所有している必要があります（chown apigee:apigee /opt/apigee/<filename>）。
  • 可読性: edge-message-processor サービスが読み取れる必要があります。

エラー リファレンス

障害コード HTTP ステータス 説明 / 原因
entities.HsmConfigNotEnabled 500 API プロキシが実行時に hsmref:// を使用しようとしましたが、Message Processor で HSM がグローバルに無効になっています（conf_system_apigee.hsm.enabled=false）。

Entrust と nShield は、Entrust Corporation またはその関連会社の商標または登録商標です。その他のすべての商標は、それぞれの所有者に帰属します。