SETTING UP SSL AND HTTPS

This article will give you pointers on how to enable communication over the Secure Socket Layer and how to enable secure HTTP connections. 1 INTRODUCTION In many cases you want to protect information passed to and from a web site using encryption. You also want to have a way to certify the identity of either the client or the server. For the client it is pretty convenient to identify itself using a username and password, but obviously the server needs some other mechanism to prove that the information you are sending to it actually ends up in the right hands, for example if you send credit card information. HTTPS solves both these problems. It guarantees the identity of the server (and optionally, also the identity of the client) through the usage of certificates as well as provide encryption for the communication. 2 CERTIFICATES AND CAS First let us familiarize ourselves with the concept of an SSL certificate. According to the documentation of Sun's keytool: "A certificate (also known as a public-key certificate) is a digitally signed statement from one entity (the issuer), saying that the public key (and some other information) of another entity (the subject) has some specific value. To understand this let us discuss the concepts used in the explanation above. Sun also has a glossary available here. 2.1 PUBLIC & PRIVATE KEYS In "public key crypto systems", every entity is associated with one public and one private key. When two entities communicate both parties use their own private key and the other sides public key, to make sure that only the two entities can talk to each other. A public key is essentially a publicly available number associated with a particular entity, and everyone who is supposed to communicate securely with the entity should know this number. A private key is also a number, but one that is kept a secret. In a typical public key crypto system, such as DSA, a private key corresponds to exactly one public key. Only the private key can be used to create a signature, but the public key can be used to verify the signature. This means that the private/public key combination means that an entity can guarantee that it knows its private key without giving away what it is.

2.2 DIGITALLY SIGNED If some data is digitally signed it has been stored with the "identity" of an entity, and a signature that proves that entity knows about the data. The data is rendered unforgeable by signing with the entity's private key. 2.3 IDENTITY A known way of addressing an entity. In some systems the identity is the public key, in others it can be anything from a Unix UID to an Email address to an X.509 Distinguished Name. Now, how can a certificate really certify the identity of anyone? The answer is the Certificate Authorities or the CAs. A Certificate Authority is an organization that issues certificates to other organizations that wish to prove their identity. The CA asks the certificate requester to provide information about itself and the CA gives back a certificate in return. The returned certificate is chained to the root certificate, establishing a chain of trust. In this way someone dealing with a company identifying itself through a certificate issued by a certain CA doesn't have to trust every company, but it is sufficient to trust the root CA. Examples of CAs are Verisign and Thawte. These are root CAs that issue certificates that are chained to their root certificates. There are also CAs that do not provide root certificates but chain to on of the root CA themselves. So if you get a certificate from such a CA, your certificate is linked to the intermediate CA and their certificate is chained to a root certificate. 3 THE KEYTOOL Provided with the JDK from Sun is a tool to create and handle certificates. The official description of the keytool is this: "Keytool is a key and certificate management utility. It enables users to administer their own public/private key pairs and associated certificates for use in self-authentication (where the user authenticates himself/herself to other users/services) or data integrity and authentication services, using digital signatures. It also allows users to cache the public keys (in the form of certificates) of their communicating peers." The keytool stores all keys and certificates in a keystore, which is normally a file, but could theoretically be something else. It stores private information by a password. For a complete reference to the keytool, please visit Sun's keytool documentation. This provides a very complete guide to the topics discussed in this document.

4 OBTAINING A CERTIFICATE The outlines for obtaining a certificate from the most common CA:s are described below for the following CA:s Getting a Thawte test SSL certificate Getting a real Thawte SSL certificate Getting a real Verisign certificate 4.1 GETTING A THAWTE TEST SSL CERTIFICATE 1. Create a keystore with a private/public keypair:

keytool -genkey -keyalg "RSA" -keystore keystore -storepass 123456 -validity 360 Listing 1: Using Keytool to generate a Keystore

