Configuring SSL for Jetty

This is an overview of how to configure SSL for Jetty, which uses Sun's reference implementation for the Java Secure Sockets Extension (JSSE).

Configuring SSL can be a confusing experience of keys, certificates, protocols and formats, thus it helps to have a reasonable understanding of the basics. The following links provide some good starting points:

The Basics

the following steps are required to configure Jetty for SSL:

Step 1) Keys and Certificates

The simplest way generate keys and certificates is to use the keytool application that comes with the JDK, as it generates keys and certificates directly into the keystore. See step 1a

The OpenSSL tools can also be used to generate keys and certificates or to convert ones that have been used with apache or other servers.

If you already have keys and certificates, please goto step 3 to load them into a JSSE key store.

The commands below only generate minimal keys and certificates. You should read the full manuals of the tools you are using if you wish to specify:


1a) Generating a certificate with JDK keytool

The following command will generate a key pair and certificate directly into a keystore:
This command will prompt for information about the certificate and for passwords to protect both the keystore and the keys within it. The only manditory response is to provide the fully qualified host name of the server at the "first and last name" prompt. For example:
You now have the minimal requirements to run an SSL connection and could proceed directly to step 4 to configure an SSL listener. However the certificate you have generated will not be trusted by the browser and the user will be prompted to this effect. This is often sufficient for testing, but most public site will need to step 2a to obtain a certificate trusted by most popular clients.

Step 1b) Keys and Certificates with openssl

The OpenSSL tool suite is commonly used by other servers such as apache to generate manipulate keys and certificates. So you may already have some keys and certificates created by openssl, or openssl may be more trusted than keytool or some certificate authorities for step 2 may also prefer the formats produced by ssl.

The following command generates a key pair in the file jetty.key:

You may also wish to use the -rand file argument to provide an arbitrary file to help seed the random number generator.

The following command generates a certificate for the key into the file jetty.crt:

This command will prompt for information about the certificate and for passwords to protect both the keystore and the keys within it. The only manditory response is to provide the fully qualified host name of the server at the "Common Name" prompt. For example:
You now have the minimal requirements to run an SSL connection and could proceed directly to step 3 to load these keys and certificats into a JSSE keystore. However the certificate you have generated will not be trusted by the browser and the user will be prompted to this effect. This is often sufficient for testing, but most public site will need to step 2b to obtain a certificate trusted by most popular clients.

Step 1c) Keys and Certificates from other sources

If you have keys and certificates from other sources, then you can proceed directly to step 3

Step 2) Request a trusted certificate

The keys and certificats generated in steps 1a and 1b are sufficient to run an SSL listener. However the certificate you have generated will not be trusted by the browser and the user will be prompted to this effect.

To obtain a certificate that will be trusted by most common browsers, you need to request a well known certificate authority (CA) to sign your key/certificate. Such trusted CAs include: AddTrust, Entrust, GeoTrust, RSA Data Security, Thawte, VISA, ValiCert, Verisign, beTRUSTed, among others.

Each CA will have their own instructions which should be followed (look for JSSE or openssl sections), but all will involved a step to generate a certificate signing request (CSR).

Step 2a) CSR from keytool

The following commands generates the file jetty.csr using keytool for a key/cert already in the keystore:

Step 2b) CSR from openssl

The following commands generates the file jetty.csr using openssl for a key in the file jetty.key:
Note that this command only uses the existing keu from jetty.key file and not a certificate in jetty.crt generated by step 1b. The details for the certificate need to be entered again.

Step 3) Loading Keys and Certificates

Once a CA has sent you a certificate, or if you generated your own certificate without keytool, then it will need to be loaded into a JSSE keystore. If you did not use keytool to generate the key, then it will also need to be loaded into the keystore.

Step 3a) Loading Certificates with keytool

A certificate in PEM form may be directly loaded into a keystore with keytool. The PEM format is a text encoding of certificates and is produced by openssl (as in step 1b) and is returned by some CAs. An example PEM file is:
The following command will load a PEM encoded certificate in the jetty.crt file into a JSSE keystore:
NOTE. That you need both the private key and the certificate in the keystore. So the certificate should be loaded into the keystore used to generate the CSR (step 2a). If your key pair is not in a keystore (eg if generated as step 1b), then you will need to use the PKCS12 format to load both key and certificate as in step 3b.

If the certificate your receive from the CA is not in a format that keytools understands, then the openssl command can be used to convert formats:


Step 3b) Loading keys and certificates via PKCS12

If you have a key and certificate in separate files, they need to be combined into a PKCS12 format file to be loaded into a new keystore. The certificate can be one you generated yourself or one that has been returned from a CA in response to your CSR.

The following openssl command will combine the keys in jetty.key and the certificate in the jetty.crt file into the jetty.pkcs12 file:

The resulting PKCS12 file may be loaded into a JSSE keystore with the following jetty utility class:

Step 4) Configure Jetty.

Assuming you already have a functioning Jetty Server and are using the Sun JVM, add the SunJsseListener as a HttpListeners, e.g. In the jetty.xml file you can uncomment the following lines:

  <Call name="addListener">
    <Arg>
      <New class="org.mortbay.http.SunJsseListener">
        <Set name="Port">8443</Set>     
        <Set name="Keystore"><SystemProperty name="jetty.home" default="."/>/keystore</Set>

	<Set name="Password">password</Set>
	<Set name="KeyPassword">password</Set>
      </New>
    </Arg>
  </Call>
Note. If you are using the IBM JSSE implementation, you may us the org.mortbay.http.IbmJsseListener class from the contrib directory of a Jetty release.

Remember that the default port for https is 443 not 80, so change 8443 to 443 if you want to be able to use URL's without explicit port numbers. For a production site it normally makes sense to have a HttpListener on port 80 and a SunJsseListener on port 443. Note that as these are privileged ports, you may want to use a redirection mechanism to map port 80 to eg 8080 and 443 to eg 8443. For details on this, see the FAQ.

The keystore file in this example is given relative to the jetty home directory. For production, choose a private directory with restricted access to keep your keystore in. Even though it has a password on it, the password may be configured into the runtime environment so is vulnerable to theft.

Jetty can now be started the normal way (make sure that jcert.jar, jnet.jar and jsse.jar are on your classpath) and SSL can be used with a URL like:


   https://localhost:8443/

Note. The most common mistake at this point is to try to access port 8443 with http rather than https.

Password Issues

If the passwords are not provided in the configuration, they may be provided as java properties (jetty.ssl.password and jetty.ssl.keypassword) else they will be prompted for.

Remember that putting your password on the command line is a security risk. They can also be set as properties within the config file, but this risks accidental discovery by developers.

If jetty is given a password that begins with "OBF:" it is treated as an obfuscated password. Passwords can be obfuscated by running org.mortbay.util.Password as a main class. This can protect passwords from casual observation.


JettyFaq