1.\" $OpenBSD: acme-client.1,v 1.11 2016/09/15 20:44:24 jmc Exp $ 2.\" 3.\" Copyright (c) 2016 Kristaps Dzonsons <kristaps@bsd.lv> 4.\" 5.\" Permission to use, copy, modify, and distribute this software for any 6.\" purpose with or without fee is hereby granted, provided that the above 7.\" copyright notice and this permission notice appear in all copies. 8.\" 9.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES 10.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF 11.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR 12.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES 13.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN 14.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF 15.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. 16.\" 17.Dd $Mdocdate: September 15 2016 $ 18.Dt ACME-CLIENT 1 19.Os 20.Sh NAME 21.Nm acme-client 22.Nd ACME client 23.Sh SYNOPSIS 24.Nm acme-client 25.Op Fl bFmNnrv 26.Op Fl a Ar agreement 27.Op Fl C Ar challengedir 28.Op Fl c Ar certdir 29.Op Fl f Ar accountkey 30.Op Fl k Ar domainkey 31.Op Fl s Ar authority 32.Ar domain 33.Op Ar altnames 34.Sh DESCRIPTION 35The 36.Nm 37utility is an 38Automatic Certificate Management Environment (ACME) client. 39.Pp 40The options are as follows: 41.Bl -tag -width Ds 42.It Fl a Ar agreement 43Use an alternative user agreement URL. 44.It Fl b 45Back up all certificates in the certificate directory. 46This only happens if a remove or replace operation is possible. 47The backups are named 48.Pa cert-NNNNN.pem , 49.Pa chain-NNNNN.pem , 50and 51.Pa fullchain-NNNNN.pem , 52where 53.Li NNNNN 54is the current 55.Ux 56Epoch. 57Any given backup uses the same Epoch time for all three certificates. 58If there are no certificates in place, this option does nothing. 59.It Fl C Ar challengedir 60The directory to register challenges. 61.It Fl c Ar certdir 62The directory to store public certificates. 63.It Fl F 64Force updating the certificate signature even if it's too soon. 65.It Fl f Ar accountkey 66The account private key. 67This was either made with a previous client or with 68.Fl n . 69.It Fl k Ar domainkey 70The private key for the domain. 71This may also be created with 72.Fl N . 73.It Fl m 74Append 75.Ar domain 76to all default paths except the challenge path 77.Pq i.e. those that are overridden by Fl c , k , f . 78Thus, 79.Ar foo.com 80as the initial domain would make the default domain private key into 81.Pa /etc/ssl/acme/private/foo.com/privkey.pem . 82This is useful in setups with multiple domain sets. 83.It Fl N 84Create a new RSA domain key if one does not already exist. 85.It Fl n 86Create a new RSA account key if one does not already exist. 87.It Fl r 88Revoke the X509 certificate found in the certificates. 89.It Fl s Ar authority 90ACME 91.Ar authority 92to talk to. 93Currently the following authorities are available: 94.Pp 95.Bl -tag -width "letsencrypt-staging" -compact 96.It Cm letsencrypt 97Let's Encrypt authority 98.It Cm letsencrypt-staging 99Let's Encrypt staging authority 100.El 101.Pp 102The default is 103.Cm letsencrypt . 104.It Fl v 105Verbose operation. 106Specify twice to also trace communication and data transfers. 107.It Ar domain 108The domain name. 109The only difference between this and 110.Ar altnames 111is that it's put into the certificate's 112.Li CN 113field and it uses the 114.Qq main 115domain when specifying 116.Fl m . 117.It Ar altnames 118Alternative names 119.Pq Dq SAN 120for the domain name. 121The number of SAN entries is limited to 100 or so. 122.El 123.Pp 124Public certificates are by default placed in 125.Pa /etc/ssl/acme 126as 127.Pa cert.pem Pq the domain certificate , 128.Pa chain.pem , 129and 130.Pa fullchain.pem , 131respectively. 132.Pa cert.pem 133is checked for its expiration: if more than 30 days from expiry, 134.Nm 135does not attempt to refresh the signature. 136.Pp 137Challenges are used to verify that the submitter has access to 138the registered domains. 139.Nm 140only implements the 141.Dq http-01 142challenge type, where a file is created within a directory accessible by 143a locally-run web server. 144The default challenge directory 145.Pa /var/www/acme 146can be served by 147.Xr httpd 8 148with this location block, 149which will properly map response challenges: 150.Bd -literal -offset indent 151location "/.well-known/acme-challenge/*" { 152 root "/acme" 153 root strip 2 154} 155.Ed 156.Sh FILES 157.Bl -tag -width "/etc/ssl/acme/private/privkey.pem" -compact 158.It Pa /etc/acme/privkey.pem 159Default accountkey. 160.It Pa /etc/ssl/acme 161Default certdir. 162.It Pa /etc/ssl/acme/private/privkey.pem 163Default domainkey. 164.It Pa /var/www/acme 165Default challengedir. 166.El 167.Sh EXIT STATUS 168.Nm 169returns 1 on failure, 2 if the certificates didn't change (up to date), 170or 0 if certificates were changed (revoked or updated). 171.Sh EXAMPLES 172To create and submit a new key for a single domain, assuming that the 173web server has already been configured to map the challenge directory 174as in the 175.Sx Challenges 176section: 177.Pp 178.Dl # acme-client -vNn foo.com www.foo.com smtp.foo.com 179.Pp 180A daily 181.Xr cron 8 182job can renew the certificates: 183.Bd -literal -offset indent 184#! /bin/sh 185 186acme-client foo.com www.foo.com smtp.foo.com 187 188if [ $? -eq 0 ] 189then 190 /etc/rc.d/httpd reload 191fi 192.Ed 193.Sh SEE ALSO 194.Xr openssl 1 , 195.Xr httpd.conf 5 196.Sh STANDARDS 197.Rs 198.%U https://tools.ietf.org/html/draft-ietf-acme-acme-03 199.%T Automatic Certificate Management Environment (ACME) 200.Re 201.Sh AUTHORS 202The 203.Nm 204utility was written by 205.An Kristaps Dzonsons Aq Mt kristaps@bsd.lv . 206.Sh BUGS 207The challenge and certificate processes currently retain their (root) 208privileges. 209.Pp 210For the time being, 211.Nm 212only supports RSA as an account key format. 213