[libvirt] [PATCH] docs: update instructions for TLS cert generation

Wed Dec 6 21:28:00 UTC 2017

On 12/06/2017 12:50 PM, Daniel P. Berrange wrote:
> Currently we only describe setting the CN field for server certs. This leads
> to inevitable pain for users who set it to the fully qualified hostname and
> then use a unqualified hostname or IP address to connect in the URI. Describe
> the usage of Subject Alt Name extensions, to provide multiple hostnames and
> IP addresses. This will help users avoid the classic mistake and is important
> future proofing, since at least in browsers, TLS libraries no longer use the
> CN field for validation, mandating use of SAN info instead.

wonderful, my TLA vocabulary now has to know that SAN can be Storage
Area Network or Subject Alternate Name ;-)

> 
> Signed-off-by: Daniel P. Berrange <berrange at redhat.com>
> ---
>  docs/remote.html.in | 72 ++++++++++++++++++++++++++++++++++++++---------------
>  1 file changed, 52 insertions(+), 20 deletions(-)
> 
> diff --git a/docs/remote.html.in b/docs/remote.html.in
> index 9bafd9de67..6ae40b2bb2 100644
> --- a/docs/remote.html.in
> +++ b/docs/remote.html.in
> @@ -30,7 +30,7 @@ to <code>virConnectOpen</code> (or <code>virsh -c ...</code>).
>  For example, if you normally use <code>qemu:///system</code>
>  to access the system-wide QEMU daemon, then to access
>  the system-wide QEMU daemon on a remote machine called
> -<code>oirase</code> you would use <code>qemu://oirase/system</code>.
> +<code>compute1.libvirt.org</code> you would use <code>qemu://compute1.libvirt.org/system</code>.

Long line consider newline starting at second <code>

>  </p>
>      <p>
>  The <a href="#Remote_URI_reference">section on remote URIs</a>
> @@ -412,7 +412,9 @@ next section.
>          <td> Server's certificate signed by the CA.
>   (<a href="#Remote_TLS_server_certificates">more info</a>) </td>
>          <td> CommonName (CN) must be the hostname of the server as it
> -  is seen by clients. </td>
> +          is seen by clients. All hostname and IP address variants that might
> +          be used to reach the server should be lkisted in Subject Alt Name

*listed

"Subject Alt Name fields" would seem to be something specific to someone
that knows TLS...  I guess it's one of those spring some sort of new
terminology on me and make me go google it experiences.

> +          fields.</td>
>        </tr>
>        <tr>
>          <td>
> @@ -564,8 +566,8 @@ X.509 certificate info:
>  
>  Version: 3
>  Serial Number (hex): 00
> -Subject: CN=Red Hat Emerging Technologies
> -Issuer: CN=Red Hat Emerging Technologies
> +Subject: CN=Libvirt Project
> +Issuer: CN=Libvirt Project
>  Signature Algorithm: RSA-SHA
>  Validity:
>          Not Before: Mon Jun 18 16:22:18 2007
> @@ -582,14 +584,20 @@ for your clients and servers.
>      </h3>
>      <p>
>  For each server (libvirtd) you need to issue a certificate
> -with the X.509 CommonName (CN) field set to the hostname
> -of the server.  The CN must match the hostname which
> -clients will be using to connect to the server.
> +containing one or more hostnames and/or IP addresses.
> +Historically the CommonName (CN) field would contain the
> +hostname of the server, and would match the hostname used

"server and would"  (e.g., comma isn't necessary since we're only
joining two things)

> +in the URI that clients pass to libvirt. In most TLS impls

s/impls/implementations/

> +the CN field is considered legacy data, the Subject Alt Name
> +(SAN) extension fields we be preferentially validated against.

considered legacy data. The preferential mechanism is to use Subject Alt
Name (SAN) extension fields to validate against.

> +In the future use of the CN field for validation may be
> +discontinuned entirely, so it is strongly recommended to

*discontinued

> +include the SAN fields.
>  </p>
>      <p>
>  In the example below, clients will be connecting to the
>  server using a <a href="#Remote_URI_reference">URI</a> of
> -<code>xen://oirase/</code>, so the CN must be "<code>oirase</code>".
> +<code>xen://virt.example/</code>, so the CN must be "<code>oirase</code>".

xen?  How about qemu!

s/virt.example/compute1.libvirt.org/

s/oirase/compute1.libvirt.org/

