<title>SSL</title>

<section title="Should I use JSSE or Apache/IIS for SSL?">

We recommend using Apache or IIS (or Netscape/Zeus) for SSL support instead
of using Sun's JSSE support.  JSSE does not appear to be quite
production-worthy and is far more complicated to configure.  While we've never
received any problems with Resin using SSL from Apache or IIS, JSSE issues
are fairly frequent.

<p/>Even if you're using Apache/IIS for SSL support, you can still use
Resin's standalone web server for non-SSL pages.  Your resin.conf will
need to list both a &lt;http port='80'/> and a &lt;srun port='6802'/>.

</section>

<section title="How do I configure Resin with SSL using JSSE?">

Nicholas Lehuen writes:

Here is a short step-by-step installation guide for SSL on Resin.
 
<p/>The purpose : to install SSL support on Resin

<subsection title='Requirements'>
<ul>
<li>The latest Resin 1.2 snapshot (I used the 08/04/2000 snapshot with success)
    http://www.caucho.com/download/index.xtp
<li>JSSE 1.0.1
    http://java.sun.com/products/jsse/
<li>Optional : a certificate authority (CA) such as Verisign, Thawte, or your own. Thawte is providing a free test certificate authority
service which enables you to check the certification process before buying your own certificate. Of course, you can also skip the CA by
providing self-signed public key certificate. This will be explained later.

<p/><a href="https://www.thawte.com/cgi/server/test.exe">https://www.thawte.com/cgi/server/test.exe</a>
</ul>
</subsection>

 
<subsection title="JSSE setup">

