From 1815534ef09fdd45ac84ad6969003a7d1b585993 Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Thu, 10 May 2007 15:55:39 +0000 Subject: [PATCH] Thu May 10 17:00:00 BST 2007 Richard W.M. Jones * docs/libvir.html, docs/libvirt.css, docs/remote.html: Added documentation for TLS certificates and libvirtd.conf. CSS changes makes the tables look nicer. remote.html is a generated file. --- ChangeLog | 7 + docs/libvir.html | 570 ++++++++++++++++++++++++++++++++++++++++++++++- docs/libvirt.css | 9 + docs/remote.html | 421 +++++++++++++++++++++++++++++++++- 4 files changed, 996 insertions(+), 11 deletions(-) diff --git a/ChangeLog b/ChangeLog index c5636613f4..b5c2c1c32c 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,10 @@ +Thu May 10 17:00:00 BST 2007 Richard W.M. Jones + + * docs/libvir.html, docs/libvirt.css, docs/remote.html: + Added documentation for TLS certificates and libvirtd.conf. + CSS changes makes the tables look nicer. remote.html is + a generated file. + Tue May 8 11:49:00 BST 2007 Richard W.M. Jones * src/hash.c, src/internal.h, src/libvirt_sym.version: Export diff --git a/docs/libvir.html b/docs/libvir.html index 348aa65b84..91fb9264dc 100644 --- a/docs/libvir.html +++ b/docs/libvir.html @@ -1456,7 +1456,7 @@ Remote URIs have the general form ("[...]" meaning an optional part):

-driver[+transport]://[username@]hostname[:port]/[path][?extraparameters] +driver[+transport]://[username@][hostname][:port]/[path][?extraparameters]

@@ -1508,7 +1508,7 @@ Note that parameter values must be URI-escaped.

- +
@@ -1597,24 +1597,586 @@ Note that parameter values must be

Generating TLS certificates

+

Public Key Infrastructure set up

+

-This section to follow. +If you are unsure how to create TLS certificates, skip to the +next section.

+
Name Transports
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Location Machine Description Required fields
/etc/pki/CA/cacert.pem Installed on all clients and servers CA's certificate (more info) n/a
/etc/pki/libvirt/ private/serverkey.pem Installed on the server Server's private key (more info) n/a
/etc/pki/libvirt/ servercert.pem Installed on the server Server's certificate signed by the CA. + (more info) CommonName (CN) must be the hostname of the server as it + is seen by clients.
/etc/pki/libvirt/ private/clientkey.pem Installed on the client Client's private key. (more info) n/a
/etc/pki/libvirt/ clientcert.pem Installed on the client Client's certificate signed by the CA + (more info) CommonName (CN) must be the client IP address as seen + by the server. Take particular care with IPv4 and IPv6 + addresses, and note that on some operating systems IPv4 addresses + may need to be encapsulated as ::ffff:a.b.c.d +
+

Background to TLS certificates

+

+Libvirt supports TLS certificates for verifying the identity +of the server and clients. There are two distinct checks involved: +

+ +
    +
  • The client should know that it is connecting to the right +server. Checking done by client by matching the certificate that +the server sends to the server's hostname. May be disabled by adding +?no_verify=1 to the +remote URI. +
    • + +
  • The server should know that only permitted clients are +connecting. This can be done based on client's IP address, or on +client's IP address and client's certificate. Checking done by the +server. May be enabled and disabled in the libvirtd.conf file. +
    • +
+ +

+For full certificate checking you will need to have certificates +issued by a recognised Certificate +Authority (CA) for your server(s) and all clients. To avoid the +expense of getting certificates from a commercial CA, you can set up +your own CA and tell your server(s) and clients to trust certificates +issues by your own CA. Follow the instructions in the next section. +

+ +

+Be aware that the default +configuration for libvirtd allows any client to connect provided +they have a valid certificate issued by the CA for their own IP +address. You may want to change this to make it less (or more) +permissive, depending on your needs. +

+ +

Setting up a Certificate Authority (CA)

+ +

+You will need the OpenSSL CA.pl Perl +script documented here. In Fedora, it is in the +openssl-perl package. In Debian and derivatives, it is +in the base openssl package. +

+ +

Notes:

