From 7284f9864fad4432b6a6e641c03adee321148107 Mon Sep 17 00:00:00 2001 From: Lexi Winter Date: Wed, 4 Jun 2025 07:04:41 +0100 Subject: add documentation for the challenge hooks --- lfacme-kerberos.5 | 58 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 58 insertions(+) create mode 100644 lfacme-kerberos.5 (limited to 'lfacme-kerberos.5') diff --git a/lfacme-kerberos.5 b/lfacme-kerberos.5 new file mode 100644 index 0000000..06b5b00 --- /dev/null +++ b/lfacme-kerberos.5 @@ -0,0 +1,58 @@ +.\" This source code is released into the public domain. +.Dd June 4, 2025 +.Dt LFACME-KERBEROS 5 +.Os +.Sh NAME +.Nm lfacme-kerberos +.Nd validate an ACME challenge via GSS-TSIG DNS updates +.Sh SYNOPSIS +In +.Xr domains.conf 5 : +.Bd -ragged -offset indent +.Ar domain +challenge=kerberos +.Ed +.Sh DESCRIPTION +The +.Nm +challenge hook will respond to an ACME domain validation using a DNS-based +.Dq dns-01 +authorization with GSS-TSIG Dynamic DNS updates. +To use this challenge hook, configure one or more domains with +.Dq challenge=kerberos +in +.Xr domains.conf 5 . +.Pp +The +.Dq dns-01 +challenge expects the authorization token to be created as a TXT record at the +DNS name +.Dq _acme-challenge. Ns Ar domain . +When +.Nm +responds to the challenge, it will use +.Xr nsupdate 1 +with the +.Fl g +flag (enable GSS-TSIG) to create this token. +The DNS update will be sent to the zone's master server (determined by the +MNAME field in the SOA record). +.Pp +Before sending the update, +.Nm +will retrieve a Kerberos ticket using +.Xr kinit 1 +for the principal configured by +.Ar ACME_KERBEROS_PRINCIPAL +in +.Xr acme.conf 5 . +The principal's key must exist in the Kerberos keytab configured by +.Ar ACME_KERBEROS_KEYTAB +(by default, +.Pa /etc/krb5.keytab ) . +.Sh SEE ALSO +.Xr acme.conf 5 , +.Xr domains.conf 5 , +.Xr kinit 1 , +.Xr lfacme-renew 8 , +.Xr nsupdate 1 -- cgit v1.2.3