Apache Tomcat 10

Tomcat 目前僅在 JKS、PKCS11 或 PKCS12 格式的儲存區中運作。JKS 格式是 Java 的標準「Java 儲存區」格式，也是 keytool 命令列工具建立的格式。此工具包含在 JDK 中。PKCS12 格式是網際網路標準，可透過 (包括) OpenSSL 和 Microsoft 的金鑰管理員來處理。

儲存區中的每個項目都由別名字串識別。雖然許多儲存區實作以不區分大小寫的方式處理別名，但有區分大小寫的實作。例如，PKCS11 規格要求別名區分大小寫。若要避免與別名大小寫敏感性相關的問題，建議不要使用僅在大小寫上不同的別名。

若要將現有憑證匯入 JKS 儲存區，請閱讀關於 keytool 的文件 (在您的 JDK 文件套件中)。請注意，OpenSSL 通常會在金鑰之前加入可讀的註解，但 keytool 不支援此功能。因此，如果您的憑證在金鑰資料之前有註解，請在使用 keytool 匯入憑證之前將其移除。

若要使用 OpenSSL 將由您自己的 CA 簽署的現有憑證匯入 PKCS12 儲存區，您可以執行類似下列的指令

openssl pkcs12 -export -in mycert.crt -inkey mykey.key
                       -out mycert.p12 -name tomcat -CAfile myCA.crt
                       -caname root -chain

對於更進階的案例，請參閱 OpenSSL 文件。

若要從頭建立新的 JKS 儲存區，其中包含單一自簽憑證，請從終端機命令列執行下列動作

Windows

"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA

Unix

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA

(RSA 演算法應優先作為安全演算法，這也能確保與其他伺服器和組件的一般相容性。)

此命令將在您執行命令的使用者家目錄中建立一個新檔案，命名為「.keystore」。若要指定不同的位置或檔案名稱，請將 -keystore 參數新增到上面顯示的 keytool 命令，後接儲存區檔案的完整路徑。您還需要在 server.xml 組態檔案中反映此新位置，如下所述。例如

Windows

"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA
  -keystore \path\to\my\keystore

Unix

$JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA
  -keystore /path/to/my/keystore

執行此命令後，系統會先提示您輸入儲存區密碼。Tomcat 使用的預設密碼為「changeit」(全部小寫)，不過您可以自行指定密碼。您還需要在 server.xml 組態檔案中指定自訂密碼，如下所述。

接下來，系統會提示您輸入此憑證的一般資訊，例如公司、聯絡人姓名等。此資訊將顯示給嘗試存取應用程式中安全頁面的使用者，因此請務必確保在此提供的資訊與他們預期的一致。

最後，系統會提示您輸入金鑰密碼，這是專門針對此憑證的密碼 (與儲存在同一個儲存區檔案中的其他憑證不同)。keytool 提示會告訴您，按下 ENTER 鍵會自動將金鑰的密碼設為與儲存區相同。您可以自由使用相同的密碼或選擇自訂密碼。如果您選擇與儲存區密碼不同的密碼，您還需要在 server.xml 組態檔案中指定自訂密碼。

如果一切順利，您現在有一個儲存區檔案，其中包含伺服器可使用的憑證。

Tomcat 可以使用兩種不同的 SSL 實作

• 作為 Java 執行時期一部分提供的 JSSE 實作
• 使用 OpenSSL 的 JSSE 實作

確切的組態詳細資料取決於使用的實作。如果您透過指定一般 protocol="HTTP/1.1" 來組態 Connector，則 Tomcat 使用的實作會自動選取。如果安裝使用 APR，也就是說您已安裝 Tomcat 本機程式庫，則它將使用 JSSE OpenSSL 實作，否則它將使用 Java JSSE 實作。

如果需要，可以避免自動選取實作。這可透過在 Connector 的 protocol 屬性中指定類別名稱來完成。

要定義 Java (JSSE) 連接器，無論 APR 函式庫是否已載入，請使用下列其中一項

<!-- Define an HTTP/1.1 Connector on port 8443, JSSE NIO implementation -->
<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
           sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation"
           port="8443" .../>

<!-- Define an HTTP/1.1 Connector on port 8443, JSSE NIO2 implementation -->
<Connector protocol="org.apache.coyote.http11.Http11Nio2Protocol"
           sslImplementationName="org.apache.tomcat.util.net.jsse.JSSEImplementation"
           port="8443" .../>

