<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"
"http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
<!ENTITY % BOOK_ENTITIES SYSTEM "../User_Guide.ent">
%BOOK_ENTITIES;
]>
<chapter id="UsingSSL">
  <title>Using SSL in mod_cluster</title>

  <para>There are 2 connections between the cluster and the front-end. Both
  could be encrypted. That chapter describes how to encrypt both
  connections.</para>

  <sect1>
    <title>Using SSL between JBossWEB and httpd</title>

    <para>As the ClusterListener allows to configure httpd it is adviced to
    use SSL for that connection. The most easy is to use a virtual host that
    will only be used to receive information from JBossWEB. Both side need
    configuration.</para>

    <sect2>
      <title>Apache httpd configuration part</title>

      <para><ulink
      url="http://httpd.apache.org/docs/2.2/mod/mod_ssl.html">mod_ssl</ulink>
      of httpd is using to do that. See in one example how easy the
      configuration is:<programlisting> Listen 6666
 &lt;VirtualHost 10.33.144.3:6666&gt;
     SSLEngine on
     SSLCipherSuite AES128-SHA:ALL:!ADH:!LOW:!MD5:!SSLV2:!NULL
     SSLCertificateFile conf/server.crt
     SSLCertificateKeyFile conf/server.key
     SSLCACertificateFile conf/server-ca.crt
     SSLVerifyClient require
     SSLVerifyDepth  10 
 &lt;/VirtualHost&gt;</programlisting></para>

      <para>The conf/server.crt file is the PEM-encoded Certificate file for
      the VirtualHost it must be signed by a Certificate Authority (CA) whose
      certificate is stored in the sslTrustStore of the ClusterListener
      parameter.</para>

      <para>The conf/server.key file is the file containing the private
      key.</para>

      <para>The conf/server-ca.crt file is the file containing the certicate
      of the CA that have signed the client certificate JBossWEB is using.
      That is the CA that have signed the certificate corresponding to the
      sslKeyAlias stored in the sslKeyStore of the ClusterListener
      parameters.</para>
    </sect2>

    <sect2>
      <title>ClusterListener configuration part</title>

      <para>There is a <ulink
      url="http://www.jboss.org/community/docs/DOC-9300">wiki</ulink>
      describing the SSL parameters of the ClusterListener. See in one example
      how easy the configuration is:<programlisting> &lt;Listener className="org.jboss.web.cluster.ClusterListener"
           ssl="true"
           sslKeyStorePass="changeit"
           sslKeyStore="/home/jfclere/CERTS/CA/test.p12"
           sslKeyStoreType="PKCS12"
           sslTrustStore="/home/jfclere/CERTS/CA/ca.p12"
           sslTrustStoreType="PKCS12" sslTrustStorePassword="changeit"
           /&gt;</programlisting></para>

      <para>The sslKeyStore file contains the private key and the signed
      certificate of the client certificate JBossWEB uses to connect to httpd.
      The certificate must be signed by a Cerficate Authority (CA) who
      certificate is in the conf/server-ca.crt file of the httpd</para>

      <para>The sslTrustStore file contains the CA certificate of the CA that
      signed the certificate contained in conf/server.crt file.</para>
    </sect2>

    <sect2>
      <title>mod-cluster-jboss-beans configuration part</title>

      <para>The mod-cluster-jboss-beans.xml in
      $JBOSS_HOME/server/<emphasis>profile</emphasis>/deploy/mod-cluster.sar/META-INF
      in the ClusterConfig you are using you should have something
      like:<programlisting>      &lt;property name="ssl"&gt;true&lt;/property&gt;
      &lt;property name="sslKeyStorePass"&gt;changeit&lt;/property&gt;
      &lt;property name="sslKeyStore"&gt;/home/jfclere/CERTS/test.p12&lt;/property&gt;
      &lt;property name="sslKeyStoreType"&gt;pkcs12&lt;/property&gt;
      &lt;property name="sslTrustStore"&gt;/home/jfclere/CERTS/ca.p12&lt;/property&gt;
      &lt;property name="sslTrustStoreType"&gt;pkcs12&lt;/property&gt;
      &lt;property name="sslTrustStorePassword"&gt;changeit&lt;/property&gt;</programlisting></para>
    </sect2>

    <sect2>
      <title>How the diferent files were created</title>

      <para>The files were created using OpenSSL utilities see <ulink
      url="http://www.openssl.org/">OpenSSL</ulink> CA.pl
      (/etc/pki/tls/misc/CA for example) has been used to create the test
      Certificate authority, the certicate requests and private keys as well
      as signing the certicate requests.</para>

      <sect3 id="createca">
        <title>Create the CA</title>

        <orderedlist>
          <listitem>
            <para>Create a work directory and work for there:<programlisting>mkdir -p CERTS/Server
