From 25ff8dd29e50b2c0d8311dd7c2d9c35c56a18ab2 Mon Sep 17 00:00:00 2001 From: "Daniel P. Berrange" Date: Wed, 6 Dec 2017 17:48:11 +0000 Subject: [PATCH] docs: update instructions for TLS cert generation 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. Reviewed-by: John Ferlan Signed-off-by: Daniel P. Berrange --- docs/remote.html.in | 87 ++++++++++++++++++++++++++++++++------------- 1 file changed, 63 insertions(+), 24 deletions(-) diff --git a/docs/remote.html.in b/docs/remote.html.in index 9bafd9de67..8c22778f53 100644 --- a/docs/remote.html.in +++ b/docs/remote.html.in @@ -30,7 +30,8 @@ to virConnectOpen (or virsh -c ...). For example, if you normally use qemu:///system to access the system-wide QEMU daemon, then to access the system-wide QEMU daemon on a remote machine called -oirase you would use qemu://oirase/system. +compute1.libvirt.org you would use +qemu://compute1.libvirt.org/system.

The section on remote URIs @@ -412,7 +413,9 @@ next section. Server's certificate signed by the CA. (more info) CommonName (CN) must be the hostname of the server as it - is seen by clients. + is seen by clients. All hostname and IP address variants that might + be used to reach the server should be listed in Subject Alt Name + fields. @@ -564,8 +567,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 +585,21 @@ for your clients and servers.

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 implementations +the CN field is 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 +discontinued entirely, so it is strongly recommended to +include the SAN fields.

In the example below, clients will be connecting to the server using a URI of -xen://oirase/, so the CN must be "oirase". +qemu://compute1.libvirt.org/system, so the CN +must be "compute1.libvirt.org".

Make a private key for the server: @@ -599,19 +609,36 @@ certtool --generate-privkey > serverkey.pem

and sign that key with the CA's private key by first -creating a template file called server.info -(only the CN field matters, which as explained above must -be the server's hostname): +creating a template file called server.info. +The template file will contain a number of fields to define +the server as follows: 

 organization = Name of your organization
-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
+

+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 more 'ip_address' fields should +also be added. +

-and sign: +Use the template file as input to a certtool +command to sign the server certificate: 

 certtool --generate-certificate --load-privkey serverkey.pem \
@@ -635,16 +662,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
+        Not Before: Wed Oct 04 09:09:44 UTC 2017
+        Not After: Thu Oct 04 09:09:44 UTC 2018
+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

-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

Finally we have two files to install: @@ -665,13 +704,13 @@ which can be installed on the server as

For each client (ie. any program linked with libvirt, such as -virt-manager) +virt-manager) 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: +policy. For example: 

-C=GB,ST=London,L=London,O=Red Hat,CN=name_of_client
+C=GB,ST=London,L=London,O=Libvirt Project,CN=name_of_client

The process is the same as for @@ -692,7 +731,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 +923,7 @@ Blank lines and comments beginning with # are ignored. The default is that DNs are not checked.

- This list may contain wildcards such as "C=GB,ST=London,L=London,O=Red Hat,CN=*" + This list may contain wildcards such as "C=GB,ST=London,L=London,O=Libvirt Project,CN=*" See the POSIX fnmatch function for the format of the wildcards.