What SSL provides

Encryption

SSL provides encryption of the data traffic betweeen a client and a server. When the traffic is encrypted, an interception of that traffic will not reveal the contents because they have been encrypted - it will be unusable nonsense.

SSL uses public key cryptography. Public key cryptography is based upon a pair of keys, the public key and the private key. The public key is used to encrypt the data. Only the corresponding private key can successfully decrypt the data.

For example, when a browser connects to Resin, Resin provides the browser a public key. The browser uses the public key to encrypt the data, and Resin uses the private key to decrypt the data. For this reason, it is important that you never allow anyone access to the private key, if the private key is obtained by someone then they can use it to decrypt the data traffic.

Encryption is arguably the more important of the security meausures that SSL provides.

Server Authentication

SSL also provides the ability for a client to verify the identity of a server. This is used to protect against identity theft, where for example a malicious person imitates your server or redirects client traffic to a different server while pretending to be you.

Server authentication uses the signature aspect of public key cryptography. The private key is used to sign messages, and the public key is used to verify the signature. With SSL, the validity of signatures depends upon signing authorities. Signing authorites (also called certificate authorities) are companies who have generated public keys that are included with browser software. The browser knows it can trust the signing authority, and the signing authority signs your SSL certificate, putting its stamp of approval on the information in your certificate.

For example, after you generate your public and private key, you then generate a signing request and send it to a signing authority. This signing request contains information about your identity, this identity information is confirmed by the signing authority and ultimately displayed to the user of the browser. The signing authority validates the identity information you have provided and uses their private key to sign, and then returns a certificate to you. This certificate contains the identity information and your public key, verified by the signing authority, and is provided to the browser. Since the browser has the public key of the signing authority, it can recognize the signature and know that the identity information has been provided by someone that can be trusted.

OpenSSL

Linking to the OpenSSL Libraries on Unix

On Unix systems, Resin's libexec/libresinssl.so JNI library supports SSL using the OpenSSL libraries. Although the ./configure script will detect many configurations, you can specify the openssl location directly:

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

Obtaining the OpenSSL Libraries on Windows

On Windows systems, the resinssl.dll includes JNI code to use OpenSSL libraries (it was in resin.dll in versions before 3.0). All you need to do is to obtain an OpenSSL binary distribution and install it.

Resin on Windows 32 is compiled against the Win32 binary, you can obtain an installation package http://www.slproweb.com (Shining Light Productions).

Resin on Windows 64 is compiled against a Win64 binary, you can obtain an installation package Dean Lee: /dev/blog.

Once you have run the installation package, you can copy the necessary dll libraries into $RESIN_HOME:

C:\> cd %RESIN_HOME%
C:\resin-4.0.x> copy "C:\Program Files\GnuWin32\bin\libssl32.dll" .\libssl32.dll
C:\resin-4.0.x> copy "C:\Program Files\GnuWin32\bin\libeay32.dll" .\libeay32.dll

Preparing to use OpenSSL for making keys

You can make a keys/ subdirectory of $RESIN_HOME to do your work from and as a place to store your generated keys.

unix> cd $RESIN_HOME
unix> mkdir keys
unix> cd keys

win> cd %RESIN_HOME%
win> mkdir keys
win> cd keys

Using OpenSSL requires a configuration file. Unix users might find the default configuration file in /usr/ssl/openssl.cnf or /usr/share/ssl/openssl.cnf. Windows users may not have received one with their package.

Either way, it can be valuable to make your own openssl.cnf that is used just for generating the keys to use with Resin. You can use the following as a template for a file $RESIN_HOME/keys/openssl.cnf. You may want to fill in the _default values so you don't have to type them in every time.

[ req ]
 default_bits            = 1024
 distinguished_name      = req_distinguished_name

[ req_distinguished_name ]
 C                      = 2 letter Country Code, for example US
 C_default              =
 ST                     = State or Province
 ST_default             =
 L                      = City
 L_default              =
 O                      = Organization Name
 O_default              =
 OU                     = Organizational Unit Name, for example 'Marketing'
 OU_default             =
 CN                     = your domain name, for example www.hogwarts.com
 CN_default             =
 emailAddress           = an email address
 emailAddress_default   =

Creating a private key

Create a private key for the server. You will be asked for a password - don't forget it! You will need this password anytime you want to do anything with this private key. But don't pick something you need to keep secret, you will need to put this password in the Resin configuration file.

unix> openssl genrsa -des3 -out gryffindor.key 1024
win>  "C:\Program Files\GnuWin32\bin\openssl.exe" \
         genrsa -des3 -out gryffindor.key 1024

