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

このドキュメントでは、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 機能を有効にする方法について説明します。この機能を使用すると、Apigee は、デベロッパー アプリのコンシューマ シークレットの暗号化に使われる秘密鍵が 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: Management Server を構成する

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

  1. ステップ 1 で生成したキーストア ファイルを、Management Server ノード上のディレクトリ（/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_PASSWORD が KEYSTORE_PASSWORD と同じになる場合があります。

  4. 次のコマンドを使用して、Management Server を再起動します。 
    /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_PASSWORD が KEYSTORE_PASSWORD と同じになる場合があります。

  4. 次のコマンドを使用して Message Processor を再起動します。 
    /opt/apigee/apigee-service/bin/apigee-service edge-message-processor restart
    /opt/apigee/apigee-service/bin/apigee-service edge-management-server 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: Management Server を構成するとステップ 3: Message Processor を構成するをご覧ください。
conf_keymanagement_kmscred.encryption.kek.alias なし キーストアに保存される KEK のエイリアス。
conf_keymanagement_kmscred.encryption.keystore.pass なし 環境変数を使用してこれらのプロパティを設定する場合は省略可能です。構成プロパティに環境変数を使用するもご覧ください。
conf_keymanagement_kmscred.encryption.kek.pass なし 環境変数を使用してこれらのプロパティを設定する場合は省略可能です。構成プロパティに環境変数を使用するもご覧ください。