diff options
Diffstat (limited to 'README')
| -rw-r--r-- | README | 85 |
1 files changed, 54 insertions, 31 deletions
@@ -1,32 +1,55 @@ +Requesting new Certificate Issuance with the ACME protocol generally +works as follows: + + 1. Generate a Certificate Signing Request. This requires access to + the private part of the server key. + 2. Issue an issuance request against the ACME server. + 3. Answer the ACME Identifier Validation Challenges. The challenge + type "http-01" requires a webserver to listen on port 80 for each + address for which an authorization request is issued; if there is + no running webserver, root privileges are required to bind against + port 80 and to install firewall rules to temporarily open the port. + 4. Install the certificate (after verification) and restart the + service. This usually requires root access as well. + +Steps 1,3,4 need to be run on the host for which an authorization +request is issued. However the the issuance itself (step 2) could be +done from another machine. Furthermore, each ACME command (step 2), as +well as the key authorization token in step 3, need to be signed using +an account key. The account key can be stored on another machine, or +even on a smartcard. + +_______________________________________________________________________ + letsencrypt is a tiny ACME client written with process isolation and -minimal privileges in mind. It is divided into three components: - -1. The "master" 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 ("new-cert" 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 "--notify". - -2. The actual ACME client, which runs as the user specified with - "--runas" (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. - -3. An optional webserver, which is spawned by the master process (when - nothing is listening on localhost:80); socat(1) is used to listen on - port 80 and to change the user (owner) and group of the process to - "www-data:www-data". (The only challenge type currently supported by - letsencrypt-tiny is "http-01", 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 - "/.well-known/acme-challenge" 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 - "/var/www/acme-challenge" root directory, which must not exist. +minimal privileges in mind. It is divided into four components, each +with its own executable: + + * A 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 this process on a different host. + + * A "master" 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, + 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. + + * An actual ACME client, which builds ACME commands and dialogues with + the remote ACME server. Since ACME commands need to be signed with + the account key, the "master" process passes the UNIX-domain socket + of the account key manager to the ACME client: data signatures are + requested by writing the data to be signed to the socket. + + * For certificate issuances, an optional webserver, which is spawned + by the "master" process when no service is listening on the HTTP + 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) + rules are automatically installed to open the HTTP port, and removed + afterwards. |