如有需要，也可以明確設定 OpenSSL JSSE 執行。如果已安裝 APR 函式庫，使用 sslImplementationName 屬性可以啟用它。使用 OpenSSL JSSE 執行時，設定可以使用 JSSE 屬性或 OpenSSL 屬性，但不得在同一個 SSLHostConfig 或 Connector 元素中混合使用兩種類型的屬性。

<!-- Define an HTTP/1.1 Connector on port 8443, JSSE NIO implementation and OpenSSL -->
<Connector protocol="org.apache.coyote.http11.Http11NioProtocol" port="8443"
           sslImplementationName="org.apache.tomcat.util.net.openssl.OpenSSLImplementation"
           .../>

如果您使用的是 JSSE OpenSSL，您可以選擇設定替代引擎至 OpenSSL。

<Listener className="org.apache.catalina.core.AprLifecycleListener"
          SSLEngine="someengine" SSLRandomSeed="somedevice" />

預設值為

<Listener className="org.apache.catalina.core.AprLifecycleListener"
          SSLEngine="on" SSLRandomSeed="builtin" />

因此，要啟用 OpenSSL，請確定 SSLEngine 屬性已設定為除 off 以外的值。預設值為 on，如果您指定其他值，則必須是有效的 OpenSSL 引擎名稱。

SSLRandomSeed 允許指定熵來源。生產系統需要可靠的熵來源，但熵可能需要花費很多時間才能收集，因此測試系統可以使用非封鎖熵來源，例如「/dev/urandom」，這將允許 Tomcat 更快啟動。

最後一個步驟是在 $CATALINA_BASE/conf/server.xml 檔案中設定 Connector，其中 $CATALINA_BASE 代表 Tomcat 執行個體的基本目錄。預設安裝在 Tomcat 中的 server.xml 檔案中包含 SSL 連接器的範例 <Connector> 元素。若要設定使用 JSSE 設定樣式的 JSSE 的 SSL 連接器，您需要移除註解並編輯它，使其看起來像這樣

<!-- Define an SSL Coyote HTTP/1.1 Connector on port 8443 -->
<Connector
    protocol="org.apache.coyote.http11.Http11NioProtocol"
    port="8443"
    maxThreads="150"
    SSLEnabled="true"
    maxParameterCount="1000"
    >
  <SSLHostConfig>
    <Certificate
      certificateKeystoreFile="${user.home}/.keystore"
      certificateKeystorePassword="changeit"
      type="RSA"
      />
    </SSLHostConfig>
</Connector>

注意：如果已安裝 tomcat-native，設定將使用具有 OpenSSL 執行的 JSSE。

APR 設定樣式對許多 SSL 設定使用不同的屬性，特別是金鑰和憑證。APR 設定樣式的範例為

<!-- Define an SSL Coyote HTTP/1.1 Connector on port 8443 -->
<Connector
    protocol="org.apache.coyote.http11.Http11NioProtocol"
    port="8443"
    maxThreads="150"
    SSLEnabled="true"
    maxParameterCount="1000"
    >
  <SSLHostConfig>
    <Certificate
        certificateKeyFile="conf/localhost-rsa-key.pem"
        certificateFile="conf/localhost-rsa-cert.pem"
        certificateChainFile="conf/localhost-rsa-chain.pem"
        type="RSA"
        />
  </SSLHostConfig>
</Connector>

設定選項和哪些屬性為強制性的資訊記載在 HTTP 連接器 設定參考的 SSL 支援區段中。Tomcat 支援所有 TLS 連接器的設定樣式（JSSE 或 OpenSSL）。

port 屬性是 Tomcat 將偵聽安全連線的 TCP/IP 埠號。您可以將它變更為任何您想要的埠號（例如預設的 https 通訊埠 443）。但是，在許多作業系統上，在低於 1024 的埠號上執行 Tomcat 需要特殊設定（不在本文檔的範圍內）。

如果您在此變更埠號，您也應該變更非 SSL 連接器上 redirectPort 屬性指定的數值。這允許 Tomcat 自動重新導向嘗試存取頁面的使用者，而該頁面具有指定 SSL 為必要的安全性限制，這符合 Servlet 規格的要求。

