From nobody Mon Apr 29 03:01:47 2024 Delivered-To: importer@patchew.org Received-SPF: pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) client-ip=209.132.183.28; envelope-from=libvir-list-bounces@redhat.com; helo=mx1.redhat.com; Authentication-Results: mx.zohomail.com; spf=pass (zoho.com: domain of redhat.com designates 209.132.183.28 as permitted sender) smtp.mailfrom=libvir-list-bounces@redhat.com Return-Path: Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) by mx.zohomail.com with SMTPS id 15125826342041008.3751150974359; Wed, 6 Dec 2017 09:50:34 -0800 (PST) Received: from smtp.corp.redhat.com (int-mx01.intmail.prod.int.phx2.redhat.com [10.5.11.11]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 2A71A5D5ED; Wed, 6 Dec 2017 17:50:33 +0000 (UTC) Received: from colo-mx.corp.redhat.com (colo-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.21]) by smtp.corp.redhat.com (Postfix) with ESMTPS id 078FF7A3CA; Wed, 6 Dec 2017 17:50:33 +0000 (UTC) Received: from lists01.pubmisc.prod.ext.phx2.redhat.com (lists01.pubmisc.prod.ext.phx2.redhat.com [10.5.19.33]) by colo-mx.corp.redhat.com (Postfix) with ESMTP id C68974BB79; Wed, 6 Dec 2017 17:50:32 +0000 (UTC) Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) by lists01.pubmisc.prod.ext.phx2.redhat.com (8.13.8/8.13.8) with ESMTP id vB6HoVZb005527 for ; Wed, 6 Dec 2017 12:50:31 -0500 Received: by smtp.corp.redhat.com (Postfix) id 0643A619AF; Wed, 6 Dec 2017 17:50:31 +0000 (UTC) Received: from t460.redhat.com (unknown [10.33.36.19]) by smtp.corp.redhat.com (Postfix) with ESMTP id 344436E72B; Wed, 6 Dec 2017 17:50:27 +0000 (UTC) From: "Daniel P. Berrange" To: libvir-list@redhat.com Date: Wed, 6 Dec 2017 17:50:23 +0000 Message-Id: <20171206175023.20378-1-berrange@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-loop: libvir-list@redhat.com Subject: [libvirt] [PATCH] docs: update instructions for TLS cert generation X-BeenThere: libvir-list@redhat.com X-Mailman-Version: 2.1.12 Precedence: junk List-Id: Development discussions about the libvirt library & tools List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Sender: libvir-list-bounces@redhat.com Errors-To: libvir-list-bounces@redhat.com X-Scanned-By: MIMEDefang 2.79 on 10.5.11.11 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.39]); Wed, 06 Dec 2017 17:50:33 +0000 (UTC) X-ZohoMail: RSF_0 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" 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. Descri= be the usage of Subject Alt Name extensions, to provide multiple hostnames and IP addresses. This will help users avoid the classic mistake and is importa= nt 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 --- 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 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.libv= irt.org/system.

The section on remote URIs @@ -412,7 +412,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 mi= ght + be used to reach the server should be lkisted in Subject Alt Name + fields. @@ -564,8 +566,8 @@ X.509 certificate info: =20 Version: 3 Serial Number (hex): 00 -Subject: CN=3DRed Hat Emerging Technologies -Issuer: CN=3DRed Hat Emerging Technologies +Subject: CN=3DLibvirt Project +Issuer: CN=3DLibvirt Project Signature Algorithm: RSA-SHA Validity: Not Before: Mon Jun 18 16:22:18 2007 @@ -582,14 +584,20 @@ 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 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.

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

Make a private key for the server: @@ -599,13 +607,25 @@ 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 '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. 

 organization =3D Name of your organization
-cn =3D oirase
+cn =3D compute1.libvirt.org
+dns_name =3D compute1
+dns_name =3D compute1.libvirt.org
+ip_address =3D 10.0.0.74
+ip_address =3D 192.168.1.24
+ip_address =3D 2001:cafe::74
+ip_address =3D fe20::24
 tls_www_server
 encryption_key
 signing_key
@@ -635,16 +655,28 @@ X.509 certificate info:
=20
 Version: 3
 Serial Number (hex): 00
-Subject: O=3DRed Hat Emerging Technologies,CN=3Doirase
-Issuer: CN=3DRed Hat Emerging Technologies
+Subject: O=3DLibvirt Project,CN=3Dcompute1.libvirt.org
+Issuer: CN=3DLibvirt 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

-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 +697,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: 

-C=3DGB,ST=3DLondon,L=3DLondon,O=3DRed Hat,CN=3Dname_of_client
+C=3DGB,ST=3DLondon,L=3DLondon,O=3DLibvirt Project,CN=3Dname_of_client

The process is the same as for @@ -692,7 +724,7 @@ Act as CA and sign the certificate. Create client.info= containing: country =3D GB state =3D London locality =3D London -organization =3D Red Hat +organization =3D Libvirt Project cn =3D client1 tls_www_client encryption_key @@ -884,7 +916,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=3DGB,ST=3DLondon,L=3DLo= ndon,O=3DRed Hat,CN=3D*" + This list may contain wildcards such as "C=3DGB,ST=3DLondon,L=3DLo= ndon,O=3DLibvirt Project,CN=3D*" See the POSIX fnmatch function for the format of the wildcards.

--=20 2.14.3 -- libvir-list mailing list libvir-list@redhat.com https://www.redhat.com/mailman/listinfo/libvir-list