+ +
    +
  • +You may find it +better to start with the basic CA.pl script from OpenSSL +itself, as Linux distributors seem to supply a hacked/broken one. +
    • +
  • +A second confounding factor may be the default +openssl.cnf file supplied with your +Linux distribution. You can switch to a custom +file by doing: +
    +export SSLEAY_CONFIG="-config your_config_file"
+
    +
    • +
+ +

+These instructions assume that CA.pl is in an empty +directory (because you will probably need to edit this script). +Please read the CA.pl manpage +carefully before starting. +

+ +

+Copy CA.pl into an empty directory and edit it. Near the top you will +find various variables: +

+ +

+$DAYS defaults to "-days 365". You may wish +to increase this, otherwise your CA and certificates will expire after +a year, suddenly leaving your systems unmanageable. +

+ +

+$CATOP may be set to "./demoCA" or some +other directory. If you want you can change the name to a suitable +directory name for your organisation. +

+ +

+Now run: +

+ +
+./CA.pl -newca
+CA certificate filename (or enter to create)
+[press enter key]
+Making CA certificate ...
+Generating a 1024 bit RSA private key
+...++++++
+.......................++++++
+writing new private key to './demoCA/private/cakey.pem'
+Enter PEM pass phrase: [type a passphrase]
+Verifying - Enter PEM pass phrase: [type a passphrase]
+
+ +

+It will ask some further questions about your organisation and then +create a CA directory structure (usually called demoCA +unless you changed it above). Some highlights of this directory: +

+ +
+demoCA/newcerts             Certificates issued by the CA
+demoCA/crl                  Certificates revoked by the CA
+demoCA/cacert.pem           The CA's own certificate (this is public)
+demoCA/private/cakey.pem    The CA's private key (keep this secret)
+
+ +

+The important file is cacert.pem which is your new CA's +X.509 certificate. This file has to be installed on clients and +server(s) to let them know that they can trust certificates issued by +your CA. +

+ +

+The normal installation directory for cacert.pem +is /etc/pki/CA/cacert.pem on all clients and servers. +

+ +

+To see the contents of this file, do: +

+ +
+openssl x509 -in demoCA/cacert.pem -text
+Certificate:
+    Data:
+        Version: 3 (0x2)
+        Serial Number:
+            dd:b4:0f:d0:58:0e:08:fa
+        Signature Algorithm: sha1WithRSAEncryption
+        Issuer: C=GB, ST=London, L=London, O=Red Hat UK Ltd, OU=Emerging Technologies, CN=Red Hat/emailAddress=rjones@redhat.com
+        Validity
+            Not Before: May 10 10:26:47 2007 GMT
+            Not After : May  7 10:26:47 2017 GMT
+        Subject: C=GB, ST=London, L=London, O=Red Hat UK Ltd, OU=Emerging Technologies, CN=Red Hat/emailAddress=rjones@redhat.com
+
+[etc]
+
+ +

+This is all that is required to set up your CA. Keep this directory +structure and the passphrase safe as you will require them later when +issuing certificates. +

+ +

Issuing server certificates

+ +

+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. +

+ +

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

+ +

+First move to the directory above the CA directory (from the example +in the last section, demoCA would be a subdirectory). +

+ +

+Make a private key and a request for a new certificate: +

+ +
+./CA.pl -newreq
+Generating a 1024 bit RSA private key
+...++++++
+....................++++++
+writing new private key to 'newreq.pem'
+Enter PEM pass phrase: [enter a passphrase]
+Verifying - Enter PEM pass phrase: [enter a passphrase]
+
+ +

+You will be asked additional details about the certificate. +The single important field is "Common Name" which as explained +above must contain the server's hostname as clients +see it. +

+ +

+The operation creates a request file called newreq.pem +which has both the private key and the unsigned certificate. +In the situation of a "real" CA, you would send the certificate +part off to be signed (along with lots of $$$). Instead we are +going to act as CA and sign it ourselves: +

