秘密鍵の暗号化を有効にする

このドキュメントでは、Cassandra データベースに保存されているデベロッパー アプリのコンシューマ シークレット(クライアント認証情報)の暗号化を有効にする方法について説明します。

概要

従来、Apigee Edge for Private Cloud では、Key-Value マップ(KVM)データと OAuth アクセス トークンを暗号化するオプションが用意されていました。

次の表に、Apigee for Private Cloud での保存データの暗号化オプションを示します。

エンティティ デフォルトで暗号化が有効 暗号化をオプションで利用可能 関連ドキュメント
KVM × 暗号化された KVM についてをご覧ください。
OAuth アクセス トークン × トークンのハッシュ化によるセキュリティの強化をご覧ください。
デベロッパー アプリのコンシューマ シークレット × 有効にするには、このドキュメントの構成手順を実施します。

クライアント認証情報の暗号化を有効にするには、すべての Message Processor ノードと Management Server ノードで次のタスクを行う必要があります。

  • 鍵暗号鍵(KEK)を保存するキーストアを作成します。Apigee は、この暗号化された鍵を使用して、データの暗号化に必要な秘密鍵を暗号化します。
  • すべての Management Server ノードと Message Processor ノードの構成プロパティを編集します。
  • キーの作成をトリガーするデベロッパー アプリを作成します。
  • ノードを再起動します。

このドキュメントでは、これらのタスクについて説明します。

鍵暗号化機能について知っておくべきこと

このドキュメントでは、KEK 機能を有効にする方法について説明します。KEK 機能を使用すると、デベロッパー アプリのコンシューマ シークレットが Cassandra データベースに保存されるときに、暗号化に使用される秘密鍵を暗号化できます。

デフォルトでは、データベース内の既存の値は(書式なしテキストで)変更されず、以前と同様に機能します。

暗号化されていないエンティティに対して書き込みオペレーションを実行すると、オペレーションが保存されるときにそのエンティティが暗号化されます。たとえば、暗号化されていないトークンを取り消して後で承認すると、新しく承認されたトークンが暗号化されます。

鍵を安全に保護する

KEK が保存されているキーストアのコピーを安全な場所に保管してください。独自の安全なメカニズムを使用して、キーストアのコピーを保存することをおすすめします。このドキュメントで説明するように、ローカル構成ファイルから参照できる各 Message Processor および Management Server ノードにキーストアを配置する必要があります。ただし、キーストアのコピーを安全な場所やバックアップとして別の場所に保存することも重要です。

鍵暗号化の有効化

コンシューマ秘密鍵の暗号化手順は次のとおりです。

前提条件

このドキュメントの手順を行う前に、次の要件を満たしている必要があります。

  • Apigee Edge for Private Cloud 4.50.00.10 以降をインストールするか、アップグレードする必要があります。
  • Apigee Edge for Private Cloud の管理者である必要があります。

ステップ 1: キーストアを生成する

鍵暗号鍵(KEK)を保持するキーストアを作成する手順は次のとおりです。

  1. 次のコマンドを実行して、KEK の暗号化に使用する鍵を保存するキーストアを生成します。表示されているとおりにコマンドを入力します。(任意のキーストア名を指定できます)。
    keytool -genseckey -alias KEYSTORE_NAME -keyalg AES -keysize 256 \
    -keystore kekstore.p12 -storetype PKCS12

    プロンプトが表示されたら、パスワードを入力します。このパスワードは、後のセクションで Management Server と Message Processor を構成するときに使用します。

    このコマンドにより、エイリアス KEYSTORE_NAME の鍵を含む kekstore.p12 キーストア ファイルが生成されます。

  2. (省略可)次のコマンドを使用して、ファイルが正しく生成されたことを確認します。ファイルが正しい場合、エイリアス KEYSTORE_NAME を持つキーが返されます。
    keytool -list -keystore kekstore.p12

手順 2: 管理サーバーを構成する

次に、管理サーバーを構成します。複数のノードに管理サーバーをインストールしている場合は、各ノードでこれらの手順を繰り返す必要があります。

  1. 手順 1 で生成したキーストア ファイルを、管理サーバーノードのディレクトリ(/opt/apigee/customer/application など)にコピーします。次に例を示します。
    cp certs/kekstore.p12 /opt/apigee/customer/application
  2. apigee ユーザーがファイルを読み取れることを確認します。
    chown apigee:apigee /opt/apigee/customer/application/kekstore.p12
    chmod 400 /opt/apigee/customer/application/kekstore.p12
  3. /opt/apigee/customer/application/management-server.properties に次のプロパティを追加します。ファイルが存在しない場合は作成します。プロパティ ファイル リファレンスもご覧ください。
    conf_keymanagement_kmscred.encryption.enabled=true
    
    # Fallback is true to ensure your existing plaintext credentials continue to work
    conf_keymanagement_kmscred.encryption.allowFallback=true
    
    conf_keymanagement_kmscred.encryption.keystore.path=PATH_TO_KEYSTORE_FILE
    conf_keymanagement_kmscred.encryption.kek.alias=KEYSTORE_NAME
    
    # These could alternately be set as environment variables. These variables should be
    # accessible to Apigee user during bootup of the Java process. If environment
    # variables are specified, you can skip the password configs below.
    # KMSCRED_ENCRYPTION_KEYSTORE_PASS=
    # KMSCRED_ENCRYPTION_KEK_PASS=
    See also Using environment variables for configuration properties.
    
    conf_keymanagement_kmscred.encryption.keystore.pass=KEYSTORE_PASSWORD
    conf_keymanagement_kmscred.encryption.kek.pass=KEK_PASSWORD

    キーストアの生成に使用するツールによっては、KEK_PASSWORDKEYSTORE_PASSWORD と同じになる場合があります。

  4. 次のコマンドを使用して、管理サーバーを再起動します。
    /opt/apigee/apigee-service/bin/apigee-service edge-management-server restart
    /opt/apigee/apigee-service/bin/apigee-service edge-management-server wait_for_ready

    Management Server の準備が整うと、wait_for_ready コマンドから次のメッセージが返されます。

    Checking if management-server is up: management-server is up.
    
  5. 複数のノードに Management Server がインストールされている場合は、各 Management Server ノードで上記の手順 1 ~ 4 を繰り返します。

