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 Kerberized 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 Kerberized nsupdate challenge handler:

+ BIND's "dig" and "nsupdate" (in FreeBSD: dns/bind-tools)
+ Kerberos kinit (either MIT or Heimdal should work)

install
-------

# make install [DESTDIR=/some/where]

usage
-----

+ create the config files (see below):
	/usr/local/etc/uacme/acme.conf and
	/usr/local/etc/uacme/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
------------

+ lfacme assumes it's installed in /usr/local.  if you want to change this,
  you'll need to edit the scripts.

+ 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.