+ +
+./CA.pl -signreq
+Enter pass phrase for demoCA/private/cakey.pem: [enter CA passphrase]
+Check that the request matches the signature
+Signature ok
+Certificate Details:
+        Serial Number:
+            dd:b4:0f:d0:58:0e:08:fb
+        Validity
+            Not Before: May 10 11:10:40 2007 GMT
+            Not After : May  9 11:10:40 2008 GMT
+        Subject:
+            countryName               = GB
+            stateOrProvinceName       = London
+            localityName              = London
+            organizationName          = Red Hat UK Ltd
+            organizationalUnitName    = Emerging Technologies
+            commonName                = oirase
+            emailAddress              = rjones@redhat.com
+        X509v3 extensions:
+            X509v3 Basic Constraints: 
+                CA:FALSE
+            Netscape Comment: 
+                OpenSSL Generated Certificate
+            X509v3 Subject Key Identifier: 
+                DE:08:0D:12:73:76:06:97:EC:57:EF:8D:1B:48:ED:53:9A:1A:FE:7F
+            X509v3 Authority Key Identifier: 
+                keyid:F6:84:4C:1B:2B:59:10:89:3F:0B:AB:05:7F:57:85:A6:33:C7:7A:60
+
+Certificate is to be certified until May  9 11:10:40 2008 GMT (365 days)
+Sign the certificate? [y/n]:y
+
+
+1 out of 1 certificate requests certified, commit? [y/n]y
+Write out database with 1 new entries
+Data Base Updated
+Signed certificate is in newcert.pem
+
+ +

+This step generates a server certificate signed by the CA +for the server oirase (NB. the commonName field +above). We can examine this certificate and its signature: +

+ +
+openssl x509 -in newcert.pem -text
+Certificate:
+    Data:
+        Version: 3 (0x2)
+        Serial Number:
+            dd:b4:0f:d0:58:0e:08:fb
+        Signature Algorithm: sha1WithRSAEncryption
+        Issuer: C=GB, ST=London, L=London, O=Red Hat UK Ltd, OU=Emerging Technologies, CN=Red Hat/emailAddress=rjones@redhat.com
+        Validity
+            Not Before: May 10 11:10:40 2007 GMT
+            Not After : May  9 11:10:40 2008 GMT
+        Subject: C=GB, ST=London, L=London, O=Red Hat UK Ltd, OU=Emerging Technologies, CN=oirase/emailAddress=rjones@redhat.com
+
+ +

+Note the "Issuer" CN is "Red Hat" (the CA) and the "Subject" CN is +"oirase" (the server). +

+ +

+At this point we have newreq.pem which contains the +private key and unsigned certificate and newcert.pem +which contains the signed certificate. For the server we need just +the private key and signed certificate. For the clients we need just +the signed certificate. So there is one final step which is to +extract the private key from newreq.pem: +

+ +
+openssl rsa -in newreq.pem -out serverkey.pem
+Enter pass phrase for newreq.pem:
+writing RSA key
+
+mv newcert.pem servercert.pem
+
+ +

+Finally we have two files to install: +

+ +
    +
  • +serverkey.pem is +the server's private key which should be copied to the +server only as +/etc/pki/libvirt/private/serverkey.pem. +
    • + +
  • +servercert.pem is the server's certificate +which can be installed on the server as +/etc/pki/libvirt/servercert.pem. +
    • +
+ +

Issuing client certificates

+ +

+For each client (ie. any program linked with libvirt, such as +virt-manager) +you need to issue a certificate with the X.509 CommonName (CN) +field set to the IP address of the client as seen from the +server. +

+ +

+Normally then the CN will just be a string such as +"192.168.2.5". On machines with IPv6 enabled, +IPv4 addresses may appear embedded, for example: +"::ffff:a.b.c.d". +

+ +

+The process is the same as for +setting up the +server certificate so here we just briefly cover the +steps. +

+ +
    +
  1. +Make a private key and a request for a new certificate: +
    +./CA.pl -newreq
+
    +You must set the CommonName (CN) field to be the +client's IP address as seen by the server. See notes above. +
    2. + +
  2. +Act as CA and sign the certificate: +
    +./CA.pl -signreq
+
    +
    3. + +
  3. +Extract the private key for the client and rename the +signed certificate: +
    +openssl rsa -in newreq.pem -out clientkey.pem
+mv newcert.pem clientcert.pem
+
    +
    4. + +
  4. +Install the certificates on the client machine: +
    +cp clientkey.pem /etc/pki/libvirt/private/clientkey.pem
+cp clientcert.pem /etc/pki/libvirt/clientcert.pem
+
    +
    5. +
+ + +

Troubleshooting TLS certificate problems