Creating a certificate

OpenSSL works by having a signed public key that corresponds to your private key. This signed public key is called a certificate. A certificate is what is sent to the browser.

You can create a self-signed certificate, or get a certificate that is signed by a certificate signer (CA).

unix> openssl req -config ./openssl.cnf -new -key gryffindor.key \
        -x509 -out gryffindor.crt
win> "C:\Program Files\GnuWin32\bin\openssl.exe" req -config ./openssl.cnf \
         -new -key gryffindor.key -x509 -out gryffindor.crt

unix> openssl req -new -config ./openssl.cnf -key gryffindor.key \
      -out gryffindor.csr
win> "C:\Program Files\GnuWin32\bin\openssl.exe" req -new \
      -config ./openssl.cnf  -key gryffindor.key -out gryffindor.csr

resin.xml - Configuring Resin to use your private key and certificate

The OpenSSL configuration has two tags certificate-file and certificate-key-file. These correspond exactly to mod_ssl's SSLCertificateFile and SSLCertificateKeyFile. So you can use the same certificates (and documentation) from mod_ssl for Resin.

The full set of parameters is in the port configuration.

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="http-tier">

  <server id="a" address="192.168.1.12">
    <http port="443">
      <openssl>
        <certificate-file>keys/gryffindor.crt</certificate-file>
        <certificate-key-file>keys/gryffindor.key</certificate-key-file>
        <password>my-password</password>
      </openssl>
   </http>
  </server>

  ...
</resin>  

Testing

Secure? <%= request.isSecure() %>

unix$ openssl s_client -connect www.some.host:443 -prexit

Certificate Chains

A certificate chain is used when the signing authority is not an authority trusted by the browser. In this case, the signing authority uses a certificate which is in turn signed by a trusted authority, giving a chain of [your certificate] <--- signed by ---- [untrusted signer] <---- signed by ---- [trusted signer].

The Resin config parameter certificate-chain-file is used to specify a certificate chain. It is used to reference a file that is a concatenation of:

1. your certificate file
2. the intermediate (untrusted) certificate
3. the root (trusted) certificate.

The certificates must be in that order, and must be in PEM format.

$ cat your_domain.crt ComodoSecurityServicesCA.crt GTECyberTrustRoot.crt > chain.txt

<http port="443">
  <openssl>
    <certificate-key-file>keys/your_domain.key</certificate-key-file>
    <certificate-file>keys/your_domain.crt</certificate-file>        
    <certificate-chain-file>keys/chain.txt</certificate-chain-file>
    <password>test123</password>
  </openssl>
</http>

JSSE

Install JSSE from Sun

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.

Resin's SSL support is provided by Sun's JSSE. Because of export restrictions, patents, etc, you'll need to download the JSSE distribution from Sun or get a commercial JSSE implementation.

More complete JSSE installation instructions for JSSE are at http://java.sun.com/products/jsse/install.html.

1. First download Sun's JSSE.
2. Uncompress and extract the downloaded file.
3. 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.
4. Register the JSSE provider (com.sun.net.ssl.internal.ssl.Provider). Modify $JAVA_HOME/jre/lib/security/java.security so it contains something like:

   security.provider.1=sun.security.provider.Sun
   security.provider.2=com.sun.net.ssl.internal.ssl.Provider
   

   Adding the JSSE provider allows "keytool" to create a key using the RSA algorithm.

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.

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

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

resin1.2.b2> mkdir keys
resin1.2.b2> keytool -genkey -keyalg RSA -keystore keys/server.keystore
Enter keystore password:  changeit
What is your first and last name?
  [Unknown]:  www.caucho.com
What is the name of your organizational unit?
  [Unknown]:  Resin Engineering
What is the name of your organization?
  [Unknown]:  Caucho Technology, Inc.
What is the name of your City or Locality?
  [Unknown]:  San Francisco
What is the name of your State or Province?
  [Unknown]:  California
What is the two-letter country code for this unit?
  [Unknown]:  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):  changeit

Currently, the key password and the keystore password must be the same.

resin.xml

The Resin SSL configuration extends the http configuration with a few new elements.

<resin xmlns="http://caucho.com/ns/resin">
  <cluster id="">

    <server-default>
    
    <http port="8443">
     <jsse-ssl>
       <key-store-type>jks</key-store-type>
       <key-store-file>keys/server.keystore</key-store-file>
       <password>changeit</password>
     </jsse-ssl>
    </http>

    </server-default>
    ...

  </cluster>
</resin>

Testing JSSE

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

Secure? <%= request.isSecure() %>