cd CERTS/Server</programlisting></para>
          </listitem>
          <listitem>
            <para>Create a new CA:<programlisting>/etc/pki/tls/misc/CA -newca </programlisting></para>

            <para>That creates a directory for example ../../CA that contains
            a cacert.pem file which content have to be added to the
            conf/server-ca.crt described above.</para>
          </listitem>
          <listitem>
            <para>Export the CA certificate to a .p12 file:<programlisting>openssl pkcs12 -export -nokeys -in ../../CA/cacert.pem -out ca.p12</programlisting></para>

             <para>That reads the file cacert.pem that was created in the previous step and convert it into a pkcs12 file the JVM is able to read.</para>
             <para>That is the ca.p12 file used in the <emphasis>sslTrustStore</emphasis> parameter above.</para>
          </listitem>
        </orderedlist>
      </sect3>

      <sect3 id="createsc">
        <title>Create the server certificate</title>

        <orderedlist>
          <listitem>
            <para>Create a new request:<programlisting>/etc/pki/tls/misc/CA -newreq </programlisting></para>

            <para>That creates 2 files named newreq.pem and newkey.pem.
            newkey.pem is the file conf/server.key described above.</para>
          </listitem>

          <listitem>
            <para>Sign the request:<programlisting> /etc/pki/tls/misc/CA -signreq </programlisting></para>

            <para>That creates a file named newcert.pem. newcert.pem is the
            file conf/server.crt described above. At that point you have
            created the SSL stuff needed for the VirtualHost in httpd. You
            should use a browser to test it after importing in the browser the
            content of the cacert.pem file.</para>
          </listitem>
        </orderedlist>
      </sect3>

      <sect3>
        <title>Create the client certificate</title>

        <orderedlist>
          <listitem>
            <para>Create a work directory and work for there:<programlisting>mkdir -p CERTS/Client
cd CERTS/Client</programlisting></para>
          </listitem>
          <listitem>
            <para>Create request and key for the JBossWEB part.<programlisting>/etc/pki/tls/misc/CA -newreq</programlisting>
             That creates 2 files: Request is in newreq.pem, private key is in newkey.pem
            </para>
          </listitem>
          <listitem>
             <para>Sign the request.<programlisting>/etc/pki/tls/misc/CA -signreq</programlisting>
             That creates a file: newcert.pem</para>
          </listitem>
          <listitem>
            <para>Don't use a passphrase when creating the client certicate or
            remove it before exporting:<programlisting>openssl rsa -in newkey.pem -out key.txt.pem
mv key.txt.pem newkey.pem</programlisting></para>
          </listitem>
          <listitem>
            <para>Export the client certificate and key into a p12
            file.<programlisting>openssl pkcs12 -export -inkey newkey.pem -in newcert.pem -out test.p12</programlisting></para>
        <para>That is the sslKeyStore file described above
        (/home/jfclere/CERTS/CA/test.p12)</para>
          </listitem>
        </orderedlist>
      </sect3>
    </sect2>
  </sect1>

  <sect1 id="mod_proxy_https">
    <title>Using SSL between httpd and JBossWEB</title>

    <para>Using https allows to encrypt communications betwen httpd and
    JBossWEB. But due to the ressources it needs that no advised to use it in
    high load configuration.</para>

    <para>(See <ulink
    url="http://www.jboss.org/community/docs/DOC-9701">Encrypting connection
    between httpd and TC</ulink> for detailed instructions).</para>

    <para>httpd is configured to be a client for AS/TC so it should provide a certificate AS/TC
    will accept and have a private key to encrypt the data, it also needs a CA certificate to valid
    the certificate AS/TC will use for the connection.</para>
