====== LetSyncrypt - Let's Encrypt Client ======

LetSyncrypt is a [[https://letsencrypt.org/|Let's Encrypt]] client for Synchronet which uses the ACMEv2 protocol.

//Let's Encrypt// is an Internet Certificate Authority that issues **free** certificates that may be used with Synchronet TLS (e.g. HTTPS).

If you don't want to use the default generated and self-signed SSL/TLS certificate (''ctrl/ssl.cert''), use of this module is the solution.

**NOTE:** This method of auto-certificate generation/renewal requires inbound TCP Port 80 to be open to the internet to allow Let's Encrypt servers to verify keys via ACMEv2 protocol.

===== Install =====

LetSyncrypt should be added as a timed event.

Add the Timed Event in [[util:SCFG]]->External Programs->Timed Events:
<file>
Internal Code                   SYNCRYPT
Start-up Directory
Command Line                    ?letsyncrypt.js
Enabled                         Yes
Execution Node                  1
Execution Months                Any
Execution Days of Month         Any
Execution Days of Week          All
Execution Frequency             1 times a day
Requires Exclusive Execution    No
Force Users Off-line For Event  No
Native Executable               No
Use Shell to Execute            No
Background Execution            No
Always Run After Init/Re-init   Yes
</file>

===== Configure =====

LetSyncrypt is configured via the ''[[dir:ctrl]]/[[http://cvs.synchro.net/cgi-bin/viewcvs.cgi/ctrl/letsyncrypt.ini|letsyncrypt.ini]]'' file.

You must indicate that you agree to the Let's Encrypt Terms of Service by setting ''TOSAgreed = true'' in this file.

You can specify the ACMEv2 endpoint using the ''Host'' and ''Directory'' keys in the [[config:ini_files#root_section|root section]] of this file.  ''Host'' is the domain name of the ACMEv2 endpoint, and ''Directory'' is appended to it to generate the URL that is fetched for the Directory object.  

You may change the email address used for the account with the SysopEmail key (defaults to to the sysop email address on the BBS)

<file ini>
Host = acme-v02.api.letsencrypt.org
Directory = /directory
TOSAgreed = true
GroupReadableKeyFile = false
SysopEmail = sysop@example.com
</file>

Note that without setting ''TOSAgreed = true'', you will likely never get a certificate, but the first few words in this file at present are "This Subscriber Agreement (“Agreement”) is a legally binding contract".

Do not modify the ''[State]'' or ''[key_id]'' sections of this file.

==== Domains ====

If you have multiple domain names, you can have LetSyncrypt put them all in a single certificate, even if you have virtual hosts.  Edit the ''[[dir:ctrl]]/letsyncrypt.ini'' file and add a ''[Domains]'' section (if it doesn't already exist) and a key for each hostname with the value of the web root for that domain:

<file ini>
[Domains]
yourbbs.synchro.net = /sbbs/webv4/root
nix.synchro.net = /sbbs/web/root
home.bbsdev.net = /sbbs/web/root
gallery.bbsdev.net = /sbbs/web/root/gallery.bbsdev.net
pics.bbsdev.net = /sbbs/web/root/pics.bbsdev.net
</file>

This example has five domains (yourbbs.synchro.net, nix.synchro.net, home.bbsdev.net, gallery.bbsdev.net, and pics.bbsdev.net).  The last two are virtual hosts, so have their web root as a subdirectory of the main [[server:web]] root.

===== Running Manually =====

You can also run the LetSyncrypt script using [[util:jsexec]].  It accepts a number of arguments:

''%%--new-key%%'' Changes the account key

''%%--force%%'' Forces a certificate renewal, ignoring the expiration date of the current certificate.

''%%--revoke%%'' Revokes the current certificate, then obtains a new one.

''%%--tos%%'' Prints the URL for the Terms of Service.

===== See Also =====
  * [[:module:|Modules]]
  * [[certtool|Synchronet Certificate Tool]]

{{tag>tls ssl cert https crypt jsutil}}