@@ -6,6 +6,132 @@ Interact with [NearlyFreeSpeech.NET][]'s [API][] from the command line.

 [NearlyFreeSpeech.NET]: https://www.nearlyfreespeech.net

 [API]: https://en.wikipedia.org/wiki/API

+## Goals

+

+`nfsn-utils` has three main goals:

+

+1.  **Be portable** (even to things like [routers][]).

+

+    POSIX shell is used as glue for standard utilities. See

+    [dependencies](#dependencies).

+

+2.  **Be modular** where it makes sense.

+

+    [`nfsn-send`](#nfsn-send) is a general purpose [NearlyFreeSpeech.NET][]

+    [API][] wrapper. [`nfsn-dns-update`](#nfsn-dns-update) is a general purpose

+    [NearlyFreeSpeech.NET][] DNS update utility.

+

+3.  **Be opinionated with sane defaults** where it makes sense.

+

+    The smaller utilities assume things like that you want to use [standard

+    email addresses][].

+

+4.  **Be easily auditable**.

+

+    The scripts are well abstracted and no more than about 100 lines of code.

+

+[routers]: https://openwrt.org

+[standard email addresses]: https://www.ietf.org/rfc/rfc2142.txt

+

+## Prerequisites

+

+### API key

+

+As described in the [NearlyFreeSpeech.NET][] [documentation][], one needs to

+submit a [free assistance request][] to obtain an API key.

+

+Place the credentials in the environment variables `NFSN_LOGIN` and

+`NFSN_API_KEY` or in the file `./.nfsn-api` or `$HOME/.nfsn-api` (location

+overridable by the `NFSN_CREDENTIALS_PATH` environment variable). This file

+should be a JSON file consisting of an object with the keys `login` and

+`api-key`. (The file format and default location is compatible with

+[WebService::NFSN][] and [python-nfsn][].)

+

+[documentation]: https://members.nearlyfreespeech.net/wiki/API/Introduction

+[free assistance request]: https://members.nearlyfreespeech.net/support/assist?tag=apikey

+[WebService::NFSN]: https://metacpan.org/pod/WebService::NFSN#INTERFACE

+[python-nfsn]: https://github.com/ktdreyer/python-nfsn#authentication

+

+### Dependencies

+

+-  Unix-like environment (in particular, `/dev/urandom`).

+-  [POSIX utilities][] with `date` supporting `+%s` (such as GNU `date`).

+-  `sha1sum` (for instance, the one in `coreutils`).

+-  [curl][].

+-  [jq][].

+-  `certbot` (only needed for `nfsn-dns-certbot*`).

+

+[POSIX utilities]: http://pubs.opengroup.org/onlinepubs/9699919799/idx/utilities.html

+[curl]: https://curl.haxx.se

+[jq]: https://github.com/stedolan/jq

+

+## Included programs

+

+Dependency graph:

+

+![included programs](doc/included-programs.dot.png)

+

+### `nfsn-send`

+

+Wraps the Requests, Responses and Authentication described in the

+[NearlyFreeSpeech.NET][] [documentation][].

+

+### `nfsn-dns-update`

+

+Updates several DNS records and outputs what data was actually changed.

+

+### `nfsn-dns-a`

+

+Updates DNS [A][] records, used to map hostnames to an IPv4 address.

+

+[A]: https://en.wikipedia.org/wiki/List_of_DNS_record_types#A

+

+### `nfsn-dns-spf`

+

+Updates DNS [SPF][] records, used for email authorization (specifying who is

+allowed to send mail from a domain).

+

+[SPF]: https://en.wikipedia.org/wiki/Sender_Policy_Framework

+

+### `nfsn-dns-dkim`

+

+Updates DNS [DKIM][] records, used for email authentication (using digital

+signatures).

+

+[DKIM]: https://en.wikipedia.org/wiki/DomainKeys_Identified_Mail

+

+### `nfsn-dns-dmarc`

+

+Updates DNS [DMARC][] records, extending [SPF][] and [DKIM][] by specifying

+failure policy and reporting.

+

+See also the [dmarc.org FAQ][].

+

+[DMARC]: https://en.wikipedia.org/wiki/DMARC

+[dmarc.org FAQ]: https://dmarc.org/wiki/FAQ#Sender_Questions

+

+### `nfsn-dns-certbot*`

+

+`nfsn-dns-certbot` calls [certbot][] (the [Electronic Frontier Foundation][]'s

+(EFF) [Let's Encrypt][] client, for getting HTTPS certificates) in [manual

+mode][] to make it use `nfsn-utils` to update DNS records in order to fullfill

+the [`dns-01` challenge][]. It does this by registering

+`nfsn-dns-certbot-{auth,cleanup}` as [hooks][].

+

+By default, the `auth` hook sleeps for 30 seconds to let the DNS records

+propagate. This can be overridden with the environment variable

+`NFSN_DNS_CERTBOT_AUTH_SLEEP`.

+

+Given that `nfsn-dns-certbot` has successfully run once, running `certbot

+renew` will suffice to renew the certificates.

+

+[certbot]: https://certbot.eff.org

+[Electronic Frontier Foundation]: https://www.eff.org

+[Let's Encrypt]: https://letsencrypt.org

+[manual mode]: https://certbot.eff.org/docs/using.html#manual

+[`dns-01` challenge]: https://tools.ietf.org/html/draft-ietf-acme-acme-03#section-7.4

+[hooks]: https://certbot.eff.org/docs/using.html#hooks

+

 ## License

 Licensed under the [ISC License][] unless otherwise noted, see the

@@ -5,3 +5,11 @@ Interact with [NearlyFreeSpeech.NET][]'s [API][] from the command line.

 [`nfsn-utils`]: https://git.rcrnstn.net/rcrnstn/nfsn-utils

 [NearlyFreeSpeech.NET]: https://www.nearlyfreespeech.net

 [API]: https://en.wikipedia.org/wiki/API

+

+## License

+

+Licensed under the [ISC License][] unless otherwise noted, see the

+[`LICENSE`][] file.

+

+[ISC License]: https://choosealicense.com/licenses/isc

+[`LICENSE`]: LICENSE

new file mode 100644

@@ -0,0 +1,7 @@

+# [`nfsn-utils`][]

+

+Interact with [NearlyFreeSpeech.NET][]'s [API][] from the command line.

+

+[`nfsn-utils`]: https://git.rcrnstn.net/rcrnstn/nfsn-utils

+[NearlyFreeSpeech.NET]: https://www.nearlyfreespeech.net

+[API]: https://en.wikipedia.org/wiki/API