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>  

The default resin configuration allows you to setup open-ssl in resin.properties.

# OpenSSL certificate configuration
openssl_file : key/gryffindor.crt
openssl_key : keys/gryffindor.key
openssl_password : my-password

Testing SSL with the browser

A quick test is the following JSP.

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

Testing with openssl to test the server

The openssl tool can be used as a client, showing some interesting information about the conversation between the client and the server:

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() %>