oops, use correct filename

1 files changed, 323 insertions, 0 deletions

diff --git a/usr.sbin/acme-client/acme-client.1 b/usr.sbin/acme-client/acme-client.1
new file mode 100644
index 00000000000..72aa22cf319
--- /dev/null
+++ b/usr.sbin/acme-client/acme-client.1
@@ -0,0 +1,323 @@
+.Dd $Mdocdate: August 31 2016 $
+.Dt LETSKENCRYPT 1
+.Os
+.Sh NAME
+.Nm letskencrypt
+.Nd secure Let's Encrypt client
+.\" .Sh LIBRARY
+.\" For sections 2, 3, and 9 only.
+.\" Not used in OpenBSD.
+.Sh SYNOPSIS
+.Nm letskencrypt
+.Op Fl bFmnNrsv
+.Op Fl a Ar agreement
+.Op Fl C Ar challengedir
+.Op Fl c Ar certdir
+.Op Fl f Ar accountkey
+.Op Fl k Ar domainkey
+.Ar domain
+.Op Ar altnames...
+.Sh DESCRIPTION
+The
+.Nm
+utility submits an X509 certificate for
+.Ar domain
+and its alternate DNS names
+.Ar altnames
+to a
+.Dq Let's Encrypt
+server for automated signing.
+It can also revoke previously-submitted signatures.
+It must be run as root.
+(Why?
+.Xr chroot 2 . )
+.Pp
+By default, it uses
+.Pa /var/www/letsencrypt
+for responding to challenges
+.Pq Fl C ,
+.Pa /etc/ssl/letsencrypt
+for the public certificate directory
+.Pq Fl c ,
+.Pa /etc/ssl/letsencrypt/private/privkey.pem
+for the domain private key
+.Pq Fl k ,
+and
+.Pa /etc/letsencrypt/privkey.pem
+for the account private key
+.Pq Fl f .
+All of these must exist unless you use
+.Fl n
+and/or
+.Fl N ,
+which will generate the account and domain private keys, respectively.
+Its arguments are as follows:
+.Bl -tag -width Ds
+.It Fl b
+Back up all
+.Sx Certificates
+in the certificate directory.
+This will only back up if something will be done to them (remove or
+replace).
+The backups are called
+.Pa cert-NNNNN.pem ,
+.Pa chain-NNNNN.pem ,
+and
+.Pa fullchain-NNNNN.pem ,
+where
+.Li NNNNN
+is the current UNIX epoch.
+Any given backup effort will use the same epoch time for all three
+certificates.
+If there are no certificates in place, this does nothing.
+.It Fl F
+Force updating the certificate signature even if it's too soon.
+.It Fl m
+Append
+.Ar domain
+to all default paths except the challenge path
+.Pq i.e., those that are overriden by Fl c , k , f .
+Thus,
+.Ar foo.com
+as the initial domain would make the default domain private key into
+.Pa /etc/ssl/letsencrypt/private/foo.com/privkey.pem .
+This is useful in setups with multiple domain sets.
+.It Fl n
+Create a new 4096-bit RSA account key if one does not already exist.
+.It Fl N
+Create a new 4096-bit RSA domain key if one does not already exist.
+.It Fl r
+Revoke the X509 certificate found in
+.Sx Certificates .
+.It Fl s
+Use the
+.Dq Let's Encrypt
+staging server instead of the real thing.
+.It Fl v
+Verbose operation.
+Specify twice to also trace communication and data transfers.
+.It Fl a Ar agreement
+Use an alternative agreement URL.
+The default uses the current one, but it may be out of date.
+.It Fl C Ar challengedir
+Where to register challenges.
+See
+.Sx Challenges
+for details.
+.It Fl c Ar certdir
+Where to put public certificates.
+See
+.Sx Certificates
+for details.
+.It Fl f Ar accountkey
+The account private key.
+This was either made with a previous
+.Dq Let's Encrypt
+client or with
+.Fl n .
+.It Fl k Ar domainkey
+The private key for the domain.
+This may also be created with
+.Fl N .
+.It Ar domain
+The domain name.
+The only difference between this and the
+.Ar altnames
+is that it's put into the certificate's
+.Li CN
+field and is use the
+.Dq main
+domain when specifying
+.Fl m .
+.It Ar altnames
+Alternative names
+.Pq Dq SAN
+for the domain name.
+The number of SAN entries is limited by
+.Dq Let's Encrypt
+to 100 or so.
+.El
+.Pp
+The process by which
+.Nm
+obtains signed certificates is roughly as follows.
+In this, the
+.Dq CA
+is the ACME server for Let's Encrypt.
+.Bl -enum
+.It
+Access the CA (unauthenticated) and requests its list of resources.
+.It
+Optionally create and register a new RSA account key.
+.It
+Read and process the RSA account key.
+This is used to authenticate each subsequent communication to the CA.
+.It
+For each domain name,
+.Bl -enum
+.It
+submit a challenge for authentication to the CA,
+.It
+create a challenge response file,
+.It
+wait until the CA has verified the challenge.
+.El
+.It
+Read and extract the domain key.
+.It
+Create an X509 request from the doman key for the domain and its
+alternative names.
+.It
+Submit a request for signature to the CA.
+.It
+Download the signed X509 certificate.
+.It
+Extract the CA issuer from the X509 certificate.
+.It
+Download the certificate chain from the issuer.
+.El
+.Pp
+The revocation sequence is similar:
+.Bl -enum
+.It
+Request list of resources, manage RSA account key as in the case for
+signing.
+.It
+Read and extract the X509 certificate (if found).
+.It
+Create an X509 revocation request.
+.It
+Submit a request for revocation to the CA.
+.It
+Remove the certificate, the chain, and the full-chain.
+.El
+.Ss Challenges
+Let's Encrypt uses challenges to verify that the submitter has access to
+the registered domains.
+.Nm
+implements only the
+.Dq http-01
+challenge type, where a file is created within a directory accessible by
+a locally-run web server configured for the requested domain.
+For example, for the domain
+.Dq foo.com
+and alternate
+.Dq www.foo.com
+and the default challenge directory, an Apache configuration snippet
+might be as follows:
+.Bd -literal
+<VirtualHost *:80>
+  [...]
+  ServerName foo.com
+  ServerAlias www.foo.com
+  Alias /.well-known/acme-challenge /var/www/letsencrypt
+  <Directory /var/www/letsencrypt>
+    Options None
+    AllowOverride None
+    Order allow,deny
+    Allow from all
+  </Directory>
+</VirtualHost>
+.Ed
+.Pp
+This way, the files placed in
+.Pa /var/www/letsencrypt
+will be properly mapped by the web server when the Let's Encrypt
+responds to a challenge.
+.Ss Certificates
+Public certificates (domain certificate, chain, and the full-chain) are
+placed by default in
+.Pa /etc/ssl/letsencrypt
+as
+.Pa cert.pem ,
+.Pa chain.pem ,
+and
+.Pa fullchain.pem ,
+respectively.
+These are all created as the root user with mode 444.
+.Pp
+An nginx configuration using these might be as follows:
+.Bd -literal
+server {
+  listen 443;
+  server_name foo.com www.foo.com;
+  [...]
+  ssl_certificate /etc/ssl/letsencrypt/fullchain.pem;
+  ssl_certificate_key /etc/ssl/letsencrypt/private/privkey.pem;
+}
+.Ed
+.Pp
+The
+.Pa cert.pem
+file, if found, is checked for its expiration: if more than 30 days from
+expiring,
+.Nm
+will not attempt to refresh the signature.
+.\" .Sh CONTEXT
+.\" For section 9 functions only.
+.\" .Sh IMPLEMENTATION NOTES
+.\" Not used in OpenBSD.
+.\" .Sh RETURN VALUES
+.\" For sections 2, 3, and 9 function return values only.
+.\" .Sh ENVIRONMENT
+.\" For sections 1, 6, 7, and 8 only.
+.\" .Sh FILES
+.Sh EXIT STATUS
+.Nm
+returns 1 on failure, 2 if the certificates didn't change (up to date),
+or 0 if certificates were changed (revoked or updated).
+.\" For sections 1, 6, and 8 only.
+.Sh EXAMPLES
+To create and submit a new key for a single domain, assuming that the
+web server has already been configured to map the challenge directory
+as in the
+.Sx Challenges
+section:
+.Bd -literal
+# mkdir /var/www/letsencrypt
+# mkdir /etc/ssl/letsencrypt
+# mkdir /etc/ssl/letsencrypt/private /etc/letsencrypt
+# chmod 0700 /etc/ssl/letsencrypt/private /etc/letsencrypt
+# letskencrypt -vNn foo.com www.foo.com smtp.foo.com
+.Ed
+.Pp
+After generating the necessary directories, the above will create all
+keys and submit them to the server.
+You'll then probably want to restart your web server to pick up the new
+certificates.
+.Pp
+You can then keep your certificates fresh with a daily
+.Xr cron 8
+invocation running the following:
+.Bd -literal
+#! /bin/sh
+
+letskencrypt foo.com www.foo.com smtp.foo.com
+
+if [ $? -eq 0 ]
+then
+	/etc/rc.d/httpd reload
+fi
+.Ed
+.Pp
+You'll need to replace the httpd-reload statement with the correct
+script to have your web server reload its certificates.
+.\" .Sh DIAGNOSTICS
+.\" For sections 1, 4, 6, 7, 8, and 9 printf/stderr messages only.
+.\" .Sh ERRORS
+.\" For sections 2, 3, 4, and 9 errno settings only.
+.Sh SEE ALSO
+.Xr openssl 1
+.\" .Sh STANDARDS
+.\" .Sh HISTORY
+.\" .Sh AUTHORS
+.\" .Sh CAVEATS
+.Sh BUGS
+The challenge and certificate processes currently retain their (root)
+privileges.
+.Pp
+For the time being,
+.Nm
+only supports RSA as an account key format.
+.\" .Sh SECURITY CONSIDERATIONS
+.\" Not used in OpenBSD.