Managing SSL keys and certificates

Generating keys and certificates with keytool

The simplest way to 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.

If you already have keys and certificates, jump to Loading Keys and certificates to load them into a JSSE keystore. That section also applies if you have a renewal certificate to replace one that is expiring. The examples below generate only basic keys and certificates.

The following command generates a key pair and a certificate directly into a file named keystore:

keytool -keystore keystore -alias jetty -genkey -keyalg RSA

Note: The DSA key algorithm certificate produces an error after loading several pages. In a browser, it displays the message "Could not establish an encrypted connection because certificate presented by localhost has an invalid signature". The solution is to use RSA for the key algorithm.

The 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.

You now have the minimum requirements for creating an SSL connection, and you could proceed directly to configuring one. However, the browser will not trust the certificate you generated, and will prompts the user to this effect. What you have at this point is sufficient for testing, but not for production.

If you want to use only a self-signed certificate, you can add -validity <days> to the keytool call above to extend the validity of the certificate beyond a month, which is the default period.

You can also use the SAN extension to set one or more names that the certificate applies to:

keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA --ext 'SAN=dns:jetty.eclipse.org,dns:*.jetty.org'

Generating keys and certificates with OpenSSL

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

openssl genrsa -aes128 -out jetty.key

You might also 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 a file named jetty.crt:

openssl req -new -x509 -b2048 -sha256 -key jetty.key -out jetty.crt

The -sha256 option generates a certificate with the SHA-256 signature algorithm, while -b2048 specifies the key length.

The 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.

You now have the minimum requirements for creating an SSL connection, and you could proceed directly to load these keys and certificates into a JSSE keystore. However, the browser will not trust the certificate you generated, and will prompts the user to this effect.

Requesting a trusted certificate

To obtain a certificate that most common browsers will trust, you need to ask a well-known certificate authority (CA) to sign your key/certificate. Trusted CAs include AddTrust, Entrust, GeoTrust, RSA Data Security, Thawte, VISA, ValiCert, Verisign, and beTRUSTed.

Each CA has its own instructions (look for information about "JSSE" or "OpenSSL"), but all involve a step that generates a certificate-signing request (CSR).

Generating a CSR with keytool

The following command uses keytool to generate the file jetty.csr for a key or certificate that's already in the keystore:

keytool -certreq -alias jetty -keystore keystore -file jetty.csr

Generating a CSR with OpenSSL

The following command uses openssl to generate the file jetty.csr for a key in the file jetty.key:

openssl req -new -key jetty.key -out jetty.csr

Notice that this command uses the existing key from the jetty.key file, and not the certificate from jetty.crt. You need to enter the details for the certificate again.

Loading keys and certificates

When a CA has sent you a certificate, or if you generated your own certificate without keytool, you need to load it into a JSSE keystore.

Note: You need both the private key and the certificate in the JSSE keystore. You should load the certificate into the keystore that was used to generate the CSR with keytool. If your key pair is not already in a keystore (for example, because it was generated with OpenSSL), you need to use the PKCS12 format to load both the key and certificate.

Loading certificates with keytool

You can use keytool to load a certificate in PEM format directly into a keystore. The PEM format is a text encoding of certificates; it is produced by OpenSSL, and is returned by some CAs.

The following command loads a PEM-encoded certificate in the jetty.crt file into a JSSE keystore:

keytool -keystore keystore -import -alias jetty -file jetty.crt -trustcacerts

If the certificate that you receive from the CA is not in a format that keytool understands, you can use the openssl command to convert formats:

openssl x509 -in jetty.der -inform DER -outform PEM -out jetty.crt

Loading keys and certificates via PKCS12

If you have a key and certificate in separate files, you need to combine them into a PKCS12 format file to load into a new keystore. The certificate can be one you generated yourself or one returned from a CA in response to your CSR.

The following OpenSSL command combines the keys in jetty.key and the certificate in the jetty.crt file into a file named jetty.pkcs12:

openssl pkcs12 -inkey jetty.key -in jetty.crt -export -out jetty.pkcs12

If you have a chain of certificates because your CA is an intermediary, build the PKCS12 file as follows:

cat example.crt intermediate.crt [intermediate2.crt] ... rootCA.crt > cert-chain.txt
openssl pkcs12 -export -inkey example.key -in cert-chain.txt -out example.pkcs12

The order of certificates must be from server to rootCA, as described in RFC2246 section 7.4.2.

OpenSSL asks for an export password. A non-empty password is required to make the next step work. Then load the resulting PKCS12 file into a JSSE keystore with keytool:

keytool -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destkeystore keystore

Renewing certificates

If you are updating your configuration to use a newer certificate because the old one is expiring, just load it as described in Loading keys and certificates.

If you originally imported the key and certificate using the PKCS12 method, use an alias of 1 rather than jetty, because that is the alias the PKCS12 process enters into the keystore.