Message-ID: <781450709.770074.1386252809667.JavaMail.firstname.lastname@example.org> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_770073_962817322.1386252809667" ------=_Part_770073_962817322.1386252809667 Content-Type: text/html; charset=UTF-8 Content-Transfer-Encoding: quoted-printable Content-Location: file:///C:/exported.html
This is an overview of how to configure SSL for Jetty, which uses Sun's = reference implementation for the Java Secure Sockets Extension (JSSE).= =20
Configuring SSL can be a confusing experience of keys, certificates, pro=
tocols and formats, thus it helps to have a reasonable understanding
= of the basics. The following links provide some good starting points:
The following steps are required to configure Jetty for SSL:
Step 1: Generate or obtain a public/pri= vate key pair and x509 certificate.
Step 2: Optionally obtain a certificate from a known certificate au= thority.
Step 3: Load the ke= ys and the certificates into a JSSE Keystore.
Step 4: Configure a JsseListener with the location and pa= sswords for the keystore.
For testing, keytool is probably the simplest way to generate the key an= d certificate you will need. However, IBMs keyman i= s also pretty good and provides a GUI rather than a command line.=20
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.
The= OpenSSL tool suite is commonly used by other servers such as Apache to gen= erate manipulate keys and certificates. So you may already have some keys a= nd certificates created by openssl, or openssl may be more trusted than key= tool or some certificate authorities for step 2 may also prefer the formats= produced by ssl.
If you want the option of using the same certificate with Jetty or a web=
server such as Apache not written in Java, you may prefer to
generat= e your private key and certificate with openSSL. The Java keytool does not = provide options for exporting private keys, and Apache
needs the priv= ate key. If you create the key and certificate with openSSL your non-Java w= eb server will have ready access to it.
The simplest way generate keys and certificates is to use the keytool ap= plication that comes with the JDK, as it generates keys and certificates di= rectly into the keystore. See Step 1a= .=20
If you already have keys and certificates, please goto Step 3 to load them into a JSSE key store.=20
If you have a renewal certificate to replace one that is expiring, take = a look at #renewals.=20
The commands below only generate minimal keys and certificates. You shou= ld read the full manuals of the tools you are using if you wish to specify:==20
The following command will generate a key pair and certificate directly = into a keystore:=20 =20
Note: DSA key algorithm certificate produces an error a= fter several loading of pages. In browser, it gives you a message "Cou= ld not establish an encrypted connection because certificate presented by l= ocalhost has an invalid signature." See more details in troubleshooting page.= =20
This command will prompt for information about the certificate and for p=
asswords to protect both the keystore and the keys within it. The only mand=
atory 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 requirement= s to run an SSL connection and could proceed directly to Step 4 to configure an SSL connector.
However = the certificate you have generated will not be trusted by the browser and t= he user will be prompted to this effect. This is often sufficient for testi= ng, but most public site will need to Step 2a to obtain a certificate trusted by most popular clients.
The following command generates a key pair in the file jetty.key:
You may also wish to use the -rand f= ile argument to provide an arbitrary file to help seed the random number ge= nerator.
The following command generates a certificate for the key in= to the file jetty.crt:
This command will prompt for informa= tion about the certificate and for passwords to protect both the keystore a= nd the keys within it. The only mandatory response is to provide the fully = qualified host name of the server at the "Common Name" prompt. Fo= r example:
You now have the minimal requirement= s to run an SSL connection and could proceed directly to Step 3 to load these keys and certificates into a JS= SE 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 p= opular clients.
If you have keys and certificates from other sources, then you can proce= ed directly to Step 3.=20
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 b= e trusted by the browser and the user will be prompted to this effect.= =20
To obtain a certificate that will be trusted by most common browsers, yo= u need to request a well known certificate authority (CA) to sign your key/= certificate. Such trusted CAs include: AddTrust, Entrust, GeoTrust, RSA Dat= a Security, Thawte, VISA, ValiCert, Verisign, beTRUSTed, among others.= =20
Each CA will have their own instructions which should be followed (look =
for JSSE or openssl sections), but all will involved a step to
genera= te a certificate signing request (CSR).
The following commands generates the file jetty.csr using keytool for a =
key/cert already in the keystore:
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 key from jetty.key file and not a certificate in jetty.crt genera= ted by step 1b. The details for the certificate need to be entered again.
Once a CA has sent you a certificate, or if you generated your own certi=
ficate without keytool, then it will need to be loaded into
a JSSE ke= ystore. If you did not use keytool to generate the key, then it will also n= eed to be loaded into the keystore.
A certificate in PEM form may be directly loaded into a keystore with ke=
ytool. 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 i=
The following command will load a PE= M encoded certificate in the jetty.crt file into a JSSE keystore:
Depending on the situation you may n= ot require the
-trustcacerts option. Try the operation without=
it if you like.
If the certificate your receive from the CA is not i= n a format that keytool understands, then the openssl command can be used t= o convert
If you have a key and certificate in separate files, they need to be com= bined into a PKCS12 format file to be loaded into a new keystore. The certi= ficate can be one you generated yourself or one that has been returned from= a CA in response to your CSR.=20
The following openssl command will combine the keys in jetty.key and the= certificate in the jetty.crt file into the jetty.pkcs12 file:=20 =20
If you have a chain of certificates, because your CA is an intermediary,= build the pkcs12 file like this:=20 =20
The order of certificates must be from server to rootCA, as per RFC2246 = section 7.4.2.=20
OpenSSL is going to ask you for an "export password". A non-em=
pty password seems to be required to make the next step work. The
res= ulting PKCS12 file may be loaded into a JSSE keystore with the following je= tty utility class:
This asks for two passphrases. Give the password from the last step as t= he input passphrase and you are set. The "output passphrase" will= need to appear in your jetty.xml config file as both the Password and KeyP= assword of the SunJsseListener that will use the certificate.=20
We may also use keytool (starting form jdk1.6) to import pkcs12 file wit= h the following command:=20 =20
Remember that the default port for h= ttps 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 s= ense to have a HttpListener on port 80 and a SunJsseListener on port 443. N= ote that as these are privileged ports, you may want to use a redirection m= echanism to map port 80 to eg 8080 and 443 to eg 8443. For details on this,= see the Running Jetty as a non-root user= .
The keystore file in this example is given relative to the jett= y home directory. For production, choose a private directory with restricte= d 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 t= o theft.
Jetty can now be started the normal way (make sure that jcer= t.jar, jnet.jar and jsse.jar are on your classpath) and SSL can be used wit= h a URL like:
Note: The most comm= on mistake at this point is to try to access port 8443 with http rather tha= n https.
If CONFIDENTIAL or INTEGRAL security constraints are being u= sed, then you should also configure the normal HTTP connector with which po= rt to use for SSL:
If the passwords are not provided in the configuration, they may be prov= ided as java properties (jetty.ssl.password and jetty.ssl.keypassword) else= they will be prompted for.=20
Remember that putting your password on the command line is a security ri= sk. They can also be set as properties within the config file, but this ris= ks accidental discovery by developers.=20
If jetty is given a password that begins with "OBF:" it is tre=
ated as an obfuscated password. Passwords can be obfuscated by
runnin= g org.mortbay.jetty.sec= urity.Password as a main class. This can protect passwords from casual = observation.
If you are updating your configuration to use a newer certificate, as wh= en the old one is expiring, just do St= ep 3. If you imported the key and certificate originally using the PKCS= 12 method, use an alias of "1" rather than "jetty", be= cause that is the alias the PKCS12 process enters into the keystore.