快速开始

重要注意事项：此Howto是指jseck 1.5及更高版本中包含的JSSE的使用。当使用APR时，JBoss Web将使用OpenSSL，它使用不同的配置。

下面的描述使用变量名称$ CATALINA_HOME来指向安装了JBoss Web的目录，并且是解决大多数相对路径的基本目录。但是，如果您通过设置CATALINA_BASE目录为多个实例配置JBoss Web，则应为每个引用使用$ CATALINA_BASE而不是$ CATALINA_HOME。

要在JBoss Web上安装和配置SSL支持，您需要遵循这些简单的步骤。有关更多信息，请阅读其余的HOW-TO。

1. 通过执行以下命令创建证书密钥库：

   视窗：

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

   Unix的：

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

   
   

   并指定密码值“changeit”。





2. 取消注释“SSL HTTP / 1.1连接器”条目， $CATALINA_HOME/conf/server.xml并根据需要进行调整。

SSL简介

SSL或安全套接字层是允许Web浏览器和Web服务器通过安全连接进行通信的技术。这意味着正在发送的数据被一侧加密，发送，然后在处理之前被另一方解密。这是一个双向过程，这意味着在发送数据之前，服务器和浏览器都会加密所有流量。

SSL协议的另一个重要方面是认证。这意味着在您初次尝试通过安全连接与Web服务器进行通信时，该服务器将以“证书”的形式向您的Web浏览器提供一组凭据，作为网站是谁以及其声明的证明成为。在某些情况下，服务器也可能从您的网络浏览器请求证书，要求您证明您是您声称的。这被称为“客户端身份验证”，虽然在实践中，这比企业对企业（B2B）交易更多地用于个人用户。大多数支持SSL的Web服务器不要求客户端身份验证。

SSL和JBoss Web

重要的是要注意，将JBoss Web配置为利用安全套接字通常仅在作为独立Web服务器运行时才需要。当JBoss Web主要作为Servlet / JSP容器运行在另一个Web服务器（如Apache或Microsoft IIS）后面时，通常需要配置主Web服务器来处理用户的SSL连接。通常，该服务器将协商所有与SSL相关的功能，然后在解密这些请求之后传递发往JBoss Web容器的任何请求。同样，JBoss Web将返回明文响应，这些响应将在被返回给用户浏览器之前被加密。在这种环境下，

证书

为了实现SSL，Web服务器必须具有接受安全连接的每个外部接口（IP地址）的关联证书。这种设计背后的理论是，服务器应该提供某种合理的保证，即其所有者是您认为的，特别是在收到任何敏感信息之前。虽然对证书的更广泛的解释超出了本文件的范围，但是将认证作为互联网地址的“数字驾驶执照”。它说明了与该网站相关联的公司，以及关于网站所有者或管理员的一些基本联系信息。

这个“驾驶执照”是由其所有者进行密码签名的，因此其他任何人都难以伪造。对于涉及电子商务的网站或身份认证重要的任何其他业务交易，证书通常从知名的 认证机构（CA）（如VeriSign或Thawte）购买。这些证书可以通过电子方式进行验证 - 实际上，证书颁发机构将证明其授予的证书的真实性，因此如果您信任授予该证书的证书颁发机构，您可以相信该证书是有效的。

然而，在许多情况下，身份验证并不是一个问题。管理员可能只想确保服务器发送和接收的数据是私有的，并且不能被任何可能在连接上被窃听的人窥探。幸运的是，Java提供了一个相对简单的命令行工具，keytool可以轻松创建“自签名”证书。自签名证书只是用户生成的证书，尚未正式注册到任何知名的CA，因此根本不保证是真实的。再次，这可能甚至不是重要的，这取决于你的需要。

运行SSL的一般提示

用户第一次尝试访问您网站上的安全页面时，他或她通常会显示一个包含证书详细信息（如公司和联系人姓名）的对话框，并询问他或她是否希望接受证书有效并继续交易。某些浏览器将提供永久接受给定证书的有效选项，在这种情况下，用户每次访问您的站点时都不会被打扰。其他浏览器不提供此选项。一旦被用户批准，证书将至少被认为对整个浏览器会话有效。

此外，虽然SSL协议被设计为尽可能高效，但从性能的角度来看，加密/解密是一个计算上昂贵的过程。通过SSL运行整个Web应用程序并不是绝对必要的，开发人员也可以选择哪些页面需要安全连接，哪些页面不需要。对于一个相当繁忙的网站，通常只能运行SSL下的某些页面，即可能会交换敏感信息的页面。这将包括登录页面，个人信息页面和购物车结帐等信息卡信息可能传输的信息。应用程序中的任何页面都可以通过安全套接字来通过简单的前缀地址来https:代替http:。任何绝对的页面要求 安全连接应检查与页面请求相关联的协议类型，并采取适当的措施，如果https没有指定。

最后，在安全连接上使用基于名称的虚拟主机可能是有问题的。这是SSL协议本身的设计限制。客户端浏览器接受服务器证书的SSL握手必须在HTTP请求被访问之前进行。结果，在认证之前不能确定包含虚拟主机名的请求信息，因此不能将多个证书分配给单个IP地址。如果单个IP地址上的所有虚拟主机需要针对相同的证书进行身份验证，则添加多个虚拟主机不应干扰服务器上的正常SSL操作。但请注意，大多数客户端浏览器会将服务器的域名与证书中列出的域名进行比较（如果有的话）（主要适用于官方，CA签署的证书）。如果域名不匹配，这些浏览器将向客户端用户显示警告。通常，只有基于地址的虚拟主机通常在生产环境中与SSL一起使用。

组态

准备证书密钥库

JBoss应用目前才动作JKS，PKCS11或 PKCS12格式的密钥库。该JKS格式是Java的标准“Java密钥库”的格式，并且是由创建的格式 keytool命令行实用程序。此工具包含在JDK中。该PKCS12格式是一个互联网标准，可以通过OpenSSL和Microsoft的密钥管理器（除其他外）进行操作。

密钥库中的每个条目都由别名字符串标识。虽然许多密钥库隐含处理方式不区分大小写，但区分大小写的实现是可用的。在PKCS11说明书中，例如，要求的别名是大小写敏感的。为了避免与别名区分大小写有关的问题，建议不要使用不同的别名。

要将现有证书导入到JKS密钥库中，请阅读有关文档（在JDK文档包中）keytool。请注意，OpenSSL通常在密钥之前添加可读注释，keytool不支持，所以在导入密钥之前删除OpenSSL注释（如果存在）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文档。

要从头创建一个新的密钥库，包含一个自签名证书，请从终端命令行执行以下操作：

视窗：

%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

执行此命令后，将首先提示您输入密钥库密码。JBoss Web使用的默认密码为“ changeit”（全部为小写），但您可以指定自定义密码。您还需要在server.xml配置文件中指定自定义密码 ，如下所述。

接下来，系统将提示您提供有关此证书的一般信息，例如公司，联系人姓名等。此信息将显示给尝试访问应用程序中安全页面的用户，因此请确保此处提供的信息与您期望的信息相匹配。

最后，系统将提示您输入密码密码，这是该证书专用的密码（而不是存储在同一密钥库文件中的任何其他证书）。您必须 在密码库密码本身使用与密码相同的密码。（目前，keytool提示会告诉您，按ENTER键可以自动执行此操作。）

如果一切都成功，您现在有一个密钥库文件，其中包含可以由您的服务器使用的证书。

注意：您的私钥密码和密钥库密码应该相同。如果它们有所不同，那么您会收到错误java.io.IOException: Cannot recover key，如 Bugzilla问题38217中所述，其中包含此问题的进一步参考。

编辑JBoss Web配置文件

如果您使用的是APR，则可以选择为openSSL配置替代引擎。

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

默认值为

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

所以要在APR下使用SSL，请确保将SSLEngine属性设置为不同于off。默认值为on，如果指定另一个值，则必须是有效的引擎名称。 
如果您尚未在Tomcat Native库中编译SSL支持，则可以关闭此初始化

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

SSLRandomSeed允许指定熵的来源。生产系统需要可靠的熵源，但是熵可能需要大量的时间才能被收集，因此测试系统可以不使用诸如“/ dev / urandom”的阻塞熵源，这将允许更快启动JBoss Web。

最后一步是在$CATALINA_HOME/conf/server.xml文件中配置安全套接字 ，其中 $CATALINA_HOME表示安装JBoss Web的目录。 使用JBoss Web安装<Connector>的默认server.xml文件中包含SSL连接器的示例元素。它看起来像这样：

<-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!--
<Connector 
           port="8443" minSpareThreads="5" maxSpareThreads="75"
           enableLookups="true" disableUploadTimeout="true" 
           acceptCount="100"  maxThreads="200"
           scheme="https" secure="true" SSLEnabled="true"
           keystoreFile="${user.home}/.keystore" keystorePass="changeit"
           clientAuth="false" sslProtocol="TLS"/>
-->

如果您的路径中有APR和Tomcat Native库，则上面的示例会抛出错误，因为tomcat会尝试自动加载APR连接器。APR连接器对SSL密钥和证书使用不同的属性。这种配置的一个例子是

<-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!--
<Connector 
           port="8443" minSpareThreads="5" maxSpareThreads="75"
           enableLookups="true" disableUploadTimeout="true" 
           acceptCount="100"  maxThreads="200"
           scheme="https" secure="true" SSLEnabled="true"
           SSLCertificateFile="/usr/local/ssl/server.crt" 
           SSLCertificateKeyFile="/usr/local/ssl/server.pem"
           clientAuth="false" sslProtocol="TLS"/>
-->

为了避免自动配置，您可以通过在协议属性中指定一个类名来定义要使用的连接器。
要定义Java连接器，无论APR库是否加载，请执行以下操作：

<-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!--
<Connector protocol="org.apache.coyote.http11.Http11Protocol"
           port="8443" minSpareThreads="5" maxSpareThreads="75"
           enableLookups="true" disableUploadTimeout="true" 
           acceptCount="100"  maxThreads="200"
           scheme="https" secure="true" SSLEnabled="true"
           keystoreFile="${user.home}/.keystore" keystorePass="changeit"
           clientAuth="false" sslProtocol="TLS"/>
-->

并指定APR连接器

<-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 -->
<!--
<Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
           port="8443" minSpareThreads="5" maxSpareThreads="75"
           enableLookups="true" disableUploadTimeout="true" 
           acceptCount="100"  maxThreads="200"
           scheme="https" secure="true" SSLEnabled="true"
           SSLCertificateFile="/usr/local/ssl/server.crt" 
           SSLCertificateKeyFile="/usr/local/ssl/server.pem"
           clientAuth="false" sslProtocol="TLS"/>
-->

您将注意到，连接器元素本身默认注释掉，因此您需要删除其周围的注释标签。然后，您可以根据需要自定义指定的属性。有关各种选项的详细信息，请参阅“ 服务器配置参考”。以下讨论仅涉及设置SSL通信时最感兴趣的那些属性。

该port属性（默认值是8443），是在其JBoss应用将监听安全连接的TCP / IP端口号。您可以将其更改为所需的任何端口号（例如，到https通信的默认端口 ，即443）。但是，在许多操作系统上运行JBoss Web端口号低于1024的特殊设置（本文档范围之外）是必需的。

如果在此更改端口号，则还应更改redirectPort非SSL连接器上属性指定的值。这允许JBoss Web根据Servlet 2.4规范的要求自动重定向尝试访问具有指定需要SSL的安全约束的页面的用户。

还有其他选项用于配置SSL协议。您可能需要添加或更改以下属性值，这取决于您之前配置密钥库的方式：

