針對私有雲設定 API 的傳輸層安全標準 (TLS) 存取權

您正在查看 Apigee Edge 說明文件。
查看 Apigee X 說明文件。 資訊

Edge 上的虛擬主機會定義要公開 API Proxy 的網域和通訊埠，以及應用程式用來存取 API Proxy 的網址。

虛擬主機也會定義要透過 HTTP 通訊協定或採用 TLS 的加密 HTTPS 通訊協定存取 API Proxy。將虛擬主機設為使用 HTTPS 和 TLS 時，請在 Edge 中建立虛擬主機，並將虛擬主機設為使用 Keystore 和 Truststore。

瞭解詳情：

• 關於 TLS/SSL
• 搭配 Edge 使用 TLS
• 關於虛擬主機
• 設定私有雲的虛擬主機
• 虛擬主機屬性參考資料
• KeyStore 和 Truststore

建立虛擬主機的必要條件

建立虛擬主機之前，您必須具備以下資訊：

• 虛擬主機的公開網域名稱。舉例來說，您應該瞭解公開名稱是否為 api.myCompany.com、myapi.myCompany.com 等。您建立虛擬主機時，以及為虛擬主機建立 DNS 記錄時，也會使用這項資訊。
• 如為單向傳輸層安全標準 (TLS)，您必須建立 KeyStore，並在其中含有下列項目：
  • TLS 憑證：是由憑證授權單位 (CA) 簽署的憑證，或是最後一個憑證由 CA 簽署的憑證鏈結。
  • 私密金鑰 - Edge 支援高達 2048 位元的金鑰大小。通關密語為選用項目。
• 如果採用雙向傳輸層安全標準 (TLS)，您需要 KeyStore，以及需要可保存用戶端憑證的信任儲存庫，以及選用憑證的 CA 鏈結。即使憑證是由 CA 簽署，您還是需要信任儲存庫。

如要進一步瞭解如何建立 KeyStore 和信任儲存庫，請參閱 Keystore 和 Truststore。

TLS 的虛擬主機設定

如要建立虛擬主機，請建立用於定義虛擬主機的 XML 物件。下列 XML 物件使用 <SSLInfo> 元素定義透過 HTTPS 的單向傳輸層安全標準 (TLS) 設定的虛擬主機：

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

在這個範例中，<Enabled> 元素設為 true 以啟用單向傳輸層安全標準 (TLS)，<KeyStore> 和 <KeyAlias> 元素則會指定 TLS 連線使用的 KeyStore 和金鑰。

如要啟用雙向傳輸層安全標準 (TLS)，請將 <ClientAuthEnabled> 元素設為 true，並使用 <TrustStore> 元素指定信任儲存庫。信任儲存庫存放了用戶端的憑證，以及 (選用) 憑證的 CA 鏈結。

決定在虛擬主機中指定 KeyStore 和信任儲存庫名稱的方式

在上方的虛擬主機範例中，您已使用「參照」指定 KeyStore。參照是一種包含 KeyStore 名稱的變數，而非直接指定 KeyStore 名稱。

使用參照的優點是，您可以變更參照的值來變更虛擬主機使用的 KeyStore，原因通常是因為目前 KeyStore 中的憑證將於近期到期。變更參照值時，不需要重新啟動邊緣路由器。

您也可以在虛擬主機中使用常值 KeyStore 名稱。不過，如果您為了變更 KeyStore 名稱來修改虛擬主機，則須重新啟動邊緣路由器。

使用 KeyStore 和 Truststore 的參照限制

使用 KeyStore 和信任儲存庫的參照時，必須考量下列限制：

• 您必須支援 SNI，並在 Apigee 路由器上終止 SSL，才能在虛擬主機中使用 KeyStore 和 Truststore 參照。
• 如果 Apigee 路由器前方有負載平衡器，且您在負載平衡器上終止 TLS，您就無法在虛擬主機中使用 KeyStore 和 Truststore 參照。

修改現有虛擬主機，以使用 KeyStore 和 Truststore 的參照

Apigee 強烈建議虛擬主機使用 KeyStore 和 Truststore 的參照。 參照可讓您變更虛擬主機使用的 KeyStore 和信任儲存庫，而不必重新啟動邊緣路由器。

如果虛擬主機目前設定為使用 KeyStore 或 Truststore 的常值名稱，您可以將這些主機轉換為使用參照。如要這麼做，請更新虛擬主機以使用參照，然後重新啟動邊緣路由器。

設定 Edge 4.15.07 以下版本的 TLS 加密和通訊協定

如果您使用的是 Edge 4.15.07 以下版本，請使用 <SSLInfo> 標記的 <Ciphers> 和 <Protocols> 子項標記，設定虛擬主機使用的 TLS 通訊協定和加密方式。下表說明這些標記。

