Synnefo » snf-ganeti

=======================================

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: