You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@tomcat.apache.org by kk...@apache.org on 2014/11/09 19:35:49 UTC
svn commit: r1637711 - in /tomcat/tc7.0.x/trunk: ./
webapps/docs/ssl-howto.xml
Author: kkolinko
Date: Sun Nov 9 18:35:48 2014
New Revision: 1637711
URL: http://svn.apache.org/r1637711
Log:
Minor improvements to SSL how-to.
- Hilite keystore type (JKS vs PKCS12) to lessen confusion
- Recommend to explicitly specify a protocol implementation when using SSL, instead of "HTTP/1.1"
- Update examples to use explicit protocol implementation instead of "HTTP/1.1"
- Remove example of setting SSLEngine="off" with APR. It makes no sense on this page as here we are enabling SSL, not disabling it. The "off" value is documented elsewhere.
- The "8443" is not the default value for a port, as far as I know. One has to explicitly configure it.
Merged r1637709 from tomcat/tc8.0.x/trunk.
Modified:
tomcat/tc7.0.x/trunk/ (props changed)
tomcat/tc7.0.x/trunk/webapps/docs/ssl-howto.xml
Propchange: tomcat/tc7.0.x/trunk/
------------------------------------------------------------------------------
Merged /tomcat/trunk:r1637695
Merged /tomcat/tc8.0.x/trunk:r1637709
Modified: tomcat/tc7.0.x/trunk/webapps/docs/ssl-howto.xml
URL: http://svn.apache.org/viewvc/tomcat/tc7.0.x/trunk/webapps/docs/ssl-howto.xml?rev=1637711&r1=1637710&r2=1637711&view=diff
==============================================================================
--- tomcat/tc7.0.x/trunk/webapps/docs/ssl-howto.xml (original)
+++ tomcat/tc7.0.x/trunk/webapps/docs/ssl-howto.xml Sun Nov 9 18:35:48 2014
@@ -201,13 +201,14 @@ to the case sensitivity of aliases, it i
differ only in case.
</p>
-<p>To import an existing certificate into a JKS keystore, please read the
+<p>To import an existing certificate into a <code>JKS</code> keystore, please read the
documentation (in your JDK documentation package) about <code>keytool</code>.
-Note that OpenSSL often adds readable comments before the key,
-<code>keytool</code>does not support that, so remove the OpenSSL comments if
-they exist before importing the key using <code>keytool</code>.
+Note that OpenSSL often adds readable comments before the key, but
+<code>keytool</code> does not support that. So if your certificate has
+comments before the key data, remove them before importing the certificate with
+<code>keytool</code>.
</p>
-<p>To import an existing certificate signed by your own CA into a PKCS12
+<p>To import an existing certificate signed by your own CA into a <code>PKCS12</code>
keystore using OpenSSL you would execute a command like:</p>
<source>openssl pkcs12 -export -in mycert.crt -inkey mykey.key
-out mycert.p12 -name tomcat -CAfile myCA.crt
@@ -215,8 +216,8 @@ keystore using OpenSSL you would execute
<p>For more advanced cases, consult the <a href="http://www.openssl.org/">OpenSSL
documentation</a>.
</p>
-<p>To create a new keystore from scratch, containing a single self-signed
-Certificate, execute the following from a terminal command line:</p>
+<p>To create a new <code>JKS</code> keystore from scratch, containing a single
+self-signed Certificate, execute the following from a terminal command line:</p>
<p>Windows:</p>
<source>"%JAVA_HOME%\bin\keytool" -genkey -alias tomcat -keyalg RSA</source>
<p>Unix:</p>
@@ -272,33 +273,33 @@ Tomcat can use two different implementat
<li>the APR implementation, which uses the OpenSSL engine by default.</li>
</ul>
The exact configuration details depend on which implementation is being used.
-The implementation used by Tomcat is chosen automatically unless it is overriden as described below.
-If the installation uses <a href="apr.html">APR</a>
+If you configured Connector by specifying generic
+<code>protocol="HTTP/1.1"</code> then the implementation used by Tomcat is
+chosen automatically. If the installation uses <a href="apr.html">APR</a>
- i.e. you have installed the Tomcat native library -
-then it will use the APR SSL implementation, otherwise it will use the Java JSSE implementation.
+then it will use the APR SSL implementation, otherwise it will use the Java
+JSSE implementation.
</p>
<p>
- To avoid auto configuration you can define which implementation to use by specifying a classname
- in the <b>protocol</b> attribute of the Connector.<br/>
- To define a Java (JSSE) connector, regardless of whether the APR library is loaded or not do:
-<source>
-<!-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
-<Connector protocol="org.apache.coyote.http11.Http11Protocol"
- port="8443" .../>
-
-<!-- Define a non-blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 -->
-<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
- port="8443" .../>
-</source>
-Alternatively, to specify an APR connector (the APR library must be available) use:
-<source>
-<!-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 -->
-<Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
- port="8443" .../>
-</source>
-
-</p>
+As configuration attributes for SSL support significally differ between
+APR vs. JSSE implementations, it is <strong>recommended</strong> to
+avoid auto-selection of implementation. It is done by specifying a classname
+in the <b>protocol</b> attribute of the <a href="config/http.html">Connector</a>.</p>
+
+<p>To define a Java (JSSE) connector, regardless of whether the APR library is
+loaded or not, use one of the following:</p>
+<source><![CDATA[<!-- Define a HTTP/1.1 Connector on port 8443, JSSE NIO implementation -->
+<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
+ port="8443" .../>
+
+<!-- Define a HTTP/1.1 Connector on port 8443, JSSE BIO implementation -->
+<Connector protocol="org.apache.coyote.http11.Http11Protocol"
+ port="8443" .../>]]></source>
+<p>Alternatively, to specify an APR connector (the APR library must be available) use:</p>
+<source><![CDATA[<!-- Define a HTTP/1.1 Connector on port 8443, APR implementation -->
+<Connector protocol="org.apache.coyote.http11.Http11AprProtocol"
+ port="8443" .../>]]></source>
<p>If you are using APR, you have the option of configuring an alternative engine to OpenSSL.
<source>
@@ -312,12 +313,9 @@ The default value is
</source>
So to use SSL under APR, make sure the SSLEngine attribute is set to something other than <code>off</code>.
The default value is <code>on</code> and if you specify another value, it has to be a valid engine name.
-<br/>
-If you haven't compiled in SSL support into your Tomcat Native library, then you can turn this initialization off
-<source>
-<Listener className="org.apache.catalina.core.AprLifecycleListener"
- SSLEngine="off" />
-</source>
+</p>
+
+<p>
SSLRandomSeed allows to specify a source of entropy. Productive system needs a reliable source of entropy
but entropy may need a lot of time to be collected therefore test systems could use no blocking entropy
sources like "/dev/urandom" that will allow quicker starts of Tomcat.
@@ -335,21 +333,19 @@ this:</p>
<source>
<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<Connector
- protocol="HTTP/1.1"
+ protocol="org.apache.coyote.http11.Http11NioProtocol"
port="8443" maxThreads="200"
scheme="https" secure="true" SSLEnabled="true"
keystoreFile="${user.home}/.keystore" keystorePass="changeit"
clientAuth="false" sslProtocol="TLS"/>
</source>
<p>
- The example above will throw an error if you have the APR and the Tomcat
- Native libraries in your path, as Tomcat will try to use the APR connector.
The APR connector uses different attributes for many SSL settings,
particularly keys and certificates. An example of an APR configuration is:
<source>
<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
<Connector
- protocol="HTTP/1.1"
+ protocol="org.apache.coyote.http11.Http11AprProtocol"
port="8443" maxThreads="200"
scheme="https" secure="true" SSLEnabled="true"
SSLCertificateFile="/usr/local/ssl/server.crt"
@@ -358,18 +354,14 @@ this:</p>
</source>
</p>
-<p>You will note that the example SSL connector elements are commented out by
-default. You can either remove the comment tags from around the the example SSL
-connector you wish to use or add a new Connector element of your own. In either
-case, you will need to configure the SSL Connector for your requirements
-and environment. The configuration options and information on which attributes
+<p>The configuration options and information on which attributes
are mandatory, are documented in the SSL Support section of the
<a href="config/http.html#SSL Support">HTTP connector</a> configuration
reference. Make sure that you use the correct attributes for the connector you
are using. The BIO and NIO connectors use JSSE whereas the APR/native connector
uses APR.</p>
-<p>The <code>port</code> attribute (default value is 8443) is the TCP/IP
+<p>The <code>port</code> attribute is the TCP/IP
port number on which Tomcat will listen for secure connections. You can
change this to any port number you wish (such as to the default port for
<code>https</code> communications, which is 443). However, special setup
@@ -406,7 +398,7 @@ you have to create a so called Certifica
by the Certificate Authority to create a Certificate that will identify your website
as "secure". To create a CSR follow these steps:</p>
<ul>
-<li>Create a local Certificate (as described in the previous section):
+<li>Create a local self-signed Certificate (as described in the previous section):
<source>keytool -genkey -alias tomcat -keyalg RSA
-keystore <your_keystore_filename></source>
Note: In some cases you will have to enter the domain of your website (i.e. <code>www.myside.org</code>)
@@ -485,7 +477,7 @@ SSL communications, and what to do about
</blockquote></li>
<li>When Tomcat starts up, I get an exception like
- "java.net.SocketException: SSL handshake errorjavax.net.ssl.SSLException: No
+ "java.net.SocketException: SSL handshake error javax.net.ssl.SSLException: No
available certificate or key corresponds to the SSL cipher suites which are
enabled."
<blockquote>
@@ -516,7 +508,8 @@ information, at
<li>Tomcat must have a connector with the attribute
<strong>isSecure</strong> set to <code>true</code>.</li>
<li>If SSL connections are managed by a proxy or a hardware accelerator
- they must populate the SSL request headers (see the SSLValve) so that
+ they must populate the SSL request headers (see the
+ <a href="config/valve.html">SSLValve</a>) so that
the SSL session ID is visible to Tomcat.</li>
<li>If Tomcat terminates the SSL connection, it will not be possible to use
session replication as the SSL session IDs will be different on each
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscribe@tomcat.apache.org
For additional commands, e-mail: dev-help@tomcat.apache.org