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 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:
# keytool -keystore keystore -alias jetty -genkey -keyalg RSA |
# keytool -keystore keystore -alias jetty -genkey -keyalg RSA
Enter keystore password: password
What is your first and last name?
[Unknown]: jetty.mortbay.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.mortbay.org, OU=Jetty, O=Mort Bay Consulting Pty. Ltd.,
L=Unknown, ST=Unknown, C=Unknown correct?
[no]: yes
Enter key password for |
The following command generates a key pair in the file jetty.key:
# openssl genrsa -des3 -out jetty.key |
The following command generates a certificate for the key into the file jetty.crt:
# openssl req -new -x509 -key jetty.key -out jetty.crt |
# 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 Widgits Pty Ltd]:Mort Bay Consulting Pty. Ltd. Organizational Unit Name (eg, section) []:Jetty Common Name (eg, YOUR name) []:jetty.mortbay.org Email Address []: # |
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).
# keytool -certreq -alias jetty -keystore keystore -file jetty.csr |
# openssl req -new -key jetty.key -out jetty.csr |
# jetty.crt -----BEGIN CERTIFICATE----- MIICSDCCAfKgAwIBAgIBADANBgkqhkiG9w0BAQQFADBUMSYwJAYDVQQKEx1Nb3J0 IEJheSBDb25zdWx0aW5nIFB0eS4gTHRkLjEOMAwGA1UECxMFSmV0dHkxGjAYBgNV BAMTEWpldHR5Lm1vcnRiYXkub3JnMB4XDTAzMDQwNjEzMTk1MFoXDTAzMDUwNjEz MTk1MFowVDEmMCQGA1UEChMdTW9ydCBCYXkgQ29uc3VsdGluZyBQdHkuIEx0ZC4x DjAMBgNVBAsTBUpldHR5MRowGAYDVQQDExFqZXR0eS5tb3J0YmF5Lm9yZzBcMA0G CSqGSIb3DQEBAQUAA0sAMEgCQQC5V4oZeVdhdhHqa9L2/ZnKySPWUqqy81riNfAJ 7uALW0kEv/LtlG34dOOcVVt/PK8/bU4dlolnJx1SpiMZbKsFAgMBAAGjga4wgasw HQYDVR0OBBYEFFV1gbB1XRvUx1UofmifQJS/MCYwMHwGA1UdIwR1MHOAFFV1gbB1 XRvUx1UofmifQJS/MCYwoVikVjBUMSYwJAYDVQQKEx1Nb3J0IEJheSBDb25zdWx0 aW5nIFB0eS4gTHRkLjEOMAwGA1UECxMFSmV0dHkxGjAYBgNVBAMTEWpldHR5Lm1v cnRiYXkub3JnggEAMAwGA1UdEwQFMAMBAf8wDQYJKoZIhvcNAQEEBQADQQA6NkaV OtXzP4ayzBcgK/qSCmF44jdcARmrXhiXUcXzjxsLjSJeYPJojhUdC2LQKy+p4ki8 Rcz6oCRvCGCe5kDB -----END CERTIFICATE----- |
# keytool -keystore keystore -import -alias jetty -file jetty.crt |
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:
# openssl x509 -in jetty.der -inform DER -outform PEM -out jetty.crt |
The following openssl command will combine the keys in jetty.key and the
certificate in the jetty.crt file into the jetty.pkcs12 file:
# openssl pkcs12 -inkey jetty.key -in jetty.crt -export -out jetty.pkcs12 |
# java -classpath $JETTY_HOME/lib/org.mortbay.jetty.jar \ org.mortbay.util.PKCS12Import jetty.pkcs12 keystore |
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.
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.