From 1a94358e1c79dfc10c981b6d9dc1afa3ead47f74 Mon Sep 17 00:00:00 2001 From: markt Date: Sun, 20 Sep 2009 23:10:15 +0000 Subject: [PATCH] Fix https://issues.apache.org/bugzilla/show_bug.cgi?id=47231 Improve the SSL docs. Based on a patch by Sebb. Remove duplication of configuration parameters - it is better to reference the config docs to prevent the two lists of attributes getting out of sync. git-svn-id: https://svn.apache.org/repos/asf/tomcat/trunk@817120 13f79535-47bb-0310-9956-ffa450edef68 --- webapps/docs/ssl-howto.xml | 216 ++++++++++++--------------------------------- 1 file changed, 54 insertions(+), 162 deletions(-) diff --git a/webapps/docs/ssl-howto.xml b/webapps/docs/ssl-howto.xml index a40322bc2..0248244ae 100644 --- a/webapps/docs/ssl-howto.xml +++ b/webapps/docs/ssl-howto.xml @@ -33,10 +33,6 @@
-

IMPORTANT NOTE: This Howto refers to usage of JSSE, that comes included with - jdk 1.5 and higher. When using APR, Tomcat will - use OpenSSL, which uses a different configuration.

-

The description below uses the variable name $CATALINA_BASE to refer the base directory against which most relative paths are resolved. If you have @@ -60,7 +56,8 @@ $JAVA_HOME/bin/keytool -genkey -alias tomcat -keyalg RSA

