Private Cloud バージョン 4.17.09 以前でキーストアとトラストストアを作成する

このドキュメントでは、Edge for Private Cloud バージョン 4.17.09 以前でキーストアとトラストストアを作成、変更、削除する方法について説明します。

キーストアとトラストストアについて

キーストアとトラストストアは、TLS 暗号化に使用されるセキュリティ証明書のリポジトリを定義します。2 つのストアの主な違いは、TLS handshake プロセス内のどこで使用されるかです。

キーストアには、TLS handshake 中にエンティティの識別に使用される TLS 証明書と秘密鍵が含まれています。

一方向 TLS では、クライアントがサーバーの TLS エンドポイントに接続するときに、サーバーのキーストアによってサーバーの証明書（公開証明書）がクライアントに提示されます。クライアントはその証明書を、Symantec や VeriSign などの認証局（CA）で検証します。

双方向 TLS では、クライアントとサーバーの両方が、相互認証に使用されるそれぞれの固有の証明書と秘密鍵を含むキーストアを維持します。
トラストストアには、TLS handshake の一環として受け取った証明書の検証に使用する証明書が含まれています。

一方向 TLS では、有効な CA によって証明書が署名されている場合、トラストストアは必要ありません。受け取った証明書が有効な CA によって署名されている場合、TLS クライアントは証明書を認証するよう CA にリクエストします。通常、TLS クライアントはトラストストアを使用して、TLS サーバーから受け取った自己署名証明書、または信頼できる CA によって署名されていない証明書を検証します。このシナリオでは、クライアントは信頼できる証明書をトラストストアに格納します。クライアントはサーバー証明書を受け取ると、その証明書をトラストストア内の証明書と照合して検証します。

たとえば、自己署名証明書を使用する TLS サーバーに TLS クライアントが接続するとします。自己署名証明書であるため、クライアントはこれを CA で検証することはできません。その代わりに、クライアントはサーバーの自己署名証明書をトラストストアにプリロードします。その後、クライアントはサーバーへの接続を試行したとき、トラストストアを使用してサーバーから受け取った証明書を検証します。

双方向 TLS の場合、トラストストアは TLS クライアントと TLS サーバーの両方で使用できます。Edge を TLS サーバーとした双方向 TLS を行う場合、トラストストアは必須です。

証明書は認証局（CA）が発行できますが、自分で生成した秘密鍵によって証明書に自己署名することもできます。CA にアクセスできる場合は、CA から提供された手順に沿って鍵を生成し、証明書を発行します。CA にアクセスできない場合は、一般公開されているさまざまな無料ツール（openssl など）のいずれかを使用して、自己署名証明書を生成できます。

Edge でのキーストアとトラストストアの実装

Edge 上のキーストアには、1 つ以上の JAR ファイルが含まれています。この JAR ファイルには次のものが含まれています。

PEM ファイル形式の TLS 証明書 - 認証局（CA）によって署名された証明書、最後の証明書が CA によって署名されている証明書チェーン、または自己署名証明書のいずれか。
PEM ファイル形式の秘密鍵。Edge でサポートされる鍵のサイズは、2,048 ビットまでです。パスフレーズは任意です。

トラストストアはキーストアと似ていますが、PEM ファイルとして含まれるのは証明書のみで、秘密鍵は含まれません。

証明書がチェーンの一部である場合は、チェーン内のすべての証明書が個別の PEM ファイルまたは単一のファイルとしてキーストア / トラストストアに含まれている必要があります。単一のファイルを使用する場合は、ファイル内の最初の証明書が TLS に使用される証明書で、その後に証明書チェーンが正しい順序で続き、最後に CA 証明書が配置されている必要があります。ファイル内の各証明書の間には空白の行を挿入します。

Edge には、キーストアとトラストストアの作成に使用する API が用意されています。実際の API は同じです。両者の違いは、キーストアを作成するときには証明書と秘密鍵を含む JAR ファイルを渡すことです。トラストストアを作成するときは、証明書のみを PEM ファイルとして渡します。

証明書と鍵のファイルの形式について

このドキュメントの例で示す TLS 証明書と鍵は、X.509 形式に準拠した PEM ファイルとして定義されています。証明書または秘密鍵が PEM ファイルとして定義されていない場合は、openssl などのユーティリティを使用して PEM ファイルに変換できます。

ただし、多くの .crt ファイルと .key ファイルはすでに PEM 形式になっています。これらのファイルがテキストファイルで、次の行で囲まれている場合があります。

-----BEGIN CERTIFICATE-----
-----END CERTIFICATE-----

または

-----BEGIN ENCRYPTED PRIVATE KEY-----
-----END ENCRYPTED PRIVATE KEY-----

この場合、これらのファイルは PEM 形式と互換性があり、PEM ファイルに変換しなくてもキーストアまたはトラストストアで使用できます。

