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`" 的新文件。要指定不同的位置或文件名，请在上述 `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" 来配置 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 实例的基目录。一个 SSL 连接器的示例 <Connector> 元素包含在 Tomcat 安装的默认 server.xml 文件中。要配置使用 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）。但是，在许多操作系统上，要将 Tomcat 运行在低于 1024 的端口号上，需要特殊的设置（超出本文档范围）。

如果您在此处更改端口号，则还应更改非 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