# `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](https://letsencrypt.org/) 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](https://community.letsencrypt.org/t/rate-limits-for-lets-encrypt/6769).

## 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](https://weakdh.org/).
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
```