+ +
+
failed to verify client's certificate
+
+

+On the server side, run the libvirtd server with +the '--remote' and '--verbose' options while the +client is connecting. The verbose messages will tell +you the client's actual IP address versus what is +in the client's certificate. Also you will find out +common problems such as expired certificates. +

+
+

libvirtd configuration

-This section to follow. +Libvirtd (the remote daemon) is configured from a file called +/etc/libvirt/libvirtd.conf, or specified on +the command line using -f filename or +--config filename.

+

+This file should contain lines of the form below. +Blank lines and comments beginning with # are ignored. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Line Default Meaning
listen_tls [0|1] 1 (on) + Listen for secure TLS connections on the public TCP/IP port. +
listen_tcp [0|1] 0 (off) + Listen for unencrypted TCP connections on the public TCP/IP port. +
tls_port "service" "16514" + The port number or service name to listen on for secure TLS connections. +
tcp_port "service" "16509" + The port number or service name to listen on for unencrypted TCP connections. +
tls_no_verify_certificate [0|1] 0 (certificates are verified) + If set to 1 then if a client certificate check fails, it is not an error. +
tls_no_verify_address [0|1] 0 (addresses are verified) + If set to 1 then if a client IP address check fails, it is not an error. +
key_file "filename" "/etc/pki/libvirt/ private/serverkey.pem" + Change the path used to find the server's private key. + If you set this to an empty string, then no private key is loaded. +
cert_file "filename" "/etc/pki/libvirt/ servercert.pem" + Change the path used to find the server's certificate. + If you set this to an empty string, then no certificate is loaded. +
ca_file "filename" "/etc/pki/CA/cacert.pem" + Change the path used to find the trusted CA certificate. + If you set this to an empty string, then no trusted CA certificate is loaded. +
crl_file "filename" (no CRL file is used) + Change the path used to find the CA certificate revocation list (CRL) file. + If you set this to an empty string, then no CRL is loaded. +
tls_allowed_clients ["ip1", "ip2", "ip3"] (none - any client can connect) +

+ Enable an access control list of the IP addresses of clients + who can connect to the TLS or TCP ports on this server. +

+

+ The default is that any client can connect, but their + certificate must match their IP address and must be + issued by the trusted CA. If you use this option, then + in addition only the IP addresses listed may connect. +

+

+ This list may contain wildcards such as 192.168.* + See the POSIX fnmatch function for the format + of the wildcards. +

+

+ Note that if this is an empty list, no client can connect. +

+

IPv6 support

diff --git a/docs/libvirt.css b/docs/libvirt.css index 757f2ed874..3272683f97 100644 --- a/docs/libvirt.css +++ b/docs/libvirt.css @@ -169,3 +169,12 @@ pre.programlisting border-style: double; background: #F0F0F0; } + +table.top_table { + border-collapse: collapse; +} + +table.top_table th, table.top_table td { + vertical-align: top; + border: 1px solid #f0f0f0; +} \ No newline at end of file diff --git a/docs/remote.html b/docs/remote.html index 1f169171e4..9da96dd1f8 100644 --- a/docs/remote.html +++ b/docs/remote.html @@ -81,7 +81,7 @@ The default transport, if no other is specified, is tls.

Remote URIs

Remote URIs have the general form ("[...]" meaning an optional part):

-driver[+transport]://[username@]hostname[:port]/[path][?extraparameters] +driver[+transport]://[username@][hostname][:port]/[path][?extraparameters]

Either the transport or the hostname must be given in order to distinguish this from a local URI. @@ -120,7 +120,7 @@ Remote URIs understand the extra parameters shown below. Any others are passed unmodified through to the back end. Note that parameter values must be URI-escaped. -

+

Name
@@ -181,11 +181,418 @@ Note that parameter values must be -
Name Transports Meaning
name
Example: no_verify=1

Generating TLS certificates

-This section to follow. -

libvirtd configuration

-This section to follow. -

IPv6 support

+

Generating TLS certificates

Public Key Infrastructure set up

+If you are unsure how to create TLS certificates, skip to the +next section. +

