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

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

概要

従来から、Apigee Edge for Private Cloud には Key-Value マップ（KVM）データと OAuth アクセス トークンを暗号化するオプション機能が備わっています。

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

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

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

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

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

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

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

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

鍵を保護する

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

FIPS 対応オペレーティング システムの BCFKS キーストアの操作

FIPS 対応のオペレーティング システムで Edge for Private Cloud を使用している場合は、BCFKS タイプのキーストアを生成する必要があります。このようなキーストアは、FIPS 以外のマシンで生成してから、FIPS 準拠のマシンに転送できます。キーストアを生成するには、次のコマンドを使用します。

keytool -genseckey -alias <KEYSTORE_NAME> -keyalg AES -keysize 256 \
-storetype BCFKS -keystore keystore.bcfks \
-providerpath /opt/apigee/edge-gateway/lib/thirdparty/bc-fips-1.0.2.4.jar \
-providerclass org.bouncycastle.jcajce.provider.BouncyCastleFipsProvider \
-keypass keystorepass -storepass keystorepass

このキーストアを生成するマシンで、追加の Java 設定を行う必要がある場合があります。マシンの Java セキュリティ ファイル（通常は /usr/lib/jvm/jre/lib/security/java.security にあります）を編集する必要がある場合があります。このファイルで、次のプロパティを見つけて編集します。

# Don't rely on /dev/random for generating random numbers
securerandom.source=file:/dev/urandom
securerandom.strongAlgorithms=PKCS11:SunPKCS11-NSS-FIPS

ステップ 2: Management Server を構成する

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

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_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-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 と管理サーバーの構成プロパティを設定することもできます。設定されている場合、この環境変数は、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 ノードに設定する必要がある構成プロパティについて説明します。