Let's Encrypt Support

The Axigen Solution: Overview & Architecture

Starting with Axigen X3, SSL certificates — including the Let's Encrypt ones — can be centrally managed from WebAdmin. See Managing SSL Certificates for more details.

Starting with version X2, Axigen can use the Let's Encrypt service to generate SSL certificates.

The certificates can be used for the following Axigen services:

  • WebMail
  • IMAP
  • POP3
  • SMTP Incoming
  • Proxy services — WebMail Proxy, IMAP Proxy, POP3 Proxy

For each certificate it generates, Axigen will attempt automatic renewal 25 days before the certificate expires.

Prerequisites

For Axigen to be able to generate SSL certificates using the Let's Encrypt service, 2 way network connectivity over HTTP and HTTPS is required between the Axigen server and the Let's Encrypt servers.

Also, make sure that DNS entries for the hostname(s) you are planning to generate SSL certificates for have been properly configured.

For example, to generate a valid "Let's Encrypt" certificate file for webmail.example.com from your Axigen server that has the IP address 1.2.3.4, you should add a DNS A record entry similar with:

webmail 3600 A        1.2.3.4


Check if the DNS entry has been propagated with the following command:

root@example:~# dig +short A webmail.example.com @8.8.8.8
1.1.1.1
root@example:~#

If you previously configured a CAA DNS record for your Axigen domain pointing to another certificate authority  modify it to allow Let's Encrypt to issue the certificate. For example the CAA DNS entry for webmail.example.com would be similar to:

webmail   CAA 0 issue "letsencrypt.org"

It is mandatory to have the CAA record set to the correct Certificate Authority but is optional to have this type of DNS record

 

The Let's Encrypt service places a limit on the number of requests you can register each day so, unless your network connectivity and DNS setup work, you may have to re-run your certificate request in the following day.

Generating and installing a certificate

Certificate repository

Axigen uses a file system based certificate repository when generating and storing certificates.

With the exception of the cert.pem file, which is the actual certificate used by SSL listeners, the files in the certificate repository are considered opaque to the system administrator. Files in the letsencrypt directory (default location /var/opt/axigen/letsencrypt) should never be edited unless instructed by Axigen support.

Generating certificate from CLI

Certificate generation can be triggered from the CLI interface using CERTS context.

To connect to Axigen command line interface (CLI), you should use the telnet command followed by your CLI Listener IP and port (the default  Axigen settings uses IP 127.0.0.1 and port 7000).

To generate the "Let's Encrypt" certificate from the Axigen CLI interface for a specific domain (e.g. webmail.example.com), you can use commands similar to the following:

The optional terms command parameter allows the sys admin to confirm that the Let's Encrypt service terms have been read and accepted.

 

See all available options in the CERTS context by issuing the "help" command:

 

In the Axigen log file you should find lines similar to:

2018-01-11 05:22:03 +0200 08 linux JOBLOG:70000013: LetsE: Acme job executing
2018-01-11 05:22:03 +0200 08 linux JOBLOG:70000013: LetsE: Generating account private key...
2018-01-11 05:22:03 +0200 08 linux JOBLOG:70000013: LetsE: Done generating account private key!
2018-01-11 05:22:03 +0200 08 linux JOBLOG:70000013: LetsE: AcmeInitState for webmail.example.com executing
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: Response code 201
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: Account location is https://acme-v01.api.letsencrypt.org/acme/reg/36301601, TOS URI is https://letsencrypt.org/documents/LE-SA-v1.2-November-15-2017.pdf
2018-01-11 05:22:04 +0200 02 linux JOBLOG:70000013: LetsE: Acme init state completed, moving to reg state
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: Job step action => Proceeding to next state
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: AcmeRegState for webmail.example.com executing
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: Response code 403
2018-01-11 05:22:04 +0200 02 linux JOBLOG:70000013: LetsE: Acme reg state terms failed, moving to terms state
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: Job step action => Proceeding to next state
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: AcmeTermsState for webmail.example.com executing
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: Response code 202
2018-01-11 05:22:04 +0200 02 linux JOBLOG:70000013: LetsE: Acme terms state completed, moving to reg state
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: Job step action => Proceeding to next state
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: AcmeRegState for webmail.example.com executing
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: Response code 201
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: we have to satisfy challenge 0, token 8gSGOhLC2cpF_tVov9Mq4e7yaKyO5iVELQEpqym9wM6U, uri https://acme-v01.api.letsencrypt.org/acme/challenge/eDjZowG_631sNOUxfCy50KDwyAsZQpudXbl48Gc8ryA/5017268123
2018-01-11 05:22:04 +0200 02 linux JOBLOG:70000013: LetsE: Acme reg state completed, moving to challenge state
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: Job step action => Proceeding to next state
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: AcmeChallengeState for webmail.example.com executing
2018-01-11 05:22:04 +0200 08 linux JOBLOG:70000013: LetsE: Response code 202
2018-01-11 05:22:05 +0200 08 linux JOBLOG:70000013: LetsE: Response code 202
2018-01-11 05:22:05 +0200 08 linux JOBLOG:70000013: LetsE: Job step action => Waiting is needed, going to sleep
2018-01-11 05:22:06 +0200 08 linux JOBLOG:70000014: LetsE: Acme job executing
2018-01-11 05:22:06 +0200 08 linux JOBLOG:70000014: LetsE: AcmeChallengeState for webmail.example.com executing
2018-01-11 05:22:06 +0200 08 linux JOBLOG:70000014: LetsE: Response code 202
2018-01-11 05:22:06 +0200 02 linux JOBLOG:70000014: LetsE: Acme challenge state completed, moving to auth state
2018-01-11 05:22:06 +0200 08 linux JOBLOG:70000014: LetsE: Job step action => Proceeding to next state
2018-01-11 05:22:06 +0200 08 linux JOBLOG:70000014: LetsE: AcmeAuthState for webmail.example.com executing
2018-01-11 05:22:06 +0200 08 linux JOBLOG:70000014: Generating private key for the certificate for webmail.example.com
2018-01-11 05:22:07 +0200 08 linux JOBLOG:70000014: LetsE: done generating private key for the certificate for webmail.example.com
2018-01-11 05:22:07 +0200 08 linux JOBLOG:70000014: Generating csr for the certificate for webmail.example.com
2018-01-11 05:22:07 +0200 08 linux JOBLOG:70000014: LetsE: done generating csr for the certificate for webmail.example.com
2018-01-11 05:22:07 +0200 08 linux JOBLOG:70000014: LetsE: Response code 201
2018-01-11 05:22:07 +0200 08 linux JOBLOG:70000014: LetsE: Certificate for webmail.example.com is available at https://acme-v01.api.letsencrypt.org/acme/cert/033ac3f32e8df65ccdaa2a239764002e0bcb3 or /var/opt/axigen/letsencrypt/webmail.example.com/cert.pem
2018-01-11 05:22:07 +0200 08 linux JOBLOG:70000014: LetsE: Intermediate certificate for /var/opt/axigen/letsencrypt/webmail.example.com/cert.pem, downloaded from http://cert.int-x3.letsencrypt.org/, is available at /var/opt/axigen/letsencrypt/webmail.example.com/cert_auth.pem
2018-01-11 05:22:07 +0200 08 linux JOBLOG:70000014: LetsE: Acme auth state completed, we're done!
2018-01-11 05:22:07 +0200 08 linux JOBLOG:70000014: LetsE: Job step action => Work item completed, rescheduling
2018-01-11 05:22:23 +0200 08 linux JOBLOG:70000015: LetsE: Acme job executing
2018-01-11 05:22:23 +0200 08 linux JOBLOG:70000015: LetsE: Nothing to do, going to sleep

 

The generated SSL certificate will be available in your <Axigen working directory>/letsencrypt/<domain name>. For example, on Linux:

Backing up your SSL certificates

It is highly recommended that you back up your server certificate in a secure location (it is recommended to backup the SSL certificates in a password protected archive). This will allow you to restore your certificate and private key in case the original becomes corrupted.

Consider the fact that omitting an SSL certificate from your backup increases recovery time and complexity.

Installing the certificate

Once the certificate has been generated, it can be assigned in WebAdmin (or CLI) to a given SSL listener.

For example, to add the newly generated certificate to a WebMail listener that was created using as IP 0.0.0.0 and port 443, you may use the following steps:

  1. Open the WebAdmin interface and navigate to ServicesWebMail→Click on "Edit" for the listener that is configured to use port 443 (the default https port)→SSL Settings tab )→Configure SSL subcategory
  2. Tick the "Enable SSL for this listener" box
  3. Under "Certificate file:" text box enter the certificate path that by default is letsencrypt/<domain name>/cert.pem
  4. Under "Certificate Authorities file:" text box enter the certificate path that by default is letsencrypt/<domain name>/cert_auth.pem
  5. Click on "Save Configuration"

After you completed this configuration, you may check the SSL listener, by opening its HTTPS address in a browser(e.g. https://webmail.example.com) and by clicking/hovering your mouse over the "lock icon" in the status bar of your browser:

 

To redirect all insecure connections you may edit the non-SSL listener (that by default is set on port 80) and under the SSL Settings tab )→Secure login subcategory → Tick the "Redirect to secure login page" option box and click on "Save Configuration".