+ + + + + + + + + + + + + + + + + + + + + + + +
Location Machine Description Required fields
/etc/pki/CA/cacert.pem Installed on all clients and servers CA's certificate (more info) n/a
/etc/pki/libvirt/ private/serverkey.pem Installed on the server Server's private key (more info) n/a
/etc/pki/libvirt/ servercert.pem Installed on the server Server's certificate signed by the CA. + (more info) CommonName (CN) must be the hostname of the server as it + is seen by clients.
/etc/pki/libvirt/ private/clientkey.pem Installed on the client Client's private key. (more info) n/a
/etc/pki/libvirt/ clientcert.pem Installed on the client Client's certificate signed by the CA + (more info) CommonName (CN) must be the client IP address as seen + by the server. Take particular care with IPv4 and IPv6 + addresses, and note that on some operating systems IPv4 addresses + may need to be encapsulated as ::ffff:a.b.c.d +

Background to TLS certificates

+Libvirt supports TLS certificates for verifying the identity +of the server and clients. There are two distinct checks involved: +

  • The client should know that it is connecting to the right +server. Checking done by client by matching the certificate that +the server sends to the server's hostname. May be disabled by adding +?no_verify=1 to the +remote URI. +
    • + +
  • The server should know that only permitted clients are +connecting. This can be done based on client's IP address, or on +client's IP address and client's certificate. Checking done by the +server. May be enabled and disabled in the libvirtd.conf file. +
    • +

+For full certificate checking you will need to have certificates +issued by a recognised Certificate +Authority (CA) for your server(s) and all clients. To avoid the +expense of getting certificates from a commercial CA, you can set up +your own CA and tell your server(s) and clients to trust certificates +issues by your own CA. Follow the instructions in the next section. +

+Be aware that the default +configuration for libvirtd allows any client to connect provided +they have a valid certificate issued by the CA for their own IP +address. You may want to change this to make it less (or more) +permissive, depending on your needs. +

Setting up a Certificate Authority (CA)

+You will need the OpenSSL CA.pl Perl +script documented here. In Fedora, it is in the +openssl-perl package. In Debian and derivatives, it is +in the base openssl package. +

Notes:

  • +You may find it +better to start with the basic CA.pl script from OpenSSL +itself, as Linux distributors seem to supply a hacked/broken one. +
    • +
  • +A second confounding factor may be the default +openssl.cnf file supplied with your +Linux distribution. You can switch to a custom +file by doing: +
    +export SSLEAY_CONFIG="-config your_config_file"
+
    +
    • +

+These instructions assume that CA.pl is in an empty +directory (because you will probably need to edit this script). +Please read the CA.pl manpage +carefully before starting. +

+Copy CA.pl into an empty directory and edit it. Near the top you will +find various variables: +

+$DAYS defaults to "-days 365". You may wish +to increase this, otherwise your CA and certificates will expire after +a year, suddenly leaving your systems unmanageable. +

+$CATOP may be set to "./demoCA" or some +other directory. If you want you can change the name to a suitable +directory name for your organisation. +

+Now run: +

+./CA.pl -newca
+CA certificate filename (or enter to create)
+[press enter key]
+Making CA certificate ...
+Generating a 1024 bit RSA private key
+...++++++
+.......................++++++
+writing new private key to './demoCA/private/cakey.pem'
+Enter PEM pass phrase: [type a passphrase]
+Verifying - Enter PEM pass phrase: [type a passphrase]
+

+It will ask some further questions about your organisation and then +create a CA directory structure (usually called demoCA +unless you changed it above). Some highlights of this directory: +

+demoCA/newcerts             Certificates issued by the CA
+demoCA/crl                  Certificates revoked by the CA
+demoCA/cacert.pem           The CA's own certificate (this is public)
+demoCA/private/cakey.pem    The CA's private key (keep this secret)
+

+The important file is cacert.pem which is your new CA's +X.509 certificate. This file has to be installed on clients and +server(s) to let them know that they can trust certificates issued by +your CA. +

+The normal installation directory for cacert.pem +is /etc/pki/CA/cacert.pem on all clients and servers. +

+To see the contents of this file, do: +

