If you have never dealt with SSL, configuring it for your Web application may seem like a dark science or anyway confusing and frustrating experience. Not to fear - you are not the only and not the first one. This posting does not provide any insights whatsoever on the nature of SSL and related technologies. Please Google if you are interested to learn more. Instead, this article is a kind of 1-2-3 type of approach written under assumption that it's possible to complete this job without knowing anything about keys, encryption, SSL and such.

So, the following steps will be needed to start and complete the job:

1. Obtain security certificate
2. Modify your Restlet Web site code to understand the HTTPs protocol and recognize the certificate obtained
3. Modify your Restlet Web site code to redirect to HTTPs protocol when needed

Before you start working on step 1. you should decide on certification authority (CA) you are going to use for getting a security certificate. One of the factors that is not really important is the Web server you are using. The only practical implication of this factor is that different CAs on their Web sites may provide more or less detailed description of the process for your particular Web server. Well, since we are using Restlets, this factor is not important at all. None of major CAs mentions Restlets, or to say more accurately, Jetty which is a default Restlet connector.

Other practical factors in choosing CA are

• Price
• Browser support
• Certificate features available in various certificates offered by a CA (warranty, encryption level, etc.)
• Time necessary to obtain a certificate
• Availability of a free test certificate
• Reputation

You can find plenty of discussions on the Web about all that stuff. To make this long story as short as possible, I can tell you that not long ago I made an extensive research (more of a consumer type than scientific) regarding different CA and found no compelling reasons to go with the market leader VeriSign and buy its very expensive certificates.

Instead, I would recommend to look at Comodo (which is also known for its firewalls and some other security). The difference in price can be astronomical - 10 times and more less with Comodo than with VeriSign. And what I found especially attractive is Comodo's free SSL trial certificate. By the way, what I do not like about Comodo service is their technical support. In my experience you are mostly on your own especially, if you are not buying one of their most expensive certificates.

These free SSL certificates provide full SSL functionality for 90 days and are issued using the same Trusted Root Certificate Authority (CA). They provide 99.3 percent browser consistency, and they are not issued by a different test CA. This unique service helps you fully test your system before you roll out you site into production.

Once you have decided on CA, you are ready for the first step in your endeavor - obtaining security certificate. Although there is little difference in how it's done with different CA, for the sake of accuracy I should say that the notes below for step 1. relate to Comodo SSL certificates.

1. Obtaining security certificate

I start off with saying that step 1 in its turn consists of thee sub-steps

