Getting Started with SSLMate

This is a tutorial for how to acquire your first certificate from SSLMate. It will teach you how to install SSLMate, purchase or import a certifiate, configure your certificate, and set up automated renewal.

These instructions assume that you are using the default SSLMate configuration, and that you are running SSLMate as root on the server where the certificate needs to reside. Although it's possible to run SSLMate as a non-root user on a desktop or laptop, running SSLMate on your server is best because it eliminates the need to copy files around and lets you use automated renewals.

For general documentation, consult the other pages in the help section.

1. Install SSLMate

Choose your operating system:

Debian 8 (Jessie)

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/jessie/sslmate.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/jessie/sslmate.gpg

apt-get update

apt-get install sslmate

Debian 7 (Wheezy)

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/wheezy/sslmate.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/wheezy/sslmate.gpg

apt-get update

apt-get install sslmate

Ubuntu 16.10

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/ubuntu1610/sslmate.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/ubuntu1610/sslmate.gpg

apt-get update

apt-get install sslmate

Ubuntu 16.04

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/ubuntu1604/sslmate.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/ubuntu1604/sslmate.gpg

apt-get update

apt-get install sslmate

Ubuntu 15.10

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/ubuntu1510/sslmate.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/ubuntu1510/sslmate.gpg

apt-get update

apt-get install sslmate

Ubuntu 15.04

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/ubuntu1504/sslmate.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/ubuntu1504/sslmate.gpg

apt-get update

apt-get install sslmate

Ubuntu 14.04

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/ubuntu1404/sslmate.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/ubuntu1404/sslmate.gpg

apt-get update

apt-get install sslmate

Ubuntu 12.04

Prerequisite: the ca-certificates package must be installed.

wget -P /etc/apt/sources.list.d https://sslmate.com/apt/ubuntu1204/sslmate.list

wget -P /etc/apt/trusted.gpg.d https://sslmate.com/apt/ubuntu1204/sslmate.gpg

apt-get update

apt-get install sslmate

RHEL/CentOS/SL (6 and 7)

Prerequisite: the wget and ca-certificates packages must be installed.

wget -P /etc/yum.repos.d https://sslmate.com/yum/centos/SSLMate.repo

wget -P /etc/pki/rpm-gpg https://sslmate.com/yum/centos/RPM-GPG-KEY-SSLMate

yum install sslmate

Fedora (20+)

Prerequisite: the wget and ca-certificates packages must be installed.

wget -P /etc/yum.repos.d https://sslmate.com/yum/fedora/SSLMate.repo

wget -P /etc/pki/rpm-gpg https://sslmate.com/yum/fedora/RPM-GPG-KEY-SSLMate

yum install sslmate

Arch Linux

yaourt sslmate

Mac OS X (Homebrew)

brew update

brew install sslmate

Or: standalone .pkg file (for OS X 10.9+ only)

Other

1. Download sslmate-latest.tar.gz and extract:

tar xzvf sslmate-latest.tar.gz

cd sslmate-VERSION

2. Install dependencies:

cpan URI Term::ReadKey JSON::PP

3. Install SSLMate to /usr/local/bin:

make install

Or, install to a custom prefix:

make install PREFIX=/path/to/directory

2. Buy or Import a Certificate

Buy a Certificate

To buy a new certificate, run the following command and follow the prompts:

sslmate buy HOSTNAME

HOSTNAME is the name for the certificate (also known as the "common name" or "CN"), such as www.example.com. For a wildcard cert, use *.example.com. Note that a certificate purchased for www.example.com is also valid for example.com.

As part of the process, you will be required to respond to an email or add a DNS record at your domain to confirm that you control the domain. For more information, see the certificate approval section.

For advanced purchasing options, see the buy documentation.

Import a Certificate

To import a certificate you already own to your SSLMate account, run:

sslmate import KEYFILE CERTFILE

  • KEYFILE is path to the certificate's private key file. Note: your private key is not uploaded to SSLMate; the SSLMate client only uses it to generate a certificate signing request.

  • CERTFILE is path to the certificate file.

3. Configure Your Server Software (Apache, nginx, etc.)

