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

Release 0.4
-----------

    Florian Hanika <florian.hanika@gmail.com>
    neumann@wu-wien.ac.at

This is a NaviServer module that implements a small Let's Encrypt ACME
client for NaviServer. 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
provied 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.
- OpenSSL binaries installed (the "openssl" command will be executed
  during certificate generation via "exec")

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 toplevel
   used for saving ACME-challenges (a link to the toplevel
   ".well-known" directory on the primary server is sufficient)

Installation:

Users might want to run "make install" from this directory to install
the script in the page dir. This is ok for non-public servers, but
otherwise please thinks about a proper space where to place
"letsencrypt.tcl"

OpenACS users might wish to copy it to packages/acs-subsite/www/admin/
such that only admins can execute it. 


Configuration:

See the top section of "letsencrypt.tcl".