| <html><head> |
| <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"> |
| <title>Configuring SSL/TLS</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, 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.3.0.v20150612</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/TLS</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/TLS</h2></div></div></div><div class="toc"><dl><dt><span class="section"><a href="configuring-ssl.html#tls-and-ssl-versions">TLS and SSL versions</a></span></dt><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 and TLS for |
| Jetty.</p><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="tls-and-ssl-versions"></a>TLS and SSL versions</h3></div></div></div><p>Which browser/OS supports which protocols can be <a class="link" href="https://en.wikipedia.org/wiki/Transport_Layer_Security#Web_browsers" target="_top">found |
| on Wikipedia</a></p><div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem"> |
| TLS v1.1 and v1.2: The protocols which should be used wherever possible. All CBC based ciphers are supported since Java 7, the new GCM modes are supported since Java 8. |
| </li><li class="listitem"> |
| TLS v1.0: still ok but affected by the POODLE attack too. To support oder browsers this protocol version is still needed. |
| </li><li class="listitem"> |
| SSL v3: is now deprecated and should only be enabled if you still need to support very old browsers like Internet Explorer 6 on Windows XP which does not support TLS 1.0 (or is disabled by default). |
| </li></ul></div></div><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/8/docs/technotes/tools/unix/keytool.html" target="_top">Keytool |
| for Unix</a></p></li><li class="listitem"><p><a class="link" href="http://docs.oracle.com/javase/8/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 -sigalg SHA256withRSA |
| 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><p>If you want to use only a self signed certificate for some kind |
| of internal admin panel add -validity <days> to the keytool call |
| above, otherwise your certificate is only valid for one month.</p><p>If you are using java 8 or later, then you may also use the SAN |
| extension to set one or more names that the certificate applies |
| to:</p><div class="screenexample"><pre class="screen">$ keytool -keystore keystore -alias jetty -genkey -keyalg RSA -sigalg SHA256withRSA -ext 'SAN=dns:jetty.eclipse.org,dns:*.jetty.org' |
| ... |
| </pre></div></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 -aes128 -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 -b2048 -sha256 -key jetty.key -out jetty.crt</pre></div><p>Adding -sha256 ensures to get a certificate with the now |
| recommended SHA-256 signature algorithm. For the paranoid ones add |
| -b4096 to get a 4069bits long key.</p><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 -aes128 -out jetty.key |
| Generating RSA private key, 2048 bit long modulus |
| ..............+++ |
| ......................................................................+++ |
| e is 65537 (0x10001) |
| Enter pass phrase for jetty.key: |
| Verifying - Enter pass phrase for jetty.key: |
| |
| $ openssl req -new -x509 -newkey rsa:2048 -sha256 -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 (e.g. server FQDN or 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 in |
| <a class="link" href="http://git.eclipse.org/c/jetty/org.eclipse.jetty.project.git/plain/jetty-server/src/main/config/etc/jetty-ssl-context.xml" target="_top">jetty-ssl-context.xml</a> |
| which configures a 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>The key and store passwords may also be set using the system |
| properties: "org.eclipse.jetty.ssl.keypassword" |
| "org.eclipse.jetty.ssl.password". This is not a recommended |
| usage.</p><p></p></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4828"></a>Configuring SNI</h4></div></div></div><p>From java8, the JVM contains support for the <a class="link" href="http://en.wikipedia.org/wiki/Server_Name_Indication" target="_top"> Server |
| Name Indicator (SNI)</a> extension, which allows a SSL connection |
| handshake to indicate one or more DNS names that it applies to. To |
| support this, the ExtendedSslContextFactory is used that will look for |
| multiple X509 certificates within the keystore, each of which may have |
| multiple DNS names (including wildcards) associated with the <a class="link" href="http://en.wikipedia.org/wiki/SubjectAltName" target="_top">Subject Alternate |
| Name</a> extension. When using the ExtendedSSlContextFactory, the |
| correct certificate is automatically selected if the SNI extension is |
| present in the handshake.</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><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 recommended to install the Java Cryptography Extension |
| (JCE) Unlimited Strength policy files in your JRE to get full strength |
| ciphers like AES-256. They can be found on the <a class="link" href="http://www.oracle.com/technetwork/java/javase/downloads/index.html" target="_top">Java |
| download page</a>. Just overwrite the two present JAR files in |
| <code class="code"><JRE_HOME>/lib/security/</code></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 an example of how to include all safe cipher suites and |
| disable old insecure ones.</p><p>Include all ciphers which support <a class="link" href="https://en.wikipedia.org/wiki/Forward_secrecy" target="_top">Forward |
| Secrecy</a> using regex:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false"> |
| <![CDATA[ |
| <Set name="IncludeCipherSuites"> |
| <Array type="String"> |
| <Item>TLS_DHE_RSA.*</Item> |
| <Item>TLS_ECDHE.*</Item> |
| </Array> |
| </Set> |
| ]]> |
| </script></div><p>Exclude all old, insecure or anonymous cipher suites:</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false"> |
| <![CDATA[ |
| <Set name="ExcludeCipherSuites"> |
| <Array type="String"> |
| <Item>.*NULL.*</Item> |
| <Item>.*RC4.*</Item> |
| <Item>.*MD5.*</Item> |
| <Item>.*DES.*</Item> |
| <Item>.*DSS.*</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><p>Since 2014 SSLv3 is considered insecure and should be |
| disabled.</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false"> |
| <![CDATA[ |
| <Set name="ExcludeProtocols"> |
| <Array type="java.lang.String"> |
| <Item>SSLv3</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>Note that disabling SSLv3 prevents very old browsers like |
| Internet Explorer 6 on Windows XP from connecting.</p></div><p>TLS renegotiation should be disabled too to prevent an attack |
| based on this feature.</p><div class="informalexample"><script type="syntaxhighlighter" class="brush: xml;toolbar: false"> |
| <![CDATA[ |
| <Set name="renegotiationAllowed">FALSE</Set> |
| |
| ]]> |
| </script></div></div><div class="section"><div class="titlepage"><div><div><h4 class="title"><a name="d0e4894"></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.ssl.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-06-15T13:18:16-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> |
