| |||||||||||||||||||||||||||||||||||||||||||||||||
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.
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'/>.
SSL provides two kinds of protection, and .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 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 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 UnixOn 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:
TODO: update for 3.0 re: how ssl libraries are used, Obtaining the OpenSSL Libraries on WindowsOn 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 is compiled against the GnuWin32 binary, you can obtain an installation package here. Once you have run the installation package, you can copy the necessary dll libraries into $RESIN_HOME:
Preparing to use OpenSSL for making keysYou can make a keys/ subdirectory of $RESIN_HOME to do your work from and as a place to store your generated 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.
Creating a private keyCreate 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 certificateOpenSSL works by having a signed public key that corresponds to your private key. This signed 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 certificateYou 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.
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 requestTo get a certificate that is signed by a CA, first you generate a (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. 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.conf - Configuring Resin to use your private key and certificateThe 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 [TODO: port configuration].
TestingTesting with the browser
Once you have SSL configured, you can come back to this page using an https:// style URL instead of an http:// url and you will get a message telling that SSL is working. A quick test is the following JSP.
Using openssl to test the serverThe openssl tool can be used as a client, showing some interesting information about the conversation between the client and the server:
Certificate ChainsA 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:
The certificates must be in that order, and must be in PEM format. Example certificate chain for Instant SSLComodo (http://instanssl.com) is a signing authority that is untrusted by most browsers. Comodo has their certificate signed by GTECyberTrust. Comodo gives you three certificates:
In addition to this, you have your key, your_domain.key. The contents of the file referred to by <certificate-chain-file> is a concatenation of the three certificates, in the correct order.
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 SunThis 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.
Create a test server certificateThe server certificate is the core of SSL. It will identify your server and contain the secret key to make encryption work.
In this case, we're using Sun's to generate the server certificate. Here's how:
Currently, the key password and the keystore password must be the same. resin.confThe Resin SSL configuration extends the http configuration with a few new elements.
Testing JSSEWith the above configuration, you can test SSL with https://localhost:8443. A quick test is the following JSP.
User Experiences with JSSEHow 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
JSSE setup
Keystore initialization
Keystore protectionYour 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.
(the default password for the cacerts keystore is 'changeit') Private key generationWe'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 :
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.
Key pair verificationIssue the following command :
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 :
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... !
|