1. Creating your CSR (Certificate Signing Request)
2. Interacting with CA (using CA's Web site) to obtain a certificate
3. Installing your security certificate provided by CA

If you want to read more about Jetty specific details reagarding the three sub-steps you may find this page (pablished by Jetty team) useful.

Creating your CSR (Certificate Signing Request)

To create a CSR, you need to create a certificate. Do this using a keytool command (utility, part of the Java). The following command will generate a key pair and certificate directly into a keystore:
keytool -genkey -keyalg RSA -keystore keystore
If you want to use an alias for the site certificate include -alias yyy (where yyy is the alias name). This command will prompt for information:

Enter keystore password: (NOTE remember this for later use)
What is your first and last name? (see below and important note on this one)
What is the name of your organizational unit?
What is the name of your organization?
What is the name of your City or Locality?
What is the name of your State or Province?
What is the two-letter country code for this unit?
You will then be asked if the information is correct:Is CN=www.yourdomain.com, OU=Your Oganizational Unit, O=Your Organization, L=Your City, ST=Your State, C=Your Country correct?
When you answer 'y' or 'yes' the password is then requested:Enter key password for NOTE: Make a note of this password ( is the default alias for the certificate)

VERY IMPORTANT! Although during this process you are asked about your first and last name THAT IS NOT WHAT THE TOOL NEEDS TO KNOW. It needs the so-called Common Name (CN) in your CSR which is one of the following:

• Your fully qualified domain name (e.g. "www.arredocenter.com")
• Full name of your internal server or developer machine (e.g. "bobcat")
• Your IP address (e.g. "192.168.0.1")

When you are done with certificate use the following keytool command to create the CSR file:
keytool -certreq -keyalg RSA -file domain.csr -keystore keystore

You will be prompted to enter the password.
Enter keystore password:

If the password is correct then the CSR is created. If the password is incorrect then a password error is displayed.

Interacting with CA (using CA's Web site) to obtain a certificate

You will need the text from the just created CSR when requesting a certificate. Go to the CA Web site and follow instructions. Mostly, this is a fully automated issuance process. For example, with Comodo, it will look like you are buying a certificate (with free trial the total will show as $0.00). At some point it will show you a page where you will need to copy and paste the CSR text using an ASCII text editor into the CSR text area provided. Just go ahead and do it. On Comodo site there is also a dropdown list to "select the server software used to generate the CSR." Select Java Based Web Servers.

What happens next varies slightly with different CAs. If you are getting free trial certificate from Comodo it's usually created almost immediately (but in other cases it may take longer even significantly longer). Also, with Comodo, you will be able to download a zip file with all the stuff you need to install the certificate.

Installing your security certificate provided by CA

If you selected "Java Based Web Servers" as described above, the ZIP file you will obtain from Comodo will contain several *.crt files. At this moment (summer 2008) you will get five files (but that may change in future). One of the file will be AddTrustExternalCARoot.crt which you can ignore; another file with your domain name will be your certificate; and the rest will be intermediate certificates. You will have to merge all that stuff (including AddTrustExternalCARoot.crt if you insist) into your keystore file created at the very beginning.

Do this using keytool utility in the following order (just in case take notes of aliases you are using)
keytool -import -trustcacerts -alias root -file AddTrustExternalCARoot.crt -keystore keystore
keytool -import -trustcacerts -alias INTER -file UTNAddTrustSGCCA.crt -keystore keystore
keytool -import -trustcacerts -alias INTER1 -file ComodoUTNSGCCA.crt -keystore keystore
keytool -import -trustcacerts -alias INTER2 -file EssentialSSLCA_2.crt -keystore keystore
keytool -import -trustcacerts -alias arredo -file arredocenter.com.crt -keystore keystore

2. Modifying your Restlet Web site code for SSL certificate obtained

This can be a bit of mystery if you do not have extensive knowledge of Restlet API. Hopefully, it will be documented better even in near future. At this moment you can follow the example in Listing 1. Just pay attention how context parameters are added ("keystorePath", "keystorePassword", "keyPassword").

Listing 1: Updating Restlet Component's context with keystore parameters

public class Camerata extends Component {
  ...
  public static void main(String ...args) throws Exception {
    new Camerata();  }

  public Camerata() throws Exception {
    getServers().add(Protocol.HTTP, "[your server IP]", 80);
    getServers().add(Protocol.HTTP, "[your server IP]", 443);
    getClients().add(Protocol.FILE);
    ....
    /* arredocenter.com */
    VirtualHost host = new VirtualHost(getContext());
    host.setHostDomain("www.arredocenter.com|arredocenter.com");
    host.attach("", new Arredocenter(getContext()));
    getHosts().add(host);

    /* naviquan.com */
    host = new VirtualHost(getContext());
    ...
    getHosts().add(host);

    // Update component's context with keystore parameters.
    File keystoreFile = new File("C:\\arredorest", "keystore");
    getContext().getParameters().add("keystorePath", 
keystoreFile.toURI().toASCIIString());
    getContext().getParameters().add("keystorePassword", 
"actualKeystorePassword");
    getContext().getParameters().add("keyPassword", "actualKeyPassword");
    ...
    start();
  }
....
}

3. Modifying your Restlet Web site code to redirect to HTTPs protocol when needed

This is the final step in configuring your site to work with encrypted connection, and its details may certainly depend on your specific ideas for the site itself. For example, currently, many US government sites prefer to use only HTTPS protocols, no matter what information communicated. This wise idea requires some immediate redirection of all HTTP requests to HTTPS.

Other sites still prefer to use HTTPS only in specific cases (for example, submitting Web forms with personal and payment information). Obviously, there are some theories why this design decision has been made (which are not a consideration in this article). Point is that both approaches require somewhat different techniques that hopefully will be discussed in a different recipe.