tomcat 配置 ssl
程序员文章站
2022-07-14 21:06:11
...
摘自 http://tomcat.jaxwiki.org/ssl-howto.html
1、检查你是否需要下载 JSSE
Java 1.4或更新的版本已经包括了JSSE。如果你使用 1.4或更新版本，你不需要另外下载JSSE。你可以跳过本节
从下面的网站下载Java Secure Socket Extensions (JSSE) 版本 1.0.3或更新版。 http://java.sun.com/products/jsse/.
在扩展这个软件包后，有两种方法让Tomcat可以使用它(选择其中之一):
通过把所有这三个JAR文件(jcert.jar , jnet.jar , 和 jsse.jar)复制到$JAVA_HOME/jre/lib/ext 目录中去，让JSSE成为 安装好的扩充目录。
产生一个新的环境变量JSSE_HOME，让它包含绝对路径，指向你拆装(unpacked) JSSE二进制分布的目录。
2、产生 Keystore
Tomcat 现在只支持 JKS或PKCS12 格式的keystores. JKS格式是 Java 的标准 KeyStore格式，它可以用 Java 的 keytool 来产生。这个工具在 Java 的 bin 目录里。 PKCS12 格式时互联网的标准，可以用 OpenSSL 和微软的 Key-Manager来修改。
To import an existing certificate into a JKS keystore, please read the documentation (in your JDK documentation package) about keytool. Note that openssl often adds a readable comments before the key, keytooldoes not support that, so remove the openssl comments if they exist before importing the key using keytool.
使用OpenSSL把一个现存的被你自己CA签署的认证书输入到PKCS12 keystore里面，你会执行象这样的一个命令：
openssl pkcs12 -export -in mycert.crt -inkey mykey.key \
-out mycert.p12 -name tomcat -CAfile myCA.crt \
-caname root -chain
更深层的情况，请查阅OpenSSL documententation。
要从头开始产生一个新的keystore，包含一个自签的认证书，从一个终端命令行执行下面的命令：
视窗
%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
Unix
%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
( 应该把RSA运算法则作为主要安全运算法则，这保证了与其它服务器和组件的兼容性。)
这个命令会在用户的home directory产生一个叫做" .keystore " 的新文件。要指定一个不同的位置(location)或文件名，在上面所示的keytool 命令里添加-keystore参数，后面紧跟着你的keystore文件的全部路径名。你还需要把这个新的位置在server.xml配置文件中反映出来，这在后面将有描述。例如：
视窗
%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
在执行这个命令后，你首先被要求出示keystore密码。Tomcat使用的默认密码是 " changeit "(全都是小写字母)，如果你愿意，你可以指定你自己的密码。你还需要在server.xml配置文件里指定自己的密码，这在以后会有描述。
下一步，你会被要求出示关于这个认证书的一般性信息，如公司，联系人名称，等等。这些信息会显示给那些试图访问你程序里安全网页的用户，以确保这里提供的信息与他们期望的相对应。
最后，你会被要求出示密钥(key)密码，也就是这个认证书所特有的密码(与其它的储存在同一个keystore文件里的认证书不同)。你必须在这里使用与keystore 密码相同的密码。(目前，keytool会提示你按ENTER键会自动帮你做这些)。
如果一切顺利，你现在就拥有了一个可以被你的服务器使用的有认证书的keystore文件。
注意： 你的 private key 的密码和 keystore 的密码应该相同。如果不同的话你会得到一下错误信息： java.io.IOException: Cannot recover key 这是一个已知的错误，详细请看： Bugzilla issue 38217
3、Edit the Tomcat Configuration File
最后的步骤是把你的secure socket配置在$CATALINA_HOME/conf/server.xml文件里, $CATALINA_HOME代表你在其中安装Tomcat 5 的目录。一个例子是SSL连接器的<Connector>元素被包括在和Tomcat一起安装的缺省server.xml文件里。它看起来象是这样：
<-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!--
<Connector
port="8443" minProcessors="5" maxProcessors="75"
enableLookups="true" disableUploadTimeout="true"
acceptCount="100" debug="0" scheme="https" secure="true";
clientAuth="false" sslProtocol="TLS"/>
-->
你会注意到Connector元素本身，其默认形式是被注释掉的(commented out)，所以你需要把它周围的注释标志删除掉。然后，你可以根据需要客户化(自己设置)特定的属性。关于各种选项的详细信息，请查阅Server Configuration Reference 。下面的讨论仅仅涵盖设置SSL通信(communication)时大家最感兴趣的那些属性。
这个port属性(默认值是8443)是 TCP/IP端口数码，Tomcat在其上监听安全连接。你可以把它更改成任何你愿意要的数值(如默认的https通信，数目是443)。不过，在许多操作系统中，要想在比1024小的端口数码上运行Tomcat，需要特殊的设置(它超出了这个文档资料的范围)。
如果你在这里更改端口数值，你还必须更改在non-SSL连接器上的redirectPort 这个属性特定的值。这允许Tomcat自动地redirect那些试图访问有安全限制页面的用户，指明根据 Servlet 2.4 Specification要求，SSL是必需的。
有一些额外的选项被用来配置SSL协定。依赖于你早先怎样配置你的keystore，你也许需要添加或更改下列属性值：
属性 描述
clientAuth 如果你想要Tomcat要求所有的SSL客户在使用这个socket时出示用户认证书，把这个值设定为 true 。如果你想要Tomcat要求出示用户认证书，但是如果没有认证书也可以， 就把这个值设定为want 。
keystoreFile 如果你产生的keystore文件不在Tomcat期望的默认地方(一个叫做.keystore 的文件在Tomcat运行的主目录)，就添加这个属性。你可以指定一个绝对路径名称， 或者一个由$CATALINA_BASE环境变量而派生的相对路径名称。
keystorePass 如果你使用一个不同的keystore(以及认证书)密码，而不是Tomcat期望的密码 (就是changeit)，添加这个元素。
keystoreType 如果使用一个PKCS12 keystore的话，就添加这个element。 有效的值是JKS 和 PKCS12 。
sslProtocol 要在这个socket上被使用的加密／解密协定。如果你在使用Sun的JVM，我们不提倡更改 这个值。据报道，TLS协定的IBM's 1.4.1 实现与一些通用的浏览器不兼容。 如果是这样，就使用value SSL 。
ciphers 这个socket允许使用的由逗号分隔开的加密密码列单。默认的情况下，任何可用的密码都允许被使用。
algorithm 可用的X509算法。默认是Sun的实现( SunX509 )。 对于IBM JVMs，你应该使用值 IbmX509。对于其他卖主，查阅JVM文档资料来 找正确的值。
truststoreFile 用来验证用户认证书的TrustStore文件。
truststorePass 访问TrustStore的密码。默认值就是keystorePass的值。
truststoreType 如果你在使用与KeyStore不同格式的TrustStore，添加这个元素。 合法的值是JKS和PKCS12。
keyAlias 如果 keystore 里面有多个 key，你可以为用这个选项为加入的 key 起一个名字。 如果没有指定名字，使用时 keystore 内的第一个 key 将会被使用。
在完成这些配置更改后，你必须象通常那样重新启动Tomcat，然后你就可以工作了。你应该可以通过SSL访问Tomcat支持的任何web应用程序。例如，试一下下面的指令：
https://localhost:8443
你应该看到通常的Tomcat splash页面(除非你修改过ROOT web应用程序)。如果不行的话，下面的章节包含一些排除故障的提示。
1、检查你是否需要下载 JSSE
Java 1.4或更新的版本已经包括了JSSE。如果你使用 1.4或更新版本，你不需要另外下载JSSE。你可以跳过本节
从下面的网站下载Java Secure Socket Extensions (JSSE) 版本 1.0.3或更新版。 http://java.sun.com/products/jsse/.
在扩展这个软件包后，有两种方法让Tomcat可以使用它(选择其中之一):
通过把所有这三个JAR文件(jcert.jar , jnet.jar , 和 jsse.jar)复制到$JAVA_HOME/jre/lib/ext 目录中去，让JSSE成为 安装好的扩充目录。
产生一个新的环境变量JSSE_HOME，让它包含绝对路径，指向你拆装(unpacked) JSSE二进制分布的目录。
2、产生 Keystore
Tomcat 现在只支持 JKS或PKCS12 格式的keystores. JKS格式是 Java 的标准 KeyStore格式，它可以用 Java 的 keytool 来产生。这个工具在 Java 的 bin 目录里。 PKCS12 格式时互联网的标准，可以用 OpenSSL 和微软的 Key-Manager来修改。
To import an existing certificate into a JKS keystore, please read the documentation (in your JDK documentation package) about keytool. Note that openssl often adds a readable comments before the key, keytooldoes not support that, so remove the openssl comments if they exist before importing the key using keytool.
使用OpenSSL把一个现存的被你自己CA签署的认证书输入到PKCS12 keystore里面，你会执行象这样的一个命令：
openssl pkcs12 -export -in mycert.crt -inkey mykey.key \
-out mycert.p12 -name tomcat -CAfile myCA.crt \
-caname root -chain
更深层的情况，请查阅OpenSSL documententation。
要从头开始产生一个新的keystore，包含一个自签的认证书，从一个终端命令行执行下面的命令：
视窗
%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
Unix
%JAVA_HOME%\bin\keytool -genkey -alias tomcat -keyalg RSA
( 应该把RSA运算法则作为主要安全运算法则，这保证了与其它服务器和组件的兼容性。)
这个命令会在用户的home directory产生一个叫做" .keystore " 的新文件。要指定一个不同的位置(location)或文件名，在上面所示的keytool 命令里添加-keystore参数，后面紧跟着你的keystore文件的全部路径名。你还需要把这个新的位置在server.xml配置文件中反映出来，这在后面将有描述。例如：
视窗
%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
在执行这个命令后，你首先被要求出示keystore密码。Tomcat使用的默认密码是 " changeit "(全都是小写字母)，如果你愿意，你可以指定你自己的密码。你还需要在server.xml配置文件里指定自己的密码，这在以后会有描述。
下一步，你会被要求出示关于这个认证书的一般性信息，如公司，联系人名称，等等。这些信息会显示给那些试图访问你程序里安全网页的用户，以确保这里提供的信息与他们期望的相对应。
最后，你会被要求出示密钥(key)密码，也就是这个认证书所特有的密码(与其它的储存在同一个keystore文件里的认证书不同)。你必须在这里使用与keystore 密码相同的密码。(目前，keytool会提示你按ENTER键会自动帮你做这些)。
如果一切顺利，你现在就拥有了一个可以被你的服务器使用的有认证书的keystore文件。
注意： 你的 private key 的密码和 keystore 的密码应该相同。如果不同的话你会得到一下错误信息： java.io.IOException: Cannot recover key 这是一个已知的错误，详细请看： Bugzilla issue 38217
3、Edit the Tomcat Configuration File
最后的步骤是把你的secure socket配置在$CATALINA_HOME/conf/server.xml文件里, $CATALINA_HOME代表你在其中安装Tomcat 5 的目录。一个例子是SSL连接器的<Connector>元素被包括在和Tomcat一起安装的缺省server.xml文件里。它看起来象是这样：
<-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!--
<Connector
port="8443" minProcessors="5" maxProcessors="75"
enableLookups="true" disableUploadTimeout="true"
acceptCount="100" debug="0" scheme="https" secure="true";
clientAuth="false" sslProtocol="TLS"/>
-->
你会注意到Connector元素本身，其默认形式是被注释掉的(commented out)，所以你需要把它周围的注释标志删除掉。然后，你可以根据需要客户化(自己设置)特定的属性。关于各种选项的详细信息，请查阅Server Configuration Reference 。下面的讨论仅仅涵盖设置SSL通信(communication)时大家最感兴趣的那些属性。
这个port属性(默认值是8443)是 TCP/IP端口数码，Tomcat在其上监听安全连接。你可以把它更改成任何你愿意要的数值(如默认的https通信，数目是443)。不过，在许多操作系统中，要想在比1024小的端口数码上运行Tomcat，需要特殊的设置(它超出了这个文档资料的范围)。
如果你在这里更改端口数值，你还必须更改在non-SSL连接器上的redirectPort 这个属性特定的值。这允许Tomcat自动地redirect那些试图访问有安全限制页面的用户，指明根据 Servlet 2.4 Specification要求，SSL是必需的。
有一些额外的选项被用来配置SSL协定。依赖于你早先怎样配置你的keystore，你也许需要添加或更改下列属性值：
属性 描述
clientAuth 如果你想要Tomcat要求所有的SSL客户在使用这个socket时出示用户认证书，把这个值设定为 true 。如果你想要Tomcat要求出示用户认证书，但是如果没有认证书也可以， 就把这个值设定为want 。
keystoreFile 如果你产生的keystore文件不在Tomcat期望的默认地方(一个叫做.keystore 的文件在Tomcat运行的主目录)，就添加这个属性。你可以指定一个绝对路径名称， 或者一个由$CATALINA_BASE环境变量而派生的相对路径名称。
keystorePass 如果你使用一个不同的keystore(以及认证书)密码，而不是Tomcat期望的密码 (就是changeit)，添加这个元素。
keystoreType 如果使用一个PKCS12 keystore的话，就添加这个element。 有效的值是JKS 和 PKCS12 。
sslProtocol 要在这个socket上被使用的加密／解密协定。如果你在使用Sun的JVM，我们不提倡更改 这个值。据报道，TLS协定的IBM's 1.4.1 实现与一些通用的浏览器不兼容。 如果是这样，就使用value SSL 。
ciphers 这个socket允许使用的由逗号分隔开的加密密码列单。默认的情况下，任何可用的密码都允许被使用。
algorithm 可用的X509算法。默认是Sun的实现( SunX509 )。 对于IBM JVMs，你应该使用值 IbmX509。对于其他卖主，查阅JVM文档资料来 找正确的值。
truststoreFile 用来验证用户认证书的TrustStore文件。
truststorePass 访问TrustStore的密码。默认值就是keystorePass的值。
truststoreType 如果你在使用与KeyStore不同格式的TrustStore，添加这个元素。 合法的值是JKS和PKCS12。
keyAlias 如果 keystore 里面有多个 key，你可以为用这个选项为加入的 key 起一个名字。 如果没有指定名字，使用时 keystore 内的第一个 key 将会被使用。
在完成这些配置更改后，你必须象通常那样重新启动Tomcat，然后你就可以工作了。你应该可以通过SSL访问Tomcat支持的任何web应用程序。例如，试一下下面的指令：
https://localhost:8443
你应该看到通常的Tomcat splash页面(除非你修改过ROOT web应用程序)。如果不行的话，下面的章节包含一些排除故障的提示。