Let's Encrypt ACME client for NaviServer
========================================

Release 0.6
-----------

    Florian Hanika <[email protected]>
    [email protected]

This is a NaviServer module that implements a small Let's Encrypt ACME
client for NaviServer based on the ACME v2 interface.

When the script is called via the browser, it prompts the user to
enter one ore more domain names (blank separated) and generated for
this a Let's Encrypt certificate by creating automatically a
letsencrypt account (or reuses the account, if it was created before),
the necessary challenges etc. Finally it obtains a certificate and
tries to update the actual config file if necessary.

The package supports Multi-Domain (SAN) Certificates, using the first
provided domain name as primary name and places the other names into
the Subject Alternative Field Name (SAN) field, such that the
same certificate can be used for all provided names.


When running this script, sometimes the Let's Encrypt interface
rejects the generated keys. Probably, the problem occurs, when the
last bit is "0", which is interpreted as a key with 2047 bits:
https://groups.google.com/forum/#!msg/mozilla.dev.security.policy/fOtt14fiDaM/IsvYqyPrNrcJ
There is no need to worry about this, since the script will retry with
another set of keys until the operation succeeds, which happens
usually after the second or third attempt.

When experimenting with this script, you might consider using the
"staging" API instead of the production API to avoid to run into rate
limits. See on the begin of letsencrypt.tcl.


Requirements:

- NaviServer (4.99.15 or newer) with the integrated OpenSSL support
  activated.
- Next Scripting Framework 2.0 or newer
- Tcllib (e.g. 1.15) installed on the Tcl library search path
  (used for the "json" package).
- OpenSSL binaries installed (the "openssl" command will be executed
  during a run of the script)

During runtime, the server (nsd) needs write permissions on
 a) [ns_info home]/modules/nsssl (for the certificate data)
 b) [ns_server pagedir] (for the challenge files)
 c) [ns_info config] (for updating the config file if necessary)

In order to obain multi-domain SAN certificates, simply add the domain
names space separated to the dialog that shows up after calling
letsencrypt.tcl. Make sure that
a) the DNS entries for all names are known to letsencrypt.org,
b) the servers behind these DNS entries are running, and
c) share the same ".well-known" directory on the top-level
   used for saving ACME-challenges (a link to the top-level
   ".well-known" directory on the primary server is sufficient)

Installation:

Run "make install" from the letsencrypt module directory.  When
letsencrypt should be called interactively, you might consider copying
the "letsencrypt.tcl" on a web-accessible place on your server and
configuring the access rights to it.  OpenACS users might wish to copy
"letsencrypt.tcl" to packages/acs-subsite/www/admin/ such that only
admins can execute it.

Configuration:

See the top section of the script "letsencrypt.tcl".

To activate the module add the following section to your NaviServer
configuration script.

    ns_section ns/server/${server}/modules {
       ns_param letsencrypt tcl
    }
    ns_section ns/server/${server}/module/letsencrypt {
       #
       # Provide one or more domain names (latter for multi-domain SAN
       # certificates). These values are a default in case the domains
       # are not provided by other means (e.g. "letsencrypt.tcl").  In
       # case multiple NaviServer virtual hosts are in used, this
       # definition must be on the ${server}, which is used for
       # obtaining updates (e.g. main site) although it retrieves a
       # certificate for many subsites.
       #
       #ns_param domains {} ;# e.g. "foo.com www.foo.com"
    }