<para><programlisting>SSLProxyEngine On
SSLProxyVerify require
SSLProxyCACertificateFile conf/cacert.pem
SSLProxyMachineCertificateFile conf/proxy.pem</programlisting></para>
  <para>conf/proxy.pem should contain both key and certificate. The
  certificate must be trusted by Tomcat via the CA in truststoreFile of &lt;connector/&gt;.</para>
  <para>conf/cacert.pem must contain the certificat of the CA
  that signed the AS/TC certificate. The correspond key and certificate are the pair specificed by keyAlias and truststoreFile
  of the &lt;connector/&gt;. Of course the &lt;connector/&gt; must be the https one (normally on port 8443).</para>
    <sect2>
      <title>How the diferent files were created</title>

      <para>The files were created using OpenSSL utilities see <ulink
      url="http://www.openssl.org/">OpenSSL</ulink> CA.pl
      (/etc/pki/tls/misc/CA for example) has been used to create the test
      Certificate authority, the certicate requests and private keys as well
      as signing the certicate requests.</para>
      <sect3>
        <title>Create the CA</title>
        (See <link linkend="createca">above</link>)
      </sect3>
      <sect3>
         <title>Create the server certificate</title>
         (See <link linkend="createsc">above</link>)
         <para>The certificate and key need to be imported into the java keystore using keytool</para>
         <para>make sure you don't use a passphare for the key (don't forget to clean the file when done)</para>
         <orderedlist>
           <listitem>
             Convert the key and certificate to p12 file:
             <programlisting>openssl pkcs12 -export -inkey key.pem -in newcert.pem -out test.p12</programlisting>
             make sure you use the keystore password as Export passphrase.
           </listitem>
           <listitem>
             Import the contents of the p12 file in the keystore:
             <programlisting>keytool -importkeystore -srckeystore test.p12 -srcstoretype PKCS12</programlisting>
           </listitem>
           <listitem>
             Import the CA certificate in the java trustore: (Fedora13 example).
             <programlisting>keytool -import -trustcacerts -alias "caname" \
-file  ../../CA/cacert.pem -keystore /etc/pki/java/cacerts</programlisting>
           </listitem>
           <listitem>
             Edit server.xml to have a &lt;connector/&gt; similar to:
<programlisting>
&lt;Connector port="8443" protocol="HTTP/1.1" SSLEnabled="true"
           keyAlias="1" 
           truststoreFile="/etc/pki/java/cacerts"
           maxThreads="150" scheme="https" secure="true"
           clientAuth="true" sslProtocol="TLS" /&gt;
</programlisting>
           </listitem>
           <listitem>
             Start TC/AS and use openssl s_client to test the connection:
             <programlisting>openssl s_client -CAfile /home/jfclere/CA/cacert.pem -cert newcert.pem -key newkey.pem \
-host localhost -port 8443</programlisting>
             There shouldn't be any error and you should be able to see your CA in the "Acceptable client certificate CA names".
           </listitem>
         </orderedlist>
      </sect3>
    </sect2>


  </sect1>

  <sect1>
    <title>Forwarding SSL browser informations when using http/https between
    httpd and JBossWEB</title>

    <para>When using http or https beween httpd and JBossWEB you need to use
    the SSLValve and export the SSL variable as header in the request in
    httpd. If you are using AJP, mod_proxy_ajp will read the SSL variables and
    forward them to JBossWEB automaticaly.</para>

    <para>(See <ulink
    url="http://www.jboss.org/community/docs/DOC-11988">Forwarding SSL
    environment when using http/https proxy</ulink> for detailed
    instructions).</para>

    <para>The SSL variable used by mod_proxy_ajp are the following:</para>

    <orderedlist>
      <listitem>
        <para>"HTTPS" SSL indicateur.</para>
      </listitem>

      <listitem>
        <para>"SSL_CLIENT_CERT" Chain of client certificates.</para>
      </listitem>

      <listitem>
        <para>"SSL_CIPHER" Cipher used.</para>
      </listitem>

      <listitem>
        <para>"SSL_SESSION_ID" Id of the session.</para>
      </listitem>

      <listitem>
        <para>"SSL_CIPHER_USEKEYSIZE" Size of the key used.</para>
      </listitem>
    </orderedlist>
  </sect1>
</chapter>
