<s1 title="SSL Test Installation">

<summarylist/>

<s2 title="Using OpenSSL on Unix">

<p>On Unix systems, Resin's JNI libraries can support SSL using the
<a href="http://www.openssl.org">OpenSSL</a> libraries.
Although the ./configure script will detect many configurations,
you can specify the openssl location directly:</p>

<example>
resin> ./configure --with-openssl=/usr/local/ssl
</example>

<p>The SSL port is configured in the httpd.conf's &lt;http> element by
adding the <var/ssl/> flag and configuring a key with the
<var/certificate-pem/> element:</p>

<example>
...
&lt;http-server>
  &lt;http port='443' ssl>
    &lt;certificate-file>/opt/resin/cert/ssl.crt&gt;/certificate-file>
    &lt;certificate-key-file>/opt/resin/cert/ssl.key&gt;/certificate-key-file>
  &lt;/http>

  ...
&lt;/http-server>
</example>

<p>Since OpenSSL uses the same certificate as Apache, you can
get signed certificates using the same method as for Apache's
mod_ssl or following the OpenSSL instructions.</p>

<p>OpenSSL's engine support is configured with crypto-device.</p>

</s2>

<s2 title="Install JSSE from Sun">

<p>If OpenSSL is not available, you can use Sun's JSSE to provide
SSL.  Sun's implementation of JSSE is significantly
slower than OpenSSL, though.</p>

<p>This section gives a quick guide to installing a test SSL
configuration using Sun's JSSE.  It avoids as many complications as
possible and uses Sun's keytool to create a server certificate.</p>

<p>Resin's SSL support is provided by Sun's
<a href='http://java.sun.com/products/jsse'>JSSE</a>.  Because of
export restrictions, patents, etc, you'll need to download the JSSE
distribution from Sun or get a commercial JSSE implementation.</p>

<p>More complete JSSE installation instructions for JSSE are at
<a href="http://java.sun.com/products/jsse/install.html">http://java.sun.com/products/jsse/install.html</a>.
</p>
<ol>
<li>First download Sun's <a href="http://java.sun.com/products/jsse">JSSE</a>.
<li>Uncompress and extract the downloaded file.
<li>Install the JSSE jar files: jsse.jar, jnet.jar, and jcert.jar.  You can
either put them into the CLASSPATH or you can put them into $JAVA_HOME/jre/lib/ext.  Since you will use "keytool" with the new jars, you need to make them
visible to keytool.  Just adding them to resin/lib is not enough.
<li>Register the JSSE provider (com.sun.net.ssl.internal.ssl.Provider).
Modify $JAVA_HOME/jre/lib/security/java.security so it contains something like:
<example>
security.provider.1=sun.security.provider.Sun
security.provider.2=com.sun.net.ssl.internal.ssl.Provider
</example>
Adding the JSSE provider allows "keytool" to create a key using the RSA
algorithm.
</ol>

</s2>

<s2 title="Create a test server certificate">

<p>The server certificate is the core of SSL.  It will identify your server and
contain the secret key to make encryption work.</p>

<ul>
<li>Sun's keytool
<li>A self-signed certificate using open_ssl
<li>A test certificate from Thawte
<li>A production certificate from one of the certificate authorities (Verisign, Thawte, etc)
</ul>

<p>In this case, we're using Sun's <var/keytool/> to generate the
server certificate.  Here's how:</p>

<example>
resin1.2.b2> <var/mkdir keys/>
resin1.2.b2> <var/keytool -genkey -keyalg RSA -keystore keys/server.keystore/>
Enter keystore password:  <var/changeit/>
What is your first and last name?
  [Unknown]:  <var/www.caucho.com/>
What is the name of your organizational unit?
  [Unknown]:  <var/Resin Engineering/>
What is the name of your organization?
  [Unknown]:  <var/Caucho Technology, Inc./>
What is the name of your City or Locality?
  [Unknown]:  <var/San Francisco/>
What is the name of your State or Province?
  [Unknown]:  <var/California/>
What is the two-letter country code for this unit?
  [Unknown]:  <var/US/>
Is &lt;CN=www.caucho.com, OU=Resin Engineering,
  O="Caucho Technology, Inc.", L=San Francisco, ST=California, C=US> correct?
  [no]:  <var/yes/>

Enter key password for &lt;mykey>
        (RETURN if same as keystore password):  <var/changeit/>
</example>

<p>Currently, the key password and the keystore password must be the same.</p>

</s2>

<s2 title="resin.conf">

<p>The Resin SSL configuration extends the http configuration with a few new
elements.</p>

<example>
&lt;caucho.com>
  &lt;http-server>

    &lt;http port=8443>
     &lt;ssl>true&lt;/ssl>
     &lt;key-store-file>keys/server.keystore&lt;/key-store-file>
     &lt;key-store-password>changeit&lt;/key-store-password>
    &lt;/http>

    ...

  &lt;/http-server>
&lt;/caucho.com>
</example>

</s2>

<s2 title="Testing">

<p>With the above configuration, you can test SSL with https://localhost:8443.
A quick test is the following JSP.</p>

<example>
Secure? &lt;%= request.isSecure() %>
</example>

</s2>
</s1>
