ACME protocol automatic certitificate manager.
This tool acquires and maintains certificates from a certificate authority using the ACME protocol, similar to EFF's Certbot. While developed and tested using Let's Encrypt, the tool should work with any certificate authority using the ACME protocol.
This tool is not intended as a replacement for Certbot and does not attempt to replicate all of Certbot's functionality, notably it does not modify configuration files of other services, or provide a server to perform stand-alone domain validation. It does however, do a few things that Certbot does not, simplifying certificate management in more advanced environments. In addition to automatically issuing and maintaining certificates, the tool can also maintain associated HPKP headers and TLSA (DANE) records.
This tool separates the authorization (domain validation) and certificate issuance processes allowing one machine to maintain authorizations (the master), while another machine issues certificates (the follower). This is useful for situations where an isolated server is providing a service, such as XMPP, behind a firewall and does not have the ability to perform authorizations over http or configure DNS records, but still needs to obtain and periodically renew one or more certificates.
This tool allows multiple certificates to be defined using the same public/private key pair.
When deploying Hypertext Puplic Key Pinning (HPKP), you can optionally use the same pins to secure subdomains. This increases security of the site because a visitor to a root domain will have previously obtained pins for subdomains, reducing the possibility of a man-in-the-middle attacker installing a false pin on first visit.
This practice obviously requires the use of the same public/private key pair for the domain and all subdomains. However, it may not be desirable to use the same certificate for all subdomains, for example, exposing the full list of subdomains in the alternative names of the root domain's certificate, or reissuing the root domain's certificate every time a subdomain is added or removed.
This tool automatically generates and maintains HPKP header information suitable to be directly included in server configuraton files. Support for Apache and Nginx are provided by default, other servers may be added by the user.
Using HPKP requires a second public key to provide a backup when private keys are changed. This tool automatically generates backup keys and switches to the pre-generated backup key when rolling over private keys. Rolling over private keys can be done automatically and is scheduled independently of certificate expiration. Private key rollover is prevented in cases where insufficient time has passed to distribute backup HPKP pins.
This tool can generate both RSA and ECDSA certificates. By default it will generate and maintain both types of certificates in parallel.
This tool can automatically register your certificates with multiple certificate transparency logs and retrieve Signed Certificate Timestamps (SCTs) for each. The retrieved SCTs are suitable to be deilvered via a TLS extension, SCT TLS extension modules are available for Apache and Nginx.
This tool automatically obtains and maintains OCSP response files for each configured certificate. These files may be used to serve stapled OCSP responses from your server without relying on the server's OCSP stapling mechanisms. Some servers, such as Nginx, obtain stapled OCSP responses lazily and cache the response in memory. When using the OCSP Must-Staple extension this can result in your server being unreachable until the OCSP response is refreshed, during OCSP responder outages, this can be a significant interval. Using OCSP responses from disk will alleviate this issue. Only OCSP responses with a "good" status will be stored.
Primary and backup private keys can optionally be encrypted using a passphrase and cipher of your choice.
By default this tool performs dns-01 authorizartions for domain validation. It is possible to configure overrides for specific domains names to use http-01 authorization instead. This is useful for situations where a domain outside your immediate control has provided an alias to your web site.
This tool can automatically add and remove DNS records for dns-01 authorizations as well as TLSA records.
Updates to a local server can be made via an external zone file processor, such as bindtool,
or to a remote DNS server via RFC 2136 dynamic DNS updates using nsupdate
.
The choice between local and remote DNS updates can be made on a zone by zone basis.
Server administrators often develop their own file naming conventions or need to match naming conventions of other tools. The names and output directories of all certificate, key, and related files are fully configurable. The defaults are intended for standard Debian installations.
Each operation that writes key, certificate, or related files have optional hooks that can call user-specified programs to assist in deploying resources to remote servers or coordinating with other tooling.
This tool can automatically connect to configured servers and verify that the generated certificates are properly served via TLS. Additional checks are made for OSCP staples and optionally HPKP headers can be verified as well.
This tool supports services running both ACME V1 and ACME V2 APIs. Wildcard certrificates may be issued when using the V2 API.
Requires Python 3.7+ and the OpenSSL support.
On Debian Stretch and later:
sudo apt-get install python3-pip libssl-dev libffi-dev sudo pip3 install acmebot
You may want to create a virtual environment and install acmebot there.
Copy either the acmebot.example.json
file or the acmebot.example.yaml
file to acmebot.json
(or acmebot.yaml
) and edit the configuration options.
The configuration file can be placed in the current directory that the tool is run from,
the /etc/acmebot directory,
or the same directory that the acmebot tool is installed in.
By default, debug level output will be written to a log file. A configuration file for logrotate is provided in the logrotate.d directory, you may want to copy, or create a link to this file in /etc/logrotate.d.
Note that when using dns-01 authorizations via a local DNS server, this tool needs to be able to add, remove, and update DNS records. This can be achieved by installing it on your master DNS server and using bindtool to manage the zone file, or you can use a custom shell script to update the DNS records.
When using dns-01 authorizations via a remote server, an update key allowing the creation and deletion of TXT and optionally TLSA record types is required.
Optional: some services require a full certificate chain including the root (OSCP stapling on Nginx, for example).
In order to generate these files,
place a copy of the root certificates from your certificate authority of choice in the same directory as the configuration file with the file names root_cert.rsa.pem
and root_cert.ecdsa.pem
for RSA and ECDSA certificate roots respectively.
Note that the root certificates are the those used to sign RSA and ECDSA client certificates,
and may not necessarily be of the same type,
e.g. Let's Encrypt currently signs ECDSA certificates with an RSA root.
If your certificate authority uses RSA certificate to sign ECDSA certificates types, place that RSA root certificate in root_cert.ecdsa.pem
.
The root certificate for Let's Encrypt can be obtained here.
Starting with version 2.0.0 of this tool, the Let's Encrypt ACME V2 API is used by default. When upgrading to version 2.0.0+, or otherwise changing API endpoints, the client key is regenerated and a new registration is performed. If running in master/follower mode, be sure to run the tool on the master first, then copy the new client key and registration files to the followers before running on the followers. Existing private keys and certificates may continue to be used.
While the example configuration file may appear complicated, it is meant to show all possible configuration options and their defaults, rather than demonstrate a basic simple configuration.
The only items that must be present in the configuration file to create and maintain a certificate are your account email address, and the file name for the certificate. By default, the common name of the certificate will be the same as the certificate file name.
For example:
{ "account": { "email": "admin@example.com" }, "certificates": { "example.com": { "alt_names": { "example.com": ["@", "www"] } } } }
will create a certificate named example.com
,
with the common name of example.com
,
and the subject alternative names of example.com
and www.example.com
.
As many certificates as desired may be configured.
The number of alternative names is limited by the certificate authority (Let's Encrypt currently allows 100).
Alternative names are specified on a DNS zone basis,
multiple zones may be specified per certificate.
The host name "@"
is used for the name of the zone itself.
By default, the tool will attempt dns-01 domain authorizations for every alternative name specified, using local DNS updates. See the later sections on configuring local or remote DNS updates.
To use http-01 authorizations instead,
configure the http_challenges
section of the configuration file specifying a challenge directory for each fully qualified host name.
For example:
{ ... "http_challenges": { "example.com": "/var/www/htdocs/.well-known/acme-challenge", "www.example.com": "/var/www/htdocs/.well-known/acme-challenge" } }
See the HTTP Challenges section for more information.
Once the configuration file is in place, simply execute the tool. For the first run you may wish to select detailed output to see exactly what the tool is doing:
acmebot --detail
If all goes well, the tool will generate a public/private key pair used for client authentication to the certificate authority, register an account with the certificate authority, prompt to accept the certificate authority's terms of service, obtain authorizations for each configured domain name, generate primary private keys as needed for the configured certificates, issue certificates, generate backup private keys, generate custom Diffie-Hellman parameters, retrieve Signed Certificate Timestamps from certificate transparency logs, retrieve an OCSP response from the certificate authority, and install the certificates and private keys into /etc/ssl/certs and /etc/ssl/private.
If desired, you can test the tool using Let's Encrypt's staging server.
To do this, specify the staging server's directory URL in the acme_directory_url
setting.
See Staging Environment for details.
When switching from the staging to production servers,
you should delete the client key and registration files (/var/local/acmebot/*.json) to ensure a fresh registration in the production environment.
After a successful certificate issuance, up to twenty one files will be created per certificate.
The locations for these files can be controlled via the directories
section of the configuration file.
The default locations are used here for brevity.
Output files will be written as a single transaction, either all files will be written, or no files will be written. This is designed to prevent a mismatch between certificates and private keys should an error happen during file creation.
Two private key files will be created in /etc/ssl/private for each key type.
The primary: <private-key-name>.<key-type>.key
; and a backup key: <private-key-name>_backup.<key-type>.key
.
The private key files will be written in PEM format and will be readable by owner and group.
Two certificate files will be created for each key type,
one in /etc/ssl/certs, named <certificate-name>.<key-type>.pem
,
containing the certificate,
followed by any intermediate certificates sent by the certificate authority,
followed by custom Diffie-Hellman and elliptic curve paramaters;
the second file will be created in /etc/ssl/private, named <certificate-name>_full.<key-type>.key
,
and will contain the private key,
followed by the certificate,
followed by any intermediate certificates sent by the certificate authority,
followed by custom Diffie-Hellman and elliptic curve paramaters.
The <certificate-name>_full.<key-type>.key
file is useful for services that require both the private key and certificate to be in the same file,
such as ZNC.
If the certificate authority uses intermediate certificates to sign your certificates,
a file will be created in /etc/ssl/certs, named <certificate-name>_chain.<key-type>.pem
for each key type,
containing the intermediate certificates sent by the certificate authority.
This file will not be created if the chain
directory is set to null
.
Note that the certificate authority may use a different type of certificate as intermediates, e.g. an ECDSA client certificate may be signed by an RSA intermediate, and therefore the intermediate certificate key type may not match the file name (or certificate type).
If the root_cert.<key-type>.pem
file is present (see Installation),
then an additional certificate file will be generated in /etc/ssl/certs,
named <certificate-name>+root.<key-type>.pem
for each key type.
This file will contain the certificate,
followed by any intermediate certificates sent by the certificate authority,
followed by the root certificate,
followed by custom Diffie-Hellman and elliptic curve paramaters.
If the root_cert.<key-type>.pem
file is not found in the same directory as the configuration file,
this certificate file will not be created.
This file is useful for configuring OSCP stapling on Nginx servers.
If custom Diffie-Hellman parameters or a custom elliptical curve are configured,
a file will be created in /etc/ssl/params, named <certificate-name>_param.pem
,
containing the Diffie-Hellman parameters and elliptical curve paramaters.
This file will not be created if the param
directory is set to null
.
Two additional files will be created in /etc/ssl/hpkp, named <private-key-name>.apache
and <private-key-name>.nginx
.
These files contain HTTP header directives setting HPKP for both the primary and backup private keys for each key type.
Each file is suitable to be included in the server configuration for either Apache or Nginx respectively.
Thess files will not be created if the hpkp
directory is set to null
.
One additional file will be created for each key type and configured certificate transparency log in /etc/ssl/scts/<certificate-name>/<key-type>/<log-name>.sct
.
These files contain SCT information in binary form suitable to be included in a TLS extension.
By default, SCTs will be retrieved from the Google Icarus and Google Pilot certificate transparency logs.
The Google Test Tube certificate transparency log can be used with the Let's Encrypt staging environment for testing.
One OCSP response file will be created for each key type,
in /etc/ssl/ocsp, named <certificate-name>.<key_type>.ocsp
.
These files contain OCSP responses in binary form suitable to be used as stapled OCSP responses.
Whenever exsiting files are replaced by subsequent runs of the tool, for example during certificate renewal or private key rollover, all existing files are preserved in the archive directory, /etc/ssl/archive.
Within the archive directory, a directory will be created with the name of the private key, containing a datestamped directory with the time of the file transaction (YYYY_MM_DD_HHMMSS). All existing files will be moved into the datestamped directory should they need to be recovered.
Because certificate files will be periodically replaced as certificates need to be renewed, it is best to have your server configurations simply refer to the certificate and key files in the locations they are created. This will prevent server configurations from having to be updated as certificate files are replaced.
If the server requires the certificate or key file to be in a particular location or have a different file name, it is best to simply create a soft link to the certificate or key file rather than rename or copy the files.
Another good practice it to isolate the configuration for each certificate into a snippet file, for example using Apache, create the file /etc/apache2/snippets/ssl/example.com containing:
SSLCertificateFile /etc/ssl/certs/example.com.rsa.pem SSLCertificateKeyFile /etc/ssl/private/example.com.rsa.key CTStaticSCTs /etc/ssl/certs/example.com.rsa.pem /etc/ssl/scts/example.com/rsa # requires mod_ssl_ct to be installed SSLCertificateFile /etc/ssl/certs/example.com.ecdsa.pem SSLCertificateKeyFile /etc/ssl/private/example.com.ecdsa.key CTStaticSCTs /etc/ssl/certs/example.com.ecdsa.pem /etc/ssl/scts/example.com/ecdsa # requires mod_ssl_ct to be installed Header always set Strict-Transport-Security "max-age=63072000" Include /etc/ssl/hpkp/example.com.apache
and then in each host configuration using that certificate, simply add:
Include snippets/ssl/example.com
For Nginx the /etc/nginx/snippets/ssl/example.com file would contain:
ssl_ct on; # requires nginx-ct module to be installed ssl_certificate /etc/ssl/certs/example.com.rsa.pem; ssl_certificate_key /etc/ssl/private/example.com.rsa.key; ssl_ct_static_scts /etc/ssl/scts/example.com/rsa; # requires nginx-ct module to be installed ssl_stapling_file /etc/ssl/ocsp/example.com.rsa.ocsp; ssl_certificate /etc/ssl/certs/example.com.ecdsa.pem; # requires nginx 1.11.0+ to use multiple certificates ssl_certificate_key /etc/ssl/private/example.com.ecdsa.key; ssl_ct_static_scts /etc/ssl/scts/example.com/ecdsa; # requires nginx-ct module to be installed ssl_stapling_file /etc/ssl/ocsp/example.com.ecdsa.ocsp; # requires nginx 1.13.3+ to use with multiple certificates ssl_trusted_certificate /etc/ssl/certs/example.com+root.rsa.pem; # not required if using ssl_stapling_file ssl_dhparam /etc/ssl/params/example.com_param.pem; ssl_ecdh_curve secp384r1; add_header Strict-Transport-Security "max-age=63072000" always; include /etc/ssl/hpkp/example.com.nginx;
and can be used via:
include snippets/ssl/example.com;
The configuration file acmebot.json
or acmebot.yaml
may be placed in the current working directory,
in /etc/acmebot,
or in the same directory as the acmebot tool is installed in.
A different configuration file name may be specified on the command line.
If the specified file name is not an absolute path,
it will be searched for in the same locations,
e.g. acmebot --config config.json
will load ./config.json
, /etc/acmebot/config.json
, or <install-dir>/config.json
.
If the file extension is omitted, the tool will search for a file with the extensions: .json
, .yaml
, and .yml
in each location.
If the speficied file is an absolute path,
only that location will be searched.
Additional configuration files may be placed in a subdirectory named conf.d
in the same directory as the configuration file.
All files with the extensions: .json
, .yaml
, or .yml
in that subdirectory will be loaded and merged into the configuration,
overriding any settings in the main configuration file.
For example,
the configurtaion for each certificate may be placed in a separate file,
while the common settings remain in the main configuration file.
The configuration file must adhere to standard JSON or YAML formats. The examples given in this document are in JSON format, however, the equivalent structures may be expressed in YAML.
The files acmebot.example.json
and acmebot.example.yaml
provide a template of all configuration options and their default values.
Entries inside angle brackets "<example>"
must be replaced (without the angle brackets),
all other values may be removed unless you want to override the default values.
Enter the email address you wish to associate with your account on the certificate authority. This email address may be useful in recovering your account should you lose access to your client key.
Example:
{ "account": { "email": "admin@example.com" }, ... }
Various settings for the tool. All of these need only be present when the desired value is different from the default.
follower_mode
specifies if the tool should run in master or follower mode. The defalt value isfalse
(master mode). The master will obtain authorizations and issue certificates, a follower will not attempt to obtain authorizations but can issue certificates.log_level
specifies the amount of information written into the log file. Possible values arenull
,"normal"
,"verbose"
,"debug"
, and"detail"
."verbose"
,"debug"
, and"detail"
settings correlate to the--verbose
,--debug
and--detail
command-line options.color_output
specifies if the output should be colorized. Colorized output will be suppressed on non-tty devices. This option may be overridden via command line options. The default value istrue
.key_types
specifies the types of private keys to generate by default. The default value is['rsa', 'ecdsa']
.key_size
specifies the size (in bits) for RSA private keys. The default value is4096
. RSA certificates can be turned off by setting this value to0
ornull
.key_curve
specifies the curve to use for ECDSA private keys. The default value is"secp384r1"
. Available curves are"secp256r1"
,"secp384r1"
, and"secp521r1"
. ECDSA certificates can be turned off by setting this value tonull
.key_cipher
specifies the cipher algorithm used to encrypt private keys. The default value is"blowfish"
. Available ciphers are those accepted by your version of OpenSSL's EVP_get_cipherbyname().key_passphrase
specifies the passphrase used to encrypt private keys. The default value isnull
. A value ofnull
orfalse
will result in private keys being written unencrypted. A value oftrue
will cause the password to be read from the command line, the environment, a prompt, or stdin. A string value will be used as the passphrase without further input.key_provided
specifies that the private keys are provided from an external source and the tool should not modify them. The default value isfalse
.dhparam_size
specifies the size (in bits) for custom Diffie-Hellman parameters. The default value is2048
. Custom Diffie-Hellman parameters can be turned off by setting this value to0
ornull
. This value should be at least be equal to half thekey_size
.ecparam_curve
speficies the curve or list of curves to use for ECDHE negotiation. This value may be a string or a list of strings. The default value is["secp521r1", "secp384r1", "secp256k1"]
. Custom EC parameters can be turned off by setting this value tonull
. You can runopenssl ecparam -list_curves
to find a list of available curves.file_user
specifies the name of the user that will own certificate and private key files. The default value is"root"
. Note that this tool must run as root, or another user that has rights to set the file ownership to this user.file_group
speficies the name of the group that will own certificate and private key files. The default value is"ssl-cert"
. Note that this tool must run as root, or another user that has rights to set the file ownership to this group.log_user
specifies the name of the user that will own log files. The default value is"root"
. Note that this tool must run as root, or another user that has rights to set the file ownership to this user.log_group
speficies the name of the group that will own log files. The default value is"adm"
. Note that this tool must run as root, or another user that has rights to set the file ownership to this group.warning_exit_code
specifies if warnings will produce a non-zero exit code. The default value isfalse
.hpkp_days
specifies the number of days that HPKP pins should be cached for. The default value is60
. HPKP pin files can be turned off by setting this value to0
ornull
.pin_subdomains
specifies whether theincludeSubdomains
directive should be included in the HPKP headers. The default value istrue
.hpkp_report_uri
specifies the uri to report HPKP failures to. The default value isnull
. If not null, thereport-uri
directive will be included in the HPKP headers.ocsp_must_staple
specifies if the OCSP Must-Staple extension is added to certificates. The default value isfalse
.ocsp_responder_urls
specifies the list of OCSP responders to use if a certificate doesn't provide them. The default value is["http://ocsp.int-x3.letsencrypt.org"]
.ct_submit_logs
specifies the list of certificate transparency logs to submit certificates to. The default value is["google_icarus", "google_pilot"]
. The value["google_testtube"]
can be used with the Let's Encrypt staging environment for testing.renewal_days
specifies the number of days before expiration when the tool will attempt to renew a certificate. The default value is30
.expiration_days
specifies the number of days that private keys should be used for. The dafault value is730
(two years). When the backup key reaches this age, the tool will notify the user that a key rollover should be performed, or automatically rollover the private key ifauto_rollover
is set totrue
. Automatic rollover and expiration notices can be disabled by setting this to0
ornull
.auto_rollover
specifies if the tool should automatically rollover private keys that have expired. The default value isfalse
. Note that when running in a master/follower configuration and sharing private keys between the master and follower, key rollovers must be performed on the master and manually transferred to the follower, therefore automatic rollovers should not be used unless running stand-alone.max_dns_lookup_attempts
specifies the number of times to check for deployed DNS records before attempting authorizations. The default value is60
.dns_lookup_delay
specifies the number of seconds to wait between DNS lookups. The default value is10
.max_domains_per_order
specifies the maximum number of domains allowed per authorization order. The default value is100
, which is the limit set by Let's Encrypt.max_authorization_attempts
specifies the number of times to check for completed authorizations. The default value is30
.authorization_delay
specifies the number of seconds to wait between authorization checks. The default value is10
.cert_poll_time
specifies the number of seconds to wait for a certificate to be issued. The default value is30
.max_ocsp_verify_attempts
specifies the number of times to check for OCSP staples during verification. Retries will only happen when the certificate has the OCSP Must-Staple extension. The default value is10
.ocsp_verify_retry_delay
specifies the number of seconds to wait between OCSP staple verification attempts. The default value is5
.min_run_delay
specifies the minimum number of seconds to wait if the--randomwait
command line option is present. The default value is300
.max_run_delay
specifies the maximum number of seconds to wait if the--randomwait
command line option is present. The default value is3600
.acme_directory_url
specifies the primary URL for the ACME service. The default value is"https://acme-v02.api.letsencrypt.org/directory"
, the Let's Encrypt production API. You can substitute the URL for Let's Encrypt's staging environment or another certificate authority.acme_directory_verify_ssl
specifies whether or not to verify the certificate of the ACME service. The default value isTrue
. Setting this toFalse
is not recommneded, but may be necessary in environments using a private ACME server.reload_zone_command
specifies the command to execute to reload local DNS zone information. When using bindtool the"reload-zone.sh"
script provides this service. If not using local DNS updates, you may set this tonull
to avoid warnings.nsupdate_command
specifies the command to perform DNS updates. The default value is"/usr/bin/nsupdate"
.verify
specifies the default ports to perform installation verification on. The default value isnull
.services
specifies the default services to associate with certificates. The default value isnull
.
Example:
{ ... "settings": { "follower_mode": false, "log_level": "debug", "key_size": 4096, "key_curve": "secp384r1", "key_cipher": "blowfish", "key_passphrase": null, "key_provided": false, "dhparam_size": 2048, "ecparam_curve": ["secp521r1", "secp384r1", "secp256k1"], "file_user": "root", "file_group": "ssl-cert", "hpkp_days": 60, "pin_subdomains": true, "hpkp_report_uri": null, "ocsp_must_staple": false, "ocsp_responder_urls": ["http://ocsp.int-x3.letsencrypt.org"], "ct_submit_logs": ["google_icarus", "google_pilot"], "renewal_days": 30, "expiration_days": 730, "auto_rollover": false, "max_dns_lookup_attempts": 60, "dns_lookup_delay": 10, "max_authorization_attempts": 30, "authorization_delay": 10, "min_run_delay": 300, "max_run_delay": 3600, "acme_directory_url": "https://acme-v02.api.letsencrypt.org/directory", "reload_zone_command": "/etc/bind/reload-zone.sh", "nsupdate_command": "/usr/bin/nsupdate", "verify": [443] }, ... }
Directories used to store the input and output files of the tool. Relative paths will be considered relative to the directory of configuration file. All of these need only be present when the desired value is different from the default.
pid
specifies the directory to store a process ID file. The default value is"/var/run"
.log
specifies the directory to store the log file. The default value is"/var/log/acmebot"
.resource
specifies the directory to store the client key and registration files for the ACME account. The default value is"/var/local/acmebot"
.private_key
specifies the directory to store primary private key files. The default value is"/etc/ssl/private"
.backup_key
specifies the directory to store backup private key files. The default value is"/etc/ssl/private"
.previous_key
specifies the directory to store previously used private key files after key rollover. The default value isnull
.full_key
specifies the directory to store primary private key files that include the certificate chain. The default value is"/etc/ssl/private"
. Full key files may be omitted by setting this tonull
.certificate
specifies the directory to store certificate files. The default value is"/etc/ssl/certs"
.full_certificate
specifies the directory to store full chain certificate files that include the root certificate. The default value is"/etc/ssl/certs"
. Full certificate files may be omitted by setting this tonull
.chain
specifies the directory to store certificate intermediate chain files. The default value is"/etc/ssl/certs"
. Chain files may be omitted by setting this tonull
.param
specifies the directory to store Diffie-Hellman parameter files. The default value is"/etc/ssl/params"
. Paramater files may be omitted by setting this tonull
.challenge
specifies the directory to store ACME dns-01 challenge files. The default value is"/etc/ssl/challenge"
.http_challenge
specifies the directory to store ACME http-01 challenge files. The default value isnull
.hpkp
specifies the directory to store HPKP header files. The default value is"/etc/ssl/hpkp"
. HPKP header files may be turned off by setting this tonull
.sct
specifies the directory to store Signed Certificate Timestamp files. The default value is"/etc/ssl/scts/<certificate-name>/<key-type>"
. SCT files may be turned off by setting this tonull
.ocsp
specifies the directory to store OCSP response files. The default value is"/etc/ssl/ocsp"
. OCSP response files may be turned off by setting this tonull
.update_key
specifies the directory to search for DNS update key files. The default value is"/etc/ssl/update_keys"
.archive
specifies the directory to store older versions of files that are replaced by this tool. The default value is"/etc/ssl/archive"
.temp
specifies the directory to write temporary files to. A value ofnull
results in using the system defined temp directory. The temp directory must be on the same file system as the output file directories. The default value isnull
.
Example:
{ ... "directories": { "pid": "/var/run", "log": "/var/log/acmebot", "resource": "/var/local/acmebot", "private_key": "/etc/ssl/private", "backup_key": "/etc/ssl/private", "full_key": "/etc/ssl/private", "certificate": "/etc/ssl/certs", "full_certificate": "/etc/ssl/certs", "chain": "/etc/ssl/certs", "param": "/etc/ssl/params", "challenge": "/etc/ssl/challenges", "http_challenge": "/var/www/{zone}/{host}/.well-known/acme-challenge", "hpkp": "/etc/ssl/hpkp", "ocsp": "/etc/ssl/ocsp/", "sct": "/etc/ssl/scts/{name}/{key_type}", "update_key": "/etc/ssl/update_keys", "archive": "/etc/ssl/archive" }, ... }
Directory values are treated as Python format strings,
fields available for directories are: name
, key_type
, suffix
, server
.
The name
field is the name of the private key or certificate.
The "http_challenge"
directory uses the fields: zone
, host
, and fqdn
,
for the zone name, host name (without the zone), and the fully qualified domain name respectively.
The host
value will be "."
if the fqdn is the same as the zone name.
This specifies a list of services that are used by issued certificates and the commands necessary to restart or reload the service when a certificate is issued or changed. You may add or remove services as needed. The list of services is arbritrary and they are referenced from individual certificate definitions.
Example:
{ ... "services": { "apache": "systemctl reload apache2", "coturn": "systemctl restart coturn", "dovecot": "systemctl restart dovecot", "etherpad": "systemctl restart etherpad", "mysql": "systemctl reload mysql", "nginx": "systemctl reload nginx", "postfix": "systemctl reload postfix", "postgresql": "systemctl reload postgresql", "prosody": "systemctl restart prosody", "slapd": "systemctl restart slapd", "synapse": "systemctl restart matrix-synapse", "znc": "systemctl restart znc" }, ... }
To specify one or more services used by a certificate,
add a services
section to the certificate definition listing the services using that certificate.
For example:
{ "certificates": { "example.com": { "alt_names": { "example.com": ["@", "www"] }, "services": ["nginx"] } } }
This will cause the command "systemctl reload nginx"
to be executed any time the certificate example.com
is issued, renewed, or updated.
This section defines the set of certificates to issue and maintain. The name of each certificate is used as the name of the certificate files.
common_name
specifies the common name for the certificate. If omitted, the name of the certificate will be used.alt_names
specifies the set of subject alternative names for the certificate. If specified, the common name of the certificate must be included as one of the alternative names. The alternative names are specified as a list of host names per DNS zone, so that associated DNS updates happen in the correct zone. The zone name may be used directly by specifying"@"
for the host name. Multiple zones may be specified. The default value is the common name of the certificate in the zone of the first registered domain name according to the Public Suffix List. For example, if the common name is "example.com", the defaultalt_names
will be:{"example.com": ["@"] }
; if the common name is "foo.bar.example.com", the defaultalt_names
will be:{ "example.com": ["foo.bar"] }
.services
specifies the list of services to be reloaded when the certificate is issued, renewed, or modified. This may be omitted. The default value is the value specified in thesettings
section.dhparam_size
specifies the number of bits to use for custom Diffie-Hellman paramaters for the certificate. The default value is the value specified in thesettings
section. Custom Diffie-Hellman paramaters may be ommitted from the certificate by setting this to0
ornull
. The value should be at least equal to half the number of bits used for the private key.ecparam_curve
specified the curve or curves used for elliptical curve paramaters. The default value is the value specified in thesettings
section. Custom elliptical curve paramaters may be ommitted from the certificate by setting this tonull
.key_types
specifies the types of keys to create for this certificate. The default value is all available key types. Provide a list of key types to restrict the certificate to only those types. Available types are"rsa"
and"ecdsa"
.key_size
specifies the number of bits to use for the certificate's RSA private key. The default value is the value specified in thesettings
section. RSA certificates can be turned off by setting this value to0
ornull
.key_curve
specifies the curve to use for ECDSA private keys. The default value is the value specified in thesettings
section. Available curves are"secp256r1"
,"secp384r1"
, and"secp521r1"
. ECDSA certificates can be turned off by setting this value tonull
.key_cipher
specifies the cipher algorithm used to encrypt the private keys. The default value is the value specified in thesettings
section. Available ciphers those accepted by your version of OpenSSL's EVP_get_cipherbyname().key_passphrase
specifies the passphrase used to encrypt private keys. The default value is the value specified in thesettings
section. A value ofnull
orfalse
will result in private keys being written unencrypted. A value oftrue
will cause the password to be read from the command line, the environment, a prompt, or stdin. A string value will be used as the passphrase without further input.key_provided
specifies that the private keys are provided from an external source and the tool should not modify them. The default value is the value specified in thesettings
section. This is useful when the same private keys are shared between multiple instances of the tool, e.g. for HPKP purposes.expiration_days
specifies the number of days that the backup private key should be considered valid. The default value is the value specified in thesettings
section. When the backup key reaches this age, the tool will notify the user that a key rollover should be performed, or automatically rollover the private key ifauto_rollover
is set totrue
. Automatic rollover and expiration notices can be disabled by setting this to0
ornull
.auto_rollover
specifies if the tool should automatically rollover the private key when it expires. The default value is the value specified in thesettings
section.hpkp_days
specifies the number of days that HPKP pins should be cached by clients. The default value is the value specified in thesettings
section. HPKP pin files can be turned off by setting this value to0
ornull
.pin_subdomains
specifies whether theincludeSubdomains
directive should be included in the HPKP headers. The default value is the value specified in thesettings
section.hpkp_report_uri
specifies the uri to report HPKP errors to. The default value is the value specified in thesettings
section. If not null, thereport-uri
directive will be included in the HPKP headers.ocsp_must_staple
specifies if the OCSP Must-Staple extension is added to certificates. The default value is the value specified in thesettings
section.ocsp_responder_urls
specifies the list of OCSP responders to use if a certificate doesn't provide them. The default value is the value specified in thesettings
section.ct_submit_logs
specifies the list of certificate transparency logs to submit the certificate to. The default value is the value specified in thesettings
section. The value["google_testtube"]
can be used with the Let's Encrypt staging environment for testing.verify
specifies the list of ports to perform certificate installation verification on. The default value is the value specified in thesettings
section.
Example:
{ ... "certificates": { "example.com": { "common_name": "example.com", "alt_names": { "example.com": ["@", "www"] }, "services": ["nginx"], "dhparam_size": 2048, "ecparam_curve": ["secp521r1", "secp384r1", "secp256k1"], "key_types": ["rsa", "ecdsa"], "key_size": 4096, "key_curve": "secp384r1", "key_cipher": "blowfish", "key_passphrase": null, "key_provided": false, "expiration_days": 730, "auto_rollover": false, "hpkp_days": 60, "pin_subdomains": true, "hpkp_report_uri": null, "ocsp_must_staple": false, "ocsp_responder_urls": ["http://ocsp.int-x3.letsencrypt.org"], "ct_submit_logs": ["google_icarus", "google_pilot"], "verify": [443] } } }
This section defines the set of private keys generated and their associated certificates. Multiple certificates may share a single private key. This is useful when it is desired to use different certificates for certain subdomains, while specifying HPKP headers for a root domain that also apply to subdomains.
The name of each private key is used as the file name for the private key files.
Note that a certificate configured in the certificates
section is equivalent to a private key configured in this section with a single certificate using the same name as the private key.
As such, it is an error to specify a certificate using the same name in both the certificates
and private_keys
sections.
The private key and certificate settings are identical to those specified in the certificates
section,
except settings relevant to the private key: key_size
, key_curve
, key_cipher
, key_passphrase
, key_provided
, expiration_days
, auto_rollover
, hpkp_days
, pin_subdomains
, and hpkp_report_uri
are specified in the private key object rather than the certificate object.
The key_types
setting may be specified in the certificate, private key, or both.
Example:
{ ... "private_keys": { "example.com": { "certificates": { "example.com": { "common_name": "example.com", "alt_names": { "example.com": ["@", "www"] }, "services": ["nginx"], "key_types": ["rsa"], "dhparam_size": 2048, "ecparam_curve": ["secp521r1", "secp384r1", "secp256k1"], "ocsp_must_staple": true, "ct_submit_logs": ["google_icarus", "google_pilot"], "verify": [443] }, "mail.example.com": { "alt_names": { "example.com": ["mail", "smtp"] }, "services": ["dovecot", "postfix"], "key_types": ["rsa", "ecdsa"] } }, "key_types": ["rsa", "ecdsa"], "key_size": 4096, "key_curve": "secp384r1", "key_cipher": "blowfish", "key_passphrase": null, "key_provided": false, "expiration_days": 730, "auto_rollover": false, "hpkp_days": 60, "pin_subdomains": true, "hpkp_report_uri": null } }, ... }
The above example will generate a single primary/backup private key set and two certificates, example.com
and mail.example.com
both using the same private keys.
An ECDSA certicicate will only be generated for mail.example.com
.
When using remote DNS updates, it is possible to have the tool automatically maintain TLSA records for each certificate. Note that this requires configuring zone update keys for each zone containing a TLSA record.
When using local DNS updates, the reload_zone
command will be called after certificates are issued, renewed, or modified to allow TLSA records to be updated by a tool such as bindtool.
The reload_zone
command will not be called in follower mode.
To specify TLSA records, add a tlsa_records
name/object pair to each certificate definition, either in the certificates
or private_keys
section.
TLSA records are specified per DNS zone, similar to alt_names
,
to specify which zone should be updated for each TLSA record.
For each zone in the TLSA record object, specify a list of either host name strings or objects. Using a host name string is equivalent to:
{ "host": "<host-name>" }
The values for the objects are:
host
specifies the host name for the TLSA record. The default value is"@"
. The host name"@"
is used for the name of the zone itself.port
specifies the port number for the TLSA record. The default value is443
.usage
is one of the following:"pkix-ta"
,"pkix-ee"
,"dane-ta"
, or"dane-ee"
. The default value is"pkix-ee"
. When specifying an end effector TLSA record ("pkix-ee"
or"dane-ee"
), the hash generated will be of the certificate or public key itself. When specifying a trust anchor TLSA record ("pkix-ta"
or"dane-ta"
), records will be generated for each of the intermediate and root certificates.selector
is one of the following:"cert"
, or"spki"
. The default value is"spki"
. When specifying a value of"spki"
and an end effector usage, records will be generated for both the primary and backup public keys.protocol
specifies the protocol for the TLSA record. The default value is"tcp"
.ttl
specifies the TTL value for the TLSA records. The default value is300
.
Example:
{ ... "private_keys": { "example.com": { "certificates": { "example.com": { "alt_names": { "example.com": ["@", "www"] }, "services": ["nginx"], "tlsa_records": { "example.com": [ "@", { "host": "www", "port": 443, "usage": "pkix-ee", "selector": "spki", "protocol": "tcp", "ttl": 300 } ] } }, "mail.example.com": { "alt_names": { "example.com": ["mail", "smtp"] }, "services": ["dovecot", "postfix"], "tlsa_records": { "example.com": [ { "host": "mail", "port": 993 }, { "host": "smtp", "port": 25, "usage": "dane-ee" }, { "host": "smtp", "port": 587 } } } } } } }, ... }
This section specifies a set of host name authorizations to obtain without issuing certificates.
This is used when running in a master/follower configuration, the master, having access to local or remote DNS updates or an HTTP server, obtains authorizations, while the follower issues the certificates.
It is not necessary to specify host name authorizations for any host names used by configured certificates, but it is not an error to have overlap.
Authorizations are specified per DNS zone so that associated DNS updates happen in the correct zone.
Simplar to alt-names
, a host name of "@"
may be used to specify the zone name.
Example:
{ ... "authorizations": { "example.com": ["@", "www"] }, ... }
By default, the tool will attempt dns-01 domain authorizations for every alternative name specified, using local or remote DNS updates.
To use http-01 authorizations instead,
configure the http_challenges
section of the configuration file specifying a challenge directory for each fully qualified domain name,
or configure a http_challenge
directory.
It is possible to mix usage of dns-01 and http-01 domain authorizations on a host by host basis, simply specify a http challenge directory only for those hosts requiring http-01 authentication.
Example:
{ ... "http_challenges": { "example.com": "/var/www/htdocs/.well-known/acme-challenge" "www.example.com": "/var/www/htdocs/.well-known/acme-challenge" }, ... }
The http_challenges
must specify a directory on the local file system such that files placed there will be served via an already running http server for each given domain name.
In the above example,
files placed in /var/www/htdocs/.well-known/acme-challenge
must be publicly available at:
http://example.com/.well-known/acme-challenge/file-name
and
http://www.example.com/.well-known/acme-challenge/file-name
Alternatively, if your are primarily using http-01 authorizations and all challenge directories have a similar path,
you may configure a single http_challenge
directory using a python format string with the fields zone
, host
, and fqdn
.
Example:
{ ... "directories": { "http_challenge": "/var/www/{zone}/{host}/.well-known/acme-challenge" }, ... }
If an http_challenge
directory is configured,
all domain authorizations will default to http-01.
To use dns-01 authorizations for selected domain names,
add an http_challenges
entry configured with a null
value.
When using remote DNS updates, it is necessary to specify a TSIG key used to sign the update requests.
For each zone using remote DNS udpates, specify either a string containing the file name of the TSIG key, or an object with further options.
The TSIG file name may an absolute path or a path relative to the update_key
directory setting.
Both the <key-file>.key
file and the <key-file>.private
files must be present.
Any zone referred to in a certificate, private key, or authorization that does not have a corresponding zone update key will use local DNS updates unless an HTTP challenge directory has been specified for every host in that zone.
file
specifies the name of the TSIG key file.server
specifies the name of the DNS server to send update requests to. If omitted, the primary name server from the zone's SOA record will be used.port
specifies the port to send update requests to. The default value is53
.
Example:
{ ... "zone_update_keys": { "example1.com": "update.example1.com.key", "example2.com": { "file": "update.example2.com.key", "server": "ns1.example2.com", "port": 53 } }, ... }
Each certificate and key file will have a suffix, just before the file extension, indicating the type of key the file is for.
The default suffix used for each key type can be overridden in the key_type_suffixes
section.
If you are only using a single key type, or want to omit the suffix from one key type,
set it to an empty string.
Note that if using multiple key types the suffix must be unique or files will be overridden.
Example:
{ ... "key_type_suffixes": { "rsa": ".rsa", "ecdsa": ".ecdsa" }, ... }
All output file names can be overridden using standard Python format strings.
Fields available for file names are: name
, key_type
, suffix
, server
.
The name
field is the name of the private key or certificate.
log
specifies the name of the log file.private_key
specifies the name of primary private key files.backup_key
specifies the name of backup private key files.full_key
specifies the name of primary private key files that include the certificate chain.certificate
specifies the name of certificate files.full_certificate
specifies the name of certificate files that include the root certificate.chain
specifies the name of intemediate certificate files.param
specifies the name of Diffie-Hellman parameter files.challenge
specifies the name of ACME challenge files used for local DNS updates.hpkp
specifies the name of HPKP header files.ocsp
specifies the name of OCSP response files.sct
specifies the name of SCT files.
Example:
{ ... "file_names": { "log": "acmebot.log", "private_key": "{name}{suffix}.key", "backup_key": "{name}_backup{suffix}.key", "full_key": "{name}_full{suffix}.key", "certificate": "{name}{suffix}.pem", "full_certificate": "{name}+root{suffix}.pem", "chain": "{name}_chain{suffix}.pem", "param": "{name}_param.pem", "challenge": "{name}", "hpkp": "{name}.{server}", "ocsp": "{name}{suffix}.ocsp", "sct": "{ct_log_name}.sct" }, ... }
This section defines the set of HPKP header files that will be generated and their contents.
Header files for additional servers can be added at will,
one file will be generated for each server.
Using standard Python format strings, the {header}
field will be replaced with the HPKP header,
the {key_name}
field will be replaced with the name of the private key,
and {server}
will be replaced with the server name.
The default servers can be omitted by setting the header to null
.
Example:
{ ... "hpkp_headers": { "apache": "Header always set Public-Key-Pins \"{header}\"\n", "nginx": "add_header Public-Key-Pins \"{header}\" always;\n" }, ... }
This section defines the set of certificate transparency logs available to submit certificates to and retrieve SCTs from. Additional logs can be aded at will. Each log definition requires the primary API URL of the log, and the log's ID in base64 format. A list of currently active logs and their IDs can be found at certificate-transparency.org.
Example:
{ ..., "ct_logs": { "google_pilot": { "url": "https://ct.googleapis.com/pilot", "id": "pLkJkLQYWBSHuxOizGdwCjw1mAT5G9+443fNDsgN3BA=" }, "google_icarus": { "url": "https://ct.googleapis.com/icarus", "id": "KTxRllTIOWW6qlD8WAfUt2+/WHopctykwwz05UVH9Hg=" } }, ... }
This section defines the set of hooks that can be called via the shell when given actions happen. Paramaters to hooks are specified using Python format strings. Fields available for each hook are described below. Output from the hooks will be captured in the log. Hooks returing a non-zero status code will generate warnings, but will not otherwise affect the operation of this tool.
set_dns_challenge
is called for each DNS challenge record that is set. Available fields aredomain
,zone
, andchallenge
.clear_dns_challenge
is called for each DNS challenge record that is removed. Available fields aredomain
,zone
, andchallenge
.dns_zone_update
is called when a DNS zone is updated via either local or remote updates. Available field iszone
.set_http_challenge
is called for each HTTP challenge file that is installed. Available fields aredomain
, andchallenge_file
.clear_http_challenge
is called for each HTTP challenge file that is removed. Available fields aredomain
, andchallenge_file
.private_key_rollover
is called when a private key is replaced by a backup private key. Available fields arekey_name
,key_type
,backup_key_file
,private_key_file
,previous_key_file
, andpassphrase
.private_key_installed
is called when a private key is installed. Available fields arekey_name
,key_type
,private_key_file
, andpassphrase
.backup_key_installed
is called when a backup private key is installed. Available fields arekey_name
,key_type
,backup_key_file
, andpassphrase
.previous_key_installed
is called when a previous private key is installed after key rollover. Available fields arekey_name
,key_type
,previous_key_file
, andpassphrase
.hpkp_header_installed
is called when a HPKP header file is installed. Available fields arekey_name
,server
,header
, andhpkp_file
.certificate_installed
is called when a certificate file is installed. Available fields arekey_name
,key_type
,certificate_name
, andcertificate_file
.full_certificate_installed
is called when a certificate file that includes the root is installed. Available fields arekey_name
,key_type
,certificate_name
, andfull_certificate_file
.chain_installed
is called when a certificate intermediate chain file is installed. Available fields arekey_name
,key_type
,certificate_name
, andchain_file
.full_key_installed
is called when a private key including the full certificate chain file is installed. Available fields arekey_name
,key_type
,certificate_name
, andfull_key_file
.params_installed
is called when a params file is installed. Available fields arekey_name
,certificate_name
, andparams_file
.sct_installed
is called when a SCT file is installed. Available fields arekey_name
,key_type
,certificate_name
,ct_log_name
, andsct_file
.ocsp_installed
is called when an OSCP file is installed. Available fields arekey_name
,key_type
,certificate_name
, andocsp_file
.
Example:
{ ... "hooks": { certificate_installed": "scp {certificate_file} remote-server:/etc/ssl/certs/" }, ... }
The tool may be configured to perform installation verification of certificates. When verifying installation, the tool will connect to every subject alternative host name for each certificate on all avaialable IP addresses, per each configured port, perform a TLS handshake, and compare the served certificate chain to the specified certificate.
Each configured port may be an integer port number, or an object specifying connection details.
When using an object, the avaialable fields are:
port
specifies the port number to connect to. Required.starttls
specifies the STARTTLS mechanism that should be used to initiate a TLS session. Allowed values are:null
,smtp
,pop3
,imap
,sieve
,ftp
,ldap
, andxmpp
. The default value isnull
.protocol
specifies the protocol used to obtain additional information to verify. Currently this can retrieve Public-Key-Pins http headers to ensure that they are properly set. Allowed values are:null
, andhttp
. The default value isnull
.hosts
specifies a list of fully qualified domain names to test. This allows testing only a subset of the alternative names specified for the certificate. Each host name must be present as an alternative name for the certificate. The default value is all alternative names.key_types
specifies a list of key types to test. This allows testing only a subset of the avaialable key types. The default value is all avaialable key types.
Example:
{ ... "verify": [ { "port": 443, "protocol": "http" }, { "port": 25, "starttls": "smtp", "hosts": "smtp.example.com", "key_types": "rsa" }, 993 ] ... }
In order to perform dns-01 authorizations, and to keep TLSA records up to date, the tool will need to be able to add, remove, and update various DNS records.
For updating DNS on a local server, this tool was designed to use a bind zone file pre-processor, such as bindtool, but may be used with another tool instead.
When using bindtool, be sure to configure bindtool's acme_path
to be equal to the value of the challenge
directory, so that it can find the ACME challenge files.
When the tool needs to update a DNS zone, it will call the configured reload_zone
command with the name of the zone as its argument.
When _acme-challenge records need to be set, a file will be placed in the challenge
directory with the name of the zone in question, e.g. /etc/ssl/challenges/example.com
.
The challenge file is a JSON format file containing a single object.
The name/value pairs of that object are the fully qualified domain names of the records needing to be set, and the values of the records, e.g.:
{ "www.example.com": "gfj9Xq...Rg85nM" }
Which should result in the following DNS record created in the zone:
_acme-challenge.www.example.com. 300 IN TXT "gfj9Xq...Rg85nM"
Note that domain names containing wildcards must have the wildcard component removed in the corresponding TXT record, e.g.:
{ "example.com": "jc87sd...kO89hG" "*.example.com": "gfj9Xq...Rg85nM" }
Must result in the following DNS records created in the zone:
_acme-challenge.example.com. 300 IN TXT "jc87sd...kO89hG" _acme-challenge.example.com. 300 IN TXT "gfj9Xq...Rg85nM"
If there is no file in the challenge
directory with the same name as the zone, all _acme-challenge records should be removed.
Any time the reload_zone
is called, it should also update any TLSA records asscoiated with the zone based on the certificates or private keys present.
All of these functions are provided automatically by bindtool via the use of {{acme:}}
and {{tlsa:}}
commands in the zone file.
For example, the zone file:
{{soa:ns1.example.com:admin@example.com}} {{ip4=192.0.2.0}} @ NS ns1 @ NS ns2 @ A {{ip4}} www A {{ip4}} {{tlsa:443}} {{tlsa:443:www}} {{acme:}} {{caa:letsencrypt.org}}
Will define the zone example.com
using the nameservers ns1.example.com
and ns1.example.com
, providing the hosts example.com
and www.example.com
, with TLSA records pinning the primary and backup keys.
If the tool is not run on a machine also hosting a DNS server, then http-01 authorizations or remote DNS updates must be used.
The use remote DNS udpates via RFC 2136 dynamic updates, configure a zone update key for each zone. See the Zone Update Keys section for more information.
It is also necesary to have the nsupdate
tool installed and the nsupdate_command
configured in the settings
configuration section.
Zone update keys may be generated via the dnssec-keygen
tool.
For example:
dnssec-keygen -r /dev/urandom -a HMAC-MD5 -b 512 -n HOST update.example.com
will generate two files, named Kupdate.example.com.+157+NNNNN.key and Kupdate.example.com.+157+NNNNN.private. Specify the .key file as the zone update key.
To configure bind to allow remote DNS updates, add an entry to named.conf.keys for the update key containg the key value from the private key file, e.g.:
key update.example.com. { algorithm hmac-md5; secret "sSeWrBDen...9WESlnEwQ=="; };
and then add an allow-update
entry to the zone configuration, e.g.:
zone "example.com" { type master; allow-update { key update.example.com.; }; ... };
On first run, the tool will generate a client key, register that key with the certificate authority, accept the certificate authority's terms and conditions, perform all needed domain authorizations, generate primary private keys, issue certificates, generate backup private keys, generate custom Diffie-Hellman parameters, install certificate and key files, update TLSA records, retrieve current Signed Certificate Timestamps (SCTs) from configured certificate transparency logs, retrieve OCSP staples, reload services associated to the certificates, and perform configured certificate installation verification.
Each subsequent run will ensure that all authorizations remain valid, check if any backup private keys have passed their expiration date, check if any certificate's expiration dates are within the renewal window, or have changes to the configured common name, or subject alternative names, or no longer match their associated private key files.
If a backup private key has passed its expiration date, the tool will rollover the private key or emit a warning recommending that the private key be rolled over, see the Private Key Rollover section for more information.
If a certificate needs to be renewed or has been modified, the certificate will be re-issued and reinstalled.
When certificates are issued or re-issued, local DNS updates will be attempted (to update TLSA records) and associated services will be reloaded.
When using remote DNS updates, all configured TLSA records will be verified and updated as needed on each run.
Configured certificate transparency logs will be queried and SCT files will be updated as necessary.
All certificates and private keys will normally be processed on each run, to restrict processing to specific private keys (and their certificates), you can list the names of the private keys to process on the command line.
In order to ensure that certificates in use do not expire, it is recommended that the tool be run at least once per day via a cron job.
By default, the tool only generates output when actions are taken making it cron friendly.
Normal output can be supressed via the --quiet
command line option.
To prevent multiple instances running at the same time,
a random wait can be introduced via the --randomwait
command line option.
The minimum and maximum wait times can be controlled via the min_run_delay
and max_run_delay
settings.
Example cron entry, in file /etc/cron.d/acmebot:
MAILTO=admin@example.com 20 0 * * * root /usr/local/bin/acmebot --randomwait
This will run the tool as root every day at 20 minutes past midnight plus a random delay of five minutes to an hour. Any output will be mailed to admin@example.com.
If using OCSP response files, it may be desirable to refresh OCSP responses at a shorter interval. (Currently Let's Encrypt updates OCSP responses every three days.) To refresh OCSP responses every six hours, add the line:
20 6,12,18 * * * root /usr/local/bin/acmebot --ocsp --randomwait
Normally the tool will only generate output to stdout when certificates are issued or private keys need to be rolled over.
More detailed output can be obtained by using any of the --verbose
, --debug
, or --detail
options on the command line.
Normal output may be supressed by using the --quiet
option.
Error and warning output will be sent to stderr and cannot be supressed.
The output can be colorized by type by adding the --color
option,
or colorized output can be suppressed via the --no-color
option.
During normal operations the private keys for certificates will not be modified, this allows renewing or modifying certificates without the need to update associated pinning information, such as HPKP headers or TLSA records using spki selectors.
However, it is a good security practice to replace the private keys at regular intervals, or immediately if it is believed that the primary private key may have been compromised. This tool maintains a backup private key for each primary private key and generates pinning information including the backup key as appropriate to allow smooth transitions to the backup key.
When the backup private key reaches the age specified via the expiration_days
setting,
the tool will notify you that it is time to rollover the private key,
unless the auto_rollover
setting has been set to true
,
in which case it will automatically perform the rollover.
The rollover process will archive the current primary private key, re-issue certificates using the existing backup key as the new primary key, generate a new backup private key, generate new custom Diffie-Hellman parameters, and reset HPKP headers and TLSA records as appropriate.
If the previous_key
directory is specified,
the current primary private key will be stored in that directory as a previous private key.
While previous private key files are present,
their key signatures will be added to HPKP pins and TLSA records.
This can assist in key rollover when keys are pinned for subdomains and private keys are shared between multiple servers.
Once the new primary and backup keys have been distributed to the other servers,
the previous private key file may be safely removed.
To manually rollover private keys, simply run the tool with the --rollover
option.
You can specify the names of individual private keys on the command line to rollover,
otherwise all private keys will be rolled over.
Note that the tool will refuse to rollover a private key if the current backup key is younger than the HPKP duration.
A private key rollover during this interval may cause a web site to become inaccessable to clients that have previously cached HPKP headers but not yet retrieved the current backup key pin.
If it is necessary to rollover the private key anyway,
for example if it is believed that the backup key has been compromised as well,
add the --force
option on the command line to force the private key rollover.
Normally certificates will be automatically renewed when the tool is run within the certificate renewal window,
e.g. within renewal_days
of the certificate's expiration date.
To cause certificates to be renewed before this time,
run the tool with the --renew
option on the command line.
Should it become necessary to revoke a certificate,
for example if it is believed that the private key has been compromised,
run the tool with the --revoke
option on the command line.
When revoking certificates, as a safety measure, it is necessary to also specify the name of the private key (or keys) that should be revoked. All certificates using that private key will be revoked, the certificate files and the primary private key file will be moved to the archive, and remote DNS TLSA records will be removed.
The next time the tool is run after a revocation, any revoked certificates that are still configured will automatically perform a private key rollover.
Use of the --auth
option on the command line will limit the tool to only performing domain authorizations.
Use of the --certs
option on the command line will limit the tool to only issuing and renewing certificates and keys,
and updating related files such as Diffie-Hellman paramaters and HPKP headers.
Use of the --tlsa
option on the command line will limit the tool to only verifying and updating configured TLSA records via remote DNS updates.
Use of the --sct
option on the command line will limit the tool to only verifying and updating configured Signed Certificate Timestamp files.
Use of the --ocsp
option on the command line will limit the tool to only updating configured OCSP response files.
Use of the --verify
option on the command line will limit the tool to only performing certificate installation verification.
The --auth
, --certs
, --tlsa
, --sct
, -ocsp
, and --verify
options may be combined to perform a combinations of operations.
If none of these options are specified, all operations will be performed as necessary and configured.
The order of the operations will not be affected by the order of the command line options.
When encrypting private keys, a passphrase must be provided. There are several options for providing the key.
Passphrases may be specified directly in the configuration file, both as a default passphrase applying to all keys, or specific passphrases for each key. Storing passphrases in cleartext in the configuration file obviously does little to protect the private keys if the configuration file is stored on the same machine. Either protect the configuration file or use an alternate method of providing passphrases.
Alternatively, by setting the passphrase to true
in the configuration file (the binary value, not the string "true"
),
the tool will attempt to obtain the passphrases at runtime.
Runtime passphrases may be provided on the command line, via an environment variable, via a text prompt, or via an input file.
A command line passphrase is passed via the --pass
option, e.g.:
acmebot --pass "passphrase"
To use an environment variable, set the passphrase in ACMEBOT_PASSPHRASE
.
A passphrase passed at the command line or an environment variable will be used for every private key that has it's key_passphrase
set to true
.
If different passphrases are desired for different keys,
run the tool for each key specifying the private key name on the command line to restrict processing to that key.
If the passphrase is not provided on the command line or an environment variable, and the tool is run via a TTY device (e.g. manually in a terminal), it will prompt the user for each passphrase as needed. Different passphrases may be provided for each private key (the same passphrase will be used for all key types of that key).
Finally, the passphrases may be stored in a file, one per line, and input redirected from that file, e.g.:
acmebot < passphrase_file.txt
Passphrases passed via an input file will be used in the order that the private keys are defined in the configuration file. If both certificates and private key sections are defined, the private keys will be processed first, then the certificates. You may wish to run the tool without the input file first to verify the private key order.
In some circumstances, it is useful to run the tool in a master/follower configuration. In this setup, the master performs domain authorizations while the follower issues and maintains certificates.
This setup is useful when the follower machine does not have the ability to perform domain authorizations, for example, an XMPP server behind a firewall that does not have port 80 open or access to a DNS server.
To create a master/follower setup, first install and configure the tool on the master server as normal. The master server may also issue certificates, but it is not necessary.
Configure any required domain authorizations (see the Authorizations section) on the master and run the tool.
Then install the tool on the follower server. It is not necessary to configure HTTP challenges or remote DNS update keys on the follower.
Before running the tool on the follower server,
copy the client key and registration files from the master server.
These files are normally found in /var/local/acmebot
but an alternate location can be configured in the resource
directory setting.
If the master server also issues certificates for the same domain names or parent domain names as the follower, you may want to copy the primary and backup private keys for those certificates to the follower. This will cause the follower certificates to use the same keys allowing HPKP headers to safey include subdomains.
Set the follower follower_mode
setting to true
and configure desired certificates on the follower.
Run the tool on the follower server.
When setting up cron jobs for the master and follower,
be sure the follower runs several minutes after the master so that all authorizations will be complete.
The master can theoretically take (max_dns_lookup_attempts
x dns_lookup_delay
) + (max_authorization_attempts
x authorization_delay
) seconds to obtain domain authorizations (15 minutes at the default settings).
It is possible to run several follower servers for each master, the follower cron jobs should not all run at the same time.
The follower server may maintain TLSA records if remote DNS updates are configured on the follower, otherwise it is recommended to use spki selectors for TLSA records so that certificate renewals on the follower will not invalidate TLSA records.
If private keys are shared between a master and follower,
be sure to turn off auto_rollover
and only perform private key rollovers on the master.
It is also useful to specify the previous_key
directory to preserve previous key pins during the key rollover process.
After a private key rollover, copy the new primary and backup private key files to the followers.
The follower will automatically detect the new private key and re-issue certificates on the next run.
Once all the followers have updated their certificates to the new keys,
you can safely delete the previous private key file.