The keystore specified is the filename where the keys will be stored, the storepass is the password for protecting the keystore and the validity is the number of days the certificate will be valid. 2. Create a Certificate Signing Request (CSR). This will be sent to the CA when a certificate or certificate chain is requested.
keytool -certreq -keyalg "RSA" -file my.host.com.csr -keystore keystore Listing 2: Using Keytool to generate a CSR

User firstname lastname: - Make this your website name www.yoursite.com Organization: - Your company name - Acme Organizational Unit: - Your company's domain name - acme.com City/Locality: - Your city - AcmeVille State: - Your state, capitalize this - Colorado Country: - The 2 letter code for country - US Make sure to use the same password for the certificate and the Keystore, as only the Keystore password can be given to JSSE. JSSE will try to use the Keystore password on the certificate per default. Visit Thawte's site for requesting a developer certificate: https://www.thawte.com/cgi/server/try.exe.
3.

4. Paste the contents of the .csr file generated in step 2 into the text area on this page. Note that the form is sensitive to linebreaks, and cut&paste may fail with certain browsers. 5. Set the validity to the number of days you specified with generating the keypair on the thawte page. 6. Set the certificate to be "Valid from now" 7. Get a "Test SSL Chained CA Cert". This will make sure that you get a whole certificate chain and will not have to add the CA's root certificate yourself to create a certificate chain.

8. For the other options, the defaults should be fine and you can click the "Generate Test Certificate" 9. Take the resulting certificate and paste it into a file called my.host.com.cer, again, note that the cert is sensitive to linebreaks, and cut&paste may fail with certain browsers. 10. Now store the certificate in your keystore:

keytool -keystore keystore -keyalg "RSA" -import -trustcacerts -file my.host.com.cer Listing 3: Importing the signed certificate

4.2 GETTING A REAL THAWTE SSL CERTIFICATE To get a real certificate with Thawte, choose "Other" as the server vendor alternative and visit http://www.thawte.com/html/RETAIL/ssl/index.html. 4.3 GETTING A REAL VERISIGN CERTIFICATE 11. Create a keystore with a private/public keypair:

keytool -genkey -keyalg "RSA" -keystore keystore -storepass 123456 -validity 360 Listing 4: Using Keytool to generate a Keystore

The keystore specified is the filename where the keys will be stored, the storepass is the password for protecting the keystore and the validity is the number of days the certificate will be valid. 12. Create a Certificate Signing Request (CSR). This will be sent to the CA when a certificate or certificate chain is requested.
keytool -certreq -keyalg "RSA" -file my.host.com.csr -keystore keystore Listing 5: Using Keytool to generate a CSR

User firstname lastname: - Make this your website name www.yoursite.com Organization: - Your company name - Acme Organizational Unit: - Your company's domain name - acme.com City/Locality: - Your city - AcmeVille State: - Your state, capitalize this - Colorado Country: - The 2 letter code for country - US Make sure to use the same password for the certificate and the Keystore, as only the Keystore password can be given to JSSE. JSSE will try to use the Keystore password on the certificate per default. You will need this CSR when filling out the Verisign website information. If there is anything wrong in your CSR, Verisign will notify you and you will not be able to proceed until you fix whatever the error is. When you are asked for type of server software in the Verisign process, choose "JavaSoft" since we are using an SSL

implementation from Sun by default. Visit Verisigns site for requesting a developer certificate: http://www.verisign.com/products/site/index.html.
13.

14. Begin the paperwork process with Verisign. Their site details what is required. You need to produce all of the required paperwork. You can help speed things by quickly faxing everything they ask for. 15. You will now get an email from Verisign with a certificate attached. Take the received certificate and paste it into a file called my.host.com.cer, again, note that the cert is sensitive to linebreaks. 16. Now store the certificate in your keystore:

keytool -keystore keystore -keyalg "RSA" -import -trustcacerts -file my.host.com.cer Listing 6: Importing the signed certificate