証明書チェーンがあり、そのチェーンをキーストアまたはトラストストアで使用する場合、すべての証明書を 1 つの PEM ファイルにまとめて、各証明書の間に改行を入れます。証明書は正しい順序で並んでいなければならず、最後の証明書はルート証明書、またはルート証明書によって署名された中間証明書でなければなりません。

-----BEGIN CERTIFICATE-----
(Your Primary TLS certificate)
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
(Intermediate certificate)
-----END CERTIFICATE-----

-----BEGIN CERTIFICATE-----
(Root certificate or intermediate certificate signed by a root certificate)
-----END CERTIFICATE-----

既存のキーストアの詳細を取得する

キーストアとトラストストアの一覧表示 API を使用して、環境に既存のキーストアが存在するかどうかを確認します。

curl -X GET \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password

Cloud のお客様には、無料トライアル組織用のデフォルトのキーストアがテスト環境と本番環境の両方で提供されます。この呼び出しの結果はどちらの環境でも次のようになります。

[ "freetrial" ]

このデフォルトのキーストアを使用して API をテストし、API を本番環境に push することもできますが、通常は、本番環境にデプロイする前に、自分で作成した証明書と鍵を含む独自のキーストアを作成します。

Private Cloud のお客様は、最初のキーストアを作成するまで、空白の配列が返されます。

キーストアまたはトラストストアの取得 API を使用して、キーストアの内容を確認します。Cloud のお客様には、サーバー TLS 証明書が 1 つ表示されます。これは、無料トライアルアカウント用に Apigee Edge から提供されるデフォルトの証明書です。

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password

レスポンスは次のように表示されます。

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

この情報は、Edge 管理 UI でも確認できます。

https://enterprise.apigee.com（クラウド）またはhttp://<ms-ip>:9000（オンプレミス）にアクセスし、Edge 管理 UI にログインします。ここで、<ms-ip> は Management Server ノードの IP アドレスです。
Edge 管理 UI のメニューで、[Admin] > [TLS Certificates] を選択します。

TLS 証明書の詳細を取得する

キーストアまたはトラストストアからの証明書詳細の取得 API を使用して、有効期限や発行者といったキーストア内の TLS 証明書の詳細を表示できます。まず、対象の証明書の名前を取得します。この例では、「freetrial」というキーストアの情報を取得します。

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial \
-u email:password

レスポンスの例:

{
 "certs" : [ "wildcard.apigee.net.crt" ],
 "keys" : [ "freetrial" ],
 "name" : "freetrial"
}

次に、certs プロパティの値を使用して証明書の詳細を取得します。

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/freetrial/certs/wildcard.apigee.net.crt \
-u email:password

レスポンスの例:

{
 "certInfo" : [ {
   "expiryDate" : "Wed, 23 Apr 2014 20:50:02 UTC",
   "isValid" : "Yes",
   "issuer" : "CN=Go Daddy Secure Certificate Authority - G2, OU=http://certs.godaddy.com/repository/, O=&quot;GoDaddy.com, Inc.&quot;, L=Scottsdale, ST=Arizona, C=US",
   "subject" : CN=*.example.apigee.net, OU=Domain Control Validated",
   "subjectAlternativeNames" : ["*.example.apigee.net","*.example.apigee.net" ],
   "validFrom" : "Tue, 15 Apr 2014 09:17:03 UTC",
   "version" : 3
 } ],
 "name" : "example.apigee.net.crt"
}

この情報は、Edge 管理 UI でも確認できます。

https://enterprise.apigee.com（クラウド）またはhttp://<ms-ip>:9000（オンプレミス）にアクセスし、Edge 管理 UI にログインします。ここで、<ms-ip> は Management Server ノードの IP アドレスです。
Edge 管理 UI のメニューで、[Admin] > [TLS Certificates] を選択します。

Edge UI では、まもなく有効期限が切れる証明書を識別するために、有効期限までの時間間隔を指定できます。デフォルトでは、今後 10 日の間に有効期限が切れる証明書が強調表示されます。

キーストアを作成する

キーストアは組織内の環境、たとえばテスト環境や本番環境に固有のものです。したがって、本番環境にデプロイする前にテスト環境でキーストアをテストする場合は、両方の環境でキーストアを作成する必要があります。

次の 2 段階の手順で、キーストアを作成します。

証明書と秘密鍵を含む JAR ファイルを作成します。
キーストアを作成し、JAR ファイルをアップロードします。

証明書と秘密鍵を含む JAR ファイルを作成する

秘密鍵、証明書、マニフェストを含む JAR ファイルを作成します。この JAR ファイルには、次のファイルとディレクトリが含まれている必要があります。

/META-INF/descriptor.properties
myCert.pem
myKey.pem

