Certbot (letsencrypt | letsencrypt-auto)

About

Certbot is a fully-featured, extensible client for the Let’s Encrypt CA (or any other CA) that speaks the ACME protocol) that can automate the tasks of obtaining certificates and configuring webservers to use them.

Certbot is an easy-to-use client that fetches a certificate from Let’s Encrypt—an open certificate authority launched by the EFF, Mozilla, and others—and deploys it to a web server.

Before May 2016, Certbot was knwon as:

  • letsencrypt
  • or letsencrypt-auto

Usage

  • Certbot runs on Unix-based operating systems
  • you’ll need root or administrator access to your web server to run Certbot.
  • Certbot is meant to be run directly on your web server
  • Only for admin: Certbot allows its user to specify arbitrary file locations and run arbitrary scripts.

Plugin

A plugin can be:

  • an authenticator
  • or/and an installer

Plugins that do both can be used with the certbot run command, which is the default when no command is specified.

See list of plugin an their challenge at Getting certificates (and choosing plugins)

Challenge:

  • http-01 (port 80) providing a file at a path
  • Dns-01 provision a TXT record containing a designated value under a specific validation domain name.

Authenticator

Authenticators are plugins used with the certonly command to obtain a certificate. The authenticator validates that you control the domain(s) you are requesting a certificate for, obtains a certificate for the specified domain(s), and places the certificate in the /etc/letsencrypt directory on your machine. The authenticator does not install the certificate (it does not edit any of your server’s configuration files to serve the obtained certificate). If you specify multiple domains to authenticate, they will all be listed in a single certificate.

Installers

Installers are Plugins used with the install command to install a certificate. These plugins can modify your webserver’s configuration to serve your website over HTTPS using certificates obtained by certbot.

Files

Let’s Encrypt CA issues short-lived certificates (90 days). Make sure you renew the certificates at least once in 3 months.

Doc

All generated keys and issued certificates can be found in /etc/letsencrypt/live/$domain where $domain is the first domain passed in via -d parameter

/etc/letsencrypt/archive and /etc/letsencrypt/keys contain all previous keys and certificates, while /etc/letsencrypt/live symlinks to the latest versions.

All files are PEM-encoded

The following files are available:

  • privkey.pem Private key for the certificate that the server will read to enable TLS/SSL
    • Apache: SSLCertificateKeyFile,
    • Nginx: ssl_certificate_key.
  • fullchain.pem - All certificates, including server certificate (aka leaf certificate or end-entity certificate). The server certificate is the first one in this file, followed by any intermediates.
    • Apache >= 2.4.8: SSLCertificateFile,
    • Nginx: ssl_certificate.
  • cert.pem and chain.pem (less common - needs to provide both)
    • cert.pem contains the server certificate by itself,
    • chain.pem contains the additional intermediate certificate in the chain to validate the certificate
    • Apache < 2.4.8 needs these for SSLCertificateFile. and SSLCertificateChainFile, respectively.
    • Nginx: chain.pem should be provided as the ssl_trusted_certificate to validate OCSP responses. If you’re using OCSP stapling with Nginx >= 1.3.7,

Verification

You can verify the certificate with the following command:

cd /etc/letsencrypt/live/$domain
# then
openssl verify -untrusted  chain.pem -verbose fullchain.pem
#or
openssl verify -untrusted  chain.pem -verbose cert.pem
# or without untrusted by building the full chain
wget  https://letsencrypt.org/certs/trustid-x3-root.pem.txt
cat chain.pem trustid-x3-root.pem.txt > completechain.pem
openssl verify -CAfile completechain.pem -verbose  fullchain.pem

where:

  • untrusted was added because the intermediate letsencrypt certificate is not in the ca certificate but its root well.

Output:

fullchain.pem: OK
# or
cert.pem: OK

Command

Usage

certbot --help
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

  certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...

Certbot can obtain and install HTTPS/TLS/SSL certificates.  By default,
it will attempt to use a webserver both for obtaining and installing the
certificate. The most common SUBCOMMANDS and flags are:

obtain, install, and renew certificates:
    (default) run   Obtain & install a certificate in your current webserver
    certonly        Obtain or renew a certificate, but do not install it
    renew           Renew all previously obtained certificates that are near
expiry
    enhance         Add security enhancements to your existing configuration
   -d DOMAINS       Comma-separated list of domains to obtain a certificate for

  (the certbot apache plugin is not installed)
  --standalone      Run a standalone webserver for authentication
  --nginx           Use the Nginx plugin for authentication & installation
  --webroot         Place files in a server's webroot folder for authentication
  --manual          Obtain certificates interactively, or using shell script
hooks

   -n               Run non-interactively
  --test-cert       Obtain a test certificate from a staging server
  --dry-run         Test "renew" or "certonly" without saving any certificates
to disk

manage certificates:
    certificates    Display information about certificates you have from Certbot
    revoke          Revoke a certificate (supply --cert-path or --cert-name)
    delete          Delete a certificate

manage your account:
    register        Create an ACME account
    unregister      Deactivate an ACME account
    update_account  Update an ACME account
  --agree-tos       Agree to the ACME server's Subscriber Agreement
   -m EMAIL         Email address for important account notifications

More detailed help:

  -h, --help [TOPIC]    print this message, or detailed help on a topic;
                        the available TOPICS are:

   all, automation, commands, paths, security, testing, or any of the
   subcommands or plugins (certonly, renew, install, register, nginx,
   apache, standalone, webroot, etc.)
  -h all                print a detailed help page including all topics
  --version             print the version number
- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -

Nginx

certbot --help nginx
usage:
  certbot [SUBCOMMAND] [options] [-d DOMAIN] [-d DOMAIN] ...

Certbot can obtain and install HTTPS/TLS/SSL certificates.  By default,
it will attempt to use a webserver both for obtaining and installing the
certificate.

optional arguments:
  -h, --help            show this help message and exit
  -c CONFIG_FILE, --config CONFIG_FILE
                        path to config file (default: /etc/letsencrypt/cli.ini
                        and ~/.config/letsencrypt/cli.ini)
  --https-port HTTPS_PORT
                        Port used to serve HTTPS. This affects which port
                        Nginx will listen on after a LE certificate is
                        installed. (default: 443)

nginx:
  Nginx Web Server plugin

  --nginx-server-root NGINX_SERVER_ROOT
                        Nginx server root directory. (default: /etc/nginx)
  --nginx-ctl NGINX_CTL
                        Path to the 'nginx' binary, used for 'configtest' and
                        retrieving nginx version number. (default: nginx)

Renew

To non-interactively renew *all* of your certificates, run

certbot renew

Installation

Glossary

expand

expand means that you will add a domain to a certificate.

Support

0001 directory

When playing with certbot, you may see the certificate in 0001 directory.

Resolution:

cd /etc/letsencrypt
rm -rf live
rm -rf renewal
rm -rf archive

and rerun your code

Documentation / Reference


Powered by ComboStrap