Author: kkolinko
Date: Sun Nov 9 20:46:05 2014
New Revision: 1637733
URL: http://svn.apache.org/r1637733
Log:
CTR: docs
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.
Backport of r1637711 from tomcat/tc7.0.x/trunk.
Modified:
tomcat/tc6.0.x/trunk/ (props changed)
tomcat/tc6.0.x/trunk/webapps/docs/ssl-howto.xml
Propchange: tomcat/tc6.0.x/trunk/
------------------------------------------------------------------------------
Merged /tomcat/trunk:r1637695
Merged /tomcat/tc7.0.x/trunk:r1637711
Merged /tomcat/tc8.0.x/trunk:r1637709
Modified: tomcat/tc6.0.x/trunk/webapps/docs/ssl-howto.xml
URL:
http://svn.apache.org/viewvc/tomcat/tc6.0.x/trunk/webapps/docs/ssl-howto.xml?rev=1637733&r1=1637732&r2=1637733&view=diff
==============================================================================
--- tomcat/tc6.0.x/trunk/webapps/docs/ssl-howto.xml (original)
+++ tomcat/tc6.0.x/trunk/webapps/docs/ssl-howto.xml Sun Nov 9 20:46:05 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>
@@ -277,33 +278,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 BIO
implementation -->
+<Connector protocol="org.apache.coyote.http11.Http11Protocol"
+ port="8443" .../>
+
+<!-- Define a HTTP/1.1 Connector on port 8443, JSSE NIO implementation -->
+<Connector protocol="org.apache.coyote.http11.Http11NioProtocol"
+ 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>
@@ -317,12 +318,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.
@@ -337,19 +335,20 @@ for an SSL connector is included in the
file installed with Tomcat. For JSSE, it should look something like this:</p>
<source>
<!-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 -->
-<Connector
+<Connector
+ protocol="org.apache.coyote.http11.Http11Protocol"
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
- SSL keys and certificates. An example of an APR configuration is:
+ 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
+<Connector
+ protocol="org.apache.coyote.http11.Http11AprProtocol"
port="8443" maxThreads="200"
scheme="https" secure="true" SSLEnabled="true"
SSLCertificateFile="/usr/local/ssl/server.crt"
@@ -358,18 +357,14 @@ file installed with Tomcat. For JSSE, i
</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 for the JSSE based connectors (BIO and NIO) are documented in the
SSL Support section of the <a href="config/http.html#SSL Support">HTTP
connector</a> configuration reference. The configuration options and
information
on which attributes are mandatory for the APR connector are documented in the
HTTPS section of the <a href="apr.html#HTTPS">APR How-To</a>.</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
@@ -407,7 +402,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>)
@@ -486,7 +481,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>
---------------------------------------------------------------------
To unsubscribe, e-mail: dev-unsubscr...@tomcat.apache.org
For additional commands, e-mail: dev-h...@tomcat.apache.org
