Edge 管理 API を使用したキーストアとトラストストアの作成

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

注: 以下の API の例では、Cloud 用の Edge 管理 API の URL（https://api.enterprise.apigee.com）に対してリクエストを送信しています。Private Cloud の場合は、URL を https://MS_IP:8080 に置き換えてください。ここで、MS_IP は Management Server の IP アドレスです。

はじめに

TLS などの公開鍵基盤に依存する機能を構成するには、必要な鍵とデジタル証明書を提供するキーストアとトラストストアを作成する必要があります。

キーストア、トラストストア、エイリアスの概要については、キーストアとトラストストアをご覧ください。

キーストアを作成する

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

キーストアを環境に作成するには:

このセクションの API 呼び出しを使用してキーストアを作成します。
エイリアスを作成し、証明書と鍵のペアをエイリアスにアップロードします。証明書と鍵をアップロードする方法は、証明書と鍵のペアの形式に基づきます。以降のセクションで、各タイプの証明書と鍵のペアをアップロードする方法について説明します。

キーストアを作成するには、キーストアまたはトラストストアの作成 API にキーストア名を指定します。キーストア名に使用できるのは英数字のみです。

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

レスポンスの例:

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

証明書と鍵を JAR ファイルとしてアップロードする

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

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

キーストア JAR に含めることができるのは、これら 3 つのファイルだけです。証明書チェーンがある場合は、チェーン内のすべての証明書を単一の 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 または PKCS ファイルからエイリアスを作成 API を使用して、証明書と秘密鍵を含む JAR ファイルをアップロードできるようになりました。

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F file="@myKeystore.jar" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertjar"

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

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

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

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

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

レスポンスの例:

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

証明書と鍵を PEM ファイルとしてアップロードする

証明書と鍵 PEM ファイルからエイリアスを作成 API を使用して、証明書と秘密鍵を含む PEM ファイルをアップロードします。

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F keyFile="@server.key" -F certFile="@signed.crt" \
-F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=keycertfile"

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

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

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

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

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

レスポンスの例:

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

証明書と鍵を PKCS12 / PFX ファイルとしてアップロードする

JAR または PKCS ファイルからエイリアスを作成 API を使用して、証明書と秘密鍵を含む PKCS12 / PFX ファイルをアップロードします。

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" \
-F file="@myKeystore.p12" -F password={key_pword} \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?alias={alias_name}&format=pkcs12"

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

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

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

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

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

レスポンスの例:

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

自己署名証明書と鍵をアップロードする

自己署名証明書を生成してエイリアスを作成 API を使用することで、自己署名証明書と鍵を作成してエイリアスにアップロードできます。次の呼び出しでは、自己署名証明書を作成するために必要な情報のみを指定しています。この呼び出しを変更して、追加情報を追加できます。

curl -u orgAdminEmail:password -X POST --header "Content-Type: application/json"  \
-d "{
    "alias": "selfsigned",
    "subject": {
        "commonName": "mycert"
    }
}" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases?format=selfsignedcert"

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

{
  "alias": "selfsigned",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:FALSE",
        "expiryDate": 1491497204000,
        "isValid": "Yes",
        "issuer": "CN=mycert",
        "publicKey": "RSA Public Key, 2048 bits",
        "serialNumber": "00:d1:b4:78:e1",
        "sigAlgName": "SHA256withRSA",
        "subject": "CN=mycert",
        "subjectAlternativeNames": [],
        "validFrom": 1459961204000,
        "version": 3
      }
    ],
    "certName": "selfsigned-cert"
  },
  "keyName": "selfsigned"
}

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

トラストストアの作成に使用する API は、キーストアの作成に使用した API と同じです。唯一の違いは、証明書ファイルだけを PEM ファイルとしてトラストストアにアップロードすることです。

証明書がチェーンの一部である場合は、チェーン内のすべての証明書をトラストストアに個別にアップロードするか、すべての証明書を含む単一のファイルを作成する必要があります。ファイル内の各証明書の間には空白の行を挿入します。

チェーンの一部ではない複数の自己署名証明書をアップロードする場合も、同じ手法を使用します。つまり、信頼する複数の証明書がある場合は、すべての証明書を 1 つのファイルにまとめてアップロードします。

最後の証明書は通常、証明書の発行者によって署名された証明書にします。たとえば、クライアント証明書 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 -u orgAdminEmail:password -X POST -H "Content-Type: text/xml" \
-d '<KeyStore name="myTruststore"/>' \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores

トラストストアを作成したら、証明書 PEM ファイルからエイリアスを作成 API を使用して、証明書を PEM ファイルとしてトラストストアにアップロードします。

curl -u orgAdminEmail:password -X POST -H "Content-Type: multipart/form-data" -F certFile="@cert.pem" \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myTruststore/aliases?alias=myTruststore&format=keycertfile"

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

既存のキーストアまたはトラストストアの詳細を確認する

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

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

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

