Add design document for X509 CA

Signed-off-by: Michael Hanselmann <hansmi@google.com>
Reviewed-by: Iustin Pop <iustin@google.com>

Makefile.am

@@ -273,6 +273,7 @@ docrst = \
 	doc/design-draft.rst \
 	doc/design-oob.rst \
 	doc/design-query2.rst \
+	doc/design-x509-ca.rst \
 	doc/cluster-merge.rst \
 	doc/design-shared-storage.rst \
 	doc/devnotes.rst \

doc/design-draft.rst

@@ -5,6 +5,8 @@ Design document drafts
 .. toctree::
    :maxdepth: 2
 
+   design-x509-ca.rst
+
 .. vim: set textwidth=72 :
 .. Local Variables:
 .. mode: rst

doc/design-x509-ca.rst

+=======================================
+Design for a X509 Certificate Authority
+=======================================
+
+.. contents:: :depth: 4
+
+Current state and shortcomings
+------------------------------
+
+Import/export in Ganeti have a need for many unique X509 certificates.
+So far these were all self-signed, but with the :doc:`new design for
+import/export <design-impexp2>` they need to be signed by a Certificate
+Authority (CA).
+
+
+Proposed changes
+----------------
+
+The plan is to implement a simple CA in Ganeti.
+
+Interacting with an external CA is too difficult or impossible for
+automated processes like exporting instances, so each Ganeti cluster
+will have its own CA. The public key will be stored in
+``…/lib/ganeti/ca/cert.pem``, the private key (only readable by the
+master daemon) in ``…/lib/ganeti/ca/key.pem``.
+
+Similar to the RAPI certificate, a new CA certificate can be installed
+using the ``gnt-cluster renew-crypto`` command. Such a CA could be an
+intermediate of a third-party CA. By default a self-signed CA is
+generated and used.
+
+.. _x509-ca-serial:
+
+Each certificate signed by the CA is required to have a unique serial
+number. The serial number is stored in the file
+``…/lib/ganeti/ca/serial``, replicated to all master candidates and
+never reset, even when a new CA is installed.
+
+The threat model is expected to be the same as with self-signed
+certificates. To reinforce this, all certificates signed by the CA must
+be valid for less than one week (168 hours).
+
+Implementing support for Certificate Revocation Lists (CRL) using
+OpenSSL is non-trivial. Lighttpd doesn't support them at all and
+`apparently never will in version 1.4.x
+<http://redmine.lighttpd.net/issues/2278>`_. Some CRL-related parts have
+only been added in the most recent version of pyOpenSSL (0.11). Instead
+of a CRL, Ganeti will gain a new cluster configuration property defining
+the minimum accepted serial number. In case of a lost or compromised
+private key this property can be set to the most recently generated
+serial number.
+
+While possible to implement in the future, other X509 certificates used
+by the cluster (e.g. RAPI or inter-node communication) will not be
+automatically signed by the per-cluster CA.
+
+The ``commonName`` attribute of signed certificates must be set to the
+the cluster name or the name of a node in the cluster.
+
+
+Software requirements
+---------------------
+
+- pyOpenSSL 0.10 or above (lower versions can't set the X509v3 extension
+  ``subjectKeyIdentifier`` recommended for certificate authority
+  certificates by :rfc:`3280`, section 4.2.1.2)
+
+
+Code samples
+------------
+
+Generating X509 CA using pyOpenSSL
+++++++++++++++++++++++++++++++++++
+
+.. highlight:: python
+
+The following code sample shows how to generate a CA certificate using
+pyOpenSSL::
+
+  key = OpenSSL.crypto.PKey()
+  key.generate_key(OpenSSL.crypto.TYPE_RSA, 2048)
+
+  ca = OpenSSL.crypto.X509()
+  ca.set_version(3)
+  ca.set_serial_number(1)
+  ca.get_subject().CN = "ca.example.com"
+  ca.gmtime_adj_notBefore(0)
+  ca.gmtime_adj_notAfter(24 * 60 * 60)
+  ca.set_issuer(ca.get_subject())
+  ca.set_pubkey(key)
+  ca.add_extensions([
+    OpenSSL.crypto.X509Extension("basicConstraints", True,
+                                 "CA:TRUE, pathlen:0"),
+    OpenSSL.crypto.X509Extension("keyUsage", True,
+                                 "keyCertSign, cRLSign"),
+    OpenSSL.crypto.X509Extension("subjectKeyIdentifier", False, "hash",
+                                 subject=ca),
+    ])
+  ca.sign(key, "sha1")
+
+
+Signing X509 certificate using CA
++++++++++++++++++++++++++++++++++
+
+.. highlight:: python
+
+The following code sample shows how to sign an X509 certificate using a
+CA::
+
+  ca_cert = OpenSSL.crypto.load_certificate(OpenSSL.crypto.FILETYPE_PEM,
+                                            "ca.pem")
+  ca_key = OpenSSL.crypto.load_privatekey(OpenSSL.crypto.FILETYPE_PEM,
+                                          "ca.pem")
+
+  key = OpenSSL.crypto.PKey()
+  key.generate_key(OpenSSL.crypto.TYPE_RSA, 2048)
+
+  cert = OpenSSL.crypto.X509()
+  cert.get_subject().CN = "node1.example.com"
+  cert.set_serial_number(1)
+  cert.gmtime_adj_notBefore(0)
+  cert.gmtime_adj_notAfter(24 * 60 * 60)
+  cert.set_issuer(ca_cert.get_subject())
+  cert.set_pubkey(key)
+  cert.sign(ca_key, "sha1")
+
+
+How to generate Certificate Signing Request
++++++++++++++++++++++++++++++++++++++++++++
+
+.. highlight:: python
+
+The following code sample shows how to generate an X509 Certificate
+Request (CSR)::
+
+  key = OpenSSL.crypto.PKey()
+  key.generate_key(OpenSSL.crypto.TYPE_RSA, 2048)
+
+  req = OpenSSL.crypto.X509Req()
+  req.get_subject().CN = "node1.example.com"
+  req.set_pubkey(key)
+  req.sign(key, "sha1")
+
+  # Write private key
+  print OpenSSL.crypto.dump_privatekey(OpenSSL.crypto.FILETYPE_PEM, key)
+
+  # Write request
+  print OpenSSL.crypto.dump_certificate_request(OpenSSL.crypto.FILETYPE_PEM, req)
+
+
+X509 certificate from Certificate Signing Request
++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. highlight:: python
+
+The following code sample shows how to create an X509 certificate from a
+Certificate Signing Request and sign it with a CA::
+
+  ca_cert = OpenSSL.crypto.load_certificate(OpenSSL.crypto.FILETYPE_PEM,
+                                            "ca.pem")
+  ca_key = OpenSSL.crypto.load_privatekey(OpenSSL.crypto.FILETYPE_PEM,
+                                          "ca.pem")
+  req = OpenSSL.crypto.load_certificate_request(OpenSSL.crypto.FILETYPE_PEM,
+                                                open("req.csr").read())
+
+  cert = OpenSSL.crypto.X509()
+  cert.set_subject(req.get_subject())
+  cert.set_serial_number(1)
+  cert.gmtime_adj_notBefore(0)
+  cert.gmtime_adj_notAfter(24 * 60 * 60)
+  cert.set_issuer(ca_cert.get_subject())
+  cert.set_pubkey(req.get_pubkey())
+  cert.sign(ca_key, "sha1")
+
+  print OpenSSL.crypto.dump_certificate(OpenSSL.crypto.FILETYPE_PEM, cert)
+
+
+Verify whether X509 certificate matches private key
++++++++++++++++++++++++++++++++++++++++++++++++++++
+
+.. highlight:: python
+
+The code sample below shows how to check whether a certificate matches
+with a certain private key. OpenSSL has a function for this,
+``X509_check_private_key``, but pyOpenSSL provides no access to it.
+
+::
+
+  ctx = OpenSSL.SSL.Context(OpenSSL.SSL.TLSv1_METHOD)
+  ctx.use_privatekey(key)
+  ctx.use_certificate(cert)
+  try:
+    ctx.check_privatekey()
+  except OpenSSL.SSL.Error:
+    print "Incorrect key"
+  else:
+    print "Key matches certificate"
+
+
+.. vim: set textwidth=72 :
+.. Local Variables:
+.. mode: rst
+.. fill-column: 72
+.. End: