From 44e522c821154e6483d9a07c9de31559f2e353da Mon Sep 17 00:00:00 2001 From: "Richard W.M. Jones" Date: Tue, 19 Jun 2007 12:12:15 +0000 Subject: [PATCH] Tue Jun 19 13:12:00 BST 2007 Richard W.M. Jones * docs/remote.html: Check in the updated documentation file for the web site. --- ChangeLog | 5 + docs/remote.html | 285 +++++++++++++++++------------------------------ 2 files changed, 108 insertions(+), 182 deletions(-) diff --git a/ChangeLog b/ChangeLog index cce9daa8b5..f7e030b887 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,8 @@ +Tue Jun 19 13:12:00 BST 2007 Richard W.M. Jones + + * docs/remote.html: Check in the updated documentation file + for the web site. + Tue Jun 19 10:30:00 BST 2007 Richard W.M. Jones * src/virsh.c: vcpupin command now documented properly and diff --git a/docs/remote.html b/docs/remote.html index 750e631827..6dfa21c41c 100644 --- a/docs/remote.html +++ b/docs/remote.html @@ -1,11 +1,6 @@ Remote support

Remote support

-NB. Remote support is available only as a series of -patches posted on libvir-list against libvirt CVS. It is only -for experimental use at the moment. -— Richard Jones, 2007-04-18. -

Libvirt allows you to access hypervisors running on remote machines through authenticated and encrypted connections.

Basic usage

@@ -242,65 +237,37 @@ 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. +You will need the GnuTLS +certtool program documented here. In Fedora, it is in the +gnutls-utils package. +

    +Create a private key for your CA: +

    +certtool --generate-privkey > cakey.pem
+

    +and self-sign it by creating a file with the +signature details called +ca.info containing: +

    +cn = Name of your organization
+ca
+cert_signing_key
+
    +certtool --generate-self-signed --load-privkey cakey.pem \
+  --template ca.info --outfile cacert.pem
+

    +(You can delete ca.info file now if you +want). +

    +Now you have two files which matter: +

    • +cakey.pem - Your CA's private key (keep this very secret!)
    • -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"
-
      +cacert.pem - Your CA's certificate (this is public).

    -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 +cacert.pem has to be installed on clients and server(s) to let them know that they can trust certificates issued by your CA.

    @@ -309,24 +276,23 @@ 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
+certtool -i --infile cacert.pem
 
+X.509 certificate info:
+
+Version: 3
+Serial Number (hex): 00
+Subject: CN=Red Hat Emerging Technologies
+Issuer: CN=Red Hat Emerging Technologies
+Signature Algorithm: RSA-SHA
+Validity:
+        Not Before: Mon Jun 18 16:22:18 2007
+        Not After: Tue Jun 17 16:22:18 2008
 [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. +This is all that is required to set up your CA. Keep the CA's private +key carefully as you will need it when you come to issue certificates +for your clients and servers.

    Issuing server certificates

    For each server (libvirtd) you need to issue a certificate with the X.509 CommonName (CN) field set to the hostname @@ -337,100 +303,52 @@ 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 for the server: +

    +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): +

    +organization = Name of your organization
+cn = oirase
+tls_www_server
+encryption_key
+signing_key
+

    +and sign: +

    +certtool --generate-certificate --load-privkey serverkey.pem \
+  --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \
+  --template server.info --outfile servercert.pem
+

    +This gives two files: +

    • +serverkey.pem - The server's private key. +
      • +
    • +servercert.pem - The server's public key. +
      • +

    +We can examine this certificate and its signature: +

    +certtool -i --infile servercert.pem
+X.509 certificate info:
+
+Version: 3
+Serial Number (hex): 00
+Subject: O=Red Hat Emerging Technologies,CN=oirase
+Issuer: CN=Red Hat Emerging Technologies
+Signature Algorithm: RSA-SHA
+Validity:
+        Not Before: Mon Jun 18 16:34:49 2007
+        Not After: Tue Jun 17 16:34:49 2008
+

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

    -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 @@ -458,26 +376,29 @@ The process is the same as for server certificate so here we just briefly cover the steps.

      1. -Make a private key and a request for a new certificate: +Make a private key: 
        -./CA.pl -newreq
-
        -Set the DN fields as required. -
        2. - -
      2. -Act as CA and sign the certificate: -
        -./CA.pl -signreq
+certtool --generate-privkey > clientkey.pem
      3. -Extract the private key for the client and rename the -signed certificate: +Act as CA and sign the certificate. Create client.info containing: 
        -openssl rsa -in newreq.pem -out clientkey.pem
-mv newcert.pem clientcert.pem
+country = GB
+state = London
+locality = London
+organization = Red Hat
+cn = client1
+tls_www_client
+encryption_key
+signing_key
+
        +and sign by doing: +
        +certtool --generate-certificate --load-privkey clientkey.pem \
+  --load-ca-certificate cacert.pem --load-ca-privkey cakey.pem \
+  --template client.info --outfile clientcert.pem