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

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

Edge Cloud のキーストア / トラストストアと仮想ホストについて

Edge Cloud のキーストア / トラストストアの作成プロセスでは、仮想ホストの使用についてのすべてのルールに従う必要があります。たとえば、Cloud の仮想ホストには次の前提条件があります。

  • 仮想ホストで TLS を使用する必要がある。
  • 仮想ホストではポート 443 のみを使用できる。
  • 署名済みの TLS 証明書を使用する必要がある。署名なしの証明書は Cloud の仮想ホストでは使用できない。
  • TLS 証明書で指定されるドメイン名が、仮想ホストのホスト エイリアスと一致している必要がある。

詳細:

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

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

Edge では、キーストアとトラストストアはどちらも、1 つ以上のエイリアスを含むキーストア エンティティによって表されます。つまり、Edge ではキーストアとトラストストアの間に実装の違いはありません。

キーストアとトラストストアの違いは、これらに含まれるエントリの種類と、TLS handshake でそれぞれのストアがどのように使用されるかにあります。

  • キーストア - 1 つ以上のエイリアスを含むキーストア エンティティ。各エイリアスには証明書と鍵のペアが含まれます。
  • トラストストア - 1 つ以上のエイリアスを含むキーストア エンティティ。各エイリアスには証明書のみが含まれます。

仮想ホストまたはターゲット エンドポイント用に TLS を構成する場合、TLS handshake プロセスにおいてキーストアとトラストストアには異なる役割があります。仮想ホストまたはターゲット エンドポイントを構成するとき、キーストアとトラストストアを <SSLInfo> タグで別々に指定します。次に仮想ホストの例を示します。

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://keystoreref</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
</VirtualHost>

この例では、仮想ホストによって TLS キーストアに使用されるキーストアの名前とエイリアスを指定しています。参照を使用してキーストア名を指定すると、後で証明書の有効期限が切れたときに参照を変更できます。エイリアスには、仮想ホストにアクセスする TLS クライアントに対してこの仮想ホストを識別するための証明書と鍵のペアが含まれています。この例では、トラストストアは必要ありません。

トラストストアが必要な場合（双方向 TLS を構成する場合など）は、<TrustStore> タグを使用してトラストストアを指定します。

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>true</ClientAuthEnabled>
        <KeyStore>ref://keystoreref</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <TrustStore>ref://truststoreref</TrustStore>
    </SSLInfo>
</VirtualHost>

この例では、<TrustStore> タグでキーストアが参照されているだけで、特定のエイリアスは指定されていません。キーストアの各エイリアスには、TLS handshake プロセスの一環として使用される証明書（または証明書チェーン）が含まれます。

エイリアスの実装について

Edge では、キーストアには 1 つ以上のエイリアスが含まれており、キーストアの各エイリアスには次のものが含まれます。

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

Edge では、トラストストアには 1 つ以上のエイリアスが含まれており、トラストストアの各エイリアスには次のものが含まれます。

  • PEM ファイル形式の TLS 証明書 - 認証局（CA）によって署名された証明書、最後の証明書が CA によって署名されている証明書チェーン、または自己署名証明書のいずれか。

Edge には、キーストアの作成、エイリアスの作成、証明書と鍵のペアのアップロード、証明書のアップロードに使用する UI と API が用意されています。トラストストアの作成に使用する UI と API は、キーストアの作成に使用するものと同じです。両者の違いは、トラストストアを作成するときには証明書のみを含むエイリアスを作成するという点です。

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

証明書と鍵は、PEM ファイルまたは PKCS12 / PFX ファイルとして表現できます。PEM ファイルは X.509 形式に準拠します。証明書または秘密鍵が PEM ファイルとして定義されていない場合は、openssl などのユーティリティを使用して PEM ファイルに変換できます。

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

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

または

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

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

証明書チェーンについて

証明書がチェーンの一部である場合は、その証明書をキーストアとトラストストアのどちらで使用するかによって扱いが異なります。

  • キーストア: 証明書がチェーンの一部である場合は、チェーン内のすべての証明書を含む 1 つのファイルを作成する必要があります。証明書は正しい順序で並んでいなければならず、最後の証明書はルート証明書、またはルート証明書によって署名された中間証明書でなければなりません。
  • トラストストア: 証明書がチェーンの一部である場合は、すべての証明書を含む 1 つのファイルを作成してそのファイルを 1 つのエイリアスにアップロードするか、チェーン内のすべての証明書をトラストストアに個別にアップロードして証明書ごとに異なるエイリアスを使用する必要があります。1 つの証明書としてアップロードする場合、証明書は正しい順序で並んでいなければならず、最後の証明書はルート証明書、またはルート証明書によって署名された中間証明書でなければなりません。
  • 複数の証明書を含む 1 つのファイルを作成する場合は、各証明書の間に空白の行を挿入する必要があります。

