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@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@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>