属性	描述
algorithm	要使用的证书编码算法。这默认为Sun实现（SunX509）。对于IBM JVM，您应该使用该值IbmX509。对于其他供应商，请查阅JVM文档以获得正确的值。
clientAuth	设置为true如果希望SSL堆栈在接受连接之前从客户端请求有效的证书链。设置为want是否希望SSL堆栈请求客户端证书，但如果没有显示客户端证书，则不会失败。一false ，除非客户端请求由使用安全约束保护的资源值（默认值）将不需要证书链CLIENT-CERT认证。
keystoreFile	存储要加载的服务器证书的密钥库文件的路径名。默认情况下，路径名.keystore是运行JBoss Web的用户的操作系统主目录中的文件“ ”。
keystorePass	用于从指定的密钥库文件访问服务器证书的密码。默认值为“ changeit”。
keystoreType	要用于服务器证书的密钥库文件的类型。如果未指定，默认值为“ JKS”。例如，可以使用openssl中的* .p12文件 PKCS12
sslProtocol	要使用的SSL协议版本。如果未指定，默认值为“ TLS”。
ciphers	可以使用的加密密码的逗号分隔列表。如果未指定，则可以使用任何可用的密码。
keyAlias	用于密钥库中服务器证书的别名。如果未指定，将使用在密钥库中读取的第一个密钥。
truststoreFile	用于验证客户端证书的TrustStore文件。
truststorePass	访问TrustStore的密码。默认值为keystorePass。
truststoreType	如果您使用的是用于KeyStore的TrustStore的不同格式，请添加此元素。

完成这些配置更改后，您必须按照通常的方式重新启动JBoss Web，并且您应该进行业务。您应该能够通过SSL访问JBoss Web支持的任何Web应用程序。例如，尝试：

https://localhost:8443

您应该看到通常的JBoss Web启动页面（除非您已修改ROOT Web应用程序）。如果这不起作用，以下部分包含一些故障排除提示。

从证书颁发机构安装证书

要从证书颁发机构（如verisign.com，thawte.com或trustcenter.de）获取并安装证书，请阅读上一节，然后按照以下说明进行操作：

创建本地证书签名请求（CSR）

为了从您选择的证书颁发机构获得证书，您必须创建一个所谓的证书签名请求（CSR）。认证机构将使用该CSR来创建一个将您的网站标识为“安全”的证书。要创建CSR，请执行以下步骤：

• 创建本地证书（如上一节所述）：

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

  注意：在某些情况下，您必须www.myside.org在“首页和姓氏”字段中输入您网站的域名（ie ），才能创建工作证书。

• 然后创建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>

故障排除

以下列出了在设置SSL通信时可能遇到的常见问题，以及如何处理。

• 我的日志文件中出现“java.security.NoSuchAlgorithmException”错误。

  JVM找不到JSSE JAR文件。按照所有方向 下载并安装JSSE。

• 当JBoss Web启动时，我收到一个例外，如“java.io.FileNotFoundException：{some-directory} / {some-file} not found”。

  可能的解释是JBoss Web找不到它所在的密钥库文件。默认情况下，JBoss Web希望密钥库文件.keystore在用户主目录（在其中运行JBoss Web的目录中）命名（可能与您的不同:-)可能不一样。如果密钥库文件位于其他位置，则需要向JBoss Web配置文件中keystoreFile的<Factory> 元素添加一个 属性。

• 当JBoss Web启动时，我收到一个例外，如“java.io.FileNotFoundException：Keystore被篡改，或密码不正确”。

  假设有人实际上没有篡改您的密钥存储文件，最可能的原因是JBoss Web使用的密码与创建密钥库文件时使用的密码不同。要解决此问题，您可以返回并 重新创建密钥库文件，也可以添加或更新JBoss Web配置文件中元素 keystorePass 上的属性。 提醒 - 密码区分大小写！<Connector>

• 当JBoss Web启动时，我收到一个异常，如“java.net.SocketException：SSL handshake errorjavax.net.ssl.SSLException：没有可用的证书或密钥对应于启用的SSL密码套件”。

  可能的解释是JBoss Web在指定的密钥库中找不到服务器密钥的别名。检查是否正确keystoreFile，并keyAlias在指定 <Connector>的元素中 的JBoss Web配置文件。 提醒 - keyAlias值可能区分大小写！

如果您仍然遇到问题，一个很好的信息来源是 TOMCAT-USER邮件列表。您可以在http://tomcat.apache.org/lists.html上找到此列表上以前邮件归档的指针以及订阅和取消订阅信息 。

其他提示和位

要从请求访问SSL会话ID，请使用：
String sslID = (String)request.getAttribute("javax.servlet.request.ssl_session");