注: キーストア JAR に含めることができる証明書は 1 つだけです。証明書チェーンがある場合は、チェーン内のすべての証明書を単一の PEM ファイルに追加する必要があります。CA によって署名された証明書を最後に配置し、各証明書を改行で区切ります。証明書は次のように正しい順序で PEM ファイルに追加する必要があります。

cert -> intermediate cert(1) -> intermediate cert(2) -> … -> root

鍵ペアと証明書を含むディレクトリに /META-INF というディレクトリを作成します。次に、descriptor.properties というファイルを /META-INF に作成し、次の内容を含めます。

certFile={myCertificate}.pem
keyFile={myKey}.pem

鍵ペアと証明書を含む JAR ファイルを生成します。

jar -cf myKeystore.jar myCert.pem myKey.pem

JAR ファイルに descriptor.properties を追加します。

jar -uf myKeystore.jar META-INF/descriptor.properties

キーストアを作成して JAR ファイルをアップロードする

環境にキーストアを作成するには、キーストアまたはトラストストアの作成 API にキーストア名を渡すだけです。名前には英数字のみを使用できます。

curl -X POST -H "Content-Type: text/xml" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-d '<KeyStore name="myKeystore"/>' -u email:password

レスポンスの例:

{
 "certs" : [ ],
 "keys" : [ ],
 "name" : "myKeystore"
}

名前付きのキーストアを環境に作成した後、キーストアへの JAR ファイルのアップロード API を使用して、証明書と秘密鍵を含む JAR ファイルをアップロードできます。

curl -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.jar" -F password={key_pass} \ "https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/{myKeystore}/keys?alias={key_alias}" \
-u email:password

ここで、-F オプションは JAR ファイルへのパスを指定します。

この呼び出しでは、次の 2 つのクエリパラメータを指定します。

alias - キーストア内の証明書と鍵を識別します。仮想ホストを作成するとき、このエイリアス名によって証明書と鍵を参照します。
password - 秘密鍵のパスワード。秘密鍵にパスワードがない場合、このパラメータは省略します。

キーストアが正しくアップロードされたことを確認します。

curl https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystore \
-u email:password

レスポンスの例:

{
 "certs" : [ "myCertificate" ],
 "keys" : [ "myKey" ],
 "name" : "myKeystore"
}

トラストストアを作成する

トラストストアの作成に使用する API は、キーストアの作成に使用した API と同じです。唯一の違いは、証明書ファイルを JAR ファイルではなく PEM ファイルとして渡すことです。

証明書がチェーンの一部である場合は、チェーン内のすべての証明書をトラストストアに個別にアップロードするか、すべての証明書を含む単一のファイルを作成する必要があります。ファイル内の各証明書の間には改行を入れます。最後の証明書は通常、証明書の発行者によって署名された証明書にします。たとえば、クライアント証明書 client_cert_1 とこのクライアント証明書の発行元の証明書 ca_cert をトラストストアにアップロードします。

双方向 TLS 認証では、TLS handshake プロセスの一環としてサーバーが client_cert_1 をクライアントに送信すると、クライアント認証が成功します。

別の例として、同じ証明書 ca_cert で署名された 2 番目の証明書 client_cert_2 があるとします。ただし、client_cert_2 はトラストストアにアップロードしません。トラストストアには引き続き client_cert_1 と ca_cert が格納されています。

サーバーが TLS handshake の一環として client_cert_2 を渡すと、リクエストは成功します。これは、client_cert_2 がトラストストアに存在しなくても、それがトラストストアに存在する証明書によって署名されていれば、Edge での TLS 検証は成功するためです。トラストストアから CA 証明書 ca_cert を削除すると、TLS 検証は失敗します。

キーストアの作成に使用した API と同じキーストアまたはトラストストアの作成 API を使用して、空のトラストストアを環境に作成します。

curl -X POST -H "Content-Type: text/xml" -d \
'<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores \
-u email:password

トラストストアへの証明書のアップロード API を使用して、証明書を PEM ファイルとしてトラストストアにアップロードします。

curl -X POST -H "Content-Type: multipart/form-data" -F file="@trust.pem" \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myTruststore/certs?alias=myTruststore \
-u email:password

ここで、-F オプションは PEM ファイルへのパスを指定します。

キーストアまたはトラストストアを削除する

キーストアまたはトラストストアを削除するには、キーストアまたはトラストストアの削除 API を使用します。

curl -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/environments/{env_name}/keystores/myKeystoreName \
-u email:password

レスポンスの例:

{
 "certs" : [ ],
 "keys" : [ ],
 "name" : "myKeystoreName"
}

仮想ホストまたはターゲットエンドポイント / ターゲットサーバーによって使用されているキーストアまたはトラストストアを削除すると、仮想ホストまたはターゲットエンドポイント / ターゲットサーバーを経由する API 呼出しはすべて失敗します。