| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Configuring SSL</title><link rel="stylesheet" type="text/css" href="css/docbook.css"><meta name="generator" content="DocBook XSL-NS Stylesheets V1.76.1"><meta name="keywords" content="jetty, servlet, servlet-api, cometd, http, spdy, websocket, eclipse, maven, java, server, software"><link rel="home" href="index.html" title="Jetty : The Definitive Reference"><link rel="up" href="configuring-connectors.html" title="Chapter 6. Configuring Jetty Connectors"><link rel="prev" href="configuring-connectors.html" title="Chapter 6. Configuring Jetty Connectors"><link rel="next" href="setting-port80-access.html" title="Setting Port 80 Access for a Non-Root User"><link xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" rel="shortcut icon" href="images/favicon.ico"><script type="text/javascript" src="js/shCore.js"></script><script type="text/javascript" src="js/shBrushJava.js"></script><script type="text/javascript" src="js/shBrushXml.js"></script><script type="text/javascript" src="js/shBrushBash.js"></script><script type="text/javascript" src="js/shBrushJScript.js"></script><script type="text/javascript" src="js/shBrushSql.js"></script><script type="text/javascript" src="js/shBrushProperties.js"></script><script type="text/javascript" src="js/shBrushPlain.js"></script><link type="text/css" rel="stylesheet" href="css/shCore.css"><link type="text/css" rel="stylesheet" href="css/shThemeEclipse.css"><link type="text/css" rel="stylesheet" href="css/font-awesome.min.css"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><table xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><tr><td style="width: 25%"><a href="http://www.eclipse.org/jetty"><img src="images/jetty-header-logo.png" alt="Jetty Logo"></a><br><span style="font-size: small"> |
| Version: 9.2.21.v20170120</span></td><td style="width: 50%"><script type="text/javascript"> (function() { |
| var cx = '016459005284625897022:obd4lsai2ds'; |
| var gcse = document.createElement('script'); |
| gcse.type = 'text/javascript'; |
| gcse.async = true; |
| gcse.src = (document.location.protocol == 'https:' ? 'https:' : 'http:') + |
| '//www.google.com/cse/cse.js?cx=' + cx; |
| var s = document.getElementsByTagName('script')[0]; |
| s.parentNode.insertBefore(gcse, s); |
| })(); |
| </script><gcse:search></gcse:search></td></tr></table><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="navheader"><table width="100%" summary="Navigation header"><tr><th colspan="3" align="center">Configuring SSL</th></tr><tr><td width="20%" align="left"><a accesskey="p" href="configuring-connectors.html"><i class="icon-chevron-left"></i> Previous</a> </td><th width="60%" align="center">Chapter 6. Configuring Jetty Connectors<br><a accesskey="p" href="index.html"><i class="icon-home"></i> Home</a></th><td width="20%" align="right"> <a accesskey="n" href="setting-port80-access.html">Next <i class="icon-chevron-right"></i></a></td></tr></table><hr></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="jetty-callout"><h5 class="callout"><a href="http://www.webtide.com/">Contact the core Jetty developers at |
| <span class="website">www.webtide.com</span></a></h5><p> |
| private support for your internal/customer projects ... custom extensions and distributions ... versioned snapshots for indefinite support ... |
| scalability guidance for your apps and Ajax/Comet projects ... development services from 1 day to full product delivery |
| </p></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuring-ssl"></a>Configuring SSL</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="configuring-ssl.html#understanding-certificates-and-keys">Understanding Certificates and Keys</a></span></dt></dl></div><p>This document provides an overview of how to configure SSL (also known as TLS) |
| for Jetty.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="understanding-certificates-and-keys"></a>Understanding Certificates and Keys</h3></div></div></div><p>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:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>Certificates: </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><a class="link" href="http://en.tldp.org/HOWTO/SSL Certificates HOWTO" target="_top">SSL |
| Certificates HOWTO</a></p></li><li class="listitem"><p><a class="link" href="http://mindprod.com/jgloss/certificate.html" target="_top">Mindprod |
| Java Glossary: Certificates</a></p></li></ul></div></li><li class="listitem"><p>Keytool: </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><a class="link" href="http://docs.oracle.com/javase/7/docs/technotes/tools/solaris/keytool.html" target="_top">Keytool |
| for Unix</a></p></li><li class="listitem"><p><a class="link" href="http://docs.oracle.com/javase/7/docs/technotes/tools/windows/keytool.html" target="_top">Keytool |
| for Windows</a></p></li></ul></div></li><li class="listitem"><p>Other tools: </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><a class="link" href="https://www.ibm.com/developerworks/mydeveloperworks/groups/service/html/communityview?communityUuid=6fb00498-f6ea-4f65-bf0c-adc5bd0c5fcc" target="_top">IBM |
| Keyman</a></p></li></ul></div></li><li class="listitem"><p>OpenSSL: </p><div class="itemizedlist"><ul class="itemizedlist" type="circle"><li class="listitem"><p><a class="link" href="http://www.openssl.org/docs/HOWTO/" target="_top">OpenSSL |
| HOWTO</a></p></li><li class="listitem"><p><a class="link" href="http://www.openssl.org/support/faq.html" target="_top">OpenSSL |
| FAQ</a></p></li></ul></div></li></ul></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="openssl-vs-keytool"></a>OpenSSL vs. Keytool</h4></div></div></div><p>For testing, the <code class="code">keytool</code> utility bundled with the JDK provides the simplest way to |
| generate the key and certificate you need.</p><p>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, or |
| you might also prefer the formats OpenSSL produces.</p><p>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.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="configuring-jetty-for-ssl"></a>Configuring Jetty for SSL</h4></div></div></div><p>To configure Jetty for SSL, complete the tasks in the following |
| sections:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p><a class="xref" href="configuring-ssl.html#generating-key-pairs-and-certificates" title="Generating Key Pairs and Certificates">Generating Key Pairs and Certificates</a></p></li><li class="listitem"><p><a class="xref" href="configuring-ssl.html#requesting-trusted-certificate" title="Requesting a Trusted Certificate">Requesting a Trusted Certificate</a></p></li><li class="listitem"><p><a class="xref" href="configuring-ssl.html#loading-keys-and-certificates" title="Loading Keys and Certificates">Loading Keys and Certificates</a></p></li><li class="listitem"><p><a class="xref" href="configuring-ssl.html#configuring-sslcontextfactory" title="Configuring SslContextFactory">Configuring SslContextFactory</a></p></li></ul></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="generating-key-pairs-and-certificates"></a>Generating Key Pairs and Certificates</h4></div></div></div><p>The simplest way to generate keys and certificates is to use the |
| <code class="code">keytool</code> application that comes with the JDK, as it generates keys and |
| certificates directly into the keystore. See <a class="xref" href="configuring-ssl.html#generating-key-pairs-and-certificates-JDK-keytool" title="Generating Keys and Certificates with JDK's keytool">Generating Keys and Certificates with JDK's keytool</a>.</p><p>If you already have keys and certificates, see <a class="xref" href="configuring-ssl.html#loading-keys-and-certificates" title="Loading Keys and Certificates">Loading Keys and Certificates</a> to load them into a JSSE keystore. |
| This section also applies if you have a renewal certificate to |
| replace one that is expiring.</p><p>The examples below generate only basic keys and certificates. You |
| should read the full manuals of the tools you are using if you want to |
| specify:</p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"><p>the key size</p></li><li class="listitem"><p>the certificate expiration date</p></li><li class="listitem"><p>alternate security providers</p></li></ul></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="generating-key-pairs-and-certificates-JDK-keytool"></a>Generating Keys and Certificates with JDK's keytool</h5></div></div></div><p>The following command generates a key pair and certificate |
| directly into file <code class="filename">keystore</code>:</p><div class="screenexample"><pre class="screen">$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA</pre></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="icon-asterisk"></i> Note</h3><p>The DSA key algorithm certificate produces an error after |
| loading several pages. In a browser, it displays a 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.</p></div><p>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:</p><div class="screenexample"><pre class="screen">$ 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): |
| $</pre></div><p>You now have the minimal requirements to run an SSL connection |
| and could proceed directly to <a class="link" href="configuring-ssl.html#configuring-sslcontextfactory" title="Configuring SslContextFactory">configure an SSL |
| connector</a>. However the browser will not trust the certificate |
| you have generated, and prompts the user to this effect. While what |
| you have at this point is often sufficient for testing, most public |
| sites need a trusted certificate, as shown in the section <a class="link" href="configuring-ssl.html#generating-csr-from-keytool" title="Generating a CSR with keytool">generating a CSR with |
| keytool</a>.</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="generating-keys-and-certificates-openssl"></a>Generating Keys and Certificates with OpenSSL</h5></div></div></div><p>The following command generates a key pair in the file |
| <code class="filename">jetty.key</code>:</p><div class="screenexample"><pre class="screen">$ openssl genrsa -des3 -out jetty.key</pre></div><p>You might also want to use the <code class="filename">-rand</code> file |
| argument to provide an arbitrary file that helps seed the random |
| number generator.</p><p>The following command generates a certificate for the key into |
| the file <code class="filename"> jetty.crt</code>:</p><div class="screenexample"><pre class="screen">$ openssl req -new -x509 -key jetty.key -out jetty.crt</pre></div><p>The next 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:</p><div class="screenexample"><pre class="screen">$ 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 to 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 is a default value, |
| If you enter '.', the field is 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 []: |
| |
| $</pre></div><p>You now have the minimal requirements to run an SSL connection |
| and could proceed directly to <a class="xref" href="configuring-ssl.html#loading-keys-and-certificates" title="Loading Keys and Certificates">Loading Keys and Certificates</a> to load these keys and |
| certificates into a JSSE keystore. However the browser will not trust |
| the certificate you have generated, and prompts the user to this |
| effect. While what you have at this point is often sufficient for |
| testing, most public sites need a trusted certificate, as shown in the |
| section, <a class="xref" href="configuring-ssl.html#generating-csr-from-openssl" title="Generating a CSR from OpenSSL">Generating a CSR from OpenSSL</a> to obtain a |
| certificate.</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="using-keys-and-certificates-from-other-sources"></a>Using Keys and Certificates from Other Sources</h5></div></div></div><p>If you have keys and certificates from other sources, you can |
| proceed directly to <a class="xref" href="configuring-ssl.html#loading-keys-and-certificates" title="Loading Keys and Certificates">Loading Keys and Certificates</a>.</p></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="requesting-trusted-certificate"></a>Requesting a Trusted Certificate</h4></div></div></div><p>The keys and certificates generated with JDK's <code class="code">keytool</code> and |
| OpenSSL are sufficient to run an SSL connector. However the browser will |
| not trust the certificate you have generated, and it will prompt the |
| user to this effect.</p><p>To obtain a certificate that most common browsers will trust, 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, and beTRUSTed, |
| among others. Each CA has its own instructions (look for JSSE or OpenSSL |
| sections), but all involve a step that generates a certificate signing |
| request (CSR).</p><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="generating-csr-from-keytool"></a>Generating a CSR with keytool</h5></div></div></div><p>The following command generates the file |
| <code class="filename">jetty.csr</code> using <code class="code">keytool</code> for a key/cert already in |
| the keystore:</p><div class="screenexample"><pre class="screen">$ keytool -certreq -alias jetty -keystore keystore -file jetty.csr</pre></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="generating-csr-from-openssl"></a>Generating a CSR from OpenSSL</h5></div></div></div><p>The following command generates the file |
| <code class="filename">jetty.csr</code> using OpenSSL for a key in the file |
| <code class="filename">jetty.key</code>:</p><div class="screenexample"><pre class="screen">$ openssl req -new -key jetty.key -out jetty.csr</pre></div><p>Notice that this command uses only the existing key from |
| <code class="filename">jetty.key</code> file, and not a certificate in |
| <code class="filename">jetty.crt</code> as generated with OpenSSL. You need to |
| enter the details for the certificate again.</p></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="loading-keys-and-certificates"></a>Loading Keys and Certificates</h4></div></div></div><p>Once a CA has sent you a certificate, or if you generated your own |
| certificate without <code class="code">keytool</code>, you need to load it into a JSSE |
| keystore.</p><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="icon-asterisk"></i> Note</h3><p>You need both the private key and the certificate in the JSSE |
| keystore. You should load the certificate into the keystore used to |
| generate the CSR with <code class="code">keytool</code>. If your key pair is not already in a keystore |
| (for example, because it has been generated with OpenSSL), you need to use the PKCS12 format to load |
| both key and certificate (see <a class="link" href="configuring-ssl.html#loading-keys-and-certificates-via-pkcks12" title="Loading Keys and Certificates via PKCS12">PKCKS12 Keys & |
| Certificates</a>).</p></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="loading-certificates-with-keytool"></a>Loading Certificates with keytool</h5></div></div></div><p>You can use <code class="code">keytool</code> to load a certificate in PEM form directly |
| into a keystore. The PEM format is a text encoding of certificates; it |
| is produced by OpenSSL, and is returned by some CAs. An example PEM |
| file is:</p><div class="screenexample"><pre class="screen">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-----</pre></div><p>The following command loads a PEM encoded certificate in the |
| <code class="filename">jetty.crt</code> file into a JSSE keystore:</p><div class="screenexample"><pre class="screen">$ keytool -keystore keystore -import -alias jetty -file jetty.crt -trustcacerts</pre></div><p>If the certificate you receive from the CA is not in a format |
| that <code class="code">keytool</code> understands, you can use the <code class="code">openssl</code> command |
| to convert formats:</p><div class="screenexample"><pre class="screen">$ openssl x509 -in jetty.der -inform DER -outform PEM -out jetty.crt</pre></div></div><div class="section"><div class="titlepage"><div><div><h5 class="title"><a name="loading-keys-and-certificates-via-pkcks12"></a>Loading Keys and Certificates via PKCS12</h5></div></div></div><p>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.</p><p>The following OpenSSL command combines the keys in |
| <code class="filename">jetty.key</code> and the certificate in the |
| <code class="filename">jetty.crt</code> file into the |
| <code class="filename">jetty.pkcs12</code> file:</p><div class="screenexample"><pre class="screen">$ openssl pkcs12 -inkey jetty.key -in jetty.crt -export -out jetty.pkcs12</pre></div><p>If you have a chain of certificates, because your CA is an |
| intermediary, build the PKCS12 file as follows:</p><div class="screenexample"><pre class="screen">$ 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</pre></div><p>The order of certificates must be from server to rootCA, as per |
| RFC2246 section 7.4.2.</p><p>OpenSSL asks for an <span class="emphasis"><em>export password</em></span>. A |
| non-empty password is required to make the next step work. |
| Then load the resulting PKCS12 file into a JSSE keystore with <code class="code">keytool</code>:</p><div class="screenexample"><pre class="screen">$ keytool -importkeystore -srckeystore jetty.pkcs12 -srcstoretype PKCS12 -destkeystore keystore</pre></div></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="configuring-sslcontextfactory"></a>Configuring SslContextFactory</h4></div></div></div><p>The generated SSL certificates held in the key store are |
| configured on Jetty by injection an instance of <a class="link" href="http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/util/ssl/SslContextFactory.html" target="_top"> |
| SslContextFactory</a> object and passing it to the connector's |
| SslConnectionFactory, which is done in the jetty distribution by both in |
| <a class="link" href="http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/plain/jetty-server/src/main/config/etc/jetty-https.xml" target="_top">jetty-https.xml</a> |
| and <a class="link" href="http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/plain/jetty-spdy/spdy-example-webapp/src/main/config/etc/jetty-spdy.xml" target="_top">jetty-spdy.xml</a>. |
| Since SPDY is able to handle HTTPS also, typically you will configure |
| jetty to use one of these configuration files or the other, which can be |
| done other on the command line or by editing the start.ini file.</p><p>These configuration files create an SslContextFactory instance |
| with the ID "sslContextFactory":</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false"> |
| <![CDATA[<New id="sslContextFactory" class="org.eclipse.jetty.util.ssl.SslContextFactory"> |
| <Set name="KeyStorePath"><Property name="jetty.home" default="." />/etc/keystore</Set> |
| <Set name="KeyStorePassword">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set> |
| <Set name="KeyManagerPassword">OBF:1u2u1wml1z7s1z7a1wnl1u2g</Set> |
| <Set name="TrustStorePath"><Property name="jetty.home" default="." />/etc/keystore</Set> |
| <Set name="TrustStorePassword">OBF:1vny1zlo1x8e1vnw1vn61x8g1zlu1vn4</Set> |
| </New>]]> |
| </script></div><p>This example uses the keystore distributed with jetty. To use your |
| own keystore you need to update at least the following settings:</p><div class="variablelist"><dl><dt><span class="term">KeyStorePath</span></dt><dd><p>You can either replace the provided keystore with your own, |
| or change the configuration to point to a different file. Note |
| that as a keystore is vital security information, it can be |
| desirable to locate the file in a directory with very restricted |
| access.</p></dd><dt><span class="term">KeyStorePassword</span></dt><dd><p>The keystore password may be set here in plain text, or as |
| some protection from casual observation, it may be obfuscated |
| using the <a class="link" href="http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/util/security/Password.html" target="_top"> |
| Password</a> class.</p></dd></dl></div><p>The Truststore is used if validating client certificates and is |
| typically set to the same keystore.</p><p>The keyManagerPassword is passed as the password arg to KeyManagerFactory.init(...). If there is no |
| keymanagerpassword, then the keystorepassword is used instead. If there is no trustmanager set, then the |
| keystore is used as the trust store and the keystorepassword is used as the truststore password</p><p>There is no need to create a new instance of SslContextFactory using the xml above as one exists in jetty-ssl.xml. |
| Edit the paths and passwords in jetty-ssl.xml and ensure you add following lines to start.ini after |
| the line jetty.dump.stop=:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: plain;toolbar: false"> |
| <![CDATA[ |
| etc/jetty-ssl.xml |
| etc/jetty-https.xml]]> |
| </script></div><p>Optionally, configure the https port either in jetty-https.xml like this: |
| </p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false"> |
| <![CDATA[<Set name="port">8443</Set>]]> |
| </script></div><p> |
| or via the commandline e.g. |
| </p><div class="screenexample"><pre class="screen">$ java -jar start.jar https.port=8443</pre></div><p> |
| </p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="configuring-sslcontextfactory-cipherSuites"></a>Disabling/Enabling specific cipher suites</h4></div></div></div><p>For example to avoid the BEAST attack it is necessary to configure a specific set of cipher suites. |
| This can either be done via |
| <a class="link" href="http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/util/ssl/SslContextFactory.html#setIncludeCipherSuites(java.lang.String...)" target="_top"> |
| SslContext.setIncludeCipherSuites(java.lang.String...) |
| </a> |
| or via<a class="link" href="http://download.eclipse.org/jetty/stable-9/apidocs/org/eclipse/jetty/util/ssl/SslContextFactory.html#setExcludeCipherSuites(java.lang.String...)" target="_top"> |
| SslContext.setExcludeCipherSuites(java.lang.String...)</a>. |
| </p><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="icon-asterisk"></i> Note</h3><p>It's crucial that you use the exact names of the cipher suites as used/known by the JDK. |
| You can get them by obtaining an instance of SSLEngine and call getSupportedCipherSuites(). |
| Tools like ssllabs.com might report slightly different names which will be ignored.</p></div><p>Both setIncludeCipherSuites and setExcludeCipherSuites can be feed by the exact cipher suite |
| name used in the jdk or by using regular expressions. |
| </p><p> |
| Here's a couple of examples on how to include only RC4 cipher suites. All of them will protect the |
| server from the <a class="link" href="https://www.google.com/search?q=beast+attack" target="_top">BEAST</a> attack. |
| </p><p>Include a preferred set of cipher suites:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false"> |
| <![CDATA[ |
| <Set name="IncludeCipherSuites"> |
| <Array type="String"> |
| <Item>TLS_RSA_WITH_RC4_128_MD5</Item> |
| <Item>TLS_RSA_WITH_RC4_128_SHA</Item> |
| <Item>TLS_ECDHE_RSA_WITH_RC4_128_SHA</Item> |
| </Array> |
| </Set> |
| ]]> |
| </script></div><p>Include all RC4 cipher suites by using a regex:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false"> |
| <![CDATA[ |
| <Set name="IncludeCipherSuites"> |
| <Array type="String"> |
| <Item>.*RC4.*</Item> |
| </Array> |
| </Set> |
| ]]> |
| </script></div><p>Exclude all non RC4 cipher suites:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false"> |
| <![CDATA[ |
| <Set name="ExcludeCipherSuites"> |
| <Array type="String"> |
| <Item>SSL_RSA_WITH_DES_CBC_SHA</Item> |
| <Item>SSL_DHE_RSA_WITH_DES_CBC_SHA</Item> |
| <Item>SSL_DHE_DSS_WITH_DES_CBC_SHA</Item> |
| <Item>SSL_RSA_EXPORT_WITH_RC4_40_MD5</Item> |
| <Item>SSL_RSA_EXPORT_WITH_DES40_CBC_SHA</Item> |
| <Item>SSL_DHE_RSA_EXPORT_WITH_DES40_CBC_SHA</Item> |
| <Item>SSL_DHE_DSS_EXPORT_WITH_DES40_CBC_SHA</Item> |
| <Item>TLS_DHE_RSA_WITH_AES_128_CBC_SHA256</Item> |
| <Item>TLS_RSA_WITH_AES_128_CBC_SHA</Item> |
| <Item>TLS_DHE_RSA_WITH_AES_128_CBC_SHA</Item> |
| <Item>TLS_RSA_WITH_AES_128_CBC_SHA256</Item> |
| <Item>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA</Item> |
| <Item>TLS_ECDHE_RSA_WITH_AES_128_CBC_SHA256</Item> |
| <Item>TLS_RSA_WITH_3DES_EDE_CBC_SHA</Item> |
| <Item>TLS_DHE_RSA_WITH_3DES_EDE_CBC_SHA</Item> |
| <Item>TLS_ECDHE_RSA_WITH_3DES_EDE_CBC_SHA</Item> |
| <Item>RSA_WITH_3DES_EDE_CBC_SHA</Item> |
| </Array> |
| </Set> |
| ]]> |
| </script></div><div xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title"><i class="icon-asterisk"></i> Note</h3><p>It is recommended to use the IncludeCipherSuites with the regex unless you've reasons you |
| need to specify specific cipher suites. This configuration will adapt to any |
| additions/removals of cipher suites to new versions of the JDK.</p></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4904"></a>Configuring SSL Connector and Port</h4></div></div></div><p>This <code class="code">SslContextFactory</code> instance created above is injected into a |
| <code class="code">SslConnectionFactory</code> instance to be used when accepting network |
| connections, which in turn is injected into an instance of |
| <code class="code">ServerConnector</code>. For example from <a class="link" href="http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/plain/jetty-server/src/main/config/etc/jetty-https.xml" target="_top">jetty-https.xml</a>:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false"> |
| <![CDATA[<Call id="sslConnector" name="addConnector"> |
| <Arg> |
| <New class="org.eclipse.jetty.server.ServerConnector"> |
| <Arg name="server"><Ref refid="Server" /></Arg> |
| <Arg name="factories"> |
| <Array type="org.eclipse.jetty.server.ConnectionFactory"> |
| <Item> |
| <New class="org.eclipse.jetty.server.SslConnectionFactory"> |
| <Arg name="next">http/1.1</Arg> |
| <Arg name="sslContextFactory"><Ref refid="sslContextFactory"/></Arg> |
| </New> |
| </Item> |
| <Item> |
| <New class="org.eclipse.jetty.server.HttpConnectionFactory"> |
| <Arg name="config"><Ref refid="tlsHttpConfig"/></Arg> |
| </New> |
| </Item> |
| </Array> |
| </Arg> |
| <Set name="host"><Property name="jetty.host" /></Set> |
| <Set name="port"><Property name="jetty.tls.port" default="8443" /></Set> |
| <Set name="idleTimeout">30000</Set> |
| </New> |
| </Arg> |
| </Call>]]> |
| </script></div><p>Note also that the SSL connector port is set directly on the |
| ServerConnector instance.</p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="renewing-certificates"></a>Renewing Certificates</h4></div></div></div><p>If you are updating your configuration to use a newer certificate, |
| as when the old one is expiring, just load the newer certificate as |
| described in the section, <a class="xref" href="configuring-ssl.html#loading-keys-and-certificates" title="Loading Keys and Certificates">Loading Keys and Certificates</a>. If you imported the key and |
| certificate originally using the PKCS12 method, use an alias of "1" |
| rather than "jetty", because that is the alias the PKCS12 process enters |
| into the keystore.</p></div></div></div><script type="text/javascript"> |
| SyntaxHighlighter.all() |
| </script><div class="navfooter"><hr><table width="100%" summary="Navigation footer"><tr><td width="40%" align="left"><a accesskey="p" href="configuring-connectors.html"><i class="icon-chevron-left"></i> Previous</a> </td><td width="20%" align="center"><a accesskey="u" href="configuring-connectors.html"><i class="icon-chevron-up"></i> Top</a></td><td width="40%" align="right"> <a accesskey="n" href="setting-port80-access.html">Next <i class="icon-chevron-right"></i></a></td></tr><tr><td width="40%" align="left" valign="top">Chapter 6. Configuring Jetty Connectors </td><td width="20%" align="center"><a accesskey="h" href="index.html"><i class="icon-home"></i> Home</a></td><td width="40%" align="right" valign="top"> Setting Port 80 Access for a Non-Root User</td></tr></table></div><p xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times"><div class="jetty-callout"> |
| See an error or something missing? |
| <span class="callout"><a href="http://github.com/jetty-project/jetty-documentation">Contribute to this documentation at |
| <span class="website"><i class="icon-github"></i> Github!</span></a></span><span style="float: right"><i>(Generated: 2015-03-13T11:47:49-05:00)</i></span></div></p><script xmlns:jfetch="java:org.eclipse.jetty.xslt.tools.JavaSourceFetchExtension" xmlns:fetch="java:org.eclipse.jetty.xslt.tools.SourceFetchExtension" xmlns:d="http://docbook.org/ns/docbook" xmlns:l="http://docbook.sourceforge.net/xmlns/l10n/1.0" xmlns:xslthl="http://xslthl.sf.net" xmlns:gcse="http://www.google.com" xmlns:date="http://exslt.org/dates-and-times" type="text/javascript"> |
| var _gaq = _gaq || []; |
| _gaq.push(['_setAccount', 'UA-1149868-7']); |
| _gaq.push(['_trackPageview']); |
| |
| (function() { |
| var ga = document.createElement('script'); ga.type = 'text/javascript'; ga.async = true; |
| ga.src = ('https:' == document.location.protocol ? 'https://ssl' : 'http://www') + '.google-analytics.com/ga.js'; |
| var s = document.getElementsByTagName('script')[0]; s.parentNode.insertBefore(ga, s); |
| })(); |
| </script></body></html> |