and specify a password value of "changeit".

  • Uncomment the "SSL HTTP/1.1 Connector" entry in - $CATALINA_BASE/conf/server.xml and tweak as necessary.
    • + $CATALINA_BASE/conf/server.xml and modify as described in + the Configuration section below.

    @@ -267,6 +264,7 @@ sure that the information provided here matches what they will expect.

    password specifically for this Certificate (as opposed to any other Certificates stored in the same keystore file). You MUST use the same password here as was used for the keystore password itself. +This is a restriction of the Tomcat implementation. (Currently, the keytool prompt will tell you that pressing the ENTER key does this for you automatically.)

    @@ -282,6 +280,41 @@ which contains further references for this issue.

    +

    +Tomcat can use two different implementations of SSL: +

      +
    • the JSSE implementation provided as part of the Java runtime (since 1.4)
      • +
    • the APR implementation, which uses the OpenSSL engine by default.
      • +
    +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 APR +- 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. +

    + +

    + To avoid auto configuration you can define which implementation to use by specifying a classname + in the protocol attribute of the Connector.
    + To define a Java (JSSE) connector, regardless of whether the APR library is loaded or not do: + +<-- 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" .../> + +Alternatively, to specify an APR connector (the APR library must be available) use: + +<-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 --> +<Connector protocol="org.apache.coyote.http11.Http11AprProtocol" + port="8443" .../> + + +

    +

    If you are using APR, you have the option of configuring an alternative engine to OpenSSL. <Listener className="org.apache.catalina.core.AprLifecycleListener" @@ -306,19 +339,17 @@ sources like "/dev/urandom" that will allow quicker starts of Tomcat.

    -

    The final step is to configure your secure socket in the +

    The final step is to configure the Connector in the $CATALINA_BASE/conf/server.xml file, where $CATALINA_BASE represents the base directory for the Tomcat 6 instance. An example <Connector> element for an SSL connector is included in the default server.xml -file installed with Tomcat. It will look something like this:

    +file installed with Tomcat. For JSSE, it should look something like this:

    <-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 --> <!-- <Connector - port="8443" minSpareThreads="5" - enableLookups="true" disableUploadTimeout="true" - acceptCount="100" maxThreads="200" + port="8443" maxThreads="200" scheme="https" secure="true" SSLEnabled="true" keystoreFile="${user.home}/.keystore" keystorePass="changeit" clientAuth="false" sslProtocol="TLS"/> @@ -326,64 +357,19 @@ file installed with Tomcat. It will look something like this:

    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 autoload the APR connector. The APR connector uses different attributes for - SSL keys and certificates. An example of such configuration would be + 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: <-- Define a SSL Coyote HTTP/1.1 Connector on port 8443 --> <!-- <Connector - port="8443" minSpareThreads="5" - 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"/> ---> - -

    - -

    - To avoid auto configuration you can define which connector to use by specifying a classname - in the protocol attribute.
    - To define a Java connector, regardless if the APR library is loaded or not do: - -<-- Define a blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 --> -<!-- -<Connector protocol="org.apache.coyote.http11.Http11Protocol" - port="8443" minSpareThreads="5" - enableLookups="true" disableUploadTimeout="true" - acceptCount="100" maxThreads="200" - scheme="https" secure="true" SSLEnabled="true" - keystoreFile="${user.home}/.keystore" keystorePass="changeit" - clientAuth="false" sslProtocol="TLS"/> ---> -<-- Define a non-blocking Java SSL Coyote HTTP/1.1 Connector on port 8443 --> -<!-- -<Connector protocol="org.apache.coyote.http11.Http11NioProtocol" - port="8443" minSpareThreads="5" - enableLookups="true" disableUploadTimeout="true" - acceptCount="100" maxThreads="200" - scheme="https" secure="true" SSLEnabled="true" - keystoreFile="${user.home}/.keystore" keystorePass="changeit" - clientAuth="false" sslProtocol="TLS"/> ---> - -and to specify an APR connector - -<-- Define a APR SSL Coyote HTTP/1.1 Connector on port 8443 --> -<!-- -<Connector protocol="org.apache.coyote.http11.Http11AprProtocol" - port="8443" minSpareThreads="5" - enableLookups="true" disableUploadTimeout="true" - acceptCount="100" maxThreads="200" + port="8443" maxThreads="200" scheme="https" secure="true" SSLEnabled="true" SSLCertificateFile="/usr/local/ssl/server.crt" SSLCertificateKeyFile="/usr/local/ssl/server.pem" - clientAuth="false" sslProtocol="TLS"/> + clientAuth="optional" SSLProtocol="TLSv1"/> --> -

    You will note that the Connector element itself is commented out by default, @@ -406,111 +392,17 @@ numbers lower than 1024 on many operating systems.

    value specified for the redirectPort attribute on the non-SSL connector. This allows Tomcat to automatically redirect users who attempt to access a page with a security constraint specifying - that SSL is required, as required by the Servlet 2.4 Specification.

    + that SSL is required, as required by the Servlet Specification.

    -

    There are additional options used to configure the SSL protocol. - You may need to add or change the following attribute -values, depending on how you configured your keystore earlier:

    - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
    AttributeDescription
    clientAuthSet this value to true if you want Tomcat to require - all SSL clients to present a client Certificate in order to use - this socket. Set this value to want if you want Tomcat - to request a client Certificate, but not fail if one isn't presented. - A false value (which is the default) will not require a - certificate chain unless the client requests a resource protected by a - security constraint that uses CLIENT-CERT authentication. -
    SSLEnabled - Use this attribute to enable SSL traffic on a connector. - To turn on SSL handshake/encryption/decryption on a connector - set this value to true. - The default value is false. - When turning this value true you will want to set the - scheme and the secure attributes as well - to pass the correct request.getScheme() and - request.isSecure() values to the servlets -
    keystoreFileAdd this attribute if the keystore file you created is not in - the default place that Tomcat expects (a file named - .keystore in the user home directory under - which Tomcat is running). You can specify an absolute pathname, - or a relative pathname that is resolved against the - $CATALINA_BASE environment variable.
    keystorePassAdd this element if you used a different keystore (and Certificate) - password than the one Tomcat expects (changeit).
    keystoreTypeAdd this element if using a keystore type other than JKS. - For example the *.p12 files from OpenSSL can be used using PKCS12.
    sslProtocolThe encryption/decryption protocol to be used on this socket. - It is not recommended to change this value if you are using Sun's - JVM. It is reported that IBM's 1.4.1 implementation - of the TLS protocol is not compatible with some popular browsers. - In this case, use the value SSL.
    ciphersThe comma separated list of encryption ciphers that this socket is - allowed to use. By default, the default ciphers for the JVM will be - used. Note that this usually means that the weak export grade ciphers - will be included in the list of available ciphers. The ciphers are - specified using the JSSE cipher naming convention.
    algorithmThe X509 algorithm to use. This defaults to the Sun - implementation (SunX509). For IBM JVMs you should use - the value IbmX509. For other vendors, consult the JVM - documentation for the correct value. -
    truststoreFileThe TrustStore file to use to validate client certificates.
    truststorePassThe password to access the TrustStore. This defaults to the value - of keystorePass.
    truststoreTypeAdd this element if your are using a different format for the - TrustStore then you are using for the KeyStore.
    keyAliasAdd this element if your have more than one key in the KeyStore. - If the element is not present the first key read in the KeyStore - will be used.
    crlFileThe certificate revocation list file to use to validate client - certificates.
    +

    There are additional options used to configure the SSL protocol. You may +need to add or change some attributes, depending on how you configured your +keystore earlier. If you are using a Java JSSE based SSL connector then +configuration options are documented in the +Java HTTP connector configuration +reference. If you are using the APR/native connector then refer to the +APR connector configuration guide for details of the +available configuration options.

    After completing these configuration changes, you must restart Tomcat as you normally do, and you should be in business. You should be able to access -- 2.11.0