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

您目前查看的是 Apigee Edge 說明文件。
前往 Apigee X 說明文件。 info

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

虛擬主機也會定義 API Proxy 是透過 HTTP 通訊協定存取，還是透過使用 TLS 的加密 HTTPS 通訊協定存取。將虛擬主機設為使用 HTTPS 和傳輸層安全標準 (TLS) 時，您會在 Edge 上建立虛擬主機，並將虛擬主機設為使用金鑰儲存區和信任儲存區。

瞭解詳情：

• 關於 TLS/SSL
• 透過 Edge 使用 TLS
• 關於虛擬主機
• 設定 Private Cloud 的虛擬主機
• 虛擬主機屬性參考資料
• 金鑰儲存區和信任儲存區

建立虛擬主機的必要條件

建立虛擬主機前，請先準備下列資訊：

• 虛擬主機的公開網域名稱。舉例來說，您應該知道公開名稱是 api.myCompany.com、myapi.myCompany.com 等。建立虛擬主機時，以及為虛擬主機建立 DNS 記錄時，都會用到這項資訊。
• 單向 TLS：您需要建立 KeyStore，其中包含下列項目：
  • TLS 憑證 - 憑證授權單位 (CA) 簽署的憑證，或最後一個憑證由 CA 簽署的憑證鏈。
  • 私密金鑰 - Edge 支援的金鑰大小上限為 2048 位元。通關密語為選用項目。
• 如要使用雙向 TLS，您需要 KeyStore 和信任儲存庫，才能保存用戶端憑證，以及憑證的 CA 鏈結 (選用)。即使憑證是由 CA 簽署，您也需要信任儲存庫。

如要進一步瞭解如何建立金鑰儲存區和信任儲存區，請參閱「金鑰儲存區和信任儲存區」。

傳輸層安全標準 (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 連線使用的金鑰儲存區和金鑰。

如要啟用雙向 TLS，請將 <ClientAuthEnabled> 元素設為 true，並使用 <TrustStore> 元素指定信任儲存庫。信任儲存庫會保留用戶端的憑證，以及憑證的 CA 鏈結 (選用)。

決定如何在虛擬主機中指定金鑰儲存區和信任儲存區名稱

在上述虛擬主機範例中，您使用參照指定了金鑰儲存區。參照是包含金鑰儲存庫名稱的變數，而不是直接指定金鑰儲存庫名稱。

使用參照的優點是，您可以變更參照的值，藉此變更虛擬主機使用的金鑰儲存區，通常是因為目前金鑰儲存區中的憑證即將到期。變更參照值不需要重新啟動 Edge 路由器。

或者，您也可以在虛擬主機中使用字串 keystore 名稱。不過，如果您修改虛擬主機來變更金鑰儲存區名稱，就必須重新啟動 Edge Router。

使用金鑰儲存區和信任儲存區參照時的限制

使用金鑰儲存區和信任儲存區的參照時，請務必考量下列限制：

• 只有在支援 SNI，且在 Apigee Router 上終止 SSL 時，才能在虛擬主機中使用金鑰儲存區和信任儲存區參照。
• 如果您在 Apigee Router 前方有負載平衡器，並在負載平衡器上終止 TLS，就無法在虛擬主機中使用金鑰儲存區和信任儲存區參照。

修改現有虛擬主機，以參照金鑰儲存區和信任儲存區

Apigee 強烈建議虛擬主機參照金鑰儲存區和信任儲存區。 您可以使用參照變更虛擬主機使用的金鑰儲存區和信任儲存區，不必重新啟動 Edge 路由器。

如果虛擬主機目前設定為使用金鑰儲存區或信任儲存區的字面名稱，您可以將其轉換為使用參照。如要這麼做，請更新虛擬主機以使用參照，然後重新啟動 Edge 路由器。

為 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 中，您可以在 Router 上為虛擬主機全域設定預設的加密演算法和通訊協定。這些預設值隨後會套用至所有虛擬主機。

使用權杖指定預設通訊協定和密碼：

• 如要指定預設通訊協定，請使用權杖 conf_load_balancing_load.balancing.driver.server.ssl.protocols
• 如要指定 Router 的預設密碼，請使用權杖 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 金鑰交換機制和 3DES 的加密套件 (!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 路由器：

   /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。使用參照可讓您變更金鑰儲存區，不必重新啟動路由器。

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

1. 按照「Keystores and Truststores」一文所述的程序，建立並設定名為 myTestKeystore 的 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 參照類型。

   使用下列 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 位址或網域名稱。

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

   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，請將虛擬主機新增至 ProxyEndpoint 中的 <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

建立及修改對金鑰儲存區或信任儲存庫的參照

您可以視需要設定虛擬主機，改為使用金鑰儲存區或信任儲存區的參照。使用參照的優點是，您可以更新參照，指向其他金鑰儲存區或信任儲存區，藉此更新 TLS 憑證，而不必重新啟動路由器。

舉例來說，以下是使用金鑰儲存區參照的虛擬主機：

<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

參照會指定金鑰儲存區的名稱和類型。

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

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

如要稍後變更參照，指向其他金鑰儲存區，請確保別名名稱相同，並使用下列 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