add documentation for the challenge hooks

1 files changed, 58 insertions, 0 deletions

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