You may add the certificate on any Axigen SSL listener (for example IMAP, SMTP, POP3) but if they have different hostnames, a certificate needs to be generated for each hostname and set on each listener.

Automatic renewal

Once a day Axigen checks if any of the domains' certificates are to be renewed; each check logs a couple of lines like:

2018-01-19 14:05:04 +0100 08 linux JOBLOG:70000006: LetsE: Acme job executing
2018-01-19 14:05:04 +0100 08 linux JOBLOG:70000006: LetsE: No cli jobs or renewals to do, going to sleep

Five days before the certificate expires, Axigen will attempt to automatically ask for renewal.

Starting with Axigen 10.2.2.53 the LE certificates renewing starts  25 days before expiry.

 

When a certificate in the renewal period is found, Axigen will log a few lines similar to:

2018-04-06 05:22:03 +0200 08 linux JOBLOG:7000005C: LetsE: Acme job executing
2018-04-06 05:22:03 +0200 08 linux JOBLOG:7000005C: LetsE: Certificate path /var/opt/axigen/letsencrypt/webmail.example.com/cert.pem is within renewal period => issuing renewal request for webmail.example.com webmail.example.com
2018-04-06 05:22:03 +0200 08 linux JOBLOG:7000005C: LetsE: Renewal for webmail.example.com successfully added
2018-04-06 05:22:03 +0200 08 linux JOBLOG:7000005C: LetsE: Found 1 certificate(s) to renew

Axigen will attempt to automatically ask for renewal:

2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: Acme job executing
2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: AcmeChallengeState for webmail.example.com executing
2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: Response code 202
2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: Acme challenge state completed, moving to auth state
2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: Job step action => Proceeding to next state
2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: AcmeAuthState for webmail.example.com executing
2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: done generating csr for the certificate for webmail.example.com
2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: Response code 201
2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: Certificate for webmail.example.com is available at https://acme-v01.api.letsencrypt.org/acme/cert/0338053d9a2bec20121259c02e483d61fd27 or /var/opt/axigen/letsencrypt/webmail.example.com/cert.pem
2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: Intermediate certificate for /var/opt/axigen/letsencrypt/webmail.example.com/cert.pem, downloaded from http://cert.int-x3.letsencrypt.org/, is available at /var/opt/axigen/letsencrypt/webmail.example.com/cert_auth.pem
2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: Acme auth state completed, we're done!
2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: Matching domain for hostname webmail.example.com is example.com
2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: certificate job completion mail for webmail.example.com sent
2018-04-06 05:22:23 +0200 08 linux JOBLOG:7000005E: LetsE: Job step action => Work item completed, rescheduling

Progress notifications

Since certificate generation and renewal are operations that sometimes happen without sys admin intervention, Axigen uses email messages to notify the sys admin of progress regarding certificate operations.

Axigen will send alerts:

  1. at certificate generation time (when the certificate is generated and when an error prevents Axigen from generating the certificate).
  2. at certificate renewal time.

Axigen uses the following algorithm when deciding where to send notifications:

  1. given a hostname webmail.example.com
  2. it will tokenize the hostname and look for domain webmail.example.com, example.com
  3. should it find domain example.com it will mail the notification to postmaster+Alerts@example.com and the contact email address provided at certificate generation time (if it exists)
  4. if no domain matching the hostname is found, the notification is only sent to the contact email address provided at certificate generation time (if it exists)

Below you may find a renewal notification sample:

Validating Let's Encrypt peer's certificate

Axigen uses the operating system's certificate bundle to validate that the data is received from a trusted Let's Encrypt server.

Axigen checks for the  certificate bundle path in the following order:

  1. caBundlePath configured in axigen.cfg
  2. if no path for caBundlePath is set in the Axigen configuration(axigen.cfg)  -the default setting -   Axigen X2 is using the working directory as bundle directory path (on all operating systems Axigen X2 places in the working directory a default certificate bundle file - cacert_default.pem)
  3. On Linux if above options do not result in a satisfactory result it tries to search for distribution's default certificate bundle paths

Taking into consideration the above order, usually there is no need to do any changes to caBundlePath

 

2018-04-06 11:12:55 +0200 08 linux JOBLOG:70000002: LetsE: Acme job executing
2018-04-06 11:12:55 +0200 08 linux JOBLOG:70000002: LetsE: Certificate path /var/opt/axigen/letsencrypt/webmail.example.com/cert.pem is within renewal period => issuing renewal request for webmail.example.com webmail.example.com
2018-04-06 11:12:55 +0200 08 linux JOBLOG:70000002: LetsE: Renewal for webmail.example.com successfully added
2018-04-06 11:12:55 +0200 08 linux JOBLOG:70000002: LetsE: Found 1 certificate(s) to renew