310 lines
15 KiB
HTML
310 lines
15 KiB
HTML
<!DOCTYPE html>
|
|
<html>
|
|
<head>
|
|
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
|
|
<title>Use a SSL certificate</title>
|
|
<link rel="stylesheet" type="text/css" href="./css/markdown.css" />
|
|
</head>
|
|
<body>
|
|
|
|
<div id="navigation">
|
|
<a href="https://www.iredmail.org" target="_blank">
|
|
<img alt="iRedMail web site"
|
|
src="./images/logo-iredmail.png"
|
|
style="vertical-align: middle; height: 30px;"
|
|
/>
|
|
<span>iRedMail</span>
|
|
</a>
|
|
// <a href="./index.html">Document Index</a></div><div class="admonition note">
|
|
<p class="admonition-title">This tutorial is available in other languages. <a href="https://bitbucket.org/zhb/iredmail-docs/src">Help translate more</a></p>
|
|
<p><a href="./use.a.bought.ssl.certificate-zh_CN.html">简体中文</a> /</p>
|
|
</div>
|
|
<h1 id="use-a-ssl-certificate">Use a SSL certificate</h1>
|
|
<div class="toc">
|
|
<ul>
|
|
<li><a href="#use-a-ssl-certificate">Use a SSL certificate</a><ul>
|
|
<li><a href="#get-a-ssl-certificate">Get a SSL certificate</a><ul>
|
|
<li><a href="#get-a-free-letsencrypt-ssl-cert">Get a free LetsEncrypt ssl cert</a></li>
|
|
<li><a href="#buy-from-a-trusted-ssl-vendor">Buy from a trusted SSL vendor</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#configure-postfixdovecotapachenginx-to-use-bought-ssl-certificate">Configure Postfix/Dovecot/Apache/Nginx to use bought SSL certificate</a><ul>
|
|
<li><a href="#postfix-smtp-server">Postfix (SMTP server)</a></li>
|
|
<li><a href="#dovecot-pop3imap-server">Dovecot (POP3/IMAP server)</a></li>
|
|
<li><a href="#apache-web-server">Apache (web server)</a></li>
|
|
<li><a href="#nginx-web-server">Nginx (web server)</a></li>
|
|
<li><a href="#mysql-mariadb">MySQL, MariaDB</a></li>
|
|
<li><a href="#openldap">OpenLDAP</a></li>
|
|
<li><a href="#openbsd-ldapd8">OpenBSD ldapd(8)</a></li>
|
|
</ul>
|
|
</li>
|
|
<li><a href="#reference">Reference</a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
</div>
|
|
<p>iRedMail generates a self-signed SSL certificate during installation, it's
|
|
fine if you just want to secure the network connections (POP3/IMAP/SMTP over
|
|
TLS, HTTPS), but mail clients or web browsers will promot a annoying message
|
|
to warn you this self-signed certificate is not trusted. To avoid this
|
|
annoying message, you have to buy a SSL certificate from SSL certificate
|
|
provider. Search <code>buy ssl certificate</code> in Google will give you many SSL
|
|
providers, choose the one you prefer.</p>
|
|
<h2 id="get-a-ssl-certificate">Get a SSL certificate</h2>
|
|
<h3 id="get-a-free-letsencrypt-ssl-cert">Get a free LetsEncrypt ssl cert</h3>
|
|
<p><a href="https://letsencrypt.org">"Let's Encrypt"</a> offers free SSL certificate, please
|
|
follow its official tutorial to get one: <a href="https://certbot.eff.org">https://certbot.eff.org</a></p>
|
|
<div class="admonition attention">
|
|
<p class="admonition-title">Attention</p>
|
|
<p>The <code>--apache</code> option of <code>certbot</code> program will modify Apache config
|
|
files, most time it messes up iRedMail configurations, so it's better
|
|
to get the cert with <code>certonly --webroot</code> option while requesting cert, then
|
|
follow tutorial below to update config files to use the cert.</p>
|
|
</div>
|
|
<h3 id="buy-from-a-trusted-ssl-vendor">Buy from a trusted SSL vendor</h3>
|
|
<p>To buy ssl cert from a trusted vendor, you need to generate a new SSL
|
|
key and signing request file on your server with <code>openssl</code> command:</p>
|
|
<div class="admonition warning">
|
|
<p class="admonition-title">Warning</p>
|
|
<p>Do NOT use key length smaller than <code>2048</code> bit, it's insecure.</p>
|
|
</div>
|
|
<pre><code># openssl req -new -newkey rsa:2048 -nodes -keyout privkey.pem -out server.csr
|
|
</code></pre>
|
|
|
|
<p>This command will generate two files:</p>
|
|
<ul>
|
|
<li><code>privkey.pem</code>: the private key for the decryption of your SSL certificate.</li>
|
|
<li><code>server.csr</code>: the certificate signing request (CSR) file used to apply
|
|
for your SSL certificate. <strong>This file is required by SSL certificate
|
|
provider.</strong></li>
|
|
</ul>
|
|
<p>The openssl command will prompt for the following X.509 attributes of the
|
|
certificate:</p>
|
|
<ul>
|
|
<li><code>Country Name (2 letter code)</code>: Use the two-letter code without punctuation
|
|
for country. for example: US, CA, CN.</li>
|
|
<li><code>State or Province Name (full name)</code>: Spell out the state completely; do not
|
|
abbreviate the state or province name, for example: California.</li>
|
|
<li><code>Locality Name (eg, city)</code>: City or town name, for example: Berkeley.</li>
|
|
<li><code>Organization Name (eg, company)</code>: Your company name.</li>
|
|
<li><code>Organizational Unit Name (eg, section)</code>: The name of the department or
|
|
organization unit making the request.</li>
|
|
<li><code>Common Name (e.g. server FQDN or YOUR name)</code>: server FQDN or your name.</li>
|
|
<li><code>Email Address []</code>: your full email address.</li>
|
|
<li><code>A challenge password []</code>: type a password for this ssl certificate.</li>
|
|
<li><code>An optional company name []</code>: an optional company name.</li>
|
|
</ul>
|
|
<p><strong>NOTE</strong>: Some certificates can only be used on web servers using the <code>Common Name</code>
|
|
specified during enrollment. For example, a certificate for the domain
|
|
<code>domain.com</code> will receive a warning if accessing a site named <code>www.domain.com</code>
|
|
or <code>secure.domain.com</code>, because <code>www.domain.com</code> and <code>secure.domain.com</code> are
|
|
different from <code>domain.com</code>.</p>
|
|
<p>Now you have two files: <code>privkey.pem</code> and <code>server.csr</code>. Go to the website of
|
|
your preferred SSL privider, it will ask you to upload <code>server.csr</code> file to
|
|
issue an SSL certificate.</p>
|
|
<p>Usually, SSL provider will give you 2 files:</p>
|
|
<ul>
|
|
<li>cert.pem</li>
|
|
<li>fullchain.pem (some SSL providers use name <code>server.ca-bundle</code>)</li>
|
|
</ul>
|
|
<p>We need above 2 files, and <code>privkey.pem</code>. Upload them to your server, you can
|
|
store them in any directory you like, recommended directories are:</p>
|
|
<ul>
|
|
<li>on RHEL/CentOS: <code>cert.pem</code> and <code>fullchain.pem</code> should be placed under
|
|
<code>/etc/pki/tls/certs/</code>, <code>privkey.pem</code> should be <code>/etc/pki/tls/private/</code>.</li>
|
|
<li>on Debian/Ubuntu, FreeBSD: <code>cert.pem</code> and <code>fullchain.pem</code> should be
|
|
placed under <code>/etc/ssl/certs/</code>, <code>privkey.pem</code> should be <code>/etc/ssl/private/</code>.</li>
|
|
<li>on OpenBSD: <code>/etc/ssl/</code>.</li>
|
|
</ul>
|
|
<h2 id="configure-postfixdovecotapachenginx-to-use-bought-ssl-certificate">Configure Postfix/Dovecot/Apache/Nginx to use bought SSL certificate</h2>
|
|
<p>We use CentOS for example in below tutorial, please adjust the file to correct
|
|
one on your server according to above description.</p>
|
|
<h3 id="postfix-smtp-server">Postfix (SMTP server)</h3>
|
|
<p>We can use <code>postconf</code> command to update SSL related settings directly:</p>
|
|
<pre><code>postconf -e smtpd_tls_cert_file='/etc/pki/tls/certs/cert.pem'
|
|
postconf -e smtpd_tls_key_file='/etc/pki/tls/private/privkey.pem'
|
|
postconf -e smtpd_tls_CAfile='/etc/pki/tls/certs/fullchain.pem'
|
|
</code></pre>
|
|
|
|
<p>Restarting Postfix service is required.</p>
|
|
<h3 id="dovecot-pop3imap-server">Dovecot (POP3/IMAP server)</h3>
|
|
<p>SSL certificate settings are defined in Dovecot main config file,
|
|
<code>/etc/dovecot/dovecot.conf</code> (Linux/OpenBSD) or
|
|
<code>/usr/local/etc/dovecot/dovecot.conf</code> (FreeBSD):</p>
|
|
<pre><code>ssl = required
|
|
ssl_cert = </etc/pki/tls/certs/cert.pem
|
|
ssl_key = </etc/pki/tls/private/privkey.pem
|
|
ssl_ca = </etc/pki/tls/certs/fullchain.pem
|
|
</code></pre>
|
|
|
|
<p>Restarting Dovecot service is required.</p>
|
|
<h3 id="apache-web-server">Apache (web server)</h3>
|
|
<ul>
|
|
<li>On RHEL/CentOS, SSL certificate is defined in <code>/etc/httpd/conf.d/ssl.conf</code>.</li>
|
|
<li>On Debian/Ubuntu, it's defined in <code>/etc/apache2/sites-available/default-ssl</code>
|
|
(or <code>default-ssl.conf</code>)</li>
|
|
<li>On FreeBSD, it's defined in <code>/usr/local/etc/apache24/extra/httpd-ssl.conf</code>. Note:
|
|
if you're running different version of Apache, the path will be slightly
|
|
different (<code>apache24</code> will be <code>apache[_version_]</code>).</li>
|
|
<li>On OpenBSD, if you're running OpenBSD 5.5 or earlier releases, it's defined
|
|
in <code>/var/www/conf/httpd.conf</code>. Note: OpenBSD 5.6 and later releases don't
|
|
ship Apache anymore.</li>
|
|
</ul>
|
|
<p>Example:</p>
|
|
<pre><code>SSLCertificateFile /etc/pki/tls/certs/cert.pem
|
|
SSLCertificateKeyFile /etc/pki/tls/private/privkey.pem
|
|
SSLCertificateChainFile /etc/pki/tls/certs/fullchain.pem
|
|
</code></pre>
|
|
|
|
<p>Restarting Apache service is required.</p>
|
|
<h3 id="nginx-web-server">Nginx (web server)</h3>
|
|
<ul>
|
|
<li>On Linux and OpenBSD, it's defined in <code>/etc/nginx/templates/ssl.tmpl</code> (or <code>/etc/nginx/conf.d/default.conf</code> on old iRedMail release)</li>
|
|
<li>On FreeBSD, it's defined in <code>/usr/local/etc/nginx/templates/ssl.tmpl</code> (or <code>/usr/local/etc/nginx/conf.d/default.conf</code> on old iRedMail release)</li>
|
|
</ul>
|
|
<pre><code>server {
|
|
listen 443;
|
|
...
|
|
ssl on;
|
|
ssl_certificate /etc/pki/tls/certs/cert.pem;
|
|
ssl_certificate_key /etc/pki/tls/private/privkey.pem;
|
|
...
|
|
}
|
|
</code></pre>
|
|
|
|
<p>Some browsers may complain about a certificate signed by a well-known
|
|
certificate authority, while other browsers may accept the certificate without
|
|
issues. This occurs because the issuing authority has signed the server
|
|
certificate using an intermediate certificate that is not present in the
|
|
certificate base of well-known trusted certificate authorities which is
|
|
distributed with a particular browser. In this case the authority provides a
|
|
bundle of chained certificates which should be concatenated to the signed
|
|
server certificate. The server certificate must appear before the chained
|
|
certificates in the combined file:</p>
|
|
<pre><code># cd /etc/pki/tls/certs/
|
|
# cat cert.pem fullchain.pem > server.chained.crt
|
|
</code></pre>
|
|
|
|
<p>Then update <code>ssl_certificate</code> parameter in <code>/etc/nginx/conf.d/default.conf</code>:</p>
|
|
<pre><code> ssl_certificate /etc/pki/tls/certs/server.chained.crt;
|
|
</code></pre>
|
|
|
|
<p>Restarting Nginx service is required.</p>
|
|
<h3 id="mysql-mariadb">MySQL, MariaDB</h3>
|
|
<blockquote>
|
|
<p>If MySQL/MariaDB is listening on localhost and not accessible from external
|
|
network, this is OPTIONAL.</p>
|
|
</blockquote>
|
|
<ul>
|
|
<li>On Red Hat and CentOS, it's defined in <code>/etc/my.cnf</code></li>
|
|
<li>On Debian and Ubuntu, it's defined in <code>/etc/mysql/my.cnf</code>.<ul>
|
|
<li>Since Ubuntu 15.04, it's defined in <code>/etc/mysql/mariadb.conf.d/mysqld.cnf</code>.</li>
|
|
</ul>
|
|
</li>
|
|
<li>On FreeBSD, it's defined in <code>/usr/local/etc/my.cnf</code>.</li>
|
|
<li>On OpenBSD, it's defined in <code>/etc/my.cnf</code>.</li>
|
|
</ul>
|
|
<pre><code>[mysqld]
|
|
|
|
ssl-ca = /etc/pki/tls/certs/fullchain.pem
|
|
ssl-cert = /etc/pki/tls/certs/cert.pem
|
|
ssl-key = /etc/pki/tls/private/privkey.pem
|
|
</code></pre>
|
|
|
|
<h3 id="openldap">OpenLDAP</h3>
|
|
<blockquote>
|
|
<p>If OpenLDAP is listening on localhost and not accessible from external
|
|
network, this is OPTIONAL.</p>
|
|
</blockquote>
|
|
<ul>
|
|
<li>On Red Hat and CentOS, it's defined in <code>/etc/openldap/slapd.conf</code>.</li>
|
|
<li>On Debian and Ubuntu, it's defined in <code>/etc/ldap/slapd.conf</code>.</li>
|
|
<li>On FreeBSD, it's defined in <code>/usr/local/etc/openldap/slapd.conf</code>.</li>
|
|
<li>On OpenBSD, it's defined in <code>/etc/openldap/slapd.conf</code>.</li>
|
|
</ul>
|
|
<pre><code>TLSCACertificateFile /etc/pki/tls/certs/fullchain.pem
|
|
TLSCertificateFile /etc/pki/tls/certs/cert.pem
|
|
TLSCertificateKeyFile /etc/pki/tls/private/privkey.pem
|
|
</code></pre>
|
|
|
|
<p>Restarting OpenLDAP service is required.</p>
|
|
<p>If you want to connect with TLS (port 389) or SSL (port 636) for secure
|
|
connection from command line tools like <code>ldapsearch</code>, please update parameter
|
|
<code>TLS_CACERT</code> in OpenLDAP client config file also, otherwise you will get
|
|
error message like <code>Peer's Certificate issuer is not recognized</code>.</p>
|
|
<ul>
|
|
<li>On Red Hat and CentOS, it's defined in <code>/etc/openldap/ldap.conf</code>.</li>
|
|
<li>On Debian and Ubuntu, it's defined in <code>/etc/ldap/ldap.conf</code>.</li>
|
|
<li>On FreeBSD, it's defined in <code>/usr/local/etc/openldap/ldap.conf</code>.</li>
|
|
<li>On OpenBSD, it's defined in <code>/etc/openldap/ldap.conf</code>.</li>
|
|
</ul>
|
|
<pre><code>TLS_CACERT /etc/pki/tls/certs/fullchain.pem
|
|
</code></pre>
|
|
|
|
<p>To connect with TLS, please run <code>ldapsearch</code> with argument <code>-Z</code> and use
|
|
<code>ldap://<your_server_name>:389</code> as ldap host. For example:</p>
|
|
<pre><code>ldapsearch -x -W -Z \
|
|
-H 'ldap://mail.example.com:389' \
|
|
-D 'cn=vmail,dc=example,dc=com' \
|
|
-b 'o=domains,dc=example,dc=com' mail
|
|
</code></pre>
|
|
|
|
<ul>
|
|
<li>To connection with SSL, use <code>ldaps://<your_server_name>:636</code> as ldap host.
|
|
for example:</li>
|
|
</ul>
|
|
<pre><code>ldapsearch -x -W \
|
|
-H 'ldaps://mail.example.com:636' \
|
|
-D 'cn=vmail,dc=example,dc=com' \
|
|
-b 'o=domains,dc=example,dc=com' mail
|
|
</code></pre>
|
|
|
|
<h3 id="openbsd-ldapd8">OpenBSD ldapd(8)</h3>
|
|
<blockquote>
|
|
<p>If ldapd(8) is listening on localhost and not accessible from external
|
|
network, this is OPTIONAL.</p>
|
|
<p>For more details about ldapd config file, please check its manual page: ldapd.conf(5).</p>
|
|
</blockquote>
|
|
<p>To make ldapd(8) listening on network interface for external network, please
|
|
make sure you have setting in <code>/etc/ldapd.conf</code> to listen on the interface. We
|
|
use <code>em0</code> as external network interface here for example.</p>
|
|
<pre><code># Listen on network interface 'em0', port 389, use STARTTLS for secure connection.
|
|
listen on em0 port 389 tls
|
|
</code></pre>
|
|
|
|
<p>If you want to use port 636 with SSL, try this:</p>
|
|
<pre><code># Listen on network interface 'em0', port 636, use SSL for secure connection.
|
|
listen on em0 port 636 ldaps
|
|
</code></pre>
|
|
|
|
<p>ldapd(8) will look for SSL cert and key from directory <code>/etc/ldap/certs/</code> by
|
|
default, the cert file name is <code><interface_name>.crt</code> and <code><interface_name>.key</code>.
|
|
In our case, it will look for <code>/etc/ldap/certs/em0.crt</code> and <code>/etc/ldap/certs/em0.key</code>.</p>
|
|
<p>Since iRedMail already generates a cert and key, we can use it directly. If you
|
|
have bought SSL cert/key, or requested one from LetsEncrypt, you can use them
|
|
too.</p>
|
|
<pre><code>cd /etc/ldap/certs/
|
|
ln -s /etc/ssl/iRedMail.crt em0.crt
|
|
ln -s /etc/ssl/iRedMail.key em0.key
|
|
</code></pre>
|
|
|
|
<p>Now restart ldapd(8) service:</p>
|
|
<pre><code>rcctl restart ldapd
|
|
</code></pre>
|
|
|
|
<h2 id="reference">Reference</h2>
|
|
<ul>
|
|
<li><a href="http://nginx.org/en/docs/http/configuring_https_servers.html">Configuring HTTPS servers</a></li>
|
|
</ul><div class="footer">
|
|
<p style="text-align: center; color: grey;">All documents are available in <a href="https://bitbucket.org/zhb/iredmail-docs/src">BitBucket repository</a>, and published under <a href="http://creativecommons.org/licenses/by-nd/3.0/us/" target="_blank">Creative Commons</a> license. You can <a href="https://bitbucket.org/zhb/iredmail-docs/get/tip.tar.bz2">download the latest version</a> for offline reading. If you found something wrong, please do <a href="https://www.iredmail.org/contact.html">contact us</a> to fix it.</p>
|
|
</div>
|
|
<!-- Global site tag (gtag.js) - Google Analytics -->
|
|
<script async src="https://www.googletagmanager.com/gtag/js?id=UA-3293801-21"></script>
|
|
<script>
|
|
window.dataLayer = window.dataLayer || [];
|
|
function gtag(){dataLayer.push(arguments);}
|
|
gtag('js', new Date());
|
|
|
|
gtag('config', 'UA-3293801-21');
|
|
</script>
|
|
</body></html> |