<?xml version="1.0"?>
<document xmlns="http://maven.apache.org/XDOC/2.0"
          xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:schemaLocation="http://maven.apache.org/XDOC/2.0 http://maven.apache.org/xsd/xdoc-2.0.xsd">

    <properties>
        <title>DavMail POP/IMAP/SMTP/Caldav/Carddav/LDAP Exchange Gateway - SSL setup</title>
        <author email="mguessan@free.fr">Mickael Guessant</author>
    </properties>

    <body>

        <section name="SSL setup">
            <subsection name="Server keystore (Client to DavMail)">
                <p>SSL is not necessary when DavMail is used in workstation mode, as communication between clients and
                    DavMail remain local. However, in server (shared) mode e.g. with a smartphone connecting to DavMail
                    over the internet, you should make sure encryption is enabled.
                </p>

                <p>The simplest way to secure communication between mail/calendar clients and DavMail is to create a
                    self signed certificate:
                </p>
                <source>keytool -genkey -keyalg rsa -keysize 2048 -storepass password -keystore davmail.p12 -storetype
                    pkcs12 -validity 3650 -dname cn=davmailhostname.company.com,ou=davmail,o=sf,o=net
                </source>

                <p>Note to iPhone users: iOS does not support the default DSA algorithm, make sure you use an RSA key
                    pair
                </p>

                <p>If you have an official certificate in PEM form, convert it to PKCS12 with the following command:</p>
                <source>openssl pkcs12 -export -in cert-davmail.pem -inkey privatekey-davmail.key -certfile
                    chain-davmail.pem -out davmail.p12
                </source>

                <p>Then add this keystore to DavMail settings:
                </p>
                <source><![CDATA[
davmail.ssl.keystoreType=PKCS12
davmail.ssl.keyPass=password
davmail.ssl.keystoreFile=davmail.p12
davmail.ssl.keystorePass=password]]></source>
                <p>If your already have your keystore in JKS format, just set keystoreType to JKS in DavMail
                    settings. keystorePass is the password used to open the KeyStore, keyPass protects the private key
                    inside the KeyStore. With PKCS12, keyPass and keystorePass are often identical.
                </p>
                <p>Restart DavMail, all DavMail listeners will switch to secure mode: POP3S/IMAPS/SMTPS/HTTPS/LDAPS.
                    You will also need to enable SSL in client applications and manually accept the certificate as it's
                    not signed by a trusted Certification Authority.
                </p>
            </subsection>

            <subsection name="DavMail to Exchange">
                <p>In most cases, using https in OWA url is enough to secure communication between DavMail and Exchange.
                    However, with Exchange servers setup to require mutual authentication, you will have to register
                    client certificate in DavMail settings, either through PKCS11 (smartcard) or file certificate:
                </p>
                <source><![CDATA[
davmail.ssl.clientKeystoreType=PKCS12
davmail.ssl.clientKeystoreFile=client.p12
davmail.ssl.clientKeystorePass=password]]></source>
            </subsection>
        </section>
    </body>
</document>