acme-certify -- A Let's Encrypt! ACME client

Let's Encrypt! ACME client

Usage: acme-certify --key FILE --domain DOMAIN --challenge-dir DIR
                    [--domain-dir DIR] [--email ADDRESS] [--terms URL]
                    [--skip-dhparams] [--staging] [--skip-provision-check]
  This program will generate a signed TLS certificate using the ACME protocol
  and the free Let's Encrypt! CA.

Available options:
  -h,--help                Show this help text
  --key FILE               Filename of your private RSA key
  --domain DOMAIN          The domain name(s) to certify; specify more than once
                           for a multi-domain certificate
  --challenge-dir DIR      Output directory for ACME challenges
  --domain-dir DIR         Directory in which to domain certificates and keys
                           are stored; the default is to use the (first) domain
                           name as a directory name
  --email ADDRESS          An email address with which to register an account
  --terms URL              The terms param of the registration request
  --skip-dhparams          Don't generate DH params for combined cert
  --staging                Use staging servers instead of live servers
                           (generated certificates will not be trusted!)
  --skip-provision-check   Don't test whether HTTP provisioning works before
                           making ACME requests; only useful for testing.

This program can be used to obtain a certificate from the Let's Encrypt certificate authority, using their ACME protocol.

Simplest usage is to specify only the mandatory options, along with an email address to register:

DOMAIN=yourdomain.com

acme-certify --email          webmaster@${DOMAIN} \
             --key            webmaster@${DOMAIN}.key \
             --domain             ${DOMAIN} \
             --domain         www.${DOMAIN} \
             --challenge-dir  /var/www/html/.well-known/acme-challenge

ls -l ${DOMAIN}/cert.combined.pem ${DOMAIN}/cert.pem

You must have write permission to /var/www/html/.well-known/acme-challenge for that to work.

(Of course, there also must be a web server hosting your domains from /var/www/html.)

Multiple Domains & Rate Limits

This tool supports multiple domain names per certificate. Note that Let's Encrypt will not sign a certificate with more than 100 names; nor will it allow more than 100 names to be signed for a single domain (no matter how many certificates the names are spread across). Furthermore, you can only issue 5 certificates per domain per week.

The Let's Encrypt community documentation contains more information about rate limits.

User account keys

Under ACME, each certificate request is associated with a private key used to sign communications with the ACME server. The key is furthermore associated with an email address.

Note: Let's Encrypt requires that this key be different from the key used for the certificate.

Use the --email command line argument to specify an email address to associate with a private key. If there is no private key, one will be generated; otherwise, the existing one will be used. This only needs to be done once per private key.

Currently, only RSA keys are supported by this tool. You can generate compatible keys like this:

openssl genrsa 4096 > user.key
mkdir -p ${DOMAIN}
openssl genrsa 4096 > ${DOMAIN}/rsa.key

Generated certificate

The signed certificate will be saved by this program in ./${DOMAIN}/cert.pem. A combined certificate -- containing the issuer certificate, the private key, and (by default) DH parameters -- will be saved in ./${DOMAIN}/cert.combined.pem. You can copy that file to the place your TLS server is configured to read it.

You can also view the certificate like so:

openssl x509 -in ${DOMAIN}/cert.pem -noout -text | less

DH Params

Vo Minh Thu, the original author of this program, suggests to include explicit DH key exchange parameters to prevent the Logjam attack. This is now automatically performed by default.

Generating DH params is CPU-intensive and takes a long time. For that reason, it is done once per domain, and the result is saved in ${DOMAIN}/dhparams.pem for reuse.

You can disable DH generation it with --skip-dhparams.

The certificate is generated by this program equivalently to this:

openssl dhparam -out ${DOMAIN}/dhparams.pem 2048
cat ${DOMAIN}/cert.pem \
    lets-encrypt-x1-cross-signed.pem \
    ${DOMAIN}/rsa.key \
    ${DOMAIN}/dhparams.pem > ${DOMAIN}/cert.combined.pem