| <?xml version="1.0" encoding="UTF-8"?> |
| <!-- |
| Licensed to the Apache Software Foundation (ASF) under one |
| or more contributor license agreements. See the NOTICE file |
| distributed with this work for additional information |
| regarding copyright ownership. The ASF licenses this file |
| to you under the Apache License, Version 2.0 (the |
| "License"); you may not use this file except in compliance |
| with the License. You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, |
| software distributed under the License is distributed on an |
| "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY |
| KIND, either express or implied. See the License for the |
| specific language governing permissions and limitations |
| under the License. |
| --> |
| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <!-- Generated by Apache Maven Doxia at 2021-09-26 --> |
| <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" /> |
| <title>Apache James Project – Apache James Server 3 - SSL / TLS Configuration</title> |
| <style type="text/css" media="all"> |
| @import url("../css/james.css"); |
| @import url("../css/maven-base.css"); |
| @import url("../css/maven-theme.css"); |
| @import url("../css/site.css"); |
| @import url("../js/jquery/css/custom-theme/jquery-ui-1.8.5.custom.css"); |
| @import url("../js/jquery/css/print.css"); |
| @import url("../js/fancybox/jquery.fancybox-1.3.4.css"); |
| </style> |
| <script type="text/javascript" src="../js/jquery/js/jquery-1.4.2.min.js"></script> |
| <script type="text/javascript" src="../js/jquery/js/jquery-ui-1.8.5.custom.min.js"></script> |
| <script type="text/javascript" src="../js/fancybox/jquery.fancybox-1.3.4.js"></script> |
| <link rel="stylesheet" href="../css/print.css" type="text/css" media="print" /> |
| <meta name="Date-Revision-yyyymmdd" content="20210926" /> |
| <meta http-equiv="Content-Language" content="en" /> |
| |
| <!-- Google Analytics --> |
| <script type="text/javascript"> |
| |
| var _gaq = _gaq || []; |
| _gaq.push(['_setAccount', 'UA-1384591-1']); |
| _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').item(0); s.parentNode.insertBefore(ga, s); |
| })(); |
| |
| </script> |
| </head> |
| <body class="composite"> |
| <div id="banner"> |
| <a href="../index.html" id="bannerLeft" title="james-logo.png"> |
| |
| |
| <img src="../images/logos/james-logo.png" alt="James Project" /> |
| </a> |
| <a href="https://www.apache.org/index.html" id="bannerRight"> |
| |
| |
| <img src="images/logos/asf_logo_small.png" alt="The Apache Software Foundation" /> |
| </a> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="breadcrumbs"> |
| |
| |
| <div class="xleft"> |
| <span id="publishDate">Last Published: 2021-09-26</span> |
| </div> |
| <div class="xright"> <a href="../index.html" title="Home">Home</a> |
| | |
| <a href="../documentation.html" title="James">James</a> |
| | |
| <a href="../mime4j/index.html" title="Mime4J">Mime4J</a> |
| | |
| <a href="../jsieve/index.html" title="jSieve">jSieve</a> |
| | |
| <a href="../jspf/index.html" title="jSPF">jSPF</a> |
| | |
| <a href="../jdkim/index.html" title="jDKIM">jDKIM</a> |
| |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| <div id="leftColumn"> |
| <div id="navcolumn"> |
| |
| |
| <h5>James components</h5> |
| <ul> |
| <li class="collapsed"> |
| <a href="../documentation.html" title="About James">About James</a> |
| </li> |
| <li class="expanded"> |
| <a href="../server/index.html" title="Server">Server</a> |
| <ul> |
| <li class="none"> |
| <a href="../server/advantages.html" title="Advantages">Advantages</a> |
| </li> |
| <li class="none"> |
| <a href="../server/objectives.html" title="Objectives">Objectives</a> |
| </li> |
| <li class="expanded"> |
| <a href="../server/quick-start.html" title="User Manual">User Manual</a> |
| <ul> |
| <li class="collapsed"> |
| <a href="../server/features.html" title="1. Features">1. Features</a> |
| </li> |
| <li class="none"> |
| <a href="../server/packaging.html" title="2. Packaging">2. Packaging</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../server/install.html" title="3. Install James">3. Install James</a> |
| </li> |
| <li class="expanded"> |
| <a href="../server/config.html" title="4. Configure James">4. Configure James</a> |
| <ul> |
| <li class="none"> |
| <a href="../server/config-listeners.html" title="Additional mailbox listeners">Additional mailbox listeners</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-antispam.html" title="Anti Spam">Anti Spam</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-blob-export.html" title="Blob Export">Blob Export</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-blobstore.html" title="BlobStore">BlobStore</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-cassandra.html" title="Cassandra">Cassandra</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-elasticsearch.html" title="ElasticSearch">ElasticSearch</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-vault.html" title="Deleted Messages Vault">Deleted Messages Vault</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-dnsservice.html" title="DNS Service">DNS Service</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-domainlist.html" title="Domain List">Domain List</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-fetchmail.html" title="FetchMail">FetchMail</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-guice.html" title="Guice">Guice</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-imap4.html" title="IMAP4">IMAP4</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-jmap.html" title="JMAP">JMAP</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-mailrepositorystore.html" title="Mail Repository Stores">Mail Repository Stores</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-mailbox.html" title="Mailbox">Mailbox</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-mailetcontainer.html" title="Mailet Container">Mailet Container</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-healthcheck.html" title="Periodical Health Checks">Periodical Health Checks</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-pop3.html" title="POP3">POP3</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-quota.html" title="Quota">Quota</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-rabbitmq.html" title="RabbitMQ">RabbitMQ</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-recipientrewritetable.html" title="Recipient Rewrite">Recipient Rewrite</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-smtp-lmtp.html" title="SMTP LMTP">SMTP LMTP</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-sieve.html" title="Sieve">Sieve</a> |
| </li> |
| <li class="none"> |
| <strong>SSL/TLS</strong> |
| </li> |
| <li class="none"> |
| <a href="../server/config-system.html" title="System">System</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-spring-jpa-postgres.html" title="Spring JPA Postgres">Spring JPA Postgres</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-users.html" title="Users">Users</a> |
| </li> |
| <li class="none"> |
| <a href="../server/config-webadmin.html" title="WebAdmin">WebAdmin</a> |
| </li> |
| </ul> |
| </li> |
| <li class="collapsed"> |
| <a href="../server/manage.html" title="5. Manage">5. Manage</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../server/monitor.html" title="6. Monitor">6. Monitor</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../server/upgrade.html" title="7. Upgrade">7. Upgrade</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../server/dev.html" title="8. Developers Corner">8. Developers Corner</a> |
| </li> |
| </ul> |
| </li> |
| <li class="none"> |
| <a href="../mail.html#James_Mailing_lists" title="Mailing Lists">Mailing Lists</a> |
| </li> |
| <li class="none"> |
| <a href="../server/release-notes.html" title="Release Notes">Release Notes</a> |
| </li> |
| <li class="none"> |
| <a href="../server/apidocs/index.html" title="Javadoc">Javadoc</a> |
| </li> |
| <li class="none"> |
| <a href="https://issues.apache.org/jira/browse/JAMES" title="Issue Tracker">Issue Tracker</a> |
| </li> |
| <li class="none"> |
| <a href="https://github.com/apache/james-project" title="Sources">Sources</a> |
| </li> |
| <li class="none"> |
| <a href="../server/rfcs.html" title="RFCs">RFCs</a> |
| </li> |
| <li class="none"> |
| <a href="../download.cgi#Apache_James_Server" title="Download releases">Download releases</a> |
| </li> |
| </ul> |
| </li> |
| <li class="collapsed"> |
| <a href="../mailet/index.html" title="Mailets">Mailets</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../mailbox/index.html" title="Mailbox">Mailbox</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../protocols/index.html" title="Protocols">Protocols</a> |
| </li> |
| <li class="collapsed"> |
| <a href="../mpt/index.html" title="MPT">MPT</a> |
| </li> |
| </ul> |
| <h5>Apache Software Foundation</h5> |
| <ul> |
| <li> |
| <strong> |
| <a title="ASF" href="http://www.apache.org/">ASF</a> |
| </strong> |
| </li> |
| <li> |
| <a title="Get Involved" href="http://www.apache.org/foundation/getinvolved.html">Get Involved</a> |
| </li> |
| <li> |
| <a title="FAQ" href="http://www.apache.org/foundation/faq.html">FAQ</a> |
| </li> |
| <li> |
| <a title="License" href="http://www.apache.org/licenses/" >License</a> |
| </li> |
| <li> |
| <a title="Sponsorship" href="http://www.apache.org/foundation/sponsorship.html">Sponsorship</a> |
| </li> |
| <li> |
| <a title="Thanks" href="http://www.apache.org/foundation/thanks.html">Thanks</a> |
| </li> |
| <li> |
| <a title="Security" href="http://www.apache.org/security/">Security</a> |
| </li> |
| </ul> |
| <a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> |
| <img class="poweredBy" alt="Built by Maven" src="../images/logos/maven-feather.png" /> |
| </a> |
| |
| |
| </div> |
| </div> |
| <div id="bodyColumn"> |
| <div id="contentBox"> |
| |
| |
| |
| |
| <section> |
| <h2><a name="SSL_.2F_TLS_Configuration"></a>SSL / TLS Configuration</h2> |
| |
| |
| <p>This document explains how to enable James 3.0 servers to use Transport Layer Security (TLS) for encrypted client-server communication.</p> |
| |
| <section> |
| <h3><a name="Configure_a_Server_to_Use_SSL.2FTLS"></a>Configure a Server to Use SSL/TLS</h3> |
| |
| |
| <p>Each of the servers <a href="config-smtp-lmtp.html">SMTP</a>, |
| <a href="config-pop3.html">POP3</a> and <a href="config-imap.html">IMAP</a> |
| supports use of SSL/TLS.</p> |
| |
| |
| <p>TLS (Transport Layer Security) and SSL (Secure Sockets Layer) are protocols that provide |
| data encryption and authentication between applications in scenarios where that data is |
| being sent across an insecure network, such as checking your email |
| (How does the Secure Socket Layer work?). The terms SSL and TLS are often used |
| interchangeably or in conjunction with each other (TLS/SSL), |
| but one is in fact the predecessor of the other — SSL 3.0 served as the basis |
| for TLS 1.0 which, as a result, is sometimes referred to as SSL 3.1.</p> |
| |
| |
| <p>You need to add a block in the corresponding configuration file (smtpserver.xml, pop3server.xml, imapserver.xml,..)</p> |
| |
| |
| <div class="source"> |
| <pre> |
| <tls socketTLS="false" startTLS="false"> |
| <keystore>file://conf/keystore</keystore> |
| <keystoreType>PKSC12</keystoreType> |
| <secret>yoursecret</secret> |
| <provider>org.bouncycastle.jce.provider.BouncyCastleProvider</provider> |
| </tls> |
| </pre></div> |
| |
| |
| <p>Alternatively TLS keys can be supplied via PEM files:</p> |
| |
| |
| <div class="source"> |
| <pre> |
| <tls socketTLS="false" startTLS="false"> |
| <privateKey>file://conf/private.key</privateKey> |
| <certificates>file://conf/certs.self-signed.csr</certificates> |
| </tls> |
| </pre></div> |
| |
| |
| <p>An optional secret might be specified for the private key:</p> |
| |
| |
| <div class="source"> |
| <pre> |
| <tls socketTLS="false" startTLS="false"> |
| <privateKey>file://conf/private.key</privateKey> |
| <certificates>file://conf/certs.self-signed.csr</certificates> |
| <secret>yoursecret</secret> |
| </tls> |
| </pre></div> |
| |
| |
| <p>Each of these block has an optional boolean configuration element <b>socketTLS</b> and <b>startTLS</b> which is used to toggle |
| use of SSL or TLS for the service.</p> |
| |
| |
| <p>With socketTLS (SSL/TLS in Thunderbird), all the communication is encrypted.</p> |
| |
| |
| <p>With startTLS (STARTTLS in Thunderbird), the preamble is readable, but the rest is encrypted.</p> |
| |
| |
| * OK JAMES IMAP4rev1 Server Server 192.168.1.4 is ready. |
| * CAPABILITY IMAP4rev1 LITERAL+ CHILDREN WITHIN STARTTLS IDLE NAMESPACE UIDPLUS UNSELECT AUTH=PLAIN |
| 1 OK CAPABILITY completed. |
| 2 OK STARTTLS Begin TLS negotiation now. |
| ... rest is encrypted... |
| |
| |
| |
| <p>You can only enable one of the both at the same time for a service.</p> |
| |
| |
| <p>It is also recommended to change the port number on which the service will listen:</p> |
| |
| <ul> |
| |
| <li>POP3 - port 110, Secure POP3 - port 995</li> |
| |
| <li>IMAP - port 143, Secure IMAP4 - port 993</li> |
| |
| <li>SMTP - port 25, Secure SMTP - port 465</li> |
| </ul> |
| |
| |
| <p>You will now need to create your certificate store and place it in the james/conf/ folder with the name you defined in the keystore tag.</p> |
| |
| |
| <p>Please note JKS keystore format is also supported (default value if no keystore type is specified):</p> |
| |
| <div class="source"> |
| <pre> |
| <tls socketTLS="false" startTLS="false"> |
| <keystore>file://conf/keystore</keystore> |
| <keystoreType>JKS</keystoreType> |
| <secret>yoursecret</secret> |
| <provider>org.bouncycastle.jce.provider.BouncyCastleProvider</provider> |
| </tls> |
| </pre></div> |
| |
| </section> |
| |
| <section> |
| <h3><a name="Creating_your_own_PEM_keys"></a>Creating your own PEM keys</h3> |
| |
| <p>The following commands can be used to create self signed PEM keys:</p> |
| |
| |
| <div class="source"> |
| <pre> |
| # Generating your private key |
| openssl genrsa -des3 -out private.key 2048 |
| |
| # Creating your certificates |
| openssl req -new -key private.key -out certs.csr |
| |
| # Signing the certificate yourself |
| openssl x509 -req -days 365 -in certs.csr -signkey private.key -out certs.self-signed.csr |
| |
| # Removing the password from the private key |
| # Not necessary if you supply the secret in the configuration |
| openssl rsa -in private.key -out private.nopass.key |
| </pre></div> |
| |
| |
| <p>You may then supply this TLS configuration:</p> |
| |
| |
| <div class="source"> |
| <pre> |
| <tls socketTLS="false" startTLS="false"> |
| <privateKey>file://conf/private.key</privateKey> |
| <certificates>file://conf/certs.self-signed.csr</certificates> |
| </tls> |
| </pre></div> |
| </section> |
| |
| <section> |
| <h3><a name="Certificate_Keystores"></a>Certificate Keystores</h3> |
| |
| |
| <p>This section gives more indication for users relying on keystores.</p> |
| |
| <p></p> |
| |
| |
| <p><b>Creating your own Certificate Keystore</b></p> |
| |
| <p>(Adapted from the Tomcat 4.1 documentation)</p> |
| |
| <p>James currently operates only on JKS and PKCS12 format keystores. This is Java's standard "Java KeyStore" format, and is the format created by the keytool command-line utility. This tool is included in the JDK.</p> |
| |
| <p>To import an existing certificate into a JKS keystore, please read the documentation (in your JDK documentation package) about keytool.</p> |
| |
| <p>To create a new keystore from scratch, containing a single self-signed Certificate, execute the following from a terminal command line:</p> |
| |
| <p>keytool -genkey -alias james -keyalg RSA -keystore your_keystore_filename</p> |
| |
| <p>(The RSA algorithm should be preferred as a secure algorithm, and this also ensures general compatibility with other servers and components.)</p> |
| |
| <p>As a suggested standard, create the keystore in the james/conf directory, with a name like james.keystore.</p> |
| |
| <p>After executing this command, you will first be prompted for the keystore password.</p> |
| |
| <p>Next, you will be prompted for general information about this Certificate, such as company, contact name, and so on. This information may be displayed to users when importing into the certificate store of the client, so make sure that the information provided here matches what they will expect.</p> |
| |
| <p>Important: in the "distinguished name", set the "common name" (CN) to the DNS name of your James server, the one you will use to access it from your mail client (like "mail.xyz.com").</p> |
| |
| <p>Finally, you will be prompted for the key password, which is the password specifically for this Certificate (as opposed to any other Certificates stored in the same keystore file).</p> |
| |
| <p>If everything was successful, you now have a keystore file with a Certificate that can be used by your server.</p> |
| |
| <p>You MUST have only one certificate in the keystore file used by James.</p> |
| |
| <p></p> |
| |
| |
| <p><b>Installing a Certificate provided by a Certificate Authority</b></p> |
| |
| <p>(Adapted from the Tomcat 4.1 documentation</p> |
| |
| <p>To obtain and install a Certificate from a Certificate Authority (like verisign.com, thawte.com or trustcenter.de) you should have read the previous section and then follow these instructions:</p> |
| |
| <p>Create a local Certificate Signing Request (CSR)</p> |
| |
| <p>In order to obtain a Certificate from the Certificate Authority of your choice you have to create a so called Certificate Signing Request (CSR). That CSR will be used by the Certificate Authority to create a Certificate that will identify your James server as "secure". To create a CSR follow these steps:</p> |
| |
| <p>Create a local Certificate as described in the previous section.</p> |
| |
| <p>The CSR is then created with:</p> |
| |
| <p>keytool -certreq -keyalg RSA -alias james -file certreq.csr -keystore your_keystore_filename</p> |
| |
| <p>Now you have a file called certreq.csr. The file is encoded in PEM format. You can submit it to the Certificate Authority (look at the documentation of the Certificate Authority website on how to do this). In return you get a Certificate.</p> |
| |
| <p></p> |
| |
| <p>Now that you have your Certificate you can import it into you local keystore. First of all you may have to import a so called Chain Certificate or Root Certificate into your keystore (the major Certificate Authorities are already in place, so it's unlikely that you will need to perform this step). After that you can procede with importing your Certificate.</p> |
| |
| <p>Optionally Importing a so called Chain Certificate or Root Certificate</p> |
| |
| <p>Download a Chain Certificate from the Certificate Authority you obtained the Certificate from.</p> |
| |
| <p>For Verisign.com go to: http://www.verisign.com/support/install/intermediate.html</p> |
| |
| <p>For Trustcenter.de go to: http://www.trustcenter.de/certservices/cacerts/en/en.htm#server</p> |
| |
| <p>For Thawte.com go to: http://www.thawte.com/certs/trustmap.html (seems no longer valid)</p> |
| |
| <p>Import the Chain Certificate into you keystore</p> |
| |
| <p>keytool -import -alias root -keystore your_keystore_filename -trustcacerts -file filename_of_the_chain_certificate</p> |
| |
| <p></p> |
| |
| <p>And finally import your new Certificate (It must be in X509 format):</p> |
| |
| <p>keytool -import -alias james -keystore your_keystore_filename -trustcacerts -file your_certificate_filename</p> |
| |
| <p></p> |
| |
| <p>See also: http://www.agentbob.info/agentbob/79.html</p> |
| |
| </section> |
| |
| <section> |
| <h3><a name="Verifying_a_SSL.2FTLS-enabled_James_Server"></a>Verifying a SSL/TLS-enabled James Server</h3> |
| |
| |
| <p>After you've configured a particular server to use TLS/SSL connections, the server port |
| should no longer accept unencrypted TCP/IP connections. This can be tested by using a telnet |
| client to directly connect to the server port. The telnet connection should simply hang until |
| the client times out.</p> |
| |
| |
| <p>To validate that the port is properly accepting SSL connections an SSL client can be used to |
| open a connection to the server port. One such client is OpenSSL, available from the |
| <a class="externalLink" href="http://www.openssl.org">OpenSSL web site</a>. Follow the instructions provided with |
| the SSL client to create a connection to the server port. Upon connection, the usual |
| server greeting should appear.</p> |
| |
| |
| <div class="source"> |
| <pre> |
| /usr/bin/openssl s_client -quiet -connect localhost:465 |
| depth=0 /C=Unknown/ST=Unknown/L=Unknown/O=Unknown/OU=Unknown/CN=Unknown |
| verify error:num=18:self signed certificate |
| verify return:1 |
| depth=0 /C=Unknown/ST=Unknown/L=Unknown/O=Unknown/OU=Unknown/CN=Unknown |
| verify return:1 |
| 220 192.168.0.208 SMTP Server (JAMES SMTP Server) ready Thu, 9 Jun |
| 2011 20:31:07 +0200 (CEST) |
| </pre></div> |
| |
| </section> |
| |
| </section> |
| |
| |
| |
| |
| </div> |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| <div id="footer"> |
| <div class="xright">Copyright © 2006-2021 |
| <a href="https://www.apache.org/">The Apache Software Foundation</a>. |
| All Rights Reserved. |
| |
| </div> |
| <div class="clear"> |
| <hr/> |
| </div> |
| </div> |
| </body> |
| </html> |