たとえば、すべての証明書を 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-----

証明書が PKCS12 / PFX ファイルとして表されている場合は、次のように openssl コマンドを使用して証明書チェーンから PKCS12 / PFX ファイルを作成できます。

openssl pkcs12 -export -out certificate.pfx -inkey privateKey.key -in certificate.crt -certfile CACert.crt

トラストストア内の証明書チェーンを扱うとき、必ずしもチェーン内のすべての証明書をアップロードする必要はありません。たとえば、クライアント証明書 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 検証は失敗します。

TLS Keystores ページの使い方

次の手順に従って [TLS Keystores] ページにアクセスします。

Edge

Edge UI を使用して [TLS Keystores] ページにアクセスするには:

  1. https://apigee.com/edge にアクセスし、組織管理者としてログインします。
  2. 組織を選択します。
  3. [Admin] > [Environment] > [TLS Keystores] の順に選択します。

Classic Edge（Private Cloud）

Classic Edge UI を使用して [TLS Keystores] ページにアクセスするには:

  1. http://ms-ip:9000 にアクセスし、組織管理者としてログインします。ここで、ms-ip は Management Server ノードの IP アドレスまたは DNS 名です。
  2. 組織を選択します。
  3. [Admin] > [Environment Configuration] > [TLS Keystores] の順に選択します。

[TLS Keystores] ページが表示されます。

上の図に示すように、[TLS Keystores] ページでは次のことができます。

エイリアスの表示

エイリアスを表示するには:

  1. [TLS Keystores] ページにアクセスします。
  2. 環境を選択します（通常は prod または test）。
  3. 表示するエイリアスに対応する行をクリックします。

    エイリアスの証明書と鍵の詳細が表示されます。

    エイリアスに関するすべての情報（有効期限など）を確認できます。

  4. ページの上部にあるボタンを使用して、次のことができます。
    • 証明書を PEM ファイルとしてダウンロードします。
    • CSR を生成します。期限切れの証明書があり、その証明書を更新する場合は、証明書署名リクエスト（CSR）をダウンロードできます。ダウンロードした CSR を CA に送信して新しい証明書を取得します。
    • 証明書を更新します。注意: 仮想ホストまたはターゲット サーバー / ターゲット エンドポイントによって現在使用されている証明書を更新する場合は、Apigee サポートに連絡して Router と Message Processor を再起動する必要があります。証明書を更新するためのおすすめの方法は次のとおりです。
      1. 新しいキーストアまたはトラストストアを作成します。
      2. 新しい証明書を新しいキーストアまたはトラストストアに追加します。
      3. 仮想ホストまたはターゲット サーバー / ターゲット エンドポイント内の、キーストアまたはトラストストアへの参照を更新します。詳細については、Cloud の TLS 証明書を更新するをご覧ください。
      4. エイリアスを削除します。注: 仮想ホストまたはターゲット エンドポイントによって現在使用されているエイリアスを削除すると、その仮想ホストまたはターゲット エンドポイントは機能しなくなります。

キーストア / トラストストアとエイリアスの作成

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

キーストアを環境に作成するには、キーストア名のみを指定する必要があります。名前付きのキーストアを環境に作成した後、エイリアスを作成し、エイリアスに証明書と鍵のペアをアップロードするか（キーストア）、証明書のみをアップロードできます（トラストストア）。

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

  1. [TLS Keystores] ページにアクセスします。
  2. 環境を選択します（通常は prod または test）。
  3. [+ Keystore] をクリックします。
  4. キーストア名を指定します。名前に使用できるのは英数字のみです。
  5. [Add Keystore] をクリックします。新しいキーストアがリストに表示されます。
  6. 次のいずれかの手順を使用して、エイリアスを追加します。

証明書からのエイリアスの作成（トラストストアのみ）

証明書からエイリアスを作成するには:

  1. [TLS Keystores] ページにアクセスします。
  2. キーストアにカーソルを合わせて操作メニューを表示し、[+] をクリックします。
  3. [Alias Name] を指定します。
  4. [Certificate details] の [Type] プルダウンから [Certificate Only] を選択します。
  5. [Certificate File] の横にある [Choose File] をクリックし、証明書を含む PEM ファイルを選択して [Open] をクリックします。
  6. デフォルトでは、API によって証明書が期限切れでないことが確認されます。必要に応じて、[Allow Expired Certificate] を選択して検証をスキップします。
  7. [Save] を選択して証明書をアップロードし、エイリアスを作成します。

