diff options
Diffstat (limited to 'letsencrypt.1')
| -rw-r--r-- | letsencrypt.1 | 413 |
1 files changed, 294 insertions, 119 deletions
diff --git a/letsencrypt.1 b/letsencrypt.1 index a16e165..2175bd2 100644 --- a/letsencrypt.1 +++ b/letsencrypt.1 @@ -1,187 +1,362 @@ -.TH LETSENCRYPT "1" "DECEMBER 2015" "Tiny Let's Encrypt ACME client" "User Commands" +.TH LETSENCRYPT "1" "MARCH 2016" "Tiny Let's Encrypt ACME client" "User Commands" .SH NAME letsencrypt \- Tiny Let's Encrypt ACME client .SH SYNOPSIS -.B letsencrypt\fR [\fIOPTION\fR ...] \fICOMMAND\fR \fIACCOUNTKEY\fR [\fIARGUMENT\fR ...] +.B letsencrypt\fR [\fB\-\-config=\fIFILENAME\fR] +[\fB\-\-socket=\fIPATH\fR] [\fIOPTION\fR ...] \fICOMMAND\fR +[\fIARGUMENT\fR ...] .SH DESCRIPTION .PP .B letsencrypt\fR is a tiny ACME client written with process isolation and minimal privileges in mind. -It is divided into three components: - -.nr step 1 1 -.IP \n[step]. 8 -The \(lqmaster\(rq process, which runs as root and is the only component -with access to the private key material (both account and server keys). -It is only used to fork the other components (after dropping -privileges), and to sign ACME requests (JSON Web Signatures); for -certificate issuance (\fBnew-cert\fR command), it is also used to -generate the Certificate Signing Request, then to verify the validity of -the issued certificate, and optionally to reload or restart services -using \fB--notify\fR. - -.IP \n[step]. 8 -The actual ACME client, which runs as the user specified with -\fB--runas\fR (or root if the option is omitted). It builds ACME -requests and dialogues with the remote ACME server. All requests need -to be signed with the account key, but this process doesn't need direct -access to any private key material: instead, it write the data to be -signed to a pipe shared with the master process, which in turns replies -with its SHA-256 signature. - -.IP \n+[step]. -An optional webserver, which is spawned by the master process (when -nothing is listening on localhost:80); \fBsocat\fR(1) is used to listen -on port 80 and to change the user (owner) and group of the process to -\(lqwww-data:www-data\(rq. +It is divided into four components, each with its own executable: + +.IP \[bu] 4 +A \fIletsencrypt\-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 \fIletsencrypt\-accountd\fR(1) and \fBletsencrypt\fR on +different hosts. + +.IP \[bu] 4 +A \(lqmaster\(rq \fBletsencrypt\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 \fBletsencrypt\fR process passes the +\fIletsencrypt\-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 \fBletsencrypt\fR process when no service is +listening on the HTTP port. (The only challenge type currently supported by \fBletsencrypt\fR is -\(lqhttp-01\(rq, hence a webserver is required.) -Some iptables rules are automatically added to open port 80, and -removed afterwards. -The web server only processes GET requests under the -\(lq/.well-known/acme-challenge\(rq URI. -If a webserver is already listening on port 80, it needs to be -configured to serve these URIs (for each virtual-hosts requiring -authorization) as static files under the \(lq/var/www/acme-challenge\(rq -root directory, which must not exist. +\(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 letsencrypt \fR[\fB\-\-agreement\-uri=\fIURI\fR]\fB \fBnew\-reg \fR[\fICONTACT\fR ...] +Register the account key managed by \fIletsencrypt\-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, \fBletsencrypt\fR prints the +URI of the existing registration and aborts. + +.TP +.B letsencrypt \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 letsencrypt \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 letsencrypt \fBrevoke\-cert \fIFILE\fR [\fIFILE\fR ...] + +Request that the given certificate(s) \fIFILE\fR(s) be revoked. For +this command, \fIletsencrypt\-accountd\fR(1) can be pointed to either +the account key or the server's private key. + .SH GENERIC OPTIONS .TP -.B \-\-runas=\fIusername\fR -Username to run the ACME client as. This user does not need access to -any private key material. The ACME client runs as root when this option -is omited (not recommended). +.B \-\-config=\fIfilename\fR +Use \fIfilename\fR as configuration file. See the \fBCONFIGURATION +FILE\fR section below for the configuration options. .TP -.B \-?\fR, \fB\-\-help\fR -Display a brief help and exit. +.B \-\-socket=\fIpath\fR +Use \fIpath\fR as the \fIletsencrypt\-accountd\fR(1) UNIX\-domain socket +to connect to for signature requests from the ACME client. +\fBletsencrypt\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 \-q\fR, \fB\-\-quiet\fR -Try to be quiet. +.B \-?\fR, \fB\-\-help\fR +Display a brief help and exit. .TP .B \-\-debug Turn on debug mode. -.SH ACCOUNT KEY REGISTRATION -.B letsencrypt\fR [\fIOPTION\fR ...] \fBnew\-reg\fR \fIACCOUNTKEY\fR [\fIEMAIL\fR ...] +.SH CONFIGURATION FILE +If \fB\-\-config=\fR is not given, \fBletsencrypt\fR uses the first +existing configuration file among +\fI./letsencrypt.conf\fR, +\fI$XDG_CONFIG_HOME/letsencrypt\-tiny/letsencrypt.conf\fR (or +\fI~/.config/letsencrypt\-tiny/letsencrypt.conf\fR if the +XDG_CONFIG_HOME environment variable is not set), and +\fI/etc/letsencrypt\-tiny/letsencrypt.conf\fR. +Valid options are: -Registers the given \fIACCOUNTKEY\fR. An optional list of \fIEMAIL\fR -addresses can be given as contact information. +.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 -.B \-\-genkey\fR[\fB=\fIALGO\fR[:\fIBITS\fR]] -Automatically generate the \fIACCOUNTKEY\fR (with mode 0600) if it does -not exist, using a \fIBITS\fR\-long \fIALGO\fR key. -The \fBopenssl\fR(1) default length is used when \fIBITS\fR is omited. -The default \fIALGO\fRrithm is \(lqRSA\(rq, which is also the only one -currently supported. +\(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.letsencrypt\(rq if the XDG_RUNTIME_DIR +environment variable is set. -.SH CERTIFICATE ISSUANCE -.B letsencrypt\fR [\fIOPTION\fR ...] \fBnew\-cert\fR \fIACCOUNTKEY\fR -\fB\-\-output=\fICERT\fR \fB\-\-csr=\fIFILE\fR +.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. -.B letsencrypt\fR [\fIOPTION\fR ...] \fBnew\-cert\fR \fIACCOUNTKEY\fR -\fB\-\-output=\fICERT\fR \fB\-\-key=\fIFILE\fR [\fB\-\-hash=\fIALGO\fR] -[\fB\-\-subject=\fISTRING\fR] [\fB\-\-san=\fISTRING\fR] -[\fB\-\-keyusage=\fISTRING\fR] +.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. -Request a new Certificate Issuance using the given \fIACCOUNTKEY\fR. -The Certificate Signing Request can be supplied directly using -\fB\-\-csr\fR, or generated from the server key (\fB\-\-key\fR) using -options \fB\-\-hash\fR, \fB\-\-subject\fR, \fB\-\-san\fR and \fB\-\-keyusage\fR. +.TP +.I command +Path to the ACME client executable. +Default: \(lq/usr/lib/letsencrypt\-tiny/client\(rq. -The issued X.509 certificate is then validated, and upon success is -placed (in PEM format) into the file specified with \fB\-\-output\fR; the -optional \fB\-\-chain\fR option can be used to append the issuer -certificate as well. +.TP +.I server +Root URI of the ACME server. +Default: \(lqhttps://acme\-v01.api.letsencrypt.org/\(rq. .TP -.B \-\-min-age=\fISECONDS -Skip the issuance if the certificate specified by \fB\-\-output\fR exists -and its expiration date is more than \fISECONDS\fR ahead. +.I timeout +Timeout in seconds after which the client stops polling the ACME server +and considers the request failed. +Default: \(lq10\(rq. .TP -.B \-\-csr=\fIFILE -Certificate Signing Request to send (alternatively, use \fB\-\-key\fR to -generate it from the private server key). +.I SSL_verify +Whether to verify the server certificate chain. +Default: \(lqYes\(rq. .TP -.B \-\-key=\fIFILE -Server private key used to generate the Certificate Signing Request when -\fB\-\-csr\fR is omitted. (Use \fB\-\-genkey\fR to generate it -automatically.) +.I SSL_version +Specify the version of the SSL protocol used to transmit data. .TP -.B \-\-genkey\fR[\fB=\fIALGO\fR[:\fIBITS\fR]] -Automatically generate the server private key (with mode 0600) if it -does not exist, using a \fIBITS\fR\-long \fIALGO\fR key. -The \fBopenssl\fR(1) default length is used when \fIBITS\fR is omited. -The default \fIALGO\fRrithm is \(lqRSA\(rq, which is also the only one -currently supported. +.I SSL_cipher_list +Specify the cipher list for the connection. +.RE .TP -.B \-\-hash=\fIDGST -Message digest to sign the Certificate Signing Request with. +\(lq[webserver]\(rq section +This section is used for configuring the ACME webserver. +.RS .TP -.B \-\-subject=\fR/\fItype0\fR=\fIvalue0\fR/\fItype1\fR=\fIvalue1\fR/\fItype2\fR=... -Subject name to use in the Certificate Signing Request. +.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 -.B \-\-san=\fItype0\fR:\fIvalue1\fR,\fItype1\fR:\fIvalue1\fR,\fItype2\fR:... -Comma-separated list of Subject Alternative Names. The only \fItype\fR -currently supported is \(lqDNS\(rq, to specify an alternative domain -name. +.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 -.B \-\-keyusage=\fISTRING -Comma-separated list of Key Usages, see x509v3_config(5ssl). -(Default: \(lqdigitalSignature,keyEncipherment,keyCertSign\(rq.) +.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 -.B \-\-output=\fIFILE -Where to copy the issued (signed) X.509 certificate. +.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 -.B \-\-chain=\fR[\fIFILE\fR] -Store the server certificate along with its intermediate CA in -\fIFILE\fR. If \fIFILE\fR is empty or omitted, use the file specified -with \fB\-\-output\fR instead. +.I command +Path to the ACME webserver executable. +Default: \(lq/usr/lib/letsencrypt\-tiny/webserver\(rq. .TP -.B \-\-notify=\fICOMMAND\fR -Command to run upon success. (This option can be repeated to run -multiple commands.) +.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 \fBletsencrypt\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 \fBletsencrypt\fR uses the first existing configuration file among +\fI./letsencrypt\-certs.conf\fR, +\fI$XDG_CONFIG_HOME/letsencrypt\-tiny/letsencrypt\-certs.conf\fR (or +\fI~/.config/letsencrypt\-tiny/letsencrypt\-certs.conf\fR if the +XDG_CONFIG_HOME environment variable is not set), and +\fI/etc/letsencrypt\-tiny/letsencrypt\-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. -.SH CERTIFICATE REVOKATION -.B letsencrypt\fR [\fIOPTION\fR ...] \fBrevoke\-cert\fR {\fIACCOUNTKEY\fR|\fISVRKEY\fR} \fIFILE\fR [\fIFILE\fR ...] +.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: -Request that the given certificate(s) \fIFILE\fR(s) be revoked. The -first argument after the command name can be either the account key file -or the private part of the certificate(s) to revoke. +.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. -.SH EXAMPLES .TP -letsencrypt \-\-runas=letsencrypt new\-reg \-\-genkey=RSA:4096 /etc/ssl/letsencrypt.key admin@fripost.org -Register a new account key \(lq/etc/ssl/letsencrypt.key\(rq using -\(lqadmin@fripost.org\(rq as contact information. A 4096-bits long RSA -key is generated (with mode 0600) if the key file does not exists. +.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/letsencrypt\-tiny/lets\-encrypt\-x1\-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 -letsencrypt \-\-runas=letsencrypt new\-cert /etc/ssl/letsencrypt.key \-\-output=/etc/nginx/ssl/www.fripost.org.pem \-\-chain \-\-key=/etc/nginx/ssl/www.fripost.org.key \-\-hash=SHA512 \-\-subject=/O=Fripost/CN=fripost.org \-\-san=DNS:fripost.org,DNS:www.fripost.org,DNS:wiki.fripost.org \-\-min-age=432000 \-\-notify='systemctl restart nginx' -Request issuance of a new (chained) certificate, but only if it doesn't exist or expires in less than 5 days; restart nginx upon success. +.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 letsencrypt new-reg mailto:noreply@example.com + ~$ sudo letsencrypt reg=/acme/reg/137760 --agreement-uri=https://letsencrypt.org/documents/LE-SA-v1.0.1-July-27-2015.pdf + ~$ sudo letsencrypt new-cert + ~$ sudo letsencrypt revoke-cert /path/to/server/certificate.pem +.fi + +.SH SEE ALSO +\fBletsencrypt\-accountd\fR(1) .SH AUTHOR Written by Guilhem Moulin |