<title>SSL Quick Installation</title>

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.

<summarylist/>

<section title="Install JSSE from Sun">

<p/>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>.

<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.  You will modify
$JAVA_HOME/jre/lib/java.security so it looks 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 "keystore" to create a key using the RSA
algorithm.
</ol>

</section>

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

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

<ul>
<li>Sun's keytool
<li>A test certificate from Thwaite

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

<example>
unix> <var/keytool -genkey -keyalg RSA -keystore keys/private.keystore/>
Enter keystore password:  <var/password1/>
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 <CN=www.caucho.com, OU=Resin Engineering, O="Caucho Technology, Inc.", L=San Francisco, ST=California, C=US> correct?
  [no]:  yes

Enter key password for <mykey>
        (RETURN if same as keystore password):  password2
</example>

</section>

<section title="resin.conf">

SSL ports are configured as enhanced HTTP connections.  You must:
<ol>
<li>Load a <var/security provider/> providing the SSL implementation.
<li>Enable SSL
<li>Specify the keystore type
<li>Specify the keystore file (certificate)
<li>Specify the keystore password
</ol>

<p/>The easiest keystore type to use is "pkcs12".  pkcs12 is a
standard format for exchanging certificates.  When you export a client
certificate from a browser, the usual format is pkcs12.

<p/>The default keystore type is "jks", the "Java KeyStore".

<example>
&lt;caucho.com>
  &lt;!-- JSSE security provider -->
  &lt;security-provider id='com.sun.net.ssl.internal.ssl.Provider'/>

  &lt;http-server>

    &lt;http port=8443>
     &lt;ssl>true&lt;/ssl>
     &lt;key-store-type>pkcs12&lt;/key-store-type>
     &lt;key-store-file>keys/server_cert.p12&lt;/key-store-file>
     &lt;key-store-password>changeit&lt;/key-store-password>
    &lt;/http>

    ...

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


</section>

