What SSL provides

SSL provides two kinds of protection, encryption and server
authentication.

Encryption

public key

A set of bytes used to encrypt data and verify signatures.
The key is public because it can be made available without a loss of security.
The public key can only be used for encryption; it cannot decrypt
anything. A public key always has a corresponding private key.

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.

private key

A set of bytes used to decrypt data and generate signatures.
The key is private because it must be kept secret or there will be a loss of
security. The private key is used for decryption of data that has been
encrypted with the corresponding public key.

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

certificate

A combination of a private key, identity information (such as company
name), and a signature generated by a signing authority.
private key.

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.

signing authority

A company that is trusted to sign certificates. Browsers include
certificates of signing authorities that they trust.

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.

certificate authority

Another name for signing authority. A company that is trusted to
sign certificates. Browsers include certificates of signing authorities that
they trust.

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

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

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.

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.

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).

Creating a self-signed certificate

You can create a certificate that is self-signed, which is good for
testing or for saving you money. Since it is self-signed, browsers will not
recognize the signature and will pop up a warning to browser users. Other than
this warning, self-signed certificates work well. The browser cannot confirm
that the server is who it says it is, but the data between the browser and the
client is still encrypted.

Most browsers are configured to recognize the signature of signing
authorities. Since they recognize the signature, they will not pop up a
warning message the way they will with self-signed certificates. The browser
can confirm that the server is who it says it is, and the data between the
browser and the client is encrypted.

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.

Testing SSL with the browser

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:

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.

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.

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.

Cloud-optimized Resin Server is a Java EE certified Java Application Server, and Web Server, and Distributed Cache Server (Memcached).Leading companies worldwide with demand for reliability and high performance web applications including SalesForce.com, CNET, DZone and many more are powered by Resin.