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@xxxxxxxxxx> > --- > 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@xxxxxxxxxx> 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> > -- libvir-list mailing list libvir-list@xxxxxxxxxx https://www.redhat.com/mailman/listinfo/libvir-list
