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

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

概要

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

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

キーストアの作成

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

環境内にキーストアを作成する方法は以下のとおりです。

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

キーストアを作成するには、キーストアまたはトラストストアの作成 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 つのファイルだけです。証明書チェーンを構成している場合、チェーン内の証明書をすべて 1 つの PEM ファイルに追加し、ルート CA によって署名された証明書を最後につなぐ必要があります。次に示すように、各証明書の間に空白の行を入れて、正しい順序で証明書を PEM ファイルに追加する必要があります。

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

鍵ペアと証明書を含むディレクトリに、/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 ファイルまたは 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 を本番環境にプッシュできますが、本番環境にデプロイする前に、自身で作成した証明書とキーを含んだ独自のキーストアを作成するのが一般的です。

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 に使用される新しい証明書をトラストストアに追加するには、次の手順を行います。

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

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

キーストアやトラストストア、エイリアスの削除

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

通常、キーストアやトラストストア、エイリアスを削除するために使用するプロセスは、次のとおりです。

  1. 上記のように、新しいキーストアやトラストストア、エイリアスを作成します。
  2. インバウンド接続、つまり Edge への API リクエストの場合、新しいキーストアとキーエイリアスを参照するように仮想ホスト構成を更新します。
  3. アウトバウンド接続、つまり 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}