JAR ファイルからのエイリアスの作成（キーストアのみ）

JAR ファイルからエイリアスを作成するには:

  1. [TLS Keystores] ページにアクセスします。
  2. キーストアにカーソルを合わせて操作メニューを表示し、[+] をクリックします。
  3. [Alias Name] を指定します。
  4. [Certificate details] の [Type] プルダウンから [JAR File] を選択します。
  5. [JAR File] の横にある [Choose File] をクリックし、証明書と鍵を含む JAR ファイルを選択して [Open] をクリックします。
  6. 鍵にパスワードがある場合は、[Password] を指定します。鍵にパスワードがない場合、このフィールドは空白のままにします。
  7. デフォルトでは、API によって証明書が期限切れでないことが確認されます。必要に応じて、[Allow Expired Certificate] を選択して検証をスキップします。
  8. [Save] を選択して鍵と証明書をアップロードし、エイリアスを作成します。

証明書と鍵からのエイリアスの作成（キーストアのみ）

証明書と鍵からエイリアスを作成するには:

  1. [TLS Keystores] ページにアクセスします。
  2. キーストアにカーソルを合わせて操作メニューを表示し、[+] をクリックします。
  3. [Alias Name] を指定します。
  4. [Certificate details] の [Type] プルダウンから [Certificate and Key] を選択します。
  5. [Certificate File] の横にある [Choose File] をクリックし、証明書を含む PEM ファイルを選択して [Open] をクリックします。
  6. 鍵にパスワードがある場合は、[Key Password] を指定します。鍵にパスワードがない場合、このフィールドは空白のままにします。
  7. [Key File] の横にある [Choose File] をクリックし、鍵を含む PEM ファイルを選択して [Open] をクリックします。
  8. デフォルトでは、API によって証明書が期限切れでないことが確認されます。必要に応じて、[Allow Expired Certificate] を選択して検証をスキップします。
  9. [Save] を選択して鍵と証明書をアップロードし、エイリアスを作成します。

PKCS12 / PFX ファイルからのエイリアスの作成（キーストアのみ）

鍵と証明書を含む PKCS12 ファイルからエイリアスを作成するには:

  1. [TLS Keystores] ページにアクセスします。
  2. キーストアにカーソルを合わせて操作メニューを表示し、[+] をクリックします。
  3. [Alias Name] を指定します。
  4. [Certificate details] の [Type] プルダウンから [PKCS12/PFX] を選択します。
  5. [PKCS12/PFX] の横にある [Choose File] をクリックし、鍵と証明書を含むファイルを選択して [Open] をクリックします。
  6. 鍵にパスワードがある場合は、PKCS12 / PFX ファイルの [Password] を指定します。鍵にパスワードがない場合、このフィールドは空白のままにします。
  7. デフォルトでは、API によって証明書が期限切れでないことが確認されます。必要に応じて、[Allow Expired Certificate] を選択して検証をスキップします。
  8. [Save] を選択してファイルをアップロードし、エイリアスを作成します。

自己署名証明書からのエイリアスの作成（キーストアのみ）

自己署名証明書を使用するエイリアスを作成するには、証明書の作成に必要な情報をフォームに入力します。そうすると、証明書と秘密鍵のペアが作成され、エイリアスにアップロードされます。

自己署名証明書からエイリアスを作成するには:

  1. [TLS Keystores] ページにアクセスします。
  2. キーストアにカーソルを合わせて操作メニューを表示し、[+] をクリックします。
  3. [Alias Name] を指定します。
  4. [Certificate details] の [Type] プルダウンから [Self-Signed Certificate] を選択します。
  5. 下記の表に従ってフォームに入力します。
  6. [Save] を選択します。そうすると、証明書と秘密鍵のペアが作成され、エイリアスにアップロードされます。

生成された証明書には、次の追加フィールドがあります。

  • Issuer
    証明書に署名して発行したエンティティ。自己署名証明書の場合、これは証明書の作成時に指定した CN です。
  • Validity
    証明書の有効期間の開始日と終了日の 2 つの日付で表される証明書の有効期間。どちらも UTCTime 値または GeneralizedTime 値としてエンコードできます。

次の表に、フォーム フィールドを示します。

フォーム フィールド 説明 デフォルト 必須
Alias Name エイリアス名。最大長は 128 文字です。 なし ○
Key Size 鍵のサイズ（ビット単位）。デフォルトおよび最大値は 2,048 ビットです。 2048 ×
Signature Algorithm 秘密鍵を生成する署名アルゴリズム。有効な値は、「SHA512withRSA」、「SHA384withRSA」、「SHA256withRSA」（デフォルト）です。 SHA256withRSA ×
Certificate validity in days 証明書の有効期間（日数）。ゼロ以外の正の値を受け入れます。 365 ×
Common Name 組織の共通名（CN）は、証明書に関連付けられた完全修飾ドメイン名を示します。これは通常、ホストとドメイン名で構成されます。たとえば、api.enterprise.apigee.com、www.apigee.com などです。最大長は 64 文字です。

