- 1 Introduction
- 2 Configuring SSL
- 3 The Basics
- 4 Step 1: Generating Keys and Certificates
- 5 Step 1a: Generating a certificate with JDK keytool
- 6 Step 1b: Keys and Certificates with openssl
- 7 Step 1c: Keys and Certificates from other sources
- 8 Step 2: Request a trusted certificate
- 9 Step 2a: CSR from keytool
- 10 Step 2b: CSR from openssl
- 11 Step 3: Loading Keys and Certificates
- 12 Additional Resources
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:
- Other tools:
- Open SSL:
To configure Jetty for SSL, complete the following steps:
[#HowtoconfigureSSL-step1 Step 1]: Generate or obtain a public/private key pair and x509 certificate. [#HowtoconfigureSSL-step2 Step 2]: Optionally obtain a certificate from a known certificate authority. [#HowtoconfigureSSL-step3 Step 3]: Load the keys and the certificates into a JSSE Keystore. [#HowtoconfigureSSL-step4 Step 4]: Configure a JsseListener with the location and passwords for the keystore.
OpenSSL Versus Keytool
For testing, keytool probably provides the simplest way to generate the key and certificate you will need. However, IBM's keyman is also pretty good, and provides a GUI rather than a command line.
You can also use the OpenSSL tools to generate keys and certificates, or to convert those that you have used with Apache or other servers. Since Apache and other servers commonly use the OpenSSL tool suite to generate and manipulate keys and certificates, you might already have some keys and certificates created by OpenSSL. Also, OpenSSL might be more trusted than keytool or some certificate authorities for step 2 You might also prefer the formats OpenSSL produces.
If you want the option of using the same certificate with Jetty or a web server such as Apache not written in Java, you might prefer to generate your private key and certificate with openSSL. The Java keytool does not provide options for exporting private keys, and Apache needs the private key. If you create the key and certificate with openSSL, your non-Java web server has ready access to it.
Step 1: Generating 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 [#HowtoconfigureSSL-step1a Step 1a].
If you already have keys and certificates, see [#HowtoconfigureSSL-step3 Step 3] to load them into a JSSE key store.
If you have a renewal certificate to replace one that is expiring, see [#HowtoconfigureSSL-renewals Renewals].
The commands below generate only basic keys and certificates. You should read the full manuals of the tools you are using if you want to specify:
- Key size.
- Certificate expiry.
- Alternate security providers.
Step 1a: Generating a certificate with JDK keytool
The following command generates a key pair and certificate directly into a keystore:
keytool -keystore keystore -alias jetty -genkey -keyalg RSA
Note: DSA key algorithm certificate produces an error after several loading of pages. In a browser, it displays a message "Could not establish an encrypted connection because certificate presented by localhost has an invalid signature." See more details in [/display/JETTY/SSL+does+not+work+with+DSA+key troubleshooting] page.
This command prompts for information about the certificate and for passwords to protect both the keystore and the keys within it. The only mandatory response is to provide the fully qualified host name of the server at the "first and last name" prompt. For example:
keytool -keystore keystore -alias jetty -genkey -keyalg RSA Enter keystore password: password What is your first and last name? [Unknown]: jetty.eclipse.org What is the name of your organizational unit? [Unknown]: Jetty What is the name of your organization? [Unknown]: Mort Bay Consulting Pty. Ltd. What is the name of your City or Locality? [Unknown]: What is the name of your State or Province? [Unknown]: What is the two-letter country code for this unit? [Unknown]: Is CN=jetty.eclipse.org, OU=Jetty, O=Mort Bay Consulting Pty. Ltd., L=Unknown, ST=Unknown, C=Unknown correct? [no]: yes Enter key password for <jetty> (RETURN if same as keystore password): password
You now have the minimal requirements to run an SSL connection and could proceed directly to [#HowtoconfigureSSL-step4 Step 4] to configure an SSL connector.
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 [#HowtoconfigureSSL-step2a Step 2a] to obtain a certificate trusted by most popular clients.
Step 1b: Keys and Certificates with openssl
The following command generates a key pair in the file jetty.key:
openssl genrsa -des3 -out jetty.key
You might sls want to use the -rand file argument to provide an arbitrary file that helps seed the random number generator.
The following command generates a certificate for the key into the file jetty.crt:
openssl req -new -x509 -key jetty.key -out jetty.crt
This command prompts for information about the certificate and for passwords to protect both the keystore and the keys within it. The only mandatory response is to provide the fully qualified host name of the server at the "Common Name" prompt. For example:
openssl genrsa -des3 -out jetty.key Generating RSA private key, 512 bit long modulus ...........................++++++++++++ ..++++++++++++ e is 65537 (0x10001) Enter pass phrase for jetty.key: Verifying - Enter pass phrase for jetty.key: # openssl req -new -x509 -key jetty.key -out jetty.crt Enter pass phrase for jetty.key: You are about to be asked to enter information that will be incorporated into your certificate request. What you are about to enter is what is called a Distinguished Name or a DN. There are quite a few fields but you can leave some blank For some fields there will be a default value, If you enter '.', the field will be left blank. ----- Country Name (2 letter code) [AU]:. State or Province Name (full name) [Some-State]:. Locality Name (eg, city) :. Organization Name (eg, company) [Internet Widgets Pty Ltd]:Mort Bay Consulting Pty. Ltd. Organizational Unit Name (eg, section) :Jetty Common Name (eg, YOUR name) :jetty.eclipse.org Email Address : #
You now have the minimal requirements to run an SSL connection and could proceed directly to [#HowtoconfigureSSL-step3 Step 3] to load these keys and certificates 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 [#HowtoconfigureSSL-step2b 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 [#HowtoconfigureSSL-step3 Step 3].
Step 2: Request a trusted certificate
The keys and certificats generated in steps 1a and 1b are sufficient to run an SSL connector. 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:
keytool -certreq -alias jetty -keystore keystore -file jetty.csr
Step 2b: CSR from openssl
The following commands generates the file jetty.csr using openssl for a key in the file jetty.key:
> openssl req -new -key jetty.key -out jetty.csr
Note that this command only uses the existing key 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 you need to load it into a JSSE keystore.