[ "freetrial" ]

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

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

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

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

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

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

エイリアスの詳細を確認する

エイリアスの一覧表示 API を使用して、キーストアのすべてのエイリアスのリストを取得します。

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases"

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

[
  "alias1",
  "alias2",
  "alias3",
]

有効期限や発行者といったエイリアスに関するすべての情報を取得するには、エイリアスの取得 API を使用してエイリアス名を指定します。

curl  -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}"

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

{
  "alias": "alias1",
  "certsInfo": {
    "certInfo": [
      {
        "basicConstraints": "CA:TRUE",
        "expiryDate": 1459371335000,
        "isValid": "No",
        "issuer": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "publicKey": "RSA Public Key, 1024 bits",
        "serialNumber": "00:86:a0:9b:5b:91:a9:fe:92",
        "sigAlgName": "SHA256withRSA",
        "subject": "EMAILADDRESS=foo@bar.com, CN=smg, OU=doc, O=Internet Widgits Pty Ltd, L=noho, ST=Some-State, C=AU",
        "subjectAlternativeNames": [],
        "validFrom": 1456779335000,
        "version": 3
      }
    ],
    "certName": "new\-cert"
  },
  "keyName": "newssl20"
}

エイリアスの証明書をダウンロードするには、エイリアスの証明書のエクスポート API を使用します。

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/e/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/certificate"

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

-----BEGIN CERTIFICATE-----
MIIDojCCAwugAwIBAgIJAIagm1uRqf6SMA0GCSqGSIb3DQEBCwUAMIGTMQswCQYD
...
RBUkaTe/570sLHY0tvkIm5tEX36ESw==
-----END CERTIFICATE-----

期限切れの証明書があり、その証明書を更新する場合は、証明書署名リクエスト（CSR）をダウンロードできます。ダウンロードした CSR を CA に送信して新しい証明書を取得します。エイリアスの CSR を生成するには、エイリアスの CSR の生成 API を使用します。

curl -u orgAdminEmail:password -X GET \
"https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/{keystore_name}/aliases/{alias_name}/csr"

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

-----BEGIN CERTIFICATE REQUEST-----
MIIB1DCCAT0CAQAwgZMxCzAJBgNVBAYTAkFVMRMwEQYDVQQIEwpTb21lLVN0YXRl
...
RF5RMytbkxkvPxIE17mDKJH0d8aekv/iEOItZ+BtQg+EibMUkkjTzQ==
-----END CERTIFICATE REQUEST-----

双方向 TLS のトラストストアに証明書を追加する

インバウンド接続（Edge への API リクエスト）に対して双方向 TLS を使用する場合、トラストストアには、Edge にリクエストを行うことが許可された各クライアントの証明書または CA チェーンが格納されます。

最初にトラストストアを構成するときに、既知のクライアントのすべての証明書を追加できます。ただし、その後新しいクライアントを追加するときに、トラストストアにさらに証明書を追加しなければならない場合もあります。

双方向 TLS に使用される新しい証明書をトラストストアに追加するには:

仮想ホストでトラストストアへの参照を使用していることを確認します。
上記のトラストストアを作成するの説明に従って、新しい証明書をトラストストアにアップロードします。
トラストストアへの参照を更新して、同じ値に設定します。この更新により、トラストストアと新しい証明書が再読み込みされます。

詳細については、参照の変更をご覧ください。

キーストア / トラストストアまたはエイリアスを削除する

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

通常、キーストア / トラストストアまたはエイリアスを削除する際は次のプロセスに従います。

上記の説明に従って、新しいキーストア / トラストストアまたはエイリアスを作成します。
インバウンド接続（Edge への API リクエスト）の場合は、仮想ホストの構成を更新して新しいキーストアとキーエイリアスを参照します。
アウトバウンド接続（Apigee からバックエンドサーバーへの接続）の場合は、次のようにします。
1. 古いキーストアとキーエイリアスを参照していた API プロキシの TargetEndpoint 構成を更新して、新しいキーストアとキーエイリアスを参照します。TargetEndpoint が TargetServer を参照している場合は、TargetServer の定義を更新して新しいキーストアとキーエイリアスを参照します。
2. キーストアとトラストストアが TargetEndpoint の定義から直接参照されている場合は、プロキシを再デプロイする必要があります。TargetEndpoint が TargetServer の定義を参照し、TargetServer の定義からキーストアとトラストストアを参照している場合、プロキシの再デプロイは必要ありません。
3. API プロキシが正しく機能していることを確認します。
4. キーストア / トラストストアまたはエイリアスを削除します。

詳細については、エイリアスの証明書を更新するをご覧ください。

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

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

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

仮想ホストによって使用されているキーストアまたはトラストストアを削除して再作成する場合は、API プロキシを再デプロイする必要があります。

エイリアスを削除する

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

curl -u orgAdminEmail:password -X DELETE \
https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/keystores/myKeystoreName/aliases/{alias_name}