2016-05-19 06:51:20 -05:00
<!DOCTYPE html>
2015-01-07 09:12:18 -06:00
< html >
< head >
< meta http-equiv = "Content-Type" content = "text/html; charset=utf-8" / >
< title > Use a bought SSL certificate< / title >
2015-07-31 23:14:52 -05:00
< link rel = "stylesheet" type = "text/css" href = "./css/markdown.css" / >
2015-01-07 09:12:18 -06:00
< / head >
< body >
< div id = "navigation" >
2016-04-19 12:48:51 -05:00
< a href = "/index.html" target = "_blank" >
< img alt = "iRedMail web site"
src="./images/logo-iredmail.png"
style="vertical-align: middle; height: 30px;"
/>
< span > iRedMail< / span >
< / a >
2016-04-21 23:33:25 -05:00
// < a href = "./index.html" > Document Index< / a > < / div > < div class = "admonition note" >
2016-11-11 02:56:08 -06:00
< 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 >
2016-04-24 09:21:04 -05:00
< p > < a href = "./use.a.bought.ssl.certificate-zh_CN.html" > 简体中文< / a > /< / p >
2016-04-21 23:33:25 -05:00
< / div >
< h1 id = "use-a-bought-ssl-certificate" > Use a bought SSL certificate< / h1 >
2015-01-07 09:12:18 -06:00
< div class = "toc" >
< ul >
< li > < a href = "#use-a-bought-ssl-certificate" > Use a bought SSL certificate< / a > < ul >
< li > < a href = "#generate-ssl-private-key-and-buy-one-ssl-certificate" > Generate SSL private key and buy one SSL certificate< / a > < / 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 >
2015-11-30 19:22:05 -06:00
< li > < a href = "#mysql-mariadb" > MySQL, MariaDB< / a > < / li >
2016-12-30 19:41:59 -06:00
< li > < a href = "#openldap" > OpenLDAP< / a > < / li >
< li > < a href = "#openbsd-ldapd8" > OpenBSD ldapd(8)< / a > < / li >
2015-01-07 09:12:18 -06:00
< / ul >
< / li >
2015-06-26 20:50:52 -05:00
< li > < a href = "#reference" > Reference< / a > < / li >
2015-01-07 09:12:18 -06:00
< / 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 >
2015-01-07 10:33:05 -06:00
< blockquote >
2016-02-25 03:17:57 -06:00
< p > < a href = "https://letsencrypt.org" > "Let's Encrypt" offers free SSL certificate< / a > < / p >
2015-01-07 10:33:05 -06:00
< / blockquote >
2015-01-07 09:12:18 -06:00
< h2 id = "generate-ssl-private-key-and-buy-one-ssl-certificate" > Generate SSL private key and buy one SSL certificate< / h2 >
< p > First of all, you need to generate a new SSL certificate on your server
2015-05-10 07:29:07 -05:00
with < code > openssl< / code > command. < strong > WARNING< / strong > : do NOT use key length smaller than < code > 2048< / code > bit,
2015-01-07 09:12:18 -06:00
it's insecure.< / p >
2015-05-10 07:29:07 -05:00
< pre > < code > # openssl req -new -newkey rsa:2048 -nodes -keyout server.key -out server.csr
2015-01-07 09:12:18 -06:00
< / code > < / pre >
< p > This command will generate two files:< / p >
< ul >
< li > < code > server.key< / 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
2015-05-14 20:54:55 -05:00
for your SSL certificate. < strong > This file is required by SSL certificate
2015-05-10 07:29:07 -05:00
provider.< / strong > < / li >
2015-01-07 09:12:18 -06:00
< / 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 >
2015-08-14 08:25:15 -05:00
< p > < strong > NOTE< / strong > : Some certificates can only be used on web servers using the < code > Common Name< / code >
2015-01-07 09:12:18 -06:00
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 > server.key< / 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 > server.crt< / li >
< li > server.ca-bundle< / li >
< / ul >
< p > We need above 2 files, and < code > server.key< / 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 > server.crt< / code > and < code > server.ca-bundle< / code > should be placed under
< code > /etc/pki/tls/certs/< / code > , < code > server.key< / code > should be < code > /etc/pki/tls/private/< / code > .< / li >
< li > on Debian/Ubuntu, FreeBSD: < code > server.crt< / code > and < code > server.ca-bundle< / code > should be
placed under < code > /etc/ssl/certs/< / code > , < code > server.key< / 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
2015-08-14 08:25:15 -05:00
one on your server according to above description.< / p >
2015-01-07 09:12:18 -06:00
< h3 id = "postfix-smtp-server" > Postfix (SMTP server)< / h3 >
< p > We can use < code > postconf< / code > command to update SSL related settings directly:< / p >
2017-01-15 03:25:45 -06:00
< pre > < code > postconf -e smtpd_tls_cert_file='/etc/pki/tls/certs/server.crt'
2015-01-07 09:12:18 -06:00
postconf -e smtpd_tls_key_file='/etc/pki/tls/private/server.key'
postconf -e smtpd_tls_CAfile='/etc/pki/tls/certs/server.ca-bundle'
< / 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/server.crt
ssl_key = < /etc/pki/tls/private/server.key
ssl_ca = < /etc/pki/tls/certs/server.ca-bundle
< / 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/server.crt
SSLCertificateKeyFile /etc/pki/tls/private/server.key
SSLCertificateChainFile /etc/pki/tls/certs/server.ca-bundle
< / 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/conf.d/default.conf< / code > .< / li >
< li > On FreeBSD, it's defined in < code > /usr/local/etc/nginx/conf.d/default.conf< / code > .< / li >
< / ul >
< pre > < code > server {
listen 443;
...
ssl on;
2015-05-10 04:34:55 -05:00
ssl_certificate /etc/pki/tls/certs/server.crt;
2015-01-07 09:12:18 -06:00
ssl_certificate_key /etc/pki/tls/private/server.key;
...
}
< / 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 server.crt server.ca-bundle > server.chained.crt
< / code > < / pre >
< p > Then update < code > ssl_certificate< / code > parameter in < code > /etc/nginx/conf.d/default.conf< / code > :< / p >
2015-05-10 04:34:55 -05:00
< pre > < code > ssl_certificate /etc/pki/tls/certs/server.chained.crt;
2015-01-07 09:12:18 -06:00
< / code > < / pre >
< p > Restarting Nginx service is required.< / p >
2016-12-30 19:41:59 -06:00
< 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/server.ca-bundle
ssl-cert = /etc/pki/tls/certs/server.crt
ssl-key = /etc/pki/tls/private/server.key
< / code > < / pre >
2015-10-18 05:18:17 -05:00
< h3 id = "openldap" > OpenLDAP< / h3 >
2015-11-30 19:22:05 -06:00
< blockquote >
< p > If OpenLDAP is listening on localhost and not accessible from external
2016-12-12 19:02:09 -06:00
network, this is OPTIONAL.< / p >
2015-11-30 19:22:05 -06:00
< / blockquote >
2015-10-18 05:18:17 -05:00
< 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/server.ca-bundle
TLSCertificateFile /etc/pki/tls/certs/server.crt
TLSCertificateKeyFile /etc/pki/tls/private/server.key
< / code > < / pre >
< p > Restarting OpenLDAP service is required.< / p >
2016-10-11 09:48:07 -05:00
< 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/server.ca-bundle
< / 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 >
2016-12-30 19:41:59 -06:00
< h3 id = "openbsd-ldapd8" > OpenBSD ldapd(8)< / h3 >
2015-11-30 19:22:05 -06:00
< blockquote >
2016-12-30 19:41:59 -06:00
< p > If ldapd(8) is listening on localhost and not accessible from external
2016-12-12 19:02:09 -06:00
network, this is OPTIONAL.< / p >
2016-12-30 19:41:59 -06:00
< p > For more details about ldapd config file, please check its manual page: ldapd.conf(5).< / p >
2015-11-30 19:22:05 -06:00
< / blockquote >
2016-12-30 19:41:59 -06:00
< 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 >
2015-11-30 19:22:05 -06:00
2016-12-30 19:41:59 -06:00
< 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
2015-11-30 19:22:05 -06:00
< / code > < / pre >
2015-06-26 20:50:52 -05:00
< h2 id = "reference" > Reference< / h2 >
< ul >
< li > < a href = "http://nginx.org/en/docs/http/configuring_https_servers.html" > Configuring HTTPS servers< / a > < / li >
2016-05-19 06:51:20 -05:00
< / 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 = "http://www.iredmail.org/contact.html" > contact us< / a > to fix it.< / p >
< / div >
< script type = "text/javascript" >
2015-02-05 07:02:53 -06:00
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-3293801-21', 'auto');
ga('send', 'pageview');
2015-01-07 09:12:18 -06:00
< / script >
< / body > < / html >
