LETSKENCRYPT(1)

NAME
letskencrypt - secure Let's Encrypt client

SYNOPSIS
letskencrypt [-Fmnrsv] [-C challengedir] [-c certdir] [-f accountkey] [-k domainkey] domain [altnames...]

DESCRIPTION
The letskencrypt utility submits an X509 certificate for domain and its alternate DNS names altnames to a “Let's Encrypt” server for automated signing. It can also revoke previously-submitted signatures. It must be run as root. (Why? chroot(2).)

By default, it uses /var/www/letsencrypt for responding to challenges (-C), /etc/ssl/letsencrypt for the public certificate directory (-c), /etc/ssl/letsencrypt/private/privkey.pem for the domain private key (-k), and /etc/letsencrypt/privkey.pem for the account private key (-f). Its arguments are as follows:

-F  Force updating the certificate signature even if it's too soon.

-m  Append domain to all default paths except the challenge path (i.e., those that are overriden by -c, -k, -f). Thus, foo.com as the initial domain would make the default domain private key into /etc/ssl/letsencrypt/private/foo.com/privkey.pem. This is useful in setups with multiple domain sets.

-n  Create a new RSA account key. This will fail if a file already exists in the account key's place.

-r  Revoke the X509 certificate found in Certificates.

-s  Use the “Let's Encrypt” staging server instead of the real thing.

-v  Verbose operation. Specify twice to also trace communication and data transfers.

-C challengedir
    Where to register challenges. See Challenges for details.

-c certdir
    Where to put public certificates. See Certificates for details.

-f accountkey
    The account private key. This was either made with a previous “Let's Encrypt” client or with -n.

-k domainkey
    The private key for the domain.

domain
    The domain name. The only difference between this and the altnames is that it's put into the certificate's CN field.

altnames
    Alternative names (“SAN”) for the domain name. The number of SAN entries is limited by “Let's Encrypt” to 100 or so.

The process by which letskencrypt obtains signed certificates is roughly as follows. In this, the “CA” is the ACME server for Let's Encrypt.

1.  Access the CA (unauthenticated) and requests its list of resources.

2.  Optionally create and register a new RSA account key.

3.  Read and process the RSA account key. This is used to authenticate each subsequent communication to the CA.

4.  For each domain name,

    1.  submit a challenge for authentication to the CA,

    2.  create a challenge response file,

    3.  wait until the CA has verified the challenge.

5.  Read and extract the domain key.

6.  Create an X509 request from the doman key for the domain and its alternative names.

7.  Submit a request for signature to the CA.

8.  Download the signed X509 certificate.

9.  Extract the CA issuer from the X509 certificate.

10. Download the certificate chain from the issuer.

The revocation sequence is similar:

1.  Request list of resources, manage RSA account key as in the case for signing.

2.  Read and extract the X509 certificate (if found).

3.  Create an X509 revocation request.

4.  Submit a request for revocation to the CA.

5.  Remove the certificate, the chain, and the full-chain.

  Challenges
Let's Encrypt uses challenges to verify that the submitter has access to the registered domains. letskencrypt implements only the “http-01” challenge type, where a file is created within a directory accessible by a locally-run web server configured for the requested domain. For example, for the domain “foo.com” and alternate “www.foo.com” and the default challenge directory, an Apache configuration snippet might be as follows:

    <VirtualHost *:80>
      [...]
      ServerName foo.com
      ServerAlias www.foo.com
      Alias /.well-known/acme-challenge /var/www/letsencrypt
      <Directory /var/www/letsencrypt>
        Options None
        AllowOverride None
        Order allow,deny
        Allow from all
      </Directory>
    </VirtualHost>

This way, the files placed in /var/www/letsencrypt will be properly mapped by the web server when the Let's Encrypt responds to a challenge.

  Certificates
Public certificates (domain certificate, chain, and the full-chain) are placed by default in /etc/ssl/letsencrypt as cert.pem, chain.pem, and fullchain.pem, respectively. These are all created as the root user with mode 444.

An nginx configuration using these might be as follows:

    server {
      listen 443;
      server_name foo.com www.foo.com;
      [...]
      ssl_certificate /etc/ssl/letsencrypt/fullchain.pem;
      ssl_certificate_key /etc/ssl/letsencrypt/private/privkey.pem;
    }

The cert.pem file, if found, is checked for its expiration: if more than 30 days from expiring, letskencrypt will not attempt to refresh the signature.

SEE ALSO
openssl(1)

BUGS
The challenge and certificate processes currently retain their (root) privileges.

For the time being, letskencrypt only supports RSA as an account key format.