>  </p>
>      <p>
>  Make a private key for the server:
> @@ -599,13 +607,25 @@ certtool --generate-privkey > serverkey.pem
>  </pre>
>      <p>
>  and sign that key with the CA's private key by first
> -creating a template file called <code>server.info</code>
> -(only the CN field matters, which as explained above must
> -be the server's hostname):
> +creating a template file called <code>server.info</code>.
> +The 'cn' field should refer to the fully qualified public

s/The/The template file will contain a number of fields to describe the
server as follows:

<place the example here>

Then after the example - describe the various fields starting with "The
'cn' field"...    Your call on documenting the fields that aren't
described or referring to whatever standard there is (tls_www_server,
encryption_key, and signing_key).

Then a new paragraph to augment "and sign:" e.g.

Use the template file as input to a <code>certtool</code> command to
sign the server certificate:

> +hostname of the server. For the SAN extension data, there
> +must also be one or more 'dns_name' fields that contain all
> +possible hostnames that can be reasonably used by clients
> +to reach the server, both with and without domain name
> +qualifiers. If clients are likely to connect to the server
> +by IP address, then one or 'ip_address' fields should also

", then one or more 'ip_address' fields would be provided."

> +be added.
>  </p>
>      <pre>
>  organization = <i>Name of your organization</i>
> -cn = oirase
> +cn = compute1.libvirt.org
> +dns_name = compute1
> +dns_name = compute1.libvirt.org
> +ip_address = 10.0.0.74
> +ip_address = 192.168.1.24
> +ip_address = 2001:cafe::74
> +ip_address = fe20::24
>  tls_www_server
>  encryption_key
>  signing_key
> @@ -635,16 +655,28 @@ X.509 certificate info:
>  
>  Version: 3
>  Serial Number (hex): 00
> -Subject: O=Red Hat Emerging Technologies,CN=oirase
> -Issuer: CN=Red Hat Emerging Technologies
> +Subject: O=Libvirt Project,CN=compute1.libvirt.org
> +Issuer: CN=Libvirt Project
>  Signature Algorithm: RSA-SHA
>  Validity:
>          Not Before: Mon Jun 18 16:34:49 2007
>          Not After: Tue Jun 17 16:34:49 2008

<haha> did the extensions exist in 2007?  Maybe tweak to be 2017
although you'd have to fix the day of the week too!  Looking at
something from a recent example also seems to print in UTC...

> +Extensions:
> +        Basic Constraints (critical):
> +                Certificate Authority (CA): FALSE
> +        Subject Alternative Name (not critical):
> +                DNSname: compute1
> +                DNSname: compute1.libvirt.org
> +                IPAddress: 10.0.0.74
> +                IPAddress: 192.168.1.24
> +                IPAddress: 2001:cafe::74
> +                IPAddress: fe20::24
>  </pre>
>      <p>
> -Note the "Issuer" CN is "Red Hat Emerging Technologies" (the CA) and
> -the "Subject" CN is "oirase" (the server).
> +Note the "Issuer" CN is "Libvirt Project" (the CA) and
> +the "Subject" CN is "compute1.libvirt.org" (the server).
> +Notice that the hostname listed in the CN must also
> +be duplicated as a DNSname entry
>  </p>
>      <p>
>  Finally we have two files to install:
> @@ -665,13 +697,13 @@ which can be installed on the server as
>      </h3>
>      <p>
>  For each client (ie. any program linked with libvirt, such as
> -<a href="http://virt-manager.et.redhat.com/">virt-manager</a>)
> +<a href="http://virt-manager.org/">virt-manager</a>)
>  you need to issue a certificate with the X.509 Distinguished Name (DN)
>  set to a suitable name.  You can decide this on a company / organisation
>  policy.  For example, I use:

"I use" could probably be dropped...

The rest seemed fine

Reviewed-by: John Ferlan <jferlan at redhat.com>

John

>  </p>
>      <pre>
> -C=GB,ST=London,L=London,O=Red Hat,CN=<i>name_of_client</i>
> +C=GB,ST=London,L=London,O=Libvirt Project,CN=<i>name_of_client</i>
>  </pre>
>      <p>
>  The process is the same as for
> @@ -692,7 +724,7 @@ Act as CA and sign the certificate.  Create client.info containing:
>  country = GB
>  state = London
>  locality = London
> -organization = Red Hat
> +organization = Libvirt Project
>  cn = client1
>  tls_www_client
>  encryption_key
> @@ -884,7 +916,7 @@ Blank lines and comments beginning with <code>#</code> are ignored.
>    The default is that DNs are not checked.
>    </p>
>            <p>
> -  This list may contain wildcards such as <code>"C=GB,ST=London,L=London,O=Red Hat,CN=*"</code>
> +  This list may contain wildcards such as <code>"C=GB,ST=London,L=London,O=Libvirt Project,CN=*"</code>
>    See the POSIX <code>fnmatch</code> function for the format
>    of the wildcards.
>    </p>
> 