Message-ID: <90416475.299530.1368996188485.JavaMail.email@example.com> Subject: Exported From Confluence MIME-Version: 1.0 Content-Type: multipart/related; boundary="----=_Part_299529_491676533.1368996188485" ------=_Part_299529_491676533.1368996188485 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).
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 publi= c/private key pair and x509 certificate.
Step 2: Optionally obtain a certif= icate from a known certificate authority.
Step 3: Load the keys and the cert= ificates into a JSSE Keystore.
Step 4: Configure a JsseListener w= ith the location and passwords 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.
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 = generate manipulate keys and certificates. So you may already have some ke= ys and certificates created by openssl, or openssl may be more trusted than= keytool or some certificate authorities for step 2 may also prefer the for= mats 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
generate your private key and certificate with openSSL. The Java keytool d= oes not provide options for exporting private keys, and Apache
needs the private key. If you create the key and certificate with openSSL y= our non-Java web server will have ready access to it.
The simplest way generate keys and certificates is to use the keytool a= pplication that comes with the JDK, as it generates keys and certificates d= irectly into the keystore. See Step 1= a.
If you already have keys and certificates, please goto Step 3 to load them into a JSSE key store.
If you have a renewal certificate to replace one that is expiring, take = a look at #renewals.
The commands below only generate minimal keys and certificates. You sho= uld read the full manuals of the tools you are using if you wish to specify= :
The following command will generate a key pair and certificate directly = into a keystore:
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.
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 man=
datory response is to provide the fully qualified host name of the server a=
t the "first and last name" prompt. For example:
You now have the minimal requirements to run an SSL connection and could pr= oceed directly to Step 4 to config= ure an SSL connector.
However the certificate you have generated will not be trusted by the brows= er 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 clien= ts.
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 fi= le to help seed the random number generator.
The following command generates a certificate for the key into the file jet= ty.crt:
This command will prompt for information about the certificate and for pass= words to protect both the keystore and the keys within it. The only mandat= ory response is to provide the fully qualified host name of the server at t= he "Common Name" prompt. For example:
You now have the minimal requirements to run an SSL connection and could pr= oceed directly to Step 3 to load t= hese 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 pu= blic site will need to Step 2b to= obtain a certificate trusted by most popular clients.
If you have keys and certificates from other sources, then you can proce= ed directly to Step 3.
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, yo= u need to request a well known certificate authority (CA) to sign your key/= certificate. Such trusted CAs include: AddTrust, Entrust, GeoTrust, RSA Da= ta 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).
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 n= ot a certificate in jetty.crt generated by step 1b. The details for the cer= tificate 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 keystore. If you did not use keytool to generate the key, then it w= ill also need to be loaded into the keystore.
|Combined Private Key and Certificate|
You need both the private key and the certificate in the keystore. So th= e 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 1= b), then you will need to use the PKCS12 format to load both key and certif= icate as in step 3b.
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 =
The following command will load a PEM encoded certificate in the jetty.crt = file into a JSSE keystore:
Depending on the situation you may not require the
-trustcacerts option. Try the operation without it if you like.
If the certificate your receive from the CA is not in a format that keytool= understands, then the openssl command can be used to 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.
The following openssl command will combine the keys in jetty.key and the= certificate in the jetty.crt file into the jetty.pkcs12 file:
If you have a chain of certificates, because your CA is an intermediary,= build the pkcs12 file like this:
The order of certificates must be from server to rootCA, as per RFC2246 = section 7.4.2.
OpenSSL is going to ask you for an "export password". A non-e=
mpty password seems to be required to make the next step work. The
resulting PKCS12 file may be loaded into a JSSE keystore with the following= jetty utility class:
This asks for two passphrases. Give the password from the last step as = the input passphrase and you are set. The "output passphrase" wi= ll need to appear in your jetty.xml config file as both the Password and Ke= yPassword of the SunJsseListener that will use the certificate.
We may also use keytool (starting form jdk1.6) to import pkcs12 file wit= h the following command:
Remember that the default port for https is 443 not 80, so change 8443 to 4= 43 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 Running Jetty as a non-root user.
The keystore file in this example is given relative to the jetty home direc= tory. For production, choose a private directory with restricted access to = keep your keystore in. Even though it has a password on it, the password ma= y 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:= p>
Note: The most com= mon mistake at this point is to try to access port 8443 with http rather th= an https.
If CONFIDENTIAL or INTEGRAL security constraints are being used, then you s= hould also configure the normal HTTP connector with which port to use for S= SL:
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.
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.
If jetty is given a password that begins with "OBF:" it is tre=
ated as an obfuscated password. Passwords can be obfuscated by
running org.mortbay.jet= ty.security.Password as a main class. This can protect passwords from c= asual 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 PKC= S 12 method, use an alias of "1" rather than "jetty", b= ecause that is the alias the PKCS12 process enters into the keystore.------=_Part_299529_491676533.1368996188485--