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. Signed-off-by: Daniel P. Berrange <berrange(a)redhat.com&gt; --- 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>;. </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 + 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 +in the URI that clients pass to libvirt. In most TLS impls +the CN field is considered legacy data, the Subject Alt Name +(SAN) extension fields we be preferentially validated against. +In the future use of the CN field for validation may be +discontinuned entirely, so it is strongly recommended to +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>". </p> <p> Make a private key for the server: @@ -599,13 +607,25 @@ certtool --generate-privkey &gt; 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 +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 +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 +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: </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> -- 2.14.3