acme_token_check.1

.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "ACME_TOKEN_CHECK 1"
.TH ACME_TOKEN_CHECK 1 29-Jun-2024 "" "Certificate Tools"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH ACME_TOKEN_CHECK
.IX Header "ACME_TOKEN_CHECK"
acme_token_check \- check DNS domain(s) for stray ACME tokens
.SH SYNOPSIS
.IX Header "SYNOPSIS"
acme_token_check [options] [domain ...]
.PP
.Vb 6
\&  Options
\&    \-\-debug       \-\-named\-address  \-\-nameservers  \-\-ns\-port \-\-recurse
\&    \-\-option      \-\-init\-file      \-\-remove       \-\-source\-address
\&    \-\-tsig\-key    \-\-source\-port    \-\-verbose      \-\-view    \-\-display
\&    \-\-cnames\-for  \-\-target\-zone    \-\-hash         \-\-install
\&    \-\-help        \-\-man            \-\-version
.Ve
.PP
If no domain is specified, domains can be obtained from \fInamed\fR if its statistics
channel is available.
.SH OPTIONS
.IX Header "OPTIONS"
.IP \fB\-\-cnames\-for\fR=\fIsource\fR 8
.IX Item "--cnames-for=source"
List of source [sub\-]domains for CNAME redirection from each domain.
.Sp
E.g. \fIwww,host1,host2\fR or \fI*\fR for wildcard.
.Sp
Do not include the parent domain name.
.Sp
Use '.' to specify the domain itself.  "*" is an alias for '.' for
the purposes of ACME wildcard validation.
.IP "\fB\-d\fR \fB\-\-[no]debug\fR" 8
.IX Item "-d --[no]debug"
Display debugging output from DNS queries.
.IP "\fB\-D\fR \fB\-\-display\fR=\fItxt|cnames|both\fR" 8
.IX Item "-D --display=txt|cnames|both"
Display all records found of the specified type(s).  Default is TXT.
.Sp
Records of the type(s) being removed are always displayed.
.IP \fB\-\-hash\fR[=\fIn\fR] 8
.IX Item "--hash[=n]"
When generating CNAMEs, include a hash of the source domain in the target
instead of the source domain itself.  This ensures that all the target names
are a fixed length, but prevents backtracking from a stranded token to the
client.  \fIn\fR is the length of the hash (in characters) used in the target
domain name.  A random factor makes each re-generation unique.
.Sp
If not specified, hashing is not used.  If \fIn\fR is omitted, 32 is used.
\&\fIn\fR must be less than 64, since the hash is a single DNS label.
.IP \fB\-\-install\fR 8
.IX Item "--install"
When generating CNAMEs, install them with DNS UPDATE.
.IP \fB\-\-named\-address\fR=\fIaddress[:port]\fR 8
.IX Item "--named-address=address[:port]"
Use a \fInamed\fR statistics channel to obtain a list of zones to process.
The address can be a literal address or a hostname.  It may be prefixed
by \fIhttps://\fR if \fInamed\fR is behind an https proxy.  The default
protocol is \fIhttp://\fR, port 80.
.Sp
Not accessed if any domain name(s) specified on the command line.
.IP \fB\-\-nameservers\fR\-\fIaddr,...\fR 8
.IX Item "--nameservers-addr,..."
Name(s) and/or Address(es) of nameservers to use.  If not specified, the
default resolvers will be used to obtain the zone's NS records.
.Sp
The \fBtsig-key\fR and/or \fBsource-address\fR will be used for this query.
.Sp
Updates (to remove records) are always sent to the \fBSOA\fR's \fImname\fR.
.IP \fB\-\-ns\-port\fR=\fIport\fR 8
.IX Item "--ns-port=port"
Destination port of nameservers.  Use if nameservers listen on a non-standard port
(e.g. test nameservers).
.Sp
Default is 53.
.IP \fB\-\-[no]recurse\fR 8
.IX Item "--[no]recurse"
Scan delegations (subzones) of the specified domains.  Default is \fB\-\-recurse\fR,
.Sp
Not applicable to CNAME generation.
.IP "\fB\-r\fR \fB\-\-[no]remove\fR=\fInone|txt|cnames|both\fR" 8
.IX Item "-r --[no]remove=none|txt|cnames|both"
Remove all records found of the specified type(s).  Default type for \fB\-\-remove\fR is \fItxt\fR.
.Sp
Requires the nameserver hosting a zone to support and permit dynamic updates (RFC2136).
The nameserver may require updates to be from a specified address (or subnet) and/or port,
or to be TSIG-signed.
.Sp
Removing \fIcnames\fR is not common; they are usually a static delegation.
.Sp
Default if not specified is \fB\-\-noremove\fR.
.IP \fB\-\-reverse\-zones\fR 8
.IX Item "--reverse-zones"
Process zones in the \fIin\-addr.arpa\fR and \fIip6.arpa\fR domains.
.Sp
Default is \fB\-\-no\-reverse\-zones\fR.
.IP "\fB\-s\fR \fB\-\-source\-address\fR=\fIaddress\fR" 8
.IX Item "-s --source-address=address"
Send queries from \fIaddress\fR.  Default is any local address.
.IP \fB\-\-source\-port\fR=\fIport\fR 8
.IX Item "--source-port=port"
Send queries from \fIport\fR.  Default is any local port.
.IP \fB\-\-target\-zone\fR=\fIupdatable.domain\fR 8
.IX Item "--target-zone=updatable.domain"
Specifies the target of generated CNAME records.  This must be a domain that
can be updated during ACME verification.
.IP "\fB\-k\fR \fB\-\-tsig\-key\fR=\fIfile\fR" 8
.IX Item "-k --tsig-key=file"
Specify a file containing TSIG key to use for the domain(s).
.Sp
The default is not to sign queries or updates.
.IP \fB\-\-[no]unique\-names\fR 8
.IX Item "--[no]unique-names"
When generating CNAMEs, with \fB\-\-unique\fR each CNAME on a host covered by the
certificate targets a unique name on the target validation server.  The target
name either includes the full domain name of the client certificate, or a
hash of that name and a random factor.  See \fB\-\-hash\fR for information about the
latter.
.IP "\fB\-V\fR \fB\-\-view\fR=\fIname\fR" 8
.IX Item "-V --view=name"
Specify view to be used when obtaining zone list with \fB\-\-named\-address\fR.
.Sp
View selection used for queries (and updates) may be influenced by \fB\-\-tsig\-key\fR
and/or \fB\-\-source\-address\fR, depending on the nameserver.
.Sp
The default is to use the \fB_default\fR view.
.IP "\fB\-v\fR \fB\-\-[no]verbose\fR" 8
.IX Item "-v --[no]verbose"
Report all findings/actions.
.Sp
Default is to report totals if any records are found, and to report errors.
.IP \fB\-\-help\fR 8
.IX Item "--help"
Print a brief help message and exit.
.IP \fB\-\-man\fR 8
.IX Item "--man"
Print the manual page and exit.
.SH DESCRIPTION
.IX Header "DESCRIPTION"
\&\fBacme_token_check\fR scans the specified domain(s) and any subdomains for \fBTXT\fR
and/or \fBCNAME\fR records of the form:
.PP
.Vb 1
\&    _acme\-challenge.*
.Ve
.PP
With \fB\-\-verbose\fR tnose found will be reported.
.PP
With \fB\-\-remove\fR, those found will be removed from the DNS.
.PP
With \fB\-\-target\-zone\fR, creates CNAME records for verification redirection.
.PP
These records are created when the ACME protocol is used to obtain TLS certificates,
validating domain ownership with its \fIDNS\-01\fR option.
.PP
The \fBTXT\fR records should be removed, but system or software failures can leave them in the DNS.
.PP
\&\fBacme_token_check\fR performs a zone transfer (AXFR) in order to locate the
\&\fBTXT\fR and/or \fBCNAME\fR records.  If requested, it uses DNS UPDATE to remove \fBTXT\fR
and to install \fBCNAME\fR records.  The nameserver(s) must be configured to permit these
transactions.
.PP
When run at a time that no renewals are active, \fBacme_token_check\fR provides a means
to detect and remove leftover challenge tokens.  By default, it only generates output
if records are found or errors are encountered, making it suitable for a \fIcron\fR job.
Such \fIcron\fR jobs should be scheduled when they will not interfere with certificate
renewals.
.PP
\&\fBacme_token_check\fR can also scan for corresponding \fBCNAME\fR records, which are used
to redirect challenges to a dynamically-updatable domain.  These are usually static,
and should not be removed.
.SS SECURITY
.IX Subsection "SECURITY"
Communications with the nameserver are signed with TSIG if \fB\-\-tsig\fR is
specified.  Unsigned communications are adequate when TSIG is not used for
view selection, zone transfer authentication, or update authentication.
.PP
If TSIG is not used, the nameserver is presumed to handle any view selection,
and authentication based on IP address.  In this case, if the host running
\&\fBacme_token_check\fR is multi-homed, \fB\-\-source\-address\fR can be used to ensure
that transactions use an authorized address to communicate with the DNS servers.
.SS "CHALLENGE REDIRECTION (CNAMES)"
.IX Subsection "CHALLENGE REDIRECTION (CNAMES)"
ACME issuer verification reaquires that the client have the ability to deposit challenge
tokens in the certificate's domain to prove ownership.  There are scenarios where,
due to security concerns, operational issues, or technical limitations, this is
inconvenient (or impossible).  To accomodate these scenarios, issuers may follow
CNAMEs for the challenge tokens to a server where the tokens can be installed, usually
by a form of dynamic update.  The CNAMEs are created in the certificate's domain, and
are static thereafter.
.PP
\&\fBacme_token_check\fR can generate these CNAMEs using the \fB\-\-cnames\-for\fR and \fB\-\-target\-zone\fR options.
The target will include a hash of the source domain, or the source domain name.  See \fB\-\-hash\fR.
.PP
Installation is generally manual, but if the domain supports dynamic updates, you can use \fB\-\-install\fR.
This is used when the certificate's domain restricts updates to designated people, who can
nonetheless benefit from \fBacme_token_check\fR's automation.
.SS "INITIALIZATION FILES"
.IX Subsection "INITIALIZATION FILES"
If the environment variable \fIACME_TOKEN_CHECK\fR is defined, the file that it points to
is parsed before the command line.  It may contain options and/or domains.
Otherwise, \fBacme_token_check\fR looks for<.acme_token_check> in \fI.\fR,  \fR\f(CI$HOME\fR\fI\fR, and
also for  \fI/etc/acme_token_check.conf\fR.
The first file found will be processed.  # comments are allowed.
.PP
\&\fB\-\-init\-file\fR specifies an initialization file to be used, and disables the automatic
search for \fI.acme_token_check\fR.
.PP
\&\fB\-\-option\fR=\fItag\fR specifies that only lines matching the \fItag\fR are to be used.
Tags consist of a word followed by ':' at the beginning of a line.  Default is to
process only untagged lines.
.PP
These options are ignored in initialization files.
.SH EXAMPLES
.IX Header "EXAMPLES"
Scan example.com (and all sub-domains) for tokens:
.PP
.Vb 1
\&    acme_token_check example.com
.Ve
.PP
Scan and delete:
.PP
.Vb 1
\&    acme_token_check example.com \-\-remove
.Ve
.PP
Scan for CNAMEs (redirections)
.PP
.Vb 1
\&    acme_token_check example.com \-\-display=cnames
.Ve
.PP
Scan and delete (remove implies display)
.PP
.Vb 1
\&    acme_token_check example.com \-\-remove=cnames
.Ve
.PP
Generate the CNAME targeting dns.example.net for a wildcard certificate on host.example.com
.PP
.Vb 2
\&     acme_token_check host.example.com \-\-target=dns.example.net \-\-cname=\*(Aq*\*(Aq
\&    _acme\-challenge.host.example.com. 1800 IN CNAME _acme\-challenge.dns.example.net.
.Ve
.PP
Generate CNAMEs for www.example.net, example.net, host2.example.net that
redirect to dns.example.net.  These will be unique with the cert. host in
the target name.  Use \-\-hash for randomized hash names in the target name.
.PP
.Vb 6
\&    acme_token_check \-\-cnames="www,.,host2" example.net \e
\&                     \-\-target=dns.example.net
\&    _acme\-challenge.host2.example.net. 1800 IN CNAME _acme\-challenge.host2.example.net.dns.example.net.
\&    _acme\-challenge.www.example.net. 1800 IN CNAME _acme\-challenge.www.example.net.dns.example.net.
\&    _acme\-challenge.example.net. 1800 IN CNAME _acme\-challenge.example.net.dns.example.net.
\&    3 acme challenge cnames generated
\&
\&    acme_token_check \-\-cnames="www,.,host2" example.net \e
\&                     \-\-target=dns.example.net \-\-hash=8
\&    _acme\-challenge.www.example.net. 1800 IN CNAME _acme\-challenge.a6ac7a77.dns.example.net.
\&    _acme\-challenge.host2.example.net. 1800 IN CNAME _acme\-challenge.c4f3ca34.dns.example.net.
\&    _acme\-challenge.example.net. 1800 IN CNAME _acme\-challenge.fff44f14.dns.example.net.
\&    3 acme challenge cnames generated
.Ve
.PP
Generate the same CNAMEs, but all target a single server name.
.PP
.Vb 6
\&    acme_token_check \-\-cnames="www,.,host2" example.net \e
\&                     \-\-target=dns.example.net \-\-nounique
\&    _acme\-challenge.example.net. 1800 IN CNAME _acme\-challenge.dns.example.net.
\&    _acme\-challenge.host2.example.net. 1800 IN CNAME _acme\-challenge.dns.example.net.
\&    _acme\-challenge.www.example.net. 1800 IN CNAME _acme\-challenge.dns.example.net.
\&    3 acme challenge cnames generated
.Ve
.PP
Generate CNAMEs for www, mail, and webmail for example.us, example.info,
and example.fr. Since the nameserver supports RFC2136 dynamic update, install them.
.PP
.Vb 10
\&    acme_token_check example.fr example.us example.info \e
\&                     \-\-cnames="www,mail,webmail"\e
\&                     \-\-target=dns.example.net \-\-hash=8 \-\-install \e
\&                     \-\-source\-address=192.0.2.15
\&    _acme\-challenge.mail.example.info. 1800 IN CNAME _acme\-challenge.f220d62d.dns.example.net.
\&    _acme\-challenge.webmail.example.info. 1800 IN CNAME _acme\-challenge.aa6364c6.dns.example.net.
\&    _acme\-challenge.www.example.info. 1800 IN CNAME _acme\-challenge.5bfb0c72.dns.example.net.
\&    _acme\-challenge.mail.example.fr. 1800 IN CNAME _acme\-challenge.4314e798.dns.example.net.
\&    _acme\-challenge.webmail.example.fr. 1800 IN CNAME _acme\-challenge.95d60169.dns.example.net.
\&    _acme\-challenge.www.example.fr. 1800 IN CNAME _acme\-challenge.f827a766.dns.example.net.
\&    _acme\-challenge.mail.example.us. 1800 IN CNAME _acme\-challenge.764c032e.dns.example.net.
\&    _acme\-challenge.webmail.example.us. 1800 IN CNAME _acme\-challenge.6a3e68e9.dns.example.net.
\&    _acme\-challenge.www.example.us. 1800 IN CNAME _acme\-challenge.7b360ab3.dns.example.net.
\&    9 acme challenge cnames installed
.Ve
.PP
Scan and delete tokens in all zones served by a BIND nameserver, except reverse zones.
.PP
.Vb 2
\&    acme_token_check \-\-named\-address=dns3.example.net:8053  \-\-view=external
\&                     \-\-remove \-\-tsig\-key=/etc/my.key
.Ve
.SH "RETURN VALUE"
.IX Header "RETURN VALUE"
The exit code provides summary status.  Values are ORed if more than one applies.
.IP "0 Success" 4
.IX Item "0 Success"
.PD 0
.IP "1 A zone transfer failed." 4
.IX Item "1 A zone transfer failed."
.IP "2 A challenge token record was found." 4
.IX Item "2 A challenge token record was found."
.IP "4 A DNS server refused to delete a challenge token record." 4
.IX Item "4 A DNS server refused to delete a challenge token record."
.IP "8 A DNS server did not return a reply to a delete request." 4
.IX Item "8 A DNS server did not return a reply to a delete request."
.IP "16 A challenge token CNAME was found." 4
.IX Item "16 A challenge token CNAME was found."
.IP "32 A DNS server refused to add a challenge CNAME." 4
.IX Item "32 A DNS server refused to add a challenge CNAME."
.IP "64 A DNS server did not return a reply to a request to add a CNAME." 4
.IX Item "64 A DNS server did not return a reply to a request to add a CNAME."
.IP "128 A query to obtain the primary server for a zone faile." 4
.IX Item "128 A query to obtain the primary server for a zone faile."
.IP "255 Error in command or unhandled error from a module." 4
.IX Item "255 Error in command or unhandled error from a module."
.PD
.SH BUGS
.IX Header "BUGS"
Report any bugs, feature requests and/or patches on the issue tracker,
located at \fIhttps://github.com/tlhackque/certtools/issues\fR.  In the
event that the project moves, contact the author directly.
.PP
\&\fINet::DNS\fR prevents efficient connection reuse when \fB\-\-recurse\fR is
used.  See RT#145835 <https://rt.cpan.org/Ticket/Display.html?id=145835>
Work-around adjusts timing at the cost of some memory.
.SH AUTHOR
.IX Header "AUTHOR"
Timothe Litt  <litt@acm.org>
.SH "COPYRIGHT and LICENSE"
.IX Header "COPYRIGHT and LICENSE"
Copyright (c) 2021\-2024 Timothe Litt
.PP
Permission is hereby granted, free of charge, to any person obtaining a
copy of this software and associated documentation files (the "Software"),
to deal in the Software without restriction, including without limitation
the rights to use, copy, modify, merge, publish, distribute, sublicense,
and/or sell copies of the Software, and to permit persons to whom the
Software is furnished to do so, subject to the following conditions:
.PP
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
.PP
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
DEALINGS IN THE SOFTWARE.
.PP
Except as contained in this notice, the name of the author shall not be
used in advertising or otherwise to promote the sale, use or other dealings
in this Software without prior written authorization from the author.
.PP
Any modifications to this software must be clearly documented by and
attributed to their author, who is responsible for their effects.
.PP
Bug reports, suggestions and patches are welcomed by the original author.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fImod_md\fR \fIgetssl\fR \fIuacme\fR \fIRFC8555\fR ...
.PP
\&\fIPOD version \fR\f(CI$Id$\fR