# Use a bought SSL certificate

[TOC]

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 `buy ssl certificate` in Google will give you many SSL
providers, choose the one you prefer.

## Get a SSL certificate

### Request a free cert from Let's Encrypt

We have another tutorial to show you to request a free cert from Let's Encrypt:
[Request a free cert from Let's Encrypt](./letsencrypt.html).

### Buy from a trusted SSL vendor

To buy ssl cert from a trusted vendor, you need to generate a new SSL
key and signing request file on your server with `openssl` command:

!!! warning

    Do NOT use key length smaller than `2048` bit, it's insecure.

```
# openssl req -new -newkey rsa:2048 -nodes -keyout privkey.pem -out server.csr
```

This command will generate two files:

* `privkey.pem`: the private key for the decryption of your SSL certificate.
* `server.csr`: the certificate signing request (CSR) file used to apply
  for your SSL certificate. __This file is required by SSL certificate
  provider.__

The openssl command will prompt for the following X.509 attributes of the
certificate:

* `Country Name (2 letter code)`: Use the two-letter code without punctuation
  for country. for example: US, CA, CN.
* `State or Province Name (full name)`: Spell out the state completely; do not
  abbreviate the state or province name, for example: California.
* `Locality Name (eg, city)`: City or town name, for example: Berkeley.
* `Organization Name (eg, company)`: Your company name.
* `Organizational Unit Name (eg, section)`: The name of the department or
  organization unit making the request.
* `Common Name (e.g. server FQDN or YOUR name)`: server FQDN or your name.
* `Email Address []`: your full email address.
* `A challenge password []`: type a password for this ssl certificate.
* `An optional company name []`: an optional company name.

__NOTE__: Some certificates can only be used on web servers using the `Common Name`
specified during enrollment. For example, a certificate for the domain
`domain.com` will receive a warning if accessing a site named `www.domain.com`
or `secure.domain.com`, because `www.domain.com` and `secure.domain.com` are
different from `domain.com`.

Now you have two files: `privkey.pem` and `server.csr`. Go to the website of
your preferred SSL privider, it will ask you to upload `server.csr` file to
issue an SSL certificate.

Usually, SSL provider will give you 2 files:

* `cert.pem`
* `fullchain.pem` (some SSL providers use name `server.ca-bundle`)

We need above 2 files, and `privkey.pem`. Upload them to your server, you can
store them in any directory you like, recommended directories are:

* on RHEL/CentOS: `cert.pem` and `fullchain.pem` should be placed under
  `/etc/pki/tls/certs/`, `privkey.pem` should be `/etc/pki/tls/private/`.
* on Debian/Ubuntu, FreeBSD: `cert.pem` and `fullchain.pem` should be
  placed under `/etc/ssl/certs/`, `privkey.pem` should be `/etc/ssl/private/`.
* on OpenBSD: `/etc/ssl/`.

## Use the bought cert

The easiest and quickest way to use the bought cert is replacing
the self-signed SSL cert generated by iRedMail installer, then
restart services which use the cert files.

### Replace cert files

!!! warning

    If you deployed iRedMail with the iRedMail Easy platform, ssl cert files
    are stored under `/opt/iredmail/ssl/`:

    * `key.pem`: private key
    * `cert.pem`: certificate
    * `combined.pem`: full chain

* On RHEL/CentOS:

```
mv /etc/pki/tls/certs/iRedMail.crt{,.bak}       # Backup. Rename iRedMail.crt to iRedMail.crt.bak
mv /etc/pki/tls/private/iRedMail.key{,.bak}     # Backup. Rename iRedMail.key to iRedMail.key.bak
cp fullchain.pem /etc/pki/tls/certs/iRedMail.crt
cp privkey.pem /etc/pki/tls/private/iRedMail.key
```

* On Debian/Ubuntu, FreeBSD and OpenBSD:

```
mv /etc/ssl/certs/iRedMail.crt{,.bak}       # Backup. Rename iRedMail.crt to iRedMail.crt.bak
mv /etc/ssl/private/iRedMail.key{,.bak}     # Backup. Rename iRedMail.key to iRedMail.key.bak
cp fullchain.pem /etc/ssl/certs/iRedMail.crt
cp privkey.pem /etc/ssl/private/iRedMail.key
```

### Restart network services

Required services:

* Postfix
* Dovecot
* Nginx or Apache

Depends on the backend you chose during iRedMail installation, you may need to
restart:

* MySQL or MariaDB
* PostgreSQL
* OpenLDAP

## Verify the cert

* To verify ssl cert used in Postfix (SMTP server) and Dovecot, please launch a
  mail client application (MUA, e.g. Outlook, Thunderbird) and create an email
  account, make sure you correctly configured the MUA to connect to mail
  server. If SSL cert is not valid, MUA will warn you.
* For Apache / Nginx web server, you can access your website with favourite web
  browser, the browser should show you the ssl cert status. Or, use other
  website to help test it, for example:
  <https://www.ssllabs.com/ssltest/index.html> (input your web host name, then
  submit and wait for a result).

## See Also

* [Request a free cert from Let's Encrypt](./letsencrypt.html)