diff options
| -rw-r--r-- | Makefile | 32 | ||||
| -rw-r--r-- | README | 2 | ||||
| -rw-r--r-- | lacme-accountd.1 | 152 | ||||
| -rw-r--r-- | lacme-accountd.md | 143 | ||||
| -rw-r--r-- | lacme.1 | 364 | ||||
| -rw-r--r-- | lacme.md | 355 |
6 files changed, 528 insertions, 520 deletions
@@ -1,6 +1,29 @@ -all: +MANPAGES = lacme-accountd.1 lacme.1 -install: +all: ${MANPAGES} + +# upper case the headers and remove the links +%.1: %.md + @pandoc -S -f markdown -t json "$<" | \ + jq ".[1][] |= if .t == \"Header\" then .c[2][] |= (if .t == \"Str\" then .c |= ascii_upcase else . end) else . end" | \ + jq " \ + def fixit: \ + if type == \"object\" then \ + if .t == \"Link\" then \ + if .c[2][0][0:7] == \"mailto:\" then . else .c[1][] end \ + else \ + map_values(fixit) \ + end \ + else if type == \"array\" then \ + map(fixit) \ + else \ + . \ + end \ + end; \ + map(fixit)" | \ + pandoc -sS -f json -t man -o "$@" + +install: ${MANPAGES} install -d $(DESTDIR)/etc/lacme install -m0644 -t $(DESTDIR)/etc/lacme config/*.conf install -d $(DESTDIR)/usr/share/lacme @@ -12,4 +35,7 @@ install: install -d $(DESTDIR)/usr/bin install -m0644 -t $(DESTDIR)/usr/bin lacme-accountd lacme -.PHONY: all install +clean: + rm -vf ${MANPAGES} + +.PHONY: all install clean @@ -27,7 +27,7 @@ own executable: port. (The only challenge type currently supported is "http-01", which requires a webserver to answer challenges.) That webserver only processes GET and HEAD requests under the - "/.well-known/acme-challenge/" URI. By default some iptables(1) + "/.well-known/acme-challenge/" URI. By default some iptables(8) rules are automatically installed to open the HTTP port, and removed afterwards. diff --git a/lacme-accountd.1 b/lacme-accountd.1 deleted file mode 100644 index 46a6a0d..0000000 --- a/lacme-accountd.1 +++ /dev/null @@ -1,152 +0,0 @@ -.TH LACME\-ACCOUNTD "1" "MARCH 2016" "ACME client (account key manager)" "User Commands" - -.SH NAME -lacme\-accountd \- ACME client (account key manager) - -.SH SYNOPSIS -.B lacme\-accountd\fR [\fB\-\-config=\fIFILENAME\fR] -[\fB\-\-privkey=\fIARG\fR] [\fB\-\-socket=\fIPATH\fR] [\fB\-\-quiet\fR] - - -.SH DESCRIPTION -.PP -.B lacme\-accountd\fR is the account key manager component of -\fIlacme\fR(1), a tiny ACME client written with process isolation and -minimal privileges in mind. No other \fIlacme\fR(1) component need -access to the account key; in fact the account key could also be stored -on a smartcard. - -.B lacme\-accountd\fR binds to a UNIX\-domain socket (specified with -\fB\-\-socket=\fR), which ACME clients can connect to in order to -request data signatures. -As a consequence, \fBlacme\-accountd\fR needs to be up and running -before using \fIlacme\fR(1) to issue ACME commands. Also, the process -does not automatically terminate after the last signature request: -instead, one sends an \fIINT\fR or \fITERM\fR signal to bring the server -down. - -Furthermore, one can use the UNIX\-domain socket forwarding facility of -OpenSSH 6.7 and later to run \fBlacme\-accountd\fR and \fIlacme\fR(1) on -different hosts. For instance one could store the account key on a -machine that is not exposed to the internet. See the \fBEXAMPLES\fR -section below. - - -.SH OPTIONS -.TP -.B \-\-config=\fIfilename\fR -Use \fIfilename\fR as configuration file. See the \fBCONFIGURATION -FILE\fR section below for the configuration options. - -.TP -.B \-\-privkey=\fIarg\fR -Specify the (private) account key to use for signing requests. -Currently supported \fIarg\fRuments are: - -.RS -.IP \[bu] 2 -file:\fIFILE\fR, to specify an encrypted private key (in PEM format); and -.IP \[bu] -gpg:\fIFILE\fR, to specify a \fIgpg\fR(1)\-encrypted private key (in PEM format). - -.PP -The following command can be used to generate a new 4096\-bits RSA key in -PEM format with mode 0600: - -.nf - openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/priv.key -.fi -.RE - -.TP -.B \-\-socket=\fIpath\fR -Use \fIpath\fR as the UNIX\-domain socket to bind against for signature -requests from the ACME client. \fBlacme\-accountd\fR aborts if -\fIpath\fR exists or if its parent directory is writable by other users. - -.TP -.B \-?\fR, \fB\-\-help\fR -Display a brief help and exit. - -.TP -.B \-q\fR, \fB\-\-quiet\fR -Be quiet. - -.TP -.B \-\-debug -Turn on debug mode. - - -.SH CONFIGURATION FILE -If \fB\-\-config=\fR is not given, \fBlacme\-accountd\fR uses the first -existing configuration file among \fI./lacme\-accountd.conf\fR, -\fI$XDG_CONFIG_HOME/lacme/lacme\-accountd.conf\fR (or -\fI~/.config/lacme/lacme\-accountd.conf\fR if the XDG_CONFIG_HOME -environment variable is not set), and -\fI/etc/lacme/lacme\-accountd.conf\fR. - -When given on the command line, the \fB\-\-privkey=\fR, -\fB\-\-socket=\fR and \fB\-\-quiet\fR options take precedence over their -counterpart (without leading \(lq\-\-\(rq) in the configuration file. -Valid options are: - -.TP -.I privkey -See \fB\-\-privkey=\fR. -This option is required when \fB\-\-privkey=\fR is not specified on the -command line. - -.TP -.I gpg -For a \fIgpg\fR(1)\-encrypted private account key, specify the binary -\fIgpg\fR(1) to use, as well as some default options. -Default: \(lqgpg \-\-quiet\(rq. - -.TP -.I socket -See \fB\-\-socket=\fR. -Default: \(lq$XDG_RUNTIME_DIR/S.lacme\(rq if the XDG_RUNTIME_DIR -environment variable is set. - -.TP -.I quiet -Be quiet. Possible values: \(lqYes\(rq/\(lqNo\(rq. - - -.SH EXAMPLES - -Run \fBlacme\-accountd\fR in a first terminal: - -.nf - ~$ lacme\-accountd \-\-privkey=file:/path/to/priv.key \-\-socket=/run/user/1000/S.lacme -.fi - -Then, while \fBlacme\-accountd\fR is running, execute locally -\fIlacme\fR(1) in another terminal: - -.nf - ~$ sudo lacme \-\-socket=/run/user/1000/S.lacme new\-cert -.fi - -Alternatively, use \fIssh\fR(1) to forward the socket and execute -\fIlacme\fR(1) remotely: - -.nf - ~$ ssh -oExitOnForwardFailure=yes -tt -R /path/to/remote.sock:/run/user/1000/S.lacme user@example.org \\ - sudo lacme --socket=/path/to/remote.sock new-cert -.fi - - -.SH SEE ALSO -\fBlacme\fR(1), \fBssh\fR(1) - -.SH AUTHOR -.ie \n[www-html] \{\ - Written by -. MTO guilhem@fripost.org "Guilhem Moulin" . -\} -.el \{\ - Written by Guilhem Moulin -. MT guilhem@fripost.org -. ME . -\} diff --git a/lacme-accountd.md b/lacme-accountd.md new file mode 100644 index 0000000..54b0ed7 --- /dev/null +++ b/lacme-accountd.md @@ -0,0 +1,143 @@ +% lacme-accountd(1) +% [Guilhem Moulin](mailto:guilhem@fripost.org) +% March 2016 + +Name +==== + +lacme-accountd - [ACME] client (account key manager) + +Synopsis +======== + +`lacme-accountd` [`--config=FILENAME`] [`--privkey=ARG`] [`--socket=PATH`] [`--quiet`] + +Description +=========== + +`lacme-accountd` is the account key manager component of [`lacme`(1)], a +small [ACME] client written with process isolation and minimal +privileges in mind. No other [`lacme`(1)] component needs access to the +account key; in fact the account key could as well be stored on another +host or a smartcard. + +`lacme-accountd` binds to a UNIX-domain socket (specified with +`--socket=`), which [ACME] clients can connect to in order to request +data signatures. +As a consequence, `lacme-accountd` needs to be up and running before +using [`lacme`(1)] to issue [ACME] commands. Also, the process does not +automatically terminate after the last signature request: instead, one +sends an `INT` or `TERM` [`signal`(7)] to bring the server down. + +Furthermore, one can use the UNIX-domain socket forwarding facility of +[OpenSSH] 6.7 and later to run `lacme-accountd` and [`lacme`(1)] on +different hosts. For instance one could store the account key on a +machine that is not exposed to the internet. See the +**[examples](#examples)** section below. + +Options +======= + +`--config=`*filename* + +: Use *filename* as configuration file. See the **[configuration + file](#configuration-file)** section below for the configuration + options. + +`--privkey=`*arg* + +: Specify the (private) account key to use for signing requests. + Currently supported *arg*uments are: + + * `file:`*FILE*, to specify an encrypted private key (in PEM + format); and + * `gpg:`*FILE*, to specify a [`gpg`(1)]-encrypted private key (in + PEM format). + + The following command can be used to generate a new 4096-bits RSA + key in PEM format with mode 0600: + + openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/priv.key + +`-socket=`*path* + +: Use *path* as the UNIX-domain socket to bind against for signature + requests from the [ACME] client. `lacme-accountd` aborts if *path* + exists or if its parent directory is writable by other users. + +`-?`, `--help` + +: Display a brief help and exit. + +`-q`, `--quiet` + +: Be quiet. + +`--debug` + +: Turn on debug mode. + +Configuration file +================== + +If `--config=` is not given, `lacme-accountd` uses the first existing +configuration file among *./lacme-accountd.conf*, +*$XDG_CONFIG_HOME/lacme/lacme-accountd.conf* (or +*~/.config/lacme/lacme-accountd.conf* if the `XDG_CONFIG_HOME` +environment variable is not set), and */etc/lacme/lacme-accountd.conf*. + +When given on the command line, the `--privkey=`, `--socket=` and +`--quiet` options take precedence over their counterpart (without +leading `--`) in the configuration file. Valid options are: + +*privkey* + +: See `--privkey=`. This option is required when `--privkey=` is not + specified on the command line. + +*gpg* + +: For a [`gpg`(1)]-encrypted private account key, specify the binary + [`gpg`(1)] to use, as well as some default options. + Default: `gpg --quiet`. + +*socket* + +: See `--socket=`. + Default: *$XDG_RUNTIME_DIR/S.lacme* if the `XDG_RUNTIME_DIR` + environment variable is set. + +*quiet* + +: Be quiet. Possible values: `Yes`/`No`. + +Examples +======== + +Run `lacme-accountd` in a first terminal: + + ~$ lacme-accountd --privkey=file:/path/to/priv.key --socket=/run/user/1000/S.lacme + +Then, while `lacme-accountd` is running, execute locally [`lacme`(1)] in +another terminal: + + ~$ sudo lacme --socket=/run/user/1000/S.lacme new-cert + +Alternatively, use [OpenSSH] 6.7 or later to forward the socket and +execute [`lacme`(1)] remotely: + + ~$ ssh -oExitOnForwardFailure=yes -tt -R /path/to/remote.sock:/run/user/1000/S.lacme user@example.org \ + sudo lacme --socket=/path/to/remote.sock new-cert + + +See also +======== + +[`lacme`(1)], [`ssh`(1)] + +[ACME]: https://tools.ietf.org/html/draft-ietf-acme-acme-02 +[`lacme`(1)]: lacme.1.html +[`signal`(7)]: http://linux.die.net/man/7/signal +[`gpg`(1)]: https://www.gnupg.org/documentation/manpage.en.html +[OpenSSH]: http://www.openssh.com/ +[`ssh`(1)]: http://man.openbsd.org/ssh diff --git a/lacme.1 b/lacme.1 deleted file mode 100644 index bfe4f45..0000000 --- a/lacme.1 +++ /dev/null @@ -1,364 +0,0 @@ -.TH LACME "1" "MARCH 2016" "ACME client" "User Commands" - -.SH NAME -lacme \- ACME client - -.SH SYNOPSIS -.B lacme\fR [\fB\-\-config=\fIFILENAME\fR] [\fB\-\-socket=\fIPATH\fR] -[\fIOPTION\fR ...] \fICOMMAND\fR [\fIARGUMENT\fR ...] - - -.SH DESCRIPTION -.PP -.B lacme\fR is a tiny ACME client written with process isolation and -minimal privileges in mind. -It is divided into four components, each with its own executable: - -.IP \[bu] 4 -A \fIlacme\-accountd\fR(1) process to manage the account key and issue -SHA\-256 signatures needed for each ACME command. (This process binds -to a UNIX\-domain socket to reply to signature requests from the ACME -client.) -One can use the UNIX\-domain socket forwarding facility of OpenSSH 6.7 -and later to run \fIlacme\-accountd\fR(1) and \fBlacme\fR on different -hosts. - -.IP \[bu] 4 -A \(lqmaster\(rq \fBlacme\fR process, which runs as root and is the only -component with access to the private key material of the server keys. -It is used to fork the ACME client (and optionally the ACME webserver) -after dropping root privileges. -For certificate issuances (\fBnew\-cert\fR command), it also generates -Certificate Signing Requests, then verifies the validity of the issued -certificate, and optionally reloads or restarts services when the -\fInotify\fR option is set. - -.IP \[bu] 4 -An actual ACME client (specified with the \fIcommand\fR option of the -\(lq[client]\(rq section of the configuration file), which builds ACME -commands and dialogues with the remote ACME server. -Since ACME commands need to be signed with the account key, the -\(lqmaster\(rq \fBlacme\fR process passes the \fIlacme\-accountd\fR(1) -UNIX\-domain socket to the ACME client: data signatures are requested by -writing the data to be signed to the socket. - -.IP \[bu] 4 -For certificate issuances (\fBnew\-cert\fR command), an optional -webserver (specified with the \fIcommand\fR option of the -\(lq[webserver]\(rq section of the configuration file), which is spawned -by the \(lqmaster\(rq \fBlacme\fR process when no service is listening -on the HTTP port. -(The only challenge type currently supported by \fBlacme\fR is -\(lqhttp\-01\(rq, which requires a webserver to answer challenges.) -That webserver only processes GET and HEAD requests under the -\(lq/.well\-known/acme\-challenge/\(rq URI. -By default some \fIiptables\fR(1) rules are automatically installed to -open the HTTP port, and removed afterwards. - -.SH COMMANDS -.TP -.B lacme \fR[\fB\-\-agreement\-uri=\fIURI\fR]\fB \fBnew\-reg -\fR[\fICONTACT\fR ...] Register the account key managed by -\fIlacme\-accountd\fR(1). A list of \fICONTACT\fR information (such as -\(lqmaito:\(rq URIs) can be specified in order for the server to contact -the client for issues related to this registration (such as -notifications about server\-initiated revocations). - -\fB\-\-agreement\-uri=\fR can be used to specify a \fIURI\fR referring -to a subscriber agreement or terms of service provided by the server; -adding this options indicates the client's agreement with the referenced -terms. Note that the server might require the client to agree to -subscriber agreement before performing any further actions. - -If the account key is already registered, \fBlacme\fR prints the URI of -the existing registration and aborts. - -.TP -.B lacme \fR[\fB\-\-agreement\-uri=\fIURI\fR]\fB \fBreg=\fIURI\fR \fR[\fICONTACT\fR ...] - -Dump or edit the registration \fIURI\fR (relative to the ACME server URI, -which is specified with the \fIserver\fR option of the \(lq[client]\(rq -section of the configuration file). - -When specified, the list of \fICONTACT\fR information and the agreement -\fIURI\fR are sent to the server to replace the existing values. - -.TP -.B lacme \fR[\fB\-\-config\-certs=\fIFILE\fR]\fB \fBnew\-cert \fR[\fISECTION\fR ...] - -Read the certificate configuration \fIFILE\fR (see the \fBCERTIFICATE -CONFIGURATION FILE\fR section below for the configuration options), and -request new Certificate Issuance for each of its sections (or the given -list of \fISECTION\fRs). - -.TP -.B lacme \fBrevoke\-cert \fIFILE\fR [\fIFILE\fR ...] - -Request that the given certificate(s) \fIFILE\fR(s) be revoked. For -this command, \fIlacme\-accountd\fR(1) can be pointed to either the -account key or the server's private key. - - -.SH GENERIC OPTIONS -.TP -.B \-\-config=\fIfilename\fR -Use \fIfilename\fR as configuration file. See the \fBCONFIGURATION -FILE\fR section below for the configuration options. - -.TP -.B \-\-socket=\fIpath\fR -Use \fIpath\fR as the \fIlacme\-accountd\fR(1) UNIX\-domain socket to -connect to for signature requests from the ACME client. \fBlacme\fR -aborts if \fIpath\fR is readable or writable by other users, or if its -parent directory is writable by other users. This overrides the -\fIsocket\fR option of the \(lq[client]\(rq section of the configuration -file. - -.TP -.B \-?\fR, \fB\-\-help\fR -Display a brief help and exit. - -.TP -.B \-\-debug -Turn on debug mode. - - -.SH CONFIGURATION FILE -If \fB\-\-config=\fR is not given, \fBlacme\fR uses the first existing -configuration file among \fI./lacme.conf\fR, -\fI$XDG_CONFIG_HOME/lacme/lacme.conf\fR (or -\fI~/.config/lacme/lacme.conf\fR if the XDG_CONFIG_HOME environment -variable is not set), and \fI/etc/lacme/lacme.conf\fR. -Valid options are: - -.TP -Default section -.RS -.TP -.I config\-certs -For certificate issuances (\fBnew\-cert\fR command), specify the -certificate configuration file to use (see the \fBCERTIFICATE -CONFIGURATION FILE\fR section below for the configuration options). -.RE - -.TP -\(lq[client]\(rq section -This section is used for configuring the ACME client (which takes care -of ACME commands and dialogues with the remote ACME server). - -.RS -.TP -.I socket -See \fB\-\-socket=\fR. -Default: \(lq$XDG_RUNTIME_DIR/S.lacme\(rq if the XDG_RUNTIME_DIR -environment variable is set. - -.TP -.I user -The username to drop privileges to (setting both effective and real -uid). -Preserve root privileges if the value is empty (not recommended). -Default: \(lqnobody\(rq. - -.TP -.I group -The groupname to drop privileges to (setting both effective and real -gid, and also setting the list of supplementary gids to that single -group). Preserve root privileges if the value is empty (not -recommended). -Default: \(lqnogroup\(rq. - -.TP -.I command -Path to the ACME client executable. -Default: \(lq/usr/lib/lacme/client\(rq. - -.TP -.I server -Root URI of the ACME server. -Default: \(lqhttps://acme\-v01.api.letsencrypt.org/\(rq. - -.TP -.I timeout -Timeout in seconds after which the client stops polling the ACME server -and considers the request failed. -Default: \(lq10\(rq. - -.TP -.I SSL_verify -Whether to verify the server certificate chain. -Default: \(lqYes\(rq. - -.TP -.I SSL_version -Specify the version of the SSL protocol used to transmit data. - -.TP -.I SSL_cipher_list -Specify the cipher list for the connection. -.RE - -.TP -\(lq[webserver]\(rq section -This section is used for configuring the ACME webserver. - -.RS -.TP -.I listen -Specify the local address to listen on, in the form -\fIADDRESS\fR[:\fIPORT\fR]. -If \fIADDRESS\fR is enclosed with brackets \(oq[\(cq/\(oq]\(cq then it -denotes an IPv6; an empty \fIADDRESS\fR means \(oq0.0.0.0\(cq. -Default: \(lq:80\(rq. - -.TP -.I challenge\-directory -If a webserver is already running, specify a non\-existent directory -under which the webserver is configured to serve GET requests for -challenge files under \(lq/.well\-known/acme\-challenge/\(rq (for each -virtual hosts requiring authorization) as static files. -Default: \(lq/var/www/acme\-challenge\(rq. - -.TP -.I user -The username to drop privileges to (setting both effective and real -uid). -Preserve root privileges if the value is empty (not recommended). -Default: \(lqwww\-data\(rq. - -.TP -.I group -The groupname to drop privileges to (setting both effective and real -gid, and also setting the list of supplementary gids to that single -group). Preserve root privileges if the value is empty (not -recommended). -Default: \(lqwww\-data\(rq. - -.TP -.I command -Path to the ACME webserver executable. -Default: \(lq/usr/lib/lacme/webserver\(rq. - -.TP -.I iptables -Whether to automatically install \fIiptables\fR(1) rules to open the -\fIADDRESS\fR[:\fIPORT\fR] specified with \fIlisten\fR. -Theses rules are automatically removed once \fBlacme\fR exits. -Default: \(lqYes\(rq. -.RE - - -.SH CERTIFICATE CONFIGURATION FILE -For certificate issuances (\fBnew\-cert\fR command), a separate file is -used to configure paths to the certificate and key, as well as the -subject, subjectAltName, etc. to generate Certificate Signing Requests. -If \fB\-\-config\-certs=\fR is not given, and if the \fIconfig\-certs\fR -configuration option is absent, then \fBlacme\fR uses the first existing -configuration file among \fI./lacme\-certs.conf\fR, -\fI$XDG_CONFIG_HOME/lacme/lacme\-certs.conf\fR (or -\fI~/.config/lacme/lacme\-certs.conf\fR if the XDG_CONFIG_HOME -environment variable is not set), and -\fI/etc/lacme/lacme\-certs.conf\fR. -Each section denotes a separate certificate issuance. -Valid options are: - -.TP -.I certificate -Where to store the issued certificate (in PEM format). -At least one of \fIcertificate\fR or \fIcertificate\-chain\fR is -required. - -.TP -.I certificate\-chain -Where to store the issued certificate, concatenated with the content of -the file specified specified with the \fICAfile\fR option (in PEM -format). -At least one of \fIcertificate\fR or \fIcertificate\-chain\fR is -required. - -.TP -.I certificate\-key -Path the service's private key. This option is required. The following -command can be used to generate a new 4096\-bits RSA key in PEM format -with mode 0600: - -.nf - openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/priv.key -.fi - -.TP -.I min\-days -For an existing certificate, the minimum number of days before its -expiration date the section is considered for re\-issuance. -Default: \(lq10\(rq. - - -.TP -.I CAfile -Path to the issuer's certificate. This is used for -\fIcertificate\-chain\fR and to verify the validity of each issued -certificate. -Specifying an empty value skip certificate validation. -Default: \(lq/usr/share/lacme/lets\-encrypt\-x3\-cross\-signed.pem\(rq. - -.TP -.I hash -Message digest to sign the Certificate Signing Request with. - -.TP -.I keyUsage -Comma\-separated list of Key Usages, see \fIx509v3_config\fR(5ssl). - -.TP -.I subject -Subject field of the Certificate Signing Request, in the form -\fR/\fItype0\fR=\fIvalue0\fR/\fItype1\fR=\fIvalue1\fR/\fItype2\fR=... -This option is required. - -.TP -.I subjectAltName -Comma\-separated list of Subject Alternative Names, in the form -\fItype0\fR:\fIvalue1\fR,\fItype1\fR:\fIvalue1\fR,\fItype2\fR:... -The only \fItype\fR currently supported is \(lqDNS\(rq, to specify an -alternative domain name. - -.TP -.I chown -An optional \fIusername\fR[:\fIgroupname\fR] to chown the issued -\fIcertificate\fR and \fIcertificate\-chain\fR with. - -.TP -.I chmod -An optional octal mode to chmod the issued \fIcertificate\fR and -\fIcertificate\-chain\fR with. - -.TP -.I notify -Command to pass the the system's command shell (\(lq/bin/sh \-c\(rq) -after successful installation of the \fIcertificate\fR and/or -\fIcertificate\-chain\fR. - - -.SH EXAMPLES - -.nf - ~$ sudo lacme new-reg mailto:noreply@example.com - ~$ sudo lacme reg=/acme/reg/137760 --agreement-uri=https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf - ~$ sudo lacme new-cert - ~$ sudo lacme revoke-cert /path/to/server/certificate.pem -.fi - - -.SH SEE ALSO -\fBlacme\-accountd\fR(1) - -.SH AUTHOR -.ie \n[www-html] \{\ - Written by -. MTO guilhem@fripost.org "Guilhem Moulin" . -\} -.el \{\ - Written by Guilhem Moulin -. MT guilhem@fripost.org -. ME . -\} diff --git a/lacme.md b/lacme.md new file mode 100644 index 0000000..a16f23d --- /dev/null +++ b/lacme.md @@ -0,0 +1,355 @@ +% lacme(1) +% [Guilhem Moulin](mailto:guilhem@fripost.org) +% December 2015 + +Name +==== + +lacme - [ACME] client + +Synopsis +======== + +`lacme` [`--config=FILENAME`] [`--socket=PATH`] [*OPTION* …] *COMMAND* [*ARGUMENT* …] + +Description +=========== + +`lacme` is a small [ACME] client written with process isolation and +minimal privileges in mind. It is divided into four components, each +with its own executable: + + 1. A [`lacme-accountd`(1)] process to manage the account key and issue + SHA-256 signatures needed for each [ACME] command. (This process + binds to a UNIX-domain socket to reply to signature requests from + the [ACME] client.) + One can use the UNIX-domain socket forwarding facility of OpenSSH + 6.7 and later to run [`lacme-accountd`(1)] and `lacme` on different + hosts. + + 2. A “master” `lacme` process, which runs as root and is the only + component with access to the private key material of the server + keys. It is used to fork the [ACME] client (and optionally the + [ACME] webserver) after dropping root privileges. + For certificate issuances (`new-cert` command), it also generates + Certificate Signing Requests, then verifies the validity of the + issued certificate, and optionally reloads or restarts services when + the *notify* option is set. + + 3. An actual [ACME] client (specified with the *command* option of the + [`[client]` section](#client-section) of the configuration file), + which builds [ACME] commands and dialogues with the remote [ACME] + server. + Since [ACME] commands need to be signed with the account key, the + “master” `lacme` process passes the [`lacme-accountd`(1)] + UNIX-domain socket to the [ACME] client: data signatures are + requested by writing the data to be signed to the socket. + + 4. For certificate issuances (`new-cert` command), an optional + webserver (specified with the *command* option of the [`[webserver]` + section](#webserver-section) of the configuration file), which is + spawned by the “master” `lacme` process when no service is listening + on the HTTP port. (The only challenge type currently supported by + `lacme` is `http-01`, which requires a webserver to answer + challenges.) That webserver only processes `GET` and `HEAD` requests + under the `/.well-known/acme-challenge/` URI. + By default some [`iptables`(8)] rules are automatically installed to + open the HTTP port, and removed afterwards. + +Commands +======== + +`lacme` [`--agreement-uri=`*URI*] `new-reg` [*CONTACT* …] + +: Register the account key managed by [`lacme-accountd`(1)]. A list + of *CONTACT* information (such as `maito:` URIs) can be specified in + order for the server to contact the client for issues related to + this registration (such as notifications about server-initiated + revocations). + + `--agreement-uri=` can be used to specify a *URI* referring to a + subscriber agreement or terms of service provided by the server; + adding this options indicates the client's agreement with the + referenced terms. Note that the server might require the client to + agree to subscriber agreement before performing any further actions. + + If the account key is already registered, `lacme` prints the URI of + the existing registration and aborts. + +`lacme` [`--agreement-uri=`*URI*] `reg=`*URI* [*CONTACT* …] + +: Dump or edit the registration *URI* (relative to the [ACME] server + URI, which is specified with the *server* option of the [`[client]` + section](#client-section) of the configuration file). + + When specified, the list of *CONTACT* information and the agreement + *URI* are sent to the server to replace the existing values. + +`lacme` [`--config-certs=`*FILE*] `new-cert` [*SECTION* …] + +: Read the certificate configuration *FILE* (see the **[certificate + configuration file](#certificate-configuration-file)** section below + for the configuration options), and request new Certificate Issuance + for each of its sections (or the given list of *SECTION*s). + +`lacme` `revoke-cert` *FILE* [*FILE* …] + +: Request that the given certificate(s) *FILE*(s) be revoked. For + this command, [`lacme-accountd`(1)] can be pointed to either the + account key or the server's private key. + +Generic options +=============== + +`--config=`*filename* + +: Use *filename* as configuration file. See the **[configuration + file](#configuration-file)** section below for the configuration + options. + +`--socket=`*path* + +: Use *path* as the [`lacme-accountd`(1)] UNIX-domain socket to + connect to for signature requests from the [ACME] client. `lacme` + aborts if `path` is readable or writable by other users, or if its + parent directory is writable by other users. This overrides the + *socket* option of the [`[client]` section](#client-section) of the + configuration file. + +`-?`, `--help` + +: Display a brief help and exit. + +`--debug` + +: Turn on debug mode. + +Configuration file +================== + +If `--config=` is not given, `lacme` uses the first existing +configuration file among *./lacme.conf*, +*$XDG_CONFIG_HOME/lacme/lacme.conf* (or *~/.config/lacme/lacme.conf* if +the `XDG_CONFIG_HOME` environment variable is not set), and +*/etc/lacme/lacme.conf*. +Valid options are: + +Default section +--------------- + +*config-certs* + +: For certificate issuances (`new-cert` command), specify the + certificate configuration file to use (see the **[certificate + configuration file](#certificate-configuration-file)** section below + for the configuration options). + +`[client]` section +------------------ + +This section is used for configuring the [ACME] client (which takes care +of [ACME] commands and dialogues with the remote [ACME] server). + +*socket* + +: See `--socket=`. + Default: *$XDG_RUNTIME_DIR/S.lacme* if the `XDG_RUNTIME_DIR` + environment variable is set. + +*user* + +: The username to drop privileges to (setting both effective and real + uid). Preserve root privileges if the value is empty (not + recommended). + Default: `nobody`. + +*group* + +: The groupname to drop privileges to (setting both effective and real + gid, and also setting the list of supplementary gids to that single + group). Preserve root privileges if the value is empty (not + recommended). + Default: `nogroup`. + +*command* + +: Path to the [ACME] client executable. + Default: `/usr/lib/lacme/client`. + +*server* + +: Root URI of the [ACME] server. + Default: `https://acme-v01.api.letsencrypt.org/`. + +*timeout* + +: Timeout in seconds after which the client stops polling the [ACME] + server and considers the request failed. + Default: `10`. + +*SSL_verify* + +: Whether to verify the server certificate chain. + Default: `Yes`. + +*SSL_version* + +: Specify the version of the SSL protocol used to transmit data. + +*SSL_cipher_list* + +: Specify the cipher list for the connection, see [`ciphers`(1ssl)] + for more information. + +`[webserver]` section +--------------------- + +This section is used for configuring the [ACME] webserver. + +*listen* + +: Specify the local address to listen on, in the form + `ADDRESS[:PORT]`. If `ADDRESS` is enclosed with brackets ‘[’/‘]’ + then it denotes an IPv6; an empty `ADDRESS` means `0.0.0.0`. + Default: `:80`. + +*challenge-directory* + +: If a webserver is already running, specify a non-existent directory + under which the webserver is configured to serve `GET` requests for + challenge files under `/.well-known/acme-challenge/` (for each + virtual hosts requiring authorization) as static files. + Default: `/var/www/acme-challenge`. + +*user* + +: The username to drop privileges to (setting both effective and real + uid). Preserve root privileges if the value is empty (not + recommended). + Default: `www-data`. + +*group* + +: The groupname to drop privileges to (setting both effective and real + gid, and also setting the list of supplementary gids to that single + group). Preserve root privileges if the value is empty (not + recommended). + Default: `www-data`. + +*command* + +: Path to the [ACME] webserver executable. + Default: `/usr/lib/lacme/webserver`. + +*iptables* + +: Whether to automatically install [`iptables`(8)] rules to open the + `ADDRESS[:PORT]` specified with *listen*. Theses rules are + automatically removed once `lacme` exits. + Default: `Yes`. + +Certificate configuration file +============================== + +For certificate issuances (`new-cert` command), a separate file is used +to configure paths to the certificate and key, as well as the subject, +subjectAltName, etc. to generate Certificate Signing Requests. +If `--config-certs=` is not given, and if the `config-certs` +configuration option is absent, then `lacme` uses the first existing +configuration file among *./lacme-certs.conf*, +*$XDG_CONFIG_HOME/lacme/lacme-certs.conf* (or +*~/.config/lacme/lacme-certs.conf* if the `XDG_CONFIG_HOME` environment +variable is not set), and */etc/lacme/lacme-certs.conf*. +Each section denotes a separate certificate issuance. +Valid options are: + +*certificate* + +: Where to store the issued certificate (in PEM format). + At least one of *certificate* or *certificate-chain* is required. + +*certificate-chain* + +: Where to store the issued certificate, concatenated with the content + of the file specified specified with the *CAfile* option (in PEM + format). + At least one of *certificate* or *certificate-chain* is required. + +*certificate-key* + +: Path the service's private key. This option is required. The + following command can be used to generate a new 4096-bits RSA key in + PEM format with mode 0600: + + openssl genrsa 4096 | install -m0600 /dev/stdin /path/to/priv.key + +*min-days* + +: For an existing certificate, the minimum number of days before its + expiration date the section is considered for re-issuance. + Default: `10`. + +*CAfile* + +: Path to the issuer's certificate. This is used for + *certificate-chain* and to verify the validity of each issued + certificate. + Specifying an empty value skip certificate validation. + Default: `/usr/share/lacme/lets-encrypt-x3-cross-signed.pem`. + +*hash* + +: Message digest algorithm to sign the Certificate Signing Request + with. + +*keyUsage* + +: Comma-separated list of Key Usages, see [`x509v3_config`(5ssl)]. + +*subject* + +: Subject field of the Certificate Signing Request, in the form + `/type0=value0/type1=value1/type2=…`. This option is required. + +*subjectAltName* + +: Comma-separated list of Subject Alternative Names, in the form + `type0:value1,type1:value1,type2:…` + The only `type` currently supported is `DNS`, to specify an + alternative domain name. + +*chown* + +: An optional `username[:groupname]` to chown the issued *certificate* + and *certificate-chain* with. + +*chmod* + +: An optional octal mode to chmod the issued *certificate* and + *certificate-chain* with. + +*notify* + +: Command to pass the the system's command shell (`/bin/sh -c`) + after successful installation of the *certificate* and/or + *certificate-chain*. + +Examples +======== + + ~$ sudo lacme new-reg mailto:noreply@example.com + ~$ sudo lacme reg=/acme/reg/137760 --agreement-uri=https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf + ~$ sudo lacme new-cert + ~$ sudo lacme revoke-cert /path/to/server/certificate.pem + + +See also +======== + +[`lacme-accountd`(1)] + +[ACME]: https://tools.ietf.org/html/draft-ietf-acme-acme-02 +[`lacme-accountd`(1)]: lacme-accountd.1.html +[`iptables`(8)]: http://linux.die.net/man/8/iptables +[`ciphers`(1ssl)]: https://www.openssl.org/docs/manmaster/apps/ciphers.html +[`x509v3_config`(5ssl)]: https://www.openssl.org/docs/manmaster/apps/x509v3_config.html |