[libvirt] [PATCH] docs: update instructions for TLS cert generation
John Ferlan
jferlan at redhat.com
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>
>
More information about the libvir-list
mailing list