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

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

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

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

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

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

    双方向 TLS では、クライアントとサーバーの両方が、相互認証に使用される独自の証明書と秘密鍵を使用して、キーストアを維持します。
  • トラストストアには、TLS ハンドシェイクの一部として受け取った証明書の検証に使用する証明書が含まれています。

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

    たとえば、自己署名証明書を使用する 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 でサポートされる鍵のサイズは、2048 ビットまでです。パスフレーズは任意です。

トラストストアはキーストアと似ていますが、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 を本番環境にプッシュできますが、本番環境にデプロイする前に、自身で作成した証明書とキーを含んだ独自のキーストアを作成するのが一般的です。

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 でも表示できます。

  1. https://enterprise.apigee.com(クラウド)または http://<ms-ip>:9000(オンプレミス)で Edge 管理 UI にログインします。ここで、<ms-ip> は Management Server ノードの IP アドレスです。
  2. 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 でも表示できます。

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

Edge UI では、証明書の期限切れを Edge が示すまでの時間間隔を指定できます。デフォルトでは、UI は次の 10 日の間に有効期限が切れる予定の証明書をハイライト表示します。

キーストアを作成する

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

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

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

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

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

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

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

    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 ハンドシェイク処理の一環としてサーバーが client_cert_1 をクライアントに送信すると、クライアント認証が成功します。

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

サーバーが TLS ハンドシェイクの一環として 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 呼出しが失敗します。