| SSL with Resin |
| Authorization |
| Security Manager |
SSL (Secure Sockets Layer) is a commonly-used protocol for managing the security of message transmission on the Internet. SSL in your web server provides support for the familiar https:// protocol.
This connection is not using SSL.
|
| Resin is not always responsible for SSL |
When you are using Resin as a servlet runner behind another web server, such as Apache or IIS, the web server is responsible for handling SSL. The request looks like a regular unencrypted request to Resin.
In a similar fashion, a hardware accelerator is sometimes used to boost the performance of a server supporting SSL. This causes the incoming requests to look like regular unencrypted requests to Resin.
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 <http port='80'/> and a <srun port='6802'/>.
| OpenSSL |
OpenSSL is the same SSL implementation that Apache's mod_ssl uses. 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.
Linking to the OpenSSL Libraries on Unix
On Unix systems, Resin's bin/resin can support 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 |
Linking to 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.
Sites providing OpenSSL binaries for Windows can be found in the binaries section of the OpenSSL website.
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:\OpenSSL\bin\openssl.exe genrsa -des3 -out gryffindor.key 1024 |
Creating a certificate
OpenSSL works by having a public key that corresponds to your private key. This public key is called a . 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).
Creating a self-signed certificate
You can create a certificate that is self-signed, which is good for testing or for saving you money.
unix> openssl req -config ./openssl.cnf -new -key gryffindor.key -x509 -out gryffindor.crt win> C:\OpenSSL\bin\openssl.exe req -config ./openssl.cnf -new -key gryffindor.key -x509 -out gryffindor.crt |
You will be asked to provide some information about the identity of your server, such as the name of your Organization etc. Common Name (CN) is your domain name, like: "www.gryffindor.com".
Creating a certificate request
To get a certificate that is signed by a CA, first you generate a (CSR).
unix> openssl req -new -config ./openssl.cnf -key gryffindor.key -out gryffindor.csr win> C:\OpenSSL\bin\openssl.exe req -new -config ./openssl.cnf -key gryffindor.key -out gryffindor.csr |
You will be asked to provide some information about the identity of your server, such as the name of your Organization etc. Common Name (CN) is your domain name, like: "www.gryffindor.com".
Send the CSR to a certificate signer (CA). You'll use the CA's instructions for Apache because the certificates are identical. Some commercial signers include:
You'll receive a gryffindor.crt file.
resin.conf - 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 .
...
<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>
|
Testing
request.isSecure() is reporting true, so it looks like you have SSL working and are viewing this page over an SSL encrypted connection.
Another quick test is the following JSP.
Secure? <%= request.isSecure() %> |
| JSSE |
We recommend avoiding JSSE if possible. It is slower than using Resin's OpenSSL support and does not appear to be as stable as Apache or IIS (or Netscape/Zeus) for SSL support. In addition, JSSE is far more complicated to configure. While we've never received any problems with Resin using OpenSSL, or SSL from Apache or IIS, JSSE issues are fairly frequent.
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.
- First download Sun's JSSE.
- Uncompress and extract the downloaded file.
- 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.
- Register the JSSE provider (com.sun.net.ssl.internal.ssl.Provider).
Modify $JAVA_HOME/jre/lib/security/java.security so it contains something like:
Adding the JSSE provider allows "keytool" to create a key using the RSA algorithm.security.provider.1=sun.security.provider.Sun security.provider.2=com.sun.net.ssl.internal.ssl.Provider
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 to generate the server certificate. Here's how:
resin1.2.b2> resin1.2.b2> Enter keystore password: What is your first and last name? [Unknown]: What is the name of your organizational unit? [Unknown]: What is the name of your organization? [Unknown]: What is the name of your City or Locality? [Unknown]: What is the name of your State or Province? [Unknown]: What is the two-letter country code for this unit? [Unknown]: Is <CN=www.caucho.com, OU=Resin Engineering, O="Caucho Technology, Inc.", L=San Francisco, ST=California, C=US> correct? [no]: Enter key password for <mykey> (RETURN if same as keystore password): |
Currently, the key password and the keystore password must be the same.
resin.conf
The Resin SSL configuration extends the http configuration with a few new elements.
<resin xmlns="http://caucho.com/ns/resin">
<server>
<http port="8443">
<jsse-ssl>
<key-store-file>keys/server.keystore</key-store-file>
<key-store-password>changeit</key-store-password>
</jsse-ssl>
</http>
...
</http-server>
</caucho.com>
|
Testing
With the above configuration, you can test SSL with https://localhost:8443. A quick test is the following JSP.
Secure? <%= request.isSecure() %> |
User Experiences with JSSE
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.
The purpose : to install SSL support on Resin
Requirements
- The latest Resin 1.2 snapshot (I used the 08/04/2000 snapshot with success) http://www.caucho.com/download/index.xtp
- JSSE 1.0.1 http://java.sun.com/products/jsse/
- 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. https://www.thawte.com/cgi/server/test.exe
JSSE setup
- Follow the installation instructions http://java.sun.com/products/jsse/install.html
- 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 <java-home>/lib/security/java.security as explained in the installation guide. This will ease the use of keytool.
Keystore initialization
- Create a directory named 'keys' somewhere in your Resin installation. I suggest you place it in the Resin home directory.
- Copy the file <java-home>/lib/security/cacerts into the 'keys' directory
- Rename the cacerts file as you want. I'll suppose you name it 'private.keystore'.
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.
- Go into the 'keys' directory
- type the following command : keytool -storepasswd -storepass changeit -new YourPasswordHere \ -keystore private.keystore
(the default password for the cacerts keystore is 'changeit')
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.
type the following command :
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 <CN=www.myserver.com, OU=Foo Dept, O=Bar, L=Paris,
ST=France, C=FR> correct?
[no]: yes
Enter key password for <myserverkeypair>
(RETURN if same as keystore password):
|
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.
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.
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.
- Generate a CSR by typing the following command :
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----- - 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
- You'll get a certificate looking like :
-----BEGIN CERTIFICATE----- MIICjzCCAfigAwIBAgIDBp8SMA0GCSqGSIb3DQEBBAUAMIGHMQswCQYDVQQGEwJa ... cut ... /93Q58iI4fgQ/kc+l8ogpVwh/IJw1Ujmszd19Jf+pxyySMM= -----END CERTIFICATE-----
- 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.
- 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 :
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 - Import the certificate and attach it to your server key pair by typing the command :
M:\keys>keytool -import -alias myserverkeypair -storepass YourPasswordHere \ -keystore private.keystore -file myserver.cer Certificate reply was installed in keystore
Key pair verification
Issue the following command :
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
|
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.
Resin configuration (resin.conf)
add the support for the SunJSSE security provider :
<resin xmlns="http://caucho.com/ns/resin">
<security-provider id='com.sun.net.ssl.internal.ssl.Provider'/>
<!-- declare a new HTTP server on port 443 (standard port for HTTPS),
- with SSL enabled -->
<server>
<!-- the http port -->
<http port="80"/>
<!-- the srun port, read by both JVM and plugin -->
<cluster>
<srun host='localhost' port='6802'/>
</cluster>
<http port=443>
<jsse>
<key-store-type>jks</key-store-type>
<key-store-file>file://m:/keys/private.keystore</key-store-file>
<key-store-password>YourPasswordHere</key-store-password>
</jsse>
</http>
|
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... !
| Authorization |
| Security Manager |
| Copyright © 1998-2003 Caucho Technology, Inc. All rights reserved. Resin® is a registered trademark, and HardCoretm and Quercustm are trademarks of Caucho Technology, Inc. |  |