5 SETTING UP A SECURE WEBSITE USING HTTPS IN ORION Configuring a secure website can be done through the following steps: 1. Copy the default-web-site.xml config in the /config directory to secure-web-site.xml and open it with a text editor. 2. Add secure="true" as an attribute to the tag. Add the keystore to the main body. 3. Install the site, this is done by adding <web-site path="./secure-web-site.xml" /> the site to server.xml.
<?xml version="1.0"?> <!DOCTYPE web-site PUBLIC "Orion Web-site" "http://www.orionserver.com/dtds/web-site.dtd"> <web-site display-name="Default Orion WebSite" secure="true"> <default-web-app application="default" name="defaultWebApp" /> <access-log path="../log/default-web-access.log" /> <ssl-config keystore="../keystore" keystore-password="123456" /> </web-site> Listing 7: Example web-site.xml file, refered to as secure-web-site.xml above.

Excerpt from server.xml with the secure web site added:

<web-site path="./secure-web-site.xml" /> Listing 8: Excerpt from server.xml with the secure web site added.

6 SETTING UP CERTIFICATE-BASED CLIENT AUTHENTICATION FOR A SECURE WEBSITE In order to use certificate based client authentication for a secure website, go through the following steps: Make sure that the site is SSL enabled by following the steps given here.
1.

Add the needs-client-auth="true" directive to the ssl-config tag of the web-site.xml file as exemplified in listing 3 below.
2.

<?xml version="1.0"?> <!DOCTYPE web-site PUBLIC "Orion Web-site" "http://www.orionserver.com/dtds/web-site.dtd"> <web-site display-name="Default Orion WebSite" secure="true" > <default-web-app application="default" name="defaultWebApp" /> <access-log path="../log/default-web-access.log" /> <ssl-config keystore="../keystore" keystore-password="123456" needs-clientauth="true" /> </web-site> Listing 9: Example web-site.xml file, refered to as secure-web-site.xml above.

Get a client-certificate for testing. Such a certificate can be gained from most CA:s, including Verisign and Thawte.
3. 4.

Login as a User and register your profile, this can be done via the page found at /demo/ssl/ssl-user-registration.jsp. 7 COMMON PROBLEMS AND SOLUTIONS keytool error: java.security.cert.CertificateException: Unsupported encoding - The keytool is sensitive to whitespace. Try deleting all trailing whitespace, if it still doesn't work, try adding a newline in your certificate reply file. keytool error: KeyPairGenerator not available - This error might indicate that a keytool from an older JDK is being run. Try to fully qualify the path of the keytool belonging to the jdk you use to run Orion. keytool error: Failed to establish chain from reply - The problem with the first command is that keytool can't find the root ca certificates in your keystore and therefore can't build up the certificate chain from your server key to the trusted root certificate authority. keytool -keystore keystore -import -alias cacert -file cacert.cer (keytool -keystore keystore -import -alias intercert -file inter.cer) If you use an intermediate CA keytool -keystore keystore -genkey -keyalg RSA -alias serverkey keytool -keystore keystore -certreq -file my.host.com.csr Get cert from csr then: keytool -keystore keystore -import -file my.host.com.cer -alias serverkey Keytool error: Signature not available - To be written No available certificate corresponds to the SSL cipher suites which are enabled - One known reason is that different passwords has been used for the certificate and the Keystore. In this case, use the Keytool to change the password of the certificate to match the password of the Keystore. 8 GENERAL SSL DEBUGGING There are a few ways to get some more verbose debug information from the JSSE implementation. To get a list of options start Orion with:

java -Djavax.net.debug=help -jar orion.jar Listing 10: Getting a list of debug options from JSSE

Or if you want to turn on full verbosity, use:

java -Djavax.net.debug=all -jar orion.jar Listing 11: Running JSSE with full verbosity debug

Copyright 2005 IronFlare AB