Apache Tomcat 11

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”的新文件。要指定不同的位置或文件名，请在上面显示的 keytool 命令中添加 -keystore 参数，后跟您的密钥库文件的完整路径名。您还需要在 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" 配置了连接器，则 Tomcat 将自动选择所使用的实现。

如果需要，可以避免自动选择实现。这通过在 连接器 的 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 实现也可以显式配置。如果安装了 Tomcat Native 库或 Java 22，使用 sslImplementationName 属性可以启用它。当使用 OpenSSL JSSE 实现时，配置可以使用 JSSE 属性或 OpenSSL 属性，但不得在同一个 SSLHostConfig 或 Connector 元素中混合使用两种类型的属性。

使用 Tomcat Native

<!-- 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"
           .../>

使用 Java 22 FFM API

<!-- 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.panama.OpenSSLImplementation"
           .../>

或者，可以将一个监听器添加到 Server 中，以在所有连接器上启用 OpenSSL，而无需在每个连接器上添加 sslImplementationName 属性。

使用 Tomcat Native

<Listener className="org.apache.catalina.core.AprLifecycleListener"/>

使用 Java 22 FFM API

<Listener className="org.apache.catalina.core.OpenSSLLifecycleListener"/>

监听器的 SSLRandomSeed 属性允许指定熵源。生产系统需要可靠的熵源，但熵可能需要大量时间来收集，因此测试系统可以使用非阻塞熵源，例如“/dev/urandom”，这将允许 Tomcat 更快地启动。

最后一步是在 $CATALINA_BASE/conf/server.xml 文件中配置连接器，其中 $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">
  <SSLHostConfig>
    <Certificate
      certificateKeystoreFile="${user.home}/.keystore"
      certificateKeystorePassword="changeit"
      type="RSA"
      />
    </SSLHostConfig>
</Connector>

OpenSSL 配置样式对许多 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" >
  <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://localhost: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