lfacme: a simple ACME client based on uacme
===========================================

lfacme is a wrapper around uacme to make it a bit more flexible.  i wrote it
primarily for my own use, but you're welcome to use it too.

lfacme comes with challenge handlers for basic HTTP validation (http-01) and
for DNS validation (dns-01) using TSIG- or Kerberos-authenticated nsupdate.
it can also be used with any uacme-compatible challenge handler.

it's only tested on FreeBSD and may or may not work on other platforms.
if it doesn't work, it shouldn't be difficult to port.

requirements
------------

+ POSIX-compatible /bin/sh
+ uacme (in FreeBSD: security/uacme)
+ OpenSSL command-line tool

if you want to use the HTTP challenge handler:

+ a web server installed on the host

if you want to use the DNS challenge handlers:

+ BIND's "dig" and "nsupdate" (in FreeBSD: dns/bind-tools)

if you want to use the Kerberos DNS challenge handler:

+ Kerberos kinit (either MIT or Heimdal should work)

install
-------

# make install [PREFIX=/usr/local] [DESTDIR=/some/where]

PREFIX is the base directory to install into.  if not specified, /usr/local
is assumed.

DESTDIR is prepend to PREFIX when installing files, and may be used when
creating packages.

a FreeBSD periodic(8) script is provided as "900.lfacme.sh" and will be
installed automatically on FreeBSD.  to run lfacme-renew once a day to
renew certificates, set "daily_lfacme_enable=YES" in /etc/periodic.conf.

usage
-----

+ create the config files (see below):
	/usr/local/etc/lfacme/acme.conf and
	/usr/local/etc/lfacme/domains.conf
+ run "lfacme-setup" to create an ACME account
+ run "lfacme-renew" to issue certificates
+ put "lfacme-renew" in cron if you want to renew certificates automatically.
  it's fine to run this once a day, since it won't renew certificates unless
  they're going to expire soon.

known issues
------------

+ we disable ARI in uacme (uacme --no-ari) because it's broken on non-glibc
  platforms.  this is a uacme bug: https://github.com/ndilieto/uacme/issues/91.
  the only impact of this is that certificates will be renewed 30 days before
  expiry, instead of when the ACME server wants us to renew them.
 
config files
------------

there are two configuration files:

+ acme.conf configures the global behaviour of lfacme
+ domains.conf lists the certificates lfacme should issue

these both come with manual pages which explain how to configure them,
and sample configs are provided.

BIND + Kerberos configuration
-----------------------------

if you want to use the provided Kerberos dns-01 challenge, you must configure
your DNS server to accept Kerberos-authenticated dynamic updates.

first, tell BIND where to load its Kerberos keytab from:

	options {
		tkey-gssapi-keytab "/usr/local/etc/namedb/krb5.keytab";
	};

the keytab MUST contain a server key for "DNS/name.of.server@<realm>", where
"name.of.server" MUST be the SOA MNAME for the zone(s) you want to update.
this is not configurable, it's a requirement of how the protocol works.

an update policy like this will allow any host to update ACME challenges for
its own hostname:

	update-policy {
		# note: "EXAMPLE.ORG" is the Kerberos realm, not the DNS zone!
		grant EXAMPLE.ORG krb5-selfsub . TXT;
	};

or to let a specific host update some other records:

	update-policy {
		grant "host/server.example.org@EXAMPLE.ORG"
			name _acme-challenge.example.org. TXT;

		grant "host/server.example.org@EXAMPLE.ORG"
			name _acme-challenge.www.example.org. TXT;
	};

this might also work with the Microsoft Windows DNS server,
but that hasn't been tested.