You are viewing a plain text version of this content. The canonical link for it is here.
Posted to server-dev@james.apache.org by er...@apache.org on 2011/05/23 17:10:22 UTC
svn commit: r1126530 - /james/server/trunk/src/site/xdoc/config-ssl-tls.xml
Author: eric
Date: Mon May 23 15:10:22 2011
New Revision: 1126530
URL: http://svn.apache.org/viewvc?rev=1126530&view=rev
Log:
Complete SSL / TLS documentation (JAMES-1219)
Modified:
james/server/trunk/src/site/xdoc/config-ssl-tls.xml
Modified: james/server/trunk/src/site/xdoc/config-ssl-tls.xml
URL: http://svn.apache.org/viewvc/james/server/trunk/src/site/xdoc/config-ssl-tls.xml?rev=1126530&r1=1126529&r2=1126530&view=diff
==============================================================================
--- james/server/trunk/src/site/xdoc/config-ssl-tls.xml (original)
+++ james/server/trunk/src/site/xdoc/config-ssl-tls.xml Mon May 23 15:10:22 2011
@@ -20,7 +20,7 @@
<document>
<properties>
- <title>TLS Configuration</title>
+ <title>SSL / TLS Configuration</title>
</properties>
<body>
@@ -35,6 +35,14 @@
<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>
<source>
@@ -46,7 +54,16 @@
</source>
<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 TLS for the service.</p>
+ use of SSL or TLS for the service.</p>
+
+ <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>
@@ -57,45 +74,43 @@
<p>To use TLS/SSL inside James you will need a certificate keystore.</p>
<p></p>
<p><b>Preparing the Certificate Keystore</b></p>
- <p>(Adapted from the Tomcat 4.1 documentation)</p>
- <p>James currently operates only on JKS 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>(Adapted from the Tomcat 4.1 documentation)</p>
+ <p>James currently operates only on JKS 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 from 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><b>Importing the Certificate</b></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><b>Importing the requested Certificate</b></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>
+ <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>
</subsection>
@@ -117,9 +132,7 @@
</section>
<section name="Simultaneous Support of SSL/TLS and non-SSL/TLS per Protocol">
-<!--
- <p>See smtp_ssl.xml in example folder.</p>
--->
+ <p>See <a href="https://svn.apache.org/repos/asf/james/server/trunk/container-spring/src/main/config/examples/smtpserver-ssl.xml">smtp_ssl.xml</a> in example folder.</p>
</section>
</body>
---------------------------------------------------------------------
To unsubscribe, e-mail: server-dev-unsubscribe@james.apache.org
For additional commands, e-mail: server-dev-help@james.apache.org