完成這些設定變更後，您必須像平常一樣重新啟動 Tomcat，您應該就可以開始了。您應該能夠透過 SSL 存取 Tomcat 支援的任何 Web 應用程式。例如，嘗試

https://127.0.0.1:8443/

您應該會看到一般的 Tomcat 歡迎頁面（除非您已修改 ROOT Web 應用程式）。如果這不起作用，下列區段包含一些疑難排解提示。

要從您選擇的憑證授權機構取得憑證，您必須建立一個所謂的憑證簽署要求 (CSR)。憑證授權機構將使用該 CSR 建立憑證，以將您的網站識別為「安全」。請遵循下列步驟建立 CSR

• 建立本機自簽憑證（如前一節所述）

  keytool -genkey -alias tomcat -keyalg RSA
      -keystore <your_keystore_filename>

  注意：在某些情況下，您必須在「名字和姓氏」欄位中輸入網站的網域（例如 www.myside.org），才能建立可運作的憑證。
• 然後使用下列方式建立 CSR

  keytool -certreq -keyalg RSA -alias tomcat -file certreq.csr
      -keystore <your_keystore_filename>

現在您有一個名為 certreq.csr 的檔案，您可以將其提交給憑證授權機構（請參閱憑證授權機構網站上的文件，了解如何執行此操作）。您將會收到憑證作為回報。

取得憑證後，您可以將其匯入本機金鑰庫。首先，您必須將所謂的鏈結憑證或根憑證匯入金鑰庫。之後，您可以繼續匯入您的憑證。

• 從您取得憑證的憑證授權機構下載鏈結憑證。
  對於 Verisign.com 商業憑證，請前往：http://www.verisign.com/support/install/intermediate.html
  對於 Verisign.com 試用憑證，請前往：http://www.verisign.com/support/verisign-intermediate-ca/Trial_Secure_Server_Root/index.html
  對於 Trustcenter.de，請前往：http://www.trustcenter.de/certservices/cacerts/en/en.htm#server
  對於 Thawte.com，請前往：http://www.thawte.com/certs/trustmap.html
  
• 將鏈結憑證匯入金鑰庫

  keytool -import -alias root -keystore <your_keystore_filename>
      -trustcacerts -file <filename_of_the_chain_certificate>

• 最後匯入您的新憑證

  keytool -import -alias tomcat -keystore <your_keystore_filename>
      -file <your_certificate_filename>

每個憑證授權機構都略有不同。他們可能需要略有不同的資訊和/或提供不同格式的憑證和相關憑證鏈。此外，憑證授權機構用於簽發憑證的規則會隨著時間而改變。因此，您可能會發現上述命令可能需要修改。如果您需要協助，則可透過 Apache Tomcat 使用者郵件清單 取得協助。

Apache Tomcat 要求啟用 OCSP 的憑證在憑證中編碼 OCSP 回應器位置。openssl.cnf 檔案中的基本 OCSP 相關憑證授權設定如下所示

#... omitted for brevity

[x509]
x509_extensions = v3_issued

[v3_issued]
subjectKeyIdentifier=hash
authorityKeyIdentifier=keyid,issuer
# The address of your responder
authorityInfoAccess = OCSP;URI:http://127.0.0.1:8088
keyUsage = critical,digitalSignature,nonRepudiation,keyEncipherment,dataEncipherment,keyAgreement,keyCertSign,cRLSign,encipherOnly,decipherOnly
basicConstraints=critical,CA:FALSE
nsComment="Testing OCSP Certificate"

#... omitted for brevity

上述設定將 OCSP 回應器地址 127.0.0.1:8088 編碼到憑證中。請注意，對於下列步驟，您必須準備好 openssl.cnf 和 CA 的其他設定。如要產生啟用 OCSP 的憑證

• 建立私密金鑰

  openssl genrsa -aes256 -out ocsp-cert.key 4096

• 建立簽署要求 (CSR)

  openssl req -config openssl.cnf -new -sha256 \
    -key ocsp-cert.key -out ocsp-cert.csr

• 簽署 CSR

  openssl ca -openssl.cnf -extensions ocsp -days 375 -notext \
    -md sha256 -in ocsp-cert.csr -out ocsp-cert.crt

• 您可以驗證憑證

  openssl x509 -noout -text -in ocsp-cert.crt