acme.sh Notes

The acme.sh script / utility is very useful when working with (free) SSL certificates issued by Let’s Encrypt (LE), ZeroSSL and other providers. It’s featured in a number of the guides I’ve written and a quick search will turn up lots of content, but this is to bring my notes together into one place.

As ever, replace mylab.domain and server.mylab.domain with your own domain / FQDN.

Installing acme.sh

My experience is that acme.sh works best when installed in sudo mode

sudo -i
curl https://get.acme.sh | sh -s email=me@mylab.domain

From here on, I assume you are in sudo -i when working with acme.sh

Default CA

Back in 2021, acme.sh changed the default CA to ZeroSSL from LE. For consistency / simplicity, I just use LE for everything so a simple command makes LE the default CA again and we don’t need to remember the parameter each time when issuing a certificate.

acme.sh --set-default-ca --server letsencrypt

Issuing an SSL using Cloudflare DNS Challenge

Set the CF_Token environment variable – this is obtained from your Cloudflare account for API access. See here on where to create one. The beauty of using a DNS challenge compared to HTTP is very little configuration is needed (no port forwarding / firewall ACL or webserver config to answer the challenge). This means you can get a trusted certificate for a private web server or other application.

export CF_Token="CF_API_Key_Here"

If we want to issue an RSA Certificate for a single FQDN using a Cloudflare DNS challenge:

acme.sh --issue --dns dns_cf --keylength 4096 -d server.mylab.domain

Or, to issue an newer ECC type certificate:

acme.sh --issue --dns dns_cf --keylength ec-256 -d server.mylab.domain

Web Server Configuration

Firstly, if you need to build SSL configuration settings for many common web servers (Apache, Nginx, Lighttpd etc) or proxies, then this Mozilla tool is great. It allows you to pick what sort of clients you need to support and some other settings, then generates the required config for your chose server to enable the right versions of TLS (etc):

https://ssl-config.mozilla.org/

Custom DH Group

To generate a strong, custom DH group for RSA certificates we can create our own file. When Logjam was discovered in 2015, generating this file could take a while but on modern hardware it’s just a few seconds. If you are only using ECC certificates, skip this step.

sudo mkdir -p /etc/apache2/ssl/server.mylab.domain/
sudo openssl dhparam -out /etc/apache2/ssl/server.mylab.domain/dhparams.pem 4096

Installing Certificates

This is easy to achieve with acme.sh following the notes below. If you don’t need to support RSA and ECC certificates, just use the instructions for one type of certificates – so create one folder, run one acme install command and only put one certificate in your Apache configuration!

Working with Dual Certificates (RSA/ECC)

If you need to support both types of certificate due to having older clients or infrastructure that do not like ECC, this is quite easy to achieve with acme.sh. Use the commands above to issue both certificates for the domain. acme.sh will put the generated certificates into separate folders – the ECC one is identified by an ecc postfix in the folder name.

I create two folders for the certificates for the appropriate web server & site. Using Apache as an example:

sudo mkdir -p /etc/apache2/ssl/server.mylab.domain/rsa/
sudo mkdir -p /etc/apache2/ssl/server.mylab.domain/ecc/

Then to install the RSA certificate by copying the files and restarting the Apache service:

acme.sh --install-cert -d server.mylab.domain \
--cert-file /etc/apache2/ssl/server.mylab.domain/rsa/server.mylab.domain.cer \
--key-file /etc/apache2/ssl/server.mylab.domain/rsa/server.mylab.domain.key \
--fullchain-file /etc/apache2/ssl/server.mylab.domain/rsa/fullchain.cer \
--reloadcmd "service apache2 force-reload"

To install the ECC certificate:

acme.sh --install-cert -d server.mylab.domain \
--cert-file /etc/apache2/ssl/server.mylab.domain/ecc/server.mylab.domain.cer \
--key-file /etc/apache2/ssl/server.mylab.domain/ecc/server.mylab.domain.key \
--fullchain-file /etc/apache2/ssl/server.mylab.domain/ecc/fullchain.cer \
--reloadcmd "service apache2 force-reload"

Your Apache configuration file for both certificates would then be something like:

#RSA Certificate
SSLCertificateFile /etc/apache2/ssl/server.mylab.domain/rsa/mylab.domain.cer 
SSLCertificateKeyFile /etc/apache2/ssl/server.mylab.domain/rsa/mylab.domain.key
SSLOpenSSLConfCmd DHParameters /etc/apache2/ssl/server.mylab.domain/dhparams.pem

#ECC Certificate
SSLCertificateFile /etc/apache2/ssl/server.mylab.domain/ecc/server.mylab.domain.cer
SSLCertificateKeyFile /etc/apache2/ssl/server.mylab.domain/ecc/fullchain.cer