Mathematical Institute of the University of Bonn

• NAME
• SYNOPSIS
• DESCRIPTION
• OPTIONS
• COMMANDS
• DEPENDENCIES
• AUTHOR
• LICENSE

NAME

acmechanic - request certificates via ACME/DNS-01 or ACME/HTTP-01 by answering proxied request with a built-in DNS/HTTP server (or without challenges if EAB permits)

SYNOPSIS

acmechanic [-v] [-n] [-d] [-s] [-c configfile] [-b config-block] [-k keyfile] [-t challenge-type] [-D domain] [-A acme-domain] [-C CA] [-U URL] [-L addr] [-P port] [-I eab-key-id] [-H eab-hmac-key] register|request|revoke [args]

DESCRIPTION

acmechanic requests certificates from a CA using the ACME/DNS-01 or ACME/HTTP-01 protocols. Contrary to common ACME clients, it does not need to update the DNS zone files or deposit (HTTP-accesible) files on the servers it requests certificates for.

For ACME/DNS-01, it contains a dedicated Name Server to answer the challenges posed by the CA. It requires a set of CNAMEs on the main DNS server redirecting _acme-challenge.name.domain to name.acme-domain where acme-domain has a NS entry pointing to where acmechanic is running on. These CNAME Resource Records only need to be installed once on the main DNS server and not need to be updated when requesting a new certificate.

For ACME/HTTP-01, it contains a minature HTTP server to answer the challenges. It requires the real HTTP servers to forward/proxy requests for /.well-known/acme-challenge/* to the server acmechanic runs on. This proxy configuration only needs to be done once on the HTTP servers and does not need to be updated when requesting a new certificate.

In case the CAs EAB (External Account Binding) permits, acmechanic can also request certificates with no ACME challenges at all.

OPTIONS

acmechanic understands the dollowing options:

-v

verbose mode. Report progess on STDERR.

-n

dry-run mode. Do not actually request the certificate. Note that, unfortunately, acmechanic is currently unable to invalidate the challenges processed.

-d

debugging mode. Print internal debugging information.

-s

staging mode. Use the CA's staging server, if available.

-c configfile

read config from (INI-style) configfile instead of the default acmechanic.conf. Supported keys are type, keyfile, (type-)listen, (type-)port, domain, acme-domain, ca, url, eab-key-id and eab-hmac-key.

-b block

use specified block in configfile.

-k key

use key to identify (or register) with the CA.

-t type

use the given challenge-type (dns, http or none). If set to none, acmechanic will not request any challenges. This assumes that the ACME key has been bound via External Account Binding (EAB) on registration to an identity that is authorized to request certificates without answering the corresponding challenges.

-C CA

use the specified CA.

-U URL

use the specified URL for the directory handler on the ACME server. Overrides CA.

-L addr

let the DNS/HTTP Server listen on the specified address.

-P port

let the DNS/HTTP Server listen on the specified port.

-D domain

(DNS-01 only) specify the DNS domain used in the CSR. If omitted, strip all of the domain part from FQDNs.

-A acme-domain

(DNS-01 only) answer challenges for acme-domain (the domain the main DNS server's _acme-challenge CNAMEs point to. If omitted, answer challenges for all domains.

-I eab-key-id

Use given Key Id for EAB (External Account Binding). Used on first registration only.

-H eab-hmac-key

Use given HMAC Key for EAB. If starting with <, treat the rest as a file name do read the key from. If this option is absent (but -I or the eab-key-id configuration option is present), use the environment variable EAB_HMAC_KEY if present, otherwise prompt for the key. Used on first registration only.

Note that, for DNS-01, you need to specify both domain and acme-domain when requesting certificates for sub-domains. E.g., in order to get certificates for foo.one.example.com and bar.two.example.com, you would need to set domain to example.com and acme-domain to acme.example.com (or whatever the CNAMEs on your main DNS server point to).

COMMANDS

The recognized commands are:

register email

register the key in keyfile and the email adress with the CA.

request|csr CSR

request a certificate based on CSR.

revoke certificate

revoke a certificate.

DEPENDENCIES

Config::Tiny, Crypt::LE, Term::ReadKey, IO::Prompter, Net::DNS; Net::DNS::RR and Net::DNS::Nameserver for DNS-01; HTTP::Daemon, HTTP::Request, URI and HTTP::Response for HTTP-01.

AUTHOR

Edgar Fuß, Mathematisches Institut der Universität Bonn <ef@math.uni-bonn.de>

LICENSE

This script may be redistributed and/or modified unter the same terms as Perl itself or under a 2-clause BSD licence.