例如：

    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>myTestKeystore</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
        <SSLInfo>
            <Enabled>true</Enabled>
            <ClientAuthEnabled>false</ClientAuthEnabled>
            <KeyStore>myTestKeystore</KeyStore>
            <KeyAlias>myKeyAlias</KeyAlias>
            <Ciphers>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Cipher>
                <Cipher>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Cipher>
            </Ciphers>
            <Protocols>
                <Protocol>TLSv1.2</Protocol>
            </Protocols>
        </SSLInfo>
   </SSLInfo>

<Cipher> 標記會使用加密套件的 Java 和 JSSE 名稱。舉例來說，針對 Java 8，請參閱 http://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#ciphersuites。

指定 Edge 4.16.01 至 4.16.09 的 TLS 加密和通訊協定

在 Edge 4.16.01 至 4.16.09 版本中，您需要為全球的虛擬主機設定預設加密方式和通訊協定。這些預設值就會套用至所有虛擬主機。

使用權杖指定預設通訊協定和加密方式：

• 如要指定預設通訊協定，請使用 conf_load_balancing_load.balancing.driver.server.ssl.protocols 權杖
• 如要為路由器指定預設加密器，請使用 conf_load_balancing_load.balancing.driver.server.ssl.ciphers 權杖

conf_load_balancing_load.balancing.driver.server.ssl.protocols 權杖的預設值如下：

conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1 TLSv1.1 TLSv1.2

這項設定會指定路由器支援 TLS 1.0、1.1 和 1.2 版。為符記指定以空格分隔的值清單。

conf_load_balancing_load.balancing.driver.server.ssl.ciphers 權杖的預設值如下：

conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES

這項設定可指定：

• 索引鍵長度至少為 128 位元 (HIGH)。
• 排除不進行驗證的加密 (!aNULL)
• 排除使用 MD5 的加密套件 (!MD5)
• 使用 DH (包括匿名 DH、暫時 DH 和固定 DH) 和三重 DES (!DH+3DES) 排除加密套件
• 使用 RSA 金鑰交換「和」三組 DES 排除加密套件 (!RSA+3DES)

如要瞭解這個權杖允許的語法和值，請參閱 OpenSSL 加密法。請注意，這個權杖使用的是 OpenSSL 加密名稱 (例如 AES128-SHA256)，而非 Java/JSSE 加密名稱 (例如 TLS_RSA_WITH_AES_128_CBC_SHA256)。

如要為路由器設定權杖：

1. 編輯 /opt/apigee/customer/application/router.properties 檔案。如果該檔案不存在，請建立一個。
2. 設定 conf_load_balancing_load.balancing.driver.server.ssl.ciphers 權杖。舉例來說，如要只指定 TLSv1.2，並使用預先共用金鑰排除加密套件，請新增 !PSK：

   conf_load_balancing_load.balancing.driver.server.ssl.protocols=TLSv1.2
   conf_load_balancing_load.balancing.driver.server.ssl.ciphers=HIGH:!aNULL:!MD5:!DH+3DES:!RSA+3DES:!PSK

3. 確保 router.properties 檔案為 Apigee 所擁有：

   chown apigee:apigee /opt/apigee/customer/application/router.properties

4. 重新啟動 Edge Router：

   /opt/apigee/apigee-service/bin/apigee-service edge-router restart

5. 請檢查權杖值：

   /opt/apigee/apigee-service/bin/apigee-service edge-router configure -search conf_load_balancing_load.balancing.driver.server.ssl.ciphers

為 Edge 4.17.01 以上版本設定 TLS 虛擬主機參數

如果您使用的是 Edge 4.17.01 以上版本，則可以使用 <VirtualHost> 標記的 <Properties> 子標記，為個別虛擬主機設定部分 TLS 屬性，例如 TLS 通訊協定和加密方式。如需這些標記的說明，請參閱虛擬主機屬性參考資料。

例如：

<VirtualHost name="myTLSVHost">
    <HostAliases>
        <HostAlias>apiTLS.myCompany.com</HostAlias>
    </HostAliases>
    <Interfaces/>
    <Port>9006</Port>
    <OCSPStapling>off</OCSPStapling>
    <SSLInfo>
        <Enabled>true</Enabled>
        <ClientAuthEnabled>false</ClientAuthEnabled>
        <KeyStore>ref://myTestKeystoreRef</KeyStore>
        <KeyAlias>myKeyAlias</KeyAlias>
    </SSLInfo>
    <Properties>
        <Property name="proxy_read_timeout">50</Property>
        <Property name="keepalive_timeout">300</Property>
        <Property name="proxy_request_buffering">off</Property>
        <Property name="proxy_buffering">off</Property>
        <Property name="ssl_protocols">TLSv1.2 TLSv1.1</Property>
        <Property name="ssl_ciphers">HIGH:!aNULL:!MD5:!DH+3DES:!kEDH</Property>
    </Properties>
