Quantcast

acme-client doc diff

Previous Topic Next Topic
 
classic Classic list List threaded Threaded
5 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

acme-client doc diff

Nick Holland
I found that the current man pages and example file for acme-client
are confusing and leave one with an imperfect certificate setup, with
the intermediate certs missing.  Doesn't generate an error on
OpenBSD, but does on some other OSs.  So I propose these changes to
the example file and man pages:

/etc/acme-client.conf: fetch a "domain full chain certificate" rather
than the "domain chain certificate" (I'd be happy with fetching both,
one extra tiny file won't hurt anything)

acme-client(1) : I know what a "host" key is, didn't recognize it in
this man page.  Also couldn't figure out how to generate the initial
host key without the help of the commit message.

The example in /etc/acme-client.conf shows "example.com", but in
acme-client(1), it's "www.example.com".  Not interchangeable, so
standardize on "example.com".

acme-client.conf(5) : Point out "full chain" is needed for
httpd(8) (and others, I'm sure).  Show a httpd.conf(5) server block.

Diff below is certainly tab mangled; raw diff can be pulled from:

https://holland-consulting.net/acme-client.diff

Nick.

Index: etc/acme-client.conf
===================================================================
RCS file: /cvs/src/etc/acme-client.conf,v
retrieving revision 1.3
diff -u -u -r1.3 acme-client.conf
--- etc/acme-client.conf        21 Jan 2017 09:06:57 -0000      1.3
+++ etc/acme-client.conf        18 Mar 2017 02:44:58 -0000
@@ -17,6 +17,6 @@
 #      alternative names { secure.example.com }
 #      domain key "/etc/ssl/private/example.com.key"
 #      domain certificate "/etc/ssl/example.com.crt"
-#      domain chain certificate "/etc/ssl/example.com.chain.pem"
+#      domain full chain certificate "/etc/ssl/example.com.fullchain.pem"
 #      sign with letsencrypt
 #}
Index: usr.sbin/acme-client/acme-client.1
===================================================================
RCS file: /cvs/src/usr.sbin/acme-client/acme-client.1,v
retrieving revision 1.20
diff -u -u -r1.20 acme-client.1
--- usr.sbin/acme-client/acme-client.1  28 Jan 2017 17:53:17 -0000      1.20
+++ usr.sbin/acme-client/acme-client.1  18 Mar 2017 02:44:58 -0000
@@ -34,7 +34,7 @@
 The options are as follows:
 .Bl -tag -width Ds
 .It Fl A
-Create a new RSA account key if one does not already exist.
+Create a new RSA account (host) key if one does not already exist.
 .It Fl D
 Create a new RSA domain key if one does not already exist.
 .It Fl F
@@ -98,11 +98,16 @@
 returns 1 on failure, 2 if the certificates didn't change (up to date),
 or 0 if certificates were changed (revoked or updated).
 .Sh EXAMPLES
+To initialize a new account (host) key:
+.Pp
+.Dl # acme-client -vAD example.com
+.Pp
+
 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 above:
 .Pp
-.Dl # acme-client -vD www.example.com
+.Dl # acme-client -vD example.com
 .Pp
 A daily
 .Xr cron 8
@@ -110,7 +115,7 @@
 .Bd -literal -offset indent
 #! /bin/sh
 
-acme-client www.example.com
+acme-client example.com
 
 if [ $? -eq 0 ]
 then
Index: usr.sbin/acme-client/acme-client.conf.5
===================================================================
RCS file: /cvs/src/usr.sbin/acme-client/acme-client.conf.5,v
retrieving revision 1.8
diff -u -u -r1.8 acme-client.conf.5
--- usr.sbin/acme-client/acme-client.conf.5     21 Jan 2017 15:53:15 -0000      1.8
+++ usr.sbin/acme-client/acme-client.conf.5     18 Mar 2017 02:44:58 -0000
@@ -134,6 +134,12 @@
 It needs to be in the same directory as the
 .Ar domain certificate
 (or in a subdirectory) and can be specified as a relative or absolute path.
+This is a combination of the
+.Ar domain certificate
+and the
+.Ar domain chain certificate
+in one file, and is required for many web servers, including
+.Xr httpd 8 .
 .It Ic sign with Ar authority
 The certificate authority (as declared above in the
 .Sx AUTHORITIES
@@ -151,8 +157,28 @@
        alternative names { secure.example.com www.example.com }
        domain key "/etc/ssl/private/example.com.key"
        domain certificate "/etc/ssl/example.com.crt"
+       domain full chain certificate "/etc/ssl/example.com.fullchain.pem"
        sign with letsencrypt
        challengedir "/var/www/acme"
+}
+.Ed
+.Pp
+An
+.Xr httpd.conf 5
+server declaration to use that certificate looks like this:
+.Bd -literal -offset indent
+server "example.com" {
+        alias "www.example.com"
+        alias "secure.example.com"
+        listen on $ext_addr port 80
+        listen on $ext_addr tls port 443
+        tls certificate "/etc/ssl/example.com.fullchain.pem"
+        tls key "/etc/ssl/private/example.com.key"
+        location "/.well-known/acme-challenge/*" {
+                root "/acme"
+                root strip 2
+        }
+        root "/htdocs"
 }
 .Ed
 .Sh FILES

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: acme-client doc diff

Walter Alejandro Iglesias-2
Nick wrote:

> I found that the current man pages and example file for acme-client
> are confusing and leave one with an imperfect certificate setup, with
> the intermediate certs missing.  Doesn't generate an error on
> OpenBSD, but does on some other OSs.

Right.  It took me some time to realize I had to use fullchain.pem
instead of chain.pem with smptd and pop3d.


Thanks!


Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: acme-client doc diff

Stuart Henderson
In reply to this post by Nick Holland
On 2017/03/18 15:07, Nick Holland wrote:
>  .It Fl A
> -Create a new RSA account key if one does not already exist.
> +Create a new RSA account (host) key if one does not already exist.

The -A key is for the letsencrypt account, "host key" implies to me
that it's the key for the cert you're applying for (i.e. the -D key)..

>  .It Fl D
>  Create a new RSA domain key if one does not already exist.

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Something that could be important to document

Walter Alejandro Iglesias-3
In reply to this post by Nick Holland
I don't know if what I read time ago about how to correctly request a CA
to use with original sendmail is still important and applicable
(currently I use opensmtpd).

As far as I understood, you must use your FQDN as the principal name in
your certificate.  That's why I use 'server.roquesor.com' (my machine
name) instead of just the domain name 'roquesor.com' as the principal
name.

I don't know if Let's Encrypt people, since they thought their
certificates mostly for web sites, didn't care about documenting this
detail or if it's not important anymore.

In case this is still important perhaps could be useful to mention it in
the man page (or in FAQ).



Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Something that could be important to document

Stuart Henderson
On 2017/03/21 09:23, Walter Alejandro Iglesias wrote:

> I don't know if what I read time ago about how to correctly request a CA
> to use with original sendmail is still important and applicable
> (currently I use opensmtpd).
>
> As far as I understood, you must use your FQDN as the principal name in
> your certificate.  That's why I use 'server.roquesor.com' (my machine
> name) instead of just the domain name 'roquesor.com' as the principal
> name.
>
> I don't know if Let's Encrypt people, since they thought their
> certificates mostly for web sites, didn't care about documenting this
> detail or if it's not important anymore.
>
> In case this is still important perhaps could be useful to mention it in
> the man page (or in FAQ).
>
>
>

It shouldn't matter, if subjectAltName is present you're not even supposed
to look at the primary name..

Loading...