+openssl x509 -in demoCA/cacert.pem -text
+Certificate:
+    Data:
+        Version: 3 (0x2)
+        Serial Number:
+            dd:b4:0f:d0:58:0e:08:fa
+        Signature Algorithm: sha1WithRSAEncryption
+        Issuer: C=GB, ST=London, L=London, O=Red Hat UK Ltd, OU=Emerging Technologies, CN=Red Hat/emailAddress=rjones@redhat.com
+        Validity
+            Not Before: May 10 10:26:47 2007 GMT
+            Not After : May  7 10:26:47 2017 GMT
+        Subject: C=GB, ST=London, L=London, O=Red Hat UK Ltd, OU=Emerging Technologies, CN=Red Hat/emailAddress=rjones@redhat.com
+
+[etc]
+

+This is all that is required to set up your CA. Keep this directory +structure and the passphrase safe as you will require them later when +issuing certificates. +

Issuing server certificates

+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. +

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

+First move to the directory above the CA directory (from the example +in the last section, demoCA would be a subdirectory). +

+Make a private key and a request for a new certificate: +

+./CA.pl -newreq
+Generating a 1024 bit RSA private key
+...++++++
+....................++++++
+writing new private key to 'newreq.pem'
+Enter PEM pass phrase: [enter a passphrase]
+Verifying - Enter PEM pass phrase: [enter a passphrase]
+

+You will be asked additional details about the certificate. +The single important field is "Common Name" which as explained +above must contain the server's hostname as clients +see it. +

+The operation creates a request file called newreq.pem +which has both the private key and the unsigned certificate. +In the situation of a "real" CA, you would send the certificate +part off to be signed (along with lots of $$$). Instead we are +going to act as CA and sign it ourselves: +

+./CA.pl -signreq
+Enter pass phrase for demoCA/private/cakey.pem: [enter CA passphrase]
+Check that the request matches the signature
+Signature ok
+Certificate Details:
+        Serial Number:
+            dd:b4:0f:d0:58:0e:08:fb
+        Validity
+            Not Before: May 10 11:10:40 2007 GMT
+            Not After : May  9 11:10:40 2008 GMT
+        Subject:
+            countryName               = GB
+            stateOrProvinceName       = London
+            localityName              = London
+            organizationName          = Red Hat UK Ltd
+            organizationalUnitName    = Emerging Technologies
+            commonName                = oirase
+            emailAddress              = rjones@redhat.com
+        X509v3 extensions:
+            X509v3 Basic Constraints: 
+                CA:FALSE
+            Netscape Comment: 
+                OpenSSL Generated Certificate
+            X509v3 Subject Key Identifier: 
+                DE:08:0D:12:73:76:06:97:EC:57:EF:8D:1B:48:ED:53:9A:1A:FE:7F
+            X509v3 Authority Key Identifier: 
+                keyid:F6:84:4C:1B:2B:59:10:89:3F:0B:AB:05:7F:57:85:A6:33:C7:7A:60
+
+Certificate is to be certified until May  9 11:10:40 2008 GMT (365 days)
+Sign the certificate? [y/n]:y
+
+
+1 out of 1 certificate requests certified, commit? [y/n]y
+Write out database with 1 new entries
+Data Base Updated
+Signed certificate is in newcert.pem
+

+This step generates a server certificate signed by the CA +for the server oirase (NB. the commonName field +above). We can examine this certificate and its signature: +

+openssl x509 -in newcert.pem -text
+Certificate:
+    Data:
+        Version: 3 (0x2)
+        Serial Number:
+            dd:b4:0f:d0:58:0e:08:fb
+        Signature Algorithm: sha1WithRSAEncryption
+        Issuer: C=GB, ST=London, L=London, O=Red Hat UK Ltd, OU=Emerging Technologies, CN=Red Hat/emailAddress=rjones@redhat.com
+        Validity
+            Not Before: May 10 11:10:40 2007 GMT
+            Not After : May  9 11:10:40 2008 GMT
+        Subject: C=GB, ST=London, L=London, O=Red Hat UK Ltd, OU=Emerging Technologies, CN=oirase/emailAddress=rjones@redhat.com
+

+Note the "Issuer" CN is "Red Hat" (the CA) and the "Subject" CN is +"oirase" (the server). +

+At this point we have newreq.pem which contains the +private key and unsigned certificate and newcert.pem +which contains the signed certificate. For the server we need just +the private key and signed certificate. For the clients we need just +the signed certificate. So there is one final step which is to +extract the private key from newreq.pem: +

+openssl rsa -in newreq.pem -out serverkey.pem
+Enter pass phrase for newreq.pem:
+writing RSA key
+
+mv newcert.pem servercert.pem
+