</VirtualHost>

如要瞭解 ssl_ciphers 權杖允許的語法和值，請參閱 OpenSSL 加密器。請注意，這個權杖使用的是 OpenSSL 加密名稱 (例如 AES128-SHA256)，而非 Java/JSSE 加密名稱 (例如 TLS_RSA_WITH_AES_128_CBC_SHA256)。

建立使用 HTTPS 的虛擬主機

這個範例透過參照指定虛擬主機的 KeyStore。使用參照可讓您變更 KeyStore，無須重新啟動路由器。

請按照下列程序建立虛擬主機：

1. 按照以下所述流程，建立及設定名為 myTestKeystore 的 KeyStore：Keystore 和 Truststores。確認 KeyStore 針對憑證和私密金鑰使用 myKeyAlias 的別名名稱。

2. 請使用下列 POST API 呼叫，為您在上方建立的 KeyStore 建立名為 keystoreref 的參照：

   curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
     -d '<ResourceReference name="keystoreref">
       <Refers>myTestKeystore</Refers>
       <ResourceType>KeyStore</ResourceType>
     </ResourceReference>'
     -u email:password
   

   參照將 KeyStore 名稱和參照類型指定為 KeyStore。

   請使用下列 GET API 呼叫來查看參照：

   curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password
   

3. 使用 Create a Virtual Host API 建立虛擬主機，其中 <ms-IP> 是管理伺服器節點的 IP 位址或網域名稱。

   請務必指定正確的 KeyStore 參照和金鑰別名：

   curl -X POST -H "Content-Type:application/xml" \
     http://<ms-IP>:8080/v1/o/{org_name}/environments/{env_name}/virtualhosts \
     -d '<VirtualHost  name="newTLSTrustStore2">
       <HostAliases>
         <HostAlias>apiTLS.myCompany.com</HostAlias>
       </HostAliases>
       <Interfaces/>
       <Port>9005</Port>
       <OCSPStapling>off</OCSPStapling>
       <SSLInfo>
         <Enabled>true</Enabled>
         <ClientAuthEnabled>false</ClientAuthEnabled>
         <KeyStore>ref://keystoreref</KeyStore>
         <KeyAlias>myKeyAlias</KeyAlias>
       </SSLInfo>
     </VirtualHost>' \
     -u email:password

4. 為與主機別名相符的虛擬主機建立 DNS 記錄。

5. 如果您有現有的 API Proxy，請將虛擬主機新增至 Proxy 端點的 <HTTPConnection> 元素。系統會自動將虛擬主機新增至所有新的 API Proxy。

   請參閱「關於虛擬主機」中的「建立虛擬主機後更新 API Proxy」一節。

將 API Proxy 更新為使用虛擬主機，並為主機別名建立 DNS 記錄後，您可以按照下列步驟存取 API Proxy：

https://apiTLS.myCompany.com/v1/{project-base-path}/{resource-path}

例如：

https://apiTLS.myCompany.com/v1/weather/forecastrss?w=12797282

建立及修改 KeyStore 或 Truststore 的參照

您可以選擇將虛擬主機設定為改用 KeyStore 或信任儲存庫的「參照」。使用參照的優點是，您可以將參照更新為指向其他 KeyStore 或信任儲存庫，這樣就能更新傳輸層安全標準 (TLS) 憑證，而不必重新啟動路由器。

例如，下列是使用 KeyStore 參照的虛擬主機：

<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>

請使用下列 POST API 呼叫建立名為 keystoreref 的參照：

curl -X POST  -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references \
  -d '<ResourceReference name="keystoreref">
    <Refers>myTestKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password

參照會指定 KeyStore 的名稱及其類型。

請使用下列 GET API 呼叫來查看參照：

curl -X GET https://api.enterprise.apigee.com/v1/o/[org_name}/e/{env_name}/references/keystoreref -u uname:password

如要在日後將參照變更為指向其他 KeyStore，並確保別名使用相同的名稱，請使用下列 PUT 呼叫：

curl -X PUT -H "Content-Type:application/xml" https://api.enterprise.apigee.com/v1/o/{org_name}/e/{env_name}/references/keystoreref \
  -d '<ResourceReference name="keystoreref">
    <Refers>myNewKeystore</Refers>
    <ResourceType>KeyStore</ResourceType>
  </ResourceReference>'
  -u email:password