ステップ 3: デベロッパー アプリを作成する

Management Server が更新されたので、クライアントの認証情報データの暗号化に使用する鍵の生成をトリガーするデベロッパー アプリを作成する必要があります。

  1. データ暗号鍵(KEK)の作成をトリガーするデベロッパー アプリを作成します。手順については、アプリの登録をご覧ください。
  2. 必要に応じてデベロッパー アプリを削除します。暗号鍵を生成した後は、これを保持する必要はありません。

ステップ 4: Message Processor を構成する

Message Processor で暗号化が有効になるまで、ランタイム リクエストは暗号化された認証情報を処理できません。

  1. 手順 1 で生成したキーストア ファイルを、Message Processor ノードのディレクトリ(/opt/apigee/customer/application など)にコピーします。次に例を示します。
    cp certs/kekstore.p12 /opt/apigee/customer/application
  2. apigee ユーザーがファイルを読み取れることを確認します。
    chown apigee:apigee /opt/apigee/customer/application/kekstore.p12
  3. /opt/apigee/customer/application/message-processor.properties に次のプロパティを追加します。ファイルが存在しない場合は作成します。プロパティ ファイル リファレンスもご覧ください。
    conf_keymanagement_kmscred.encryption.enabled=true
    
    # Fallback is true to ensure your existing plaintext credentials continue to work
    conf_keymanagement_kmscred.encryption.allowFallback=true
    
    conf_keymanagement_kmscred.encryption.keystore.path=PATH_TO_KEYSTORE_FILE
    conf_keymanagement_kmscred.encryption.kek.alias=KEYSTORE_NAME
    
    # These could alternately be set as environment variables. These variables should be
    # accessible to Apigee user during bootup of the Java process. If environment
    # variables are specified, you can skip the password configs below.
    # KMSCRED_ENCRYPTION_KEYSTORE_PASS=
    # KMSCRED_ENCRYPTION_KEK_PASS=
    See also Using environment variables for configuration properties.
    
    
    conf_keymanagement_kmscred.encryption.keystore.pass=KEYSTORE_PASSWORD
    conf_keymanagement_kmscred.encryption.kek.pass=KEK_PASSWORD

    キーストアの生成に使用するツールによっては、KEK_PASSWORDKEYSTORE_PASSWORD と同じになる場合があります。

  4. 次のコマンドを使用して、Message Processor を再起動します。
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor wait_for_ready

    Message Processor でメッセージを処理する準備が整うと、wait_for_ready コマンドから次のメッセージが返されます。

    Checking if message-processor is up: message-processor is up.
  5. 複数のノードに Message Processor がインストールされている場合は、各 Message Processor ノードで手順 1 ~ 4 を繰り返します。

概要

今後作成するデベロッパー アプリの場合、Cassandra データベースで認証情報のシークレットが暗号化されることになります。

構成プロパティに環境変数を使用する

環境変数を使用して、次の Message Processor と Management Server の構成プロパティを設定することもできます。設定すると、環境変数は、Message Processor または Management Server の構成ファイルに設定されているプロパティをオーバーライドします。

conf_keymanagement_kmscred.encryption.keystore.pass=
conf_keymanagement_kmscred.encryption.kek.pass=

対応する環境変数は次のとおりです。

export KMSCRED_ENCRYPTION_KEYSTORE_PASS=KEYSTORE_PASSWORD
export KMSCRED_ENCRYPTION_KEK_PASS=KEK_PASSWORD

これらの環境変数を設定する場合、これらの構成プロパティは無視されるため、Message Processor ノードと Management Server ノードの構成ファイルから省略できます。

conf_keymanagement_kmscred.encryption.keystore.pass
conf_keymanagement_kmscred.encryption.kek.pass

プロパティ ファイル リファレンス

このセクションでは、このドキュメントで前述したように、すべての Message Processor ノードと Management Server ノードで設定する必要がある構成プロパティについて説明します。

プロパティ デフォルト 説明
conf_keymanagement_kmscred.encryption.enabled false 鍵の暗号化を有効にするには、true にする必要があります。
conf_keymanagement_kmscred.encryption.allowFallback false 既存の平文の認証情報が引き続き機能するように、allowFallback を true に設定します。
conf_keymanagement_kmscred.encryption.keystore.path なし Message Processor または Management Server ノード上の KEK キーストアへのパスを指定します。ステップ 2: 管理サーバーを構成するステップ 3: Message Processor を構成するをご覧ください。
conf_keymanagement_kmscred.encryption.kek.alias なし KEK がキーストアに保存されているエイリアス。
conf_keymanagement_kmscred.encryption.keystore.pass なし 環境変数を使用してこれらのプロパティを設定する場合は省略可能です。構成プロパティに環境変数を使用するもご覧ください。
conf_keymanagement_kmscred.encryption.kek.pass なし 環境変数を使用してこれらのプロパティを設定する場合は省略可能です。構成プロパティに環境変数を使用するもご覧ください。