+Finally we have two files to install: +

  • +serverkey.pem is +the server's private key which should be copied to the +server only as +/etc/pki/libvirt/private/serverkey.pem. +
    • + +
  • +servercert.pem is the server's certificate +which can be installed on the server as +/etc/pki/libvirt/servercert.pem. +
    • +

Issuing client certificates

+For each client (ie. any program linked with libvirt, such as +virt-manager) +you need to issue a certificate with the X.509 CommonName (CN) +field set to the IP address of the client as seen from the +server. +

+Normally then the CN will just be a string such as +"192.168.2.5". On machines with IPv6 enabled, +IPv4 addresses may appear embedded, for example: +"::ffff:a.b.c.d". +

+The process is the same as for +setting up the +server certificate so here we just briefly cover the +steps. +

  1. +Make a private key and a request for a new certificate: +
    +./CA.pl -newreq
+
    +You must set the CommonName (CN) field to be the +client's IP address as seen by the server. See notes above. +
    2. + +
  2. +Act as CA and sign the certificate: +
    +./CA.pl -signreq
+
    +
    3. + +
  3. +Extract the private key for the client and rename the +signed certificate: +
    +openssl rsa -in newreq.pem -out clientkey.pem
+mv newcert.pem clientcert.pem
+
    +
    4. + +
  4. +Install the certificates on the client machine: +
    +cp clientkey.pem /etc/pki/libvirt/private/clientkey.pem
+cp clientcert.pem /etc/pki/libvirt/clientcert.pem
+
    +
    5. +

Troubleshooting TLS certificate problems

failed to verify client's certificate
+
+

+On the server side, run the libvirtd server with +the '--remote' and '--verbose' options while the +client is connecting. The verbose messages will tell +you the client's actual IP address versus what is +in the client's certificate. Also you will find out +common problems such as expired certificates. +

+
+

libvirtd configuration

+Libvirtd (the remote daemon) is configured from a file called +/etc/libvirt/libvirtd.conf, or specified on +the command line using -f filename or +--config filename. +

+This file should contain lines of the form below. +Blank lines and comments beginning with # are ignored. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
Line Default Meaning
listen_tls [0|1] 1 (on) + Listen for secure TLS connections on the public TCP/IP port. +
listen_tcp [0|1] 0 (off) + Listen for unencrypted TCP connections on the public TCP/IP port. +
tls_port "service" "16514" + The port number or service name to listen on for secure TLS connections. +
tcp_port "service" "16509" + The port number or service name to listen on for unencrypted TCP connections. +
tls_no_verify_certificate [0|1] 0 (certificates are verified) + If set to 1 then if a client certificate check fails, it is not an error. +
tls_no_verify_address [0|1] 0 (addresses are verified) + If set to 1 then if a client IP address check fails, it is not an error. +
key_file "filename" "/etc/pki/libvirt/ private/serverkey.pem" + Change the path used to find the server's private key. + If you set this to an empty string, then no private key is loaded. +
cert_file "filename" "/etc/pki/libvirt/ servercert.pem" + Change the path used to find the server's certificate. + If you set this to an empty string, then no certificate is loaded. +
ca_file "filename" "/etc/pki/CA/cacert.pem" + Change the path used to find the trusted CA certificate. + If you set this to an empty string, then no trusted CA certificate is loaded. +
crl_file "filename" (no CRL file is used) + Change the path used to find the CA certificate revocation list (CRL) file. + If you set this to an empty string, then no CRL is loaded. +
tls_allowed_clients ["ip1", "ip2", "ip3"] (none - any client can connect) +

+ Enable an access control list of the IP addresses of clients + who can connect to the TLS or TCP ports on this server. +

+

+ The default is that any client can connect, but their + certificate must match their IP address and must be + issued by the trusted CA. If you use this option, then + in addition only the IP addresses listed may connect. +

+

+ This list may contain wildcards such as 192.168.* + See the POSIX fnmatch function for the format + of the wildcards. +

+

+ Note that if this is an empty list, no client can connect. +

+

IPv6 support

IPv6 has received some limited testing and should work. Problems with libvirt and IPv6 should be reported as bugs.

Limitations

  • Remote storage: To be fully useful, particularly for