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": "[email protected]"
},
"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": "[email protected]"
},
...
}
Various settings for the tool. All of these need only be present when the desired value is different from the default.
follower_modespecifies 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_levelspecifies 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,--debugand--detailcommand-line options.color_outputspecifies 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_typesspecifies the types of private keys to generate by default. The default value is['rsa', 'ecdsa'].key_sizespecifies the size (in bits) for RSA private keys. The default value is4096. RSA certificates can be turned off by setting this value to0ornull.key_curvespecifies 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_cipherspecifies 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_passphrasespecifies the passphrase used to encrypt private keys. The default value isnull. A value ofnullorfalsewill result in private keys being written unencrypted. A value oftruewill 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_providedspecifies that the private keys are provided from an external source and the tool should not modify them. The default value isfalse.dhparam_sizespecifies 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 to0ornull. This value should be at least be equal to half thekey_size.ecparam_curvespeficies 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_curvesto find a list of available curves.file_userspecifies 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_groupspeficies 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_userspecifies 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_groupspeficies 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_codespecifies if warnings will produce a non-zero exit code. The default value isfalse.hpkp_daysspecifies 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 to0ornull.pin_subdomainsspecifies whether theincludeSubdomainsdirective should be included in the HPKP headers. The default value istrue.hpkp_report_urispecifies the uri to report HPKP failures to. The default value isnull. If not null, thereport-uridirective will be included in the HPKP headers.ocsp_must_staplespecifies if the OCSP Must-Staple extension is added to certificates. The default value isfalse.ocsp_responder_urlsspecifies 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_logsspecifies 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_daysspecifies the number of days before expiration when the tool will attempt to renew a certificate. The default value is30.expiration_daysspecifies 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_rolloveris set totrue. Automatic rollover and expiration notices can be disabled by setting this to0ornull.auto_rolloverspecifies 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_attemptsspecifies the number of times to check for deployed DNS records before attempting authorizations. The default value is60.dns_lookup_delayspecifies the number of seconds to wait between DNS lookups. The default value is10.max_domains_per_orderspecifies the maximum number of domains allowed per authorization order. The default value is100, which is the limit set by Let's Encrypt.max_authorization_attemptsspecifies the number of times to check for completed authorizations. The default value is30.authorization_delayspecifies the number of seconds to wait between authorization checks. The default value is10.cert_poll_timespecifies the number of seconds to wait for a certificate to be issued. The default value is30.max_ocsp_verify_attemptsspecifies 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_delayspecifies the number of seconds to wait between OCSP staple verification attempts. The default value is5.min_run_delayspecifies the minimum number of seconds to wait if the--randomwaitcommand line option is present. The default value is300.max_run_delayspecifies the maximum number of seconds to wait if the--randomwaitcommand line option is present. The default value is3600.acme_directory_urlspecifies 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_sslspecifies whether or not to verify the certificate of the ACME service. The default value isTrue. Setting this toFalseis not recommneded, but may be necessary in environments using a private ACME server.reload_zone_commandspecifies 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 tonullto avoid warnings.nsupdate_commandspecifies the command to perform DNS updates. The default value is"/usr/bin/nsupdate".verifyspecifies the default ports to perform installation verification on. The default value isnull.servicesspecifies 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.
pidspecifies the directory to store a process ID file. The default value is"/var/run".logspecifies the directory to store the log file. The default value is"/var/log/acmebot".resourcespecifies the directory to store the client key and registration files for the ACME account. The default value is"/var/local/acmebot".private_keyspecifies the directory to store primary private key files. The default value is"/etc/ssl/private".backup_keyspecifies the directory to store backup private key files. The default value is"/etc/ssl/private".previous_keyspecifies the directory to store previously used private key files after key rollover. The default value isnull.full_keyspecifies 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.certificatespecifies the directory to store certificate files. The default value is"/etc/ssl/certs".full_certificatespecifies 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.chainspecifies the directory to store certificate intermediate chain files. The default value is"/etc/ssl/certs". Chain files may be omitted by setting this tonull.paramspecifies the directory to store Diffie-Hellman parameter files. The default value is"/etc/ssl/params". Paramater files may be omitted by setting this tonull.challengespecifies the directory to store ACME dns-01 challenge files. The default value is"/etc/ssl/challenge".http_challengespecifies the directory to store ACME http-01 challenge files. The default value isnull.hpkpspecifies 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.sctspecifies 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.ocspspecifies 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_keyspecifies the directory to search for DNS update key files. The default value is"/etc/ssl/update_keys".archivespecifies the directory to store older versions of files that are replaced by this tool. The default value is"/etc/ssl/archive".tempspecifies the directory to write temporary files to. A value ofnullresults 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_namespecifies the common name for the certificate. If omitted, the name of the certificate will be used.alt_namesspecifies 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_nameswill be:{"example.com": ["@"] }; if the common name is "foo.bar.example.com", the defaultalt_nameswill be:{ "example.com": ["foo.bar"] }.servicesspecifies 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 thesettingssection.dhparam_sizespecifies the number of bits to use for custom Diffie-Hellman paramaters for the certificate. The default value is the value specified in thesettingssection. Custom Diffie-Hellman paramaters may be ommitted from the certificate by setting this to0ornull. The value should be at least equal to half the number of bits used for the private key.ecparam_curvespecified the curve or curves used for elliptical curve paramaters. The default value is the value specified in thesettingssection. Custom elliptical curve paramaters may be ommitted from the certificate by setting this tonull.key_typesspecifies 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_sizespecifies the number of bits to use for the certificate's RSA private key. The default value is the value specified in thesettingssection. RSA certificates can be turned off by setting this value to0ornull.key_curvespecifies the curve to use for ECDSA private keys. The default value is the value specified in thesettingssection. Available curves are"secp256r1","secp384r1", and"secp521r1". ECDSA certificates can be turned off by setting this value tonull.key_cipherspecifies the cipher algorithm used to encrypt the private keys. The default value is the value specified in thesettingssection. Available ciphers those accepted by your version of OpenSSL's EVP_get_cipherbyname().key_passphrasespecifies the passphrase used to encrypt private keys. The default value is the value specified in thesettingssection. A value ofnullorfalsewill result in private keys being written unencrypted. A value oftruewill 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_providedspecifies 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 thesettingssection. This is useful when the same private keys are shared between multiple instances of the tool, e.g. for HPKP purposes.expiration_daysspecifies the number of days that the backup private key should be considered valid. The default value is the value specified in thesettingssection. 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_rolloveris set totrue. Automatic rollover and expiration notices can be disabled by setting this to0ornull.auto_rolloverspecifies if the tool should automatically rollover the private key when it expires. The default value is the value specified in thesettingssection.hpkp_daysspecifies the number of days that HPKP pins should be cached by clients. The default value is the value specified in thesettingssection. HPKP pin files can be turned off by setting this value to0ornull.pin_subdomainsspecifies whether theincludeSubdomainsdirective should be included in the HPKP headers. The default value is the value specified in thesettingssection.hpkp_report_urispecifies the uri to report HPKP errors to. The default value is the value specified in thesettingssection. If not null, thereport-uridirective will be included in the HPKP headers.ocsp_must_staplespecifies if the OCSP Must-Staple extension is added to certificates. The default value is the value specified in thesettingssection.ocsp_responder_urlsspecifies the list of OCSP responders to use if a certificate doesn't provide them. The default value is the value specified in thesettingssection.ct_submit_logsspecifies the list of certificate transparency logs to submit the certificate to. The default value is the value specified in thesettingssection. The value["google_testtube"]can be used with the Let's Encrypt staging environment for testing.verifyspecifies the list of ports to perform certificate installation verification on. The default value is the value specified in thesettingssection.
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:
hostspecifies the host name for the TLSA record. The default value is"@". The host name"@"is used for the name of the zone itself.portspecifies the port number for the TLSA record. The default value is443.usageis 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.selectoris 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.protocolspecifies the protocol for the TLSA record. The default value is"tcp".ttlspecifies 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.
filespecifies the name of the TSIG key file.serverspecifies 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.portspecifies 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.
logspecifies the name of the log file.private_keyspecifies the name of primary private key files.backup_keyspecifies the name of backup private key files.full_keyspecifies the name of primary private key files that include the certificate chain.certificatespecifies the name of certificate files.full_certificatespecifies the name of certificate files that include the root certificate.chainspecifies the name of intemediate certificate files.paramspecifies the name of Diffie-Hellman parameter files.challengespecifies the name of ACME challenge files used for local DNS updates.hpkpspecifies the name of HPKP header files.ocspspecifies the name of OCSP response files.sctspecifies 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_challengeis called for each DNS challenge record that is set. Available fields aredomain,zone, andchallenge.clear_dns_challengeis called for each DNS challenge record that is removed. Available fields aredomain,zone, andchallenge.dns_zone_updateis called when a DNS zone is updated via either local or remote updates. Available field iszone.set_http_challengeis called for each HTTP challenge file that is installed. Available fields aredomain, andchallenge_file.clear_http_challengeis called for each HTTP challenge file that is removed. Available fields aredomain, andchallenge_file.private_key_rolloveris 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_installedis called when a private key is installed. Available fields arekey_name,key_type,private_key_file, andpassphrase.backup_key_installedis called when a backup private key is installed. Available fields arekey_name,key_type,backup_key_file, andpassphrase.previous_key_installedis called when a previous private key is installed after key rollover. Available fields arekey_name,key_type,previous_key_file, andpassphrase.hpkp_header_installedis called when a HPKP header file is installed. Available fields arekey_name,server,header, andhpkp_file.certificate_installedis called when a certificate file is installed. Available fields arekey_name,key_type,certificate_name, andcertificate_file.full_certificate_installedis called when a certificate file that includes the root is installed. Available fields arekey_name,key_type,certificate_name, andfull_certificate_file.chain_installedis called when a certificate intermediate chain file is installed. Available fields arekey_name,key_type,certificate_name, andchain_file.full_key_installedis 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_installedis called when a params file is installed. Available fields arekey_name,certificate_name, andparams_file.sct_installedis called when a SCT file is installed. Available fields arekey_name,key_type,certificate_name,ct_log_name, andsct_file.ocsp_installedis 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:
portspecifies the port number to connect to. Required.starttlsspecifies 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.protocolspecifies 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.hostsspecifies 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_typesspecifies 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:[email protected]}}
{{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:
[email protected] 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 [email protected].
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.