証明書のタイプに応じて、CN は、同じドメインに属する 1 つ以上のホスト名（example.com、www.example.com など）、ワイルドカード名（*.example.com など）、ドメインのリストのいずれかになります。プロトコル（http:// または https://）、ポート番号、リソースパスは含めないでください。

証明書は、リクエストのホスト名が証明書の共通名の少なくとも 1 つと一致する場合にのみ有効です。

 なし ○
Email メールアドレス。最大長は 255 文字です。 なし ×
Org Unit Name 組織チーム名。最大長は 64 文字です。 なし ×
Org Name 組織名。最大長は 64 文字です。 なし ×
Locality 市町村名。最大長は 128 文字です。 なし ×
State/Province 都道府県名。最大長は 128 文字です。 なし ×
Country 2 文字の国コード。たとえば、インドは IN、米国は US です。 なし ×
Alternative Names 代替ホスト名のリスト。追加の ID を証明書のサブジェクトにバインドできます。定義されているオプションは、インターネット メールアドレス、DNS 名、IP アドレス、Uniform Resource Identifier（URI）です。

それぞれの値の最大文字数は 255 文字です。名前を区切るには、カンマを使用するか、それぞれの名前の後で Enter キーを押します。

 なし ×

キーストアまたはトラストストアのテスト

Edge UI でトラストストアとキーストアをテストして、適切に構成されていることを確認できます。テスト UI によって、Edge からバックエンド サービスへの TLS リクエストが検証されます。バックエンド サービスは、一方向または双方向の TLS をサポートするように構成できます。

一方向 TLS をテストするには:

  1. [TLS Keystores] ページにアクセスします。
  2. 環境を選択します（通常は prod または test）。
  3. テストする TLS キーストアにカーソルを合わせて操作メニューを表示し、[Test] をクリックします。次のダイアログ ボックスが表示され、トラストストアの名前が示されます。
  4. バックエンド サービスのホスト名を入力します。
  5. TLS ポート番号（通常は 443）を入力します。
  6. 必要に応じて、プロトコルまたは暗号を指定します。
  7. [Test] を選択します。

双方向 TLS をテストするには:

  1. 目的のトラストストアに対して [Test] ボタンを選択します。
  2. ダイアログ ボックスの [SSL Test Type] で [Two Way] を選択します。次のダイアログ ボックスが表示されます。
  3. 双方向 TLS で使用されるキーストアの名前を指定します。
  4. 証明書と鍵を含むキーストアのエイリアス名を指定します。
  5. バックエンド サービスのホスト名を入力します。
  6. TLS ポート番号（通常は 443）を入力します。
  7. 必要に応じて、プロトコルまたは暗号を指定します。
  8. [Test] を選択します。

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

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

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

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

  1. 仮想ホストでトラストストアへの参照を使用していることを確認します。
  2. 上記の証明書からのエイリアスの作成（トラストストアのみ）の説明に従って、新しい証明書をトラストストアにアップロードします。

  3. トラストストアへの参照を更新して、同じ値に設定します。この更新により、トラストストアと新しい証明書が再読み込みされます。

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

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

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

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

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

キーストアを削除する

キーストアまたはトラストストアを削除するには、リスト内のキーストアまたはトラストストアにカーソルを合わせて操作メニューを表示し、 をクリックします。仮想ホストまたはターゲット エンドポイント / ターゲット / サーバーによって使用されているキーストアまたはトラストストアを削除すると、仮想ホストまたはターゲット エンドポイント / ターゲット サーバーを経由するすべての API 呼出しが失敗します。

注意: キーストアを削除する前に必ず、仮想ホストとターゲット エンドポイント / ターゲット サーバーを更新して新しいキーストアが使用されるようにしてください。

エイリアスを削除する

エイリアスを削除するには、リスト内のエイリアスにカーソルを合わせて操作メニューを表示し、 をクリックします。仮想ホストまたはターゲット エンドポイント / ターゲット サーバーによって使用されているエイリアスを削除すると、仮想ホストまたはターゲット エンドポイント / ターゲット サーバーを経由するすべての API 呼び出しが失敗します。

注意: エイリアスを削除する前に必ず、仮想ホストとターゲット エンドポイント / ターゲット サーバーを更新して新しいキーストアとエイリアスが使用されるようにしてください。