By default, SSLMate stores keys and certificates in the /etc/sslmate directory. You should configure your server software to refer to keys and certificates in /etc/sslmate instead of moving these files to a different directory. (If you've imported certificates, you should update your current server configuration to refer to these new paths.) Keeping keys and certificates in their standard SSLMate location will make automated renewals work more smoothly.

SSLMate creates four files for every certificate:

  • example.com.key - the private key
  • example.com.crt - the certificate
  • example.com.chain.crt - the certificate chain (aka intermediate cert)
  • example.com.chained.crt - concatenation of the certificate and the chain

You need to configure your server software with the private key file (.key) and some combination of the .crt files. Some software requires you to specify the certificate (.crt) and the chain (.chain.crt) in separate files, while other software requires you to specify both in a single file (.chained.crt). Consult your software's documentation, or use the config guide below.

Choose your software:

Apache

SSLEngine on

SSLCertificateKeyFile /etc/sslmate/example.com.key

SSLCertificateFile /etc/sslmate/example.com.crt

SSLCertificateChainFile /etc/sslmate/example.com.chain.crt

Apache (with recommended security settings)

SSLEngine on

SSLCertificateKeyFile /etc/sslmate/example.com.key

SSLCertificateFile /etc/sslmate/example.com.crt

SSLCertificateChainFile /etc/sslmate/example.com.chain.crt

# Recommended security settings from https://wiki.mozilla.org/Security/Server_Side_TLS

SSLProtocol all -SSLv2 -SSLv3

SSLCipherSuite ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS

SSLHonorCipherOrder on

SSLCompression off

# Enable this if you want HSTS (recommended)

# Header add Strict-Transport-Security "max-age=15768000"

nginx

ssl on;

ssl_certificate_key /etc/sslmate/example.com.key;

ssl_certificate /etc/sslmate/example.com.chained.crt;

nginx (with recommended security settings)

ssl on;

ssl_certificate_key /etc/sslmate/example.com.key;

ssl_certificate /etc/sslmate/example.com.chained.crt;

# Recommended security settings from https://wiki.mozilla.org/Security/Server_Side_TLS

ssl_protocols TLSv1 TLSv1.1 TLSv1.2;

ssl_ciphers 'ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS';

ssl_prefer_server_ciphers on;

ssl_dhparam /usr/share/sslmate/dhparams/dh2048-group14.pem;

ssl_session_timeout 5m;

ssl_session_cache shared:SSL:5m;

# Enable this if you want HSTS (recommended)

# add_header Strict-Transport-Security max-age=15768000;

Lighttpd

ssl.engine = "enable"

ssl.pemfile = "__COMBINED_PATH__"

ssl.ca-file = "/etc/sslmate/example.com.chain.crt"

Lighttpd (with recommended security settings)

ssl.engine = "enable"

ssl.pemfile = "__COMBINED_PATH__"

ssl.ca-file = "/etc/sslmate/example.com.chain.crt"

# Recommended ciphers from https://wiki.mozilla.org/Security/Server_Side_TLS

ssl.cipher-list = "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS"

ssl.honor-cipher-order = "enable"

# lighttpd >= 1.4.29 only:

#ssl.dh-file = /usr/share/sslmate/dhparams/dh2048-group14.pem"

# lighttpd < 1.4.21 only:

#ssl.use-sslv2 = "disable"

# lighttpd >= 1.4.29 only:

#ssl.use-sslv3 = "disable"

stunnel

key = /etc/sslmate/example.com.key

cert = /etc/sslmate/example.com.chained.crt

stunnel (with recommended security settings)

key = /etc/sslmate/example.com.key

cert = /etc/sslmate/example.com.chained.crt

; Recommended security settings adapted from https://wiki.mozilla.org/Security/Server_Side_TLS

options = NO_SSLv2

options = NO_SSLv3

options = CIPHER_SERVER_PREFERENCE

options = NO_COMPRESSION

ciphers = ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS

titus

key /etc/sslmate/example.com.key

cert /etc/sslmate/example.com.chained.crt

titus (with recommended security settings)

key /etc/sslmate/example.com.key

cert /etc/sslmate/example.com.chained.crt

# Recommended security settings adapted from https://wiki.mozilla.org/Security/Server_Side_TLS

ciphers ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS

Dovecot 2

ssl_key = </etc/sslmate/example.com.key

ssl_cert = </etc/sslmate/example.com.chained.crt

Dovecot 2 (with recommended security settings)

ssl_key = </etc/sslmate/example.com.key

ssl_cert = </etc/sslmate/example.com.chained.crt

# Recommended security settings adapted from https://wiki.mozilla.org/Security/Server_Side_TLS

ssl_protocols = !SSLv2 !SSLv3

ssl_cipher_list = ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS

# Note: ssl_dh_parameters_length is only available in Dovecot 2.2.7 and higher:

ssl_dh_parameters_length = 2048

Postfix

smtp_tls_security_level = may

smtpd_tls_security_level = may

smtpd_tls_key_file = /etc/sslmate/example.com.key

smtpd_tls_cert_file = /etc/sslmate/example.com.chained.crt

Postfix (with recommended security settings)

smtp_tls_security_level = may

smtpd_tls_security_level = may

smtpd_tls_key_file = /etc/sslmate/example.com.key

smtpd_tls_cert_file = /etc/sslmate/example.com.chained.crt

# Recommended security settings adapted from https://wiki.mozilla.org/Security/Server_Side_TLS

smtpd_tls_mandatory_protocols = !SSLv2, !SSLv3

smtpd_tls_mandatory_ciphers = high

smtp_tls_mandatory_protocols = !SSLv2, !SSLv3

smtp_tls_mandatory_ciphers = high

tls_high_cipherlist = ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS

smtpd_tls_dh1024_param_file = /usr/share/sslmate/dhparams/dh2048-group14.pem

Prosody

ssl = {

key = "/etc/sslmate/example.com.key";

certificate = "/etc/sslmate/example.com.chained.crt";

}

Prosody (with recommended security settings)

ssl = {

key = "/etc/sslmate/example.com.key";

certificate = "/etc/sslmate/example.com.chained.crt";

-- Recommended security settings adapted from https://wiki.mozilla.org/Security/Server_Side_TLS

options = { "no_sslv2", "no_sslv3", "no_ticket", "no_compression", "cipher_server_preference", "single_dh_use", "single_ecdh_use" };

ciphers = "ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-AES128-SHA256:ECDHE-RSA-AES128-SHA256:ECDHE-ECDSA-AES128-SHA:ECDHE-RSA-AES256-SHA384:ECDHE-RSA-AES128-SHA:ECDHE-ECDSA-AES256-SHA384:ECDHE-ECDSA-AES256-SHA:ECDHE-RSA-AES256-SHA:DHE-RSA-AES128-SHA256:DHE-RSA-AES128-SHA:DHE-RSA-AES256-SHA256:DHE-RSA-AES256-SHA:ECDHE-ECDSA-DES-CBC3-SHA:ECDHE-RSA-DES-CBC3-SHA:EDH-RSA-DES-CBC3-SHA:AES128-GCM-SHA256:AES256-GCM-SHA384:AES128-SHA256:AES256-SHA256:AES128-SHA:AES256-SHA:DES-CBC3-SHA:!DSS";

-- Note: dhparam is only available in Prosody 0.9.1 and higher:

dhparam = "/usr/share/sslmate/dhparams/dh2048-group14.pem";

}

Remember to restart your server software after changing its configuration. Note that Apache must be fully restarted after changing certificate configuration; a reload is not sufficient.

4. Test Your Server

After configuring your server, you can use the sslmate test command to make sure that your certificate has been properly installed:

sslmate test HOSTNAME

5. Set Up Automated Renewals

After buying or importing a certificate, you may want to set up your server to periodically download new versions of the certificate. Then, when the certificate auto-renews, your server will automatically get the renewed certificate.

The best way to do this is to set up a daily cron job that runs sslmate download. If sslmate download exits with status 0, new certificates were downloaded and you should restart your server software so that it loads the updated certificate files.

For example, the following cron script, /etc/cron.daily/sslmate, downloads the latest certificates, and restarts Apache (on Debian/Ubuntu) if a new certificate was downloaded:

#!/bin/sh if sslmate download --all > /dev/null then service apache2 restart > /dev/null fi
  • Make sure your script is executable (chmod +x /etc/cron.daily/sslmate).
  • If you installed sslmate by hand in a non-standard location, make sure to specify the full path to sslmate.
  • Your server must be linked with your SSLMate account for sslmate download to work. To link your server, run sslmate link as root, or create a config file with your API key, as found on your account page.
  • Remember, sslmate puts certs in /etc/sslmate by default, so make sure your server software reads certs from this location!
  • Double-check your certificate dashboard to make sure your certificate is set to auto-renew (this is the default).

6. Learn More

Check out our extensive help section, run sslmate help, or consult the sslmate(1) man page to learn about the other features of SSLMate.

Get Started with SSLMate Today

Buy a new certificate, or import your existing certs for free.

Click to sign up