<ol>
<li>Follow the installation instructions
<a href="http://java.sun.com/products/jsse/install.html">http://java.sun.com/products/jsse/install.html</a>
<li>Even if Resin has its own provider registration system (we'll see it on next step), I suggest that you statically register the SunJSSE
by editing the &lt;java-home>/lib/security/java.security as explained in the installation guide. This will ease the use of keytool.
</ol>
</subsection>
 
<subsection title="Keystore initialization">
<ol>
<li>Create a directory named 'keys' somewhere in your Resin installation. I suggest you place it in the Resin home directory.
<li>Copy the file &lt;java-home>/lib/security/cacerts into the 'keys' directory
<li>Rename the cacerts file as you want. I'll suppose you name it 'private.keystore'.
</ol>

</subsection>
<subsection title="Keystore protection">
Your private.keystore file is for the moment a copy of the cacerts keystore, which contains the CA public key certificates (very
important for client HTTPS connections). We will insert your own private key in this file, thus it'll have to be password-protected, so
that anyone stealing it will have difficulties in forging certificates on your behalf.

<ol>
<li>Go into the 'keys' directory
<li>type the following command :
keytool -storepasswd -storepass changeit -new YourPasswordHere \
        -keystore private.keystore
</ol>
 
(the default password for the cacerts keystore is 'changeit')
 
</subsection>

<subsection title="Private key generation">
We'll now generate your key pair, which is composed of a private (the one which MUST remain secret !) and a public key. The point here is
to use the RSA key pair generator, and NOT the default one, which is DSA. This is were the JSSE security provider is used.
 
<p/>type the following command :
<example>
M:\keys>keytool -genkey -keyalg RSA -alias myserverkeypair \
                -storepass YourPasswordHere -keystore private.keystore
What is your first and last name?
  [Unknown]:  www.myserver.com
What is the name of your organizational unit?
  [Unknown]:  Foo Dept
What is the name of your organization?
  [Unknown]:  Bar
What is the name of your City or Locality?
  [Unknown]:  Paris
What is the name of your State or Province?
  [Unknown]:  France
What is the two-letter country code for this unit?
  [Unknown]:  FR
Is &lt;CN=www.myserver.com, OU=Foo Dept, O=Bar, L=Paris,
                ST=France, C=FR> correct?
  [no]:  yes
 
Enter key password for &lt;myserverkeypair>
        (RETURN if same as keystore password):
</example>
 
<p/>You MUST mention your HTTP server name as the CN of the certificate (thus the reply to 'first and last name'). Browsers would emit
warnings to your users if you didn't. Any other informations are at your choice, however the process of key pair generation and
attributes definitions is very strict for "real-life" cryptography, i.e. Verisign will double-check your identity, address and so on.
 
<p/>Another important point : DON'T AFFECT A PASSWORD to your key pair. It must remain the same as the keystore, at least until Resin
provides a means of configuring the key pair password.
</subsection>

<subsection title="Public Key Certificate (optional)">

Request a public key certificate and insert the public key certificate into your keystore.

For users to trust your server, you'll have to have your public key
certificate (PKC) signed by a Certificate Authority (CA) (Verisign,
Thawte, Certplus...). This is done by sending a certificate signature
request (CSR) to the CA, coping with all the legal stuff and
getting a signed PKC in return. This step is mandatory for production server, unless you have some means to convince your users that your
PKC is valid without a CA signature, which is possible in intranet environment for example. However, for testing purpose, you can start
by using your self-signed PKC without any CA signature. An intermediary solution is to use a test CA so that you can check that your CSR
is correctly emitted, that the Certificate Chain is correctly checked, and so on. Thawte provides a test CA at the address mentioned
above.

<li>Generate a CSR by typing the following command :

<pre>

M:\keys>keytool -certreq -alias myserverkeypair -storepass YourPasswordHere \
                -keystore private.keystore
-----BEGIN NEW CERTIFICATE REQUEST-----
MIIBqjCCARMCAQAwajELMAkGA1UEBhMCRlIxDzANBgNVBAgTBkZyYW5jZTEOMAwGA1UEBxMFUGFy
... cut ...
KDYZTklbg1NOiXTdXIhPHb3+YOgZ+HoeDTxOx/rRhA==
-----END NEW CERTIFICATE REQUEST-----
</pre>
 
<li>Copy/Paste the CSR into the text box at the following address. Leave all options with their default value.
    https://www.thawte.com/cgi/server/test.exe
 
<li>You'll get a certificate looking like :
<pre>
-----BEGIN CERTIFICATE-----
MIICjzCCAfigAwIBAgIDBp8SMA0GCSqGSIb3DQEBBAUAMIGHMQswCQYDVQQGEwJa
... cut ...
/93Q58iI4fgQ/kc+l8ogpVwh/IJw1Ujmszd19Jf+pxyySMM=
-----END CERTIFICATE-----
</pre>
<li>Copy/Paste this certificate into a file named 'myserver.cer' . If you have Microsoft Internet Explorer 5.0 (maybe 4.0) installed, you
can open this .cer file and see the certificate as your user will when they ask the security properties of pages served securely by your
server. A warning should be emitted, stating that you can't trust the certificate as it does not point to a trusted root CA. You can keep
going with this warning or download and trust the test root CA (available on https://www.thawte.com/servertest.crt ). Be ware though that
the final user should not and surely won't accept to trust this test root CA.
 
<li>Anyway, to be able to import your signed certificate, you'll have to import the test root CA certificate. Download it and import it
using the following command :
<example>
M:\keys>keytool -import -alias servertest -storepass YourPasswordHere \
                -keystore private.keystore -file servertest.crt
Owner: CN=Thawte Test CA Root, OU=TEST, O=Thawte, ST=FOR TESTING, C=ZA
Issuer: CN=Thawte Test CA Root, OU=TEST, O=Thawte, ST=FOR TESTING, C=ZA
Serial number: 0
Valid from: Thu Aug 01 02:00:00 CEST 1996 until: Thu Dec 31 22:59:59 CET 2020
Certificate fingerprints:
         MD5:  5E:E0:0E:1D:17:B7:CA:A5:7D:36:D6:02:DF:4D:26:A4
         SHA1: 39:C6:9D:27:AF:DC:EB:47:D6:33:36:6A:B2:05:F1:47:A9:B4:DA:EA
Trust this certificate? [no]:  yes
Certificate was added to keystore
</example>
 
<li>Import the certificate and attach it to your server key pair by typing the command :
<example>
M:\keys>keytool -import -alias myserverkeypair -storepass YourPasswordHere \
                -keystore private.keystore -file myserver.cer
Certificate reply was installed in keystore
</example>
</subsection>

<subsection title="Key pair verification">

Issue the following command :
<example>
M:\keys>keytool -list -v -alias myserverkeypair -storepass YourPasswordHere \
                -keystore private.keystore
Alias name: myserverkeypair
Creation date: Fri Aug 11 23:07:53 CEST 2000
Entry type: keyEntry
Certificate chain length: 2
Certificate[1]:
Owner: CN=www.myserver.com, OU=Foo Dept, O=Bar, L=Paris, ST=France, C=FR
Issuer: CN=Thawte Test CA Root, OU=TEST, O=Thawte, ST=FOR TESTING, C=ZA
Serial number: 69f12
Valid from: Fri Aug 11 23:00:07 CEST 2000 until: Mon Sep 11 23:00:07 CEST 2000
Certificate fingerprints:
         MD5:  41:84:55:8C:A1:85:28:DA:B0:5A:47:D6:5B:D2:ED:41
         SHA1: 61:DE:DB:E6:7C:3C:AD:90:63:9B:20:E0:FF:3B:02:3A:60:EB:B4:82
Certificate[2]:
Owner: CN=Thawte Test CA Root, OU=TEST, O=Thawte, ST=FOR TESTING, C=ZA
Issuer: CN=Thawte Test CA Root, OU=TEST, O=Thawte, ST=FOR TESTING, C=ZA
Serial number: 0
Valid from: Thu Aug 01 02:00:00 CEST 1996 until: Thu Dec 31 22:59:59 CET 2020
Certificate fingerprints:
         MD5:  5E:E0:0E:1D:17:B7:CA:A5:7D:36:D6:02:DF:4D:26:A4
         SHA1: 39:C6:9D:27:AF:DC:EB:47:D6:33:36:6A:B2:05:F1:47:A9:B4:DA:EA
</example>
 
As you can see the alias myserverkeypair points to a keyEntry type entry, its certificate chain has 2 certificate, the first being your
own certificate, signed by the Thawte Test CA Root, and the other being the Thawte Test CA Root own.
 
</subsection>

<subsection title="Resin configuration (resin.conf)">

add the support for the SunJSSE security provider :

<example>
&lt;caucho.com>
    &lt;security-provider id='com.sun.net.ssl.internal.ssl.Provider'/>
 
&lt;!-- declare a new HTTP server on port 443 (standard port for HTTPS),
      - with SSL enabled -->
 
&lt;http-server>
  &lt;app-dir>doc&lt;/app-dir>
 
  &lt;!-- the http port -->
  &lt;http port=80/>
 
  &lt;!-- the srun port, read by both JVM and plugin -->
  &lt;srun host='localhost' port='6802'/>
 
  &lt;http port=443>
    &lt;ssl>true&lt;/ssl>
    &lt;key-store-type>jks&lt;/key-store-type>
    &lt;key-store-file>file://m:/keys/private.keystore&lt;/key-store-file>
    &lt;key-store-password>YourPasswordHere&lt;/key-store-password>
  &lt;/http>
</example>
</subsection>

<subsection title="Test !">
Try connecting to your server with https instead of http !
 
I've been running successfully SSL on Resin with JDK 1.3 on Windows NT 4 SP6 and JDK 1.2.2 on Solaris 7.
 
And the fun begins when mixing HTTPS and WAP... !

</subsection>
</section>
