certauth 1.3.0
Simple Certificate Authority for MITM proxies
License: MIT

Certificate Authority Certificate Maker Tools
=============================================

.. image:: https://travis-ci.org/ikreymer/certauth.svg?branch=master
    :target: https://travis-ci.org/ikreymer/certauth
.. image:: https://coveralls.io/repos/ikreymer/certauth/badge.svg?branch=master
    :target: https://coveralls.io/r/ikreymer/certauth?branch=master

This package provides a small library, built on top of ``pyOpenSSL``, which allows for creating a custom certificate authority certificate,
and genereating on-demand dynamic host certs using that CA certificate.

It is most useful for use with a man-in-the-middle HTTPS proxy, for example, for recording or replaying web content.

Trusting the CA created by this tool should be used with caution in a controlled setting to avoid security risks.


CertificateAuthority API
============================

The ``CertificateAuthority`` class provides an interface to manage a root CA and generate dynamic host certificates suitable
for use with the native Python ``ssl`` library as well as pyOpenSSL ``SSL`` module.

The class provides several options for storing the root CA and generated host CAs.


File-based Certificate Cache
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

   ca = CertificateAuthority('My Custom CA', 'my-ca.pem', cert_cache='/tmp/certs')
   filename = ca.cert_for_host('example.com')

In this configuration, the root CA is stored at ``my-ca.pem`` and dynamically generated certs
are placed in ``/tmp/certs``. The ``filename`` returned would be ``/tmp/certs/example.com.pem`` in this example.

This filename can then be used with the Python `ssl.load_cert_chain(certfile) <https://docs.python.org/3/library/ssl.html#ssl.SSLContext.load_cert_chain>`_ command.

Note that the dynamically created certs are never deleted by ``certauth``, it remains up to the user to handle cleanup occasionally if desired.


In-memory Certificate Cache
~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. code:: python

   ca = CertificateAuthority('My Custom CA', 'my-ca.pem', cert_cache=50)
   cert, key = ca.load_cert('example.com')

This configuration stores the root CA at ``my-ca.pem`` but uses an in-memory certificate cache for dynamically created certs. 
These certs are stored in an LRU cache, configured to keep at most 50 certs.

The ``cert`` and ``key`` can then be used with `OpenSSL.SSL.Context.use_certificate <http://www.pyopenssl.org/en/stable/api/ssl.html#OpenSSL.SSL.Context.use_certificate>`_

.. code:: python

        context = SSl.Context(...)
        context.use_privatekey(key)
        context.use_certificate(cert)


Custom Cache
~~~~~~~~~~~~

A custom cache implementations which stores and retrieves per-host certificates can also be provided:

.. code:: python

   ca = CertificateAuthority('My Custom CA', 'my-ca.pem', cert_cache=CustomCache())
   cert, key = ca.load_cert('example.com')

   class CustomCache:
       def __setitem__(self, host, cert_string):
          # store cert_string for host

       def get(self, host):
          # return cached cert_string, if available
          cert_string = ...
          return cert_string


Wildcard Certs
~~~~~~~~~~~~~~

To reduce the number of certs generated, it is convenient to generate wildcard certs.

.. code:: python

   cert, key = ca.load_cert('example.com', wildcard=True)

This will generate a cert for ``*.example.com``.

To automatically generate a wildcard cert for parent domain, use:

.. code:: python

   cert, key = ca.load_cert('test.example.com', wildcard=True, wildcard_for_parent=True)

This will also generate a cert for ``*.example.com``

Starting with 1.3.0, ``certauth`` uses ``tldextract`` to determine the tld for a given host,
and will not use a parent domain if it is itself a tld suffix.

For example, calling:

.. code:: python

   cert, key = ca.load_cert('example.co.uk', wildcard=True, wildcard_for_parent=True)

will now result in a cert for ``*.example.co.uk``, not ``*.co.uk``.


CLI Usage Examples
==================

``certauth`` also includes a simple command-line API for certificate creation and management.

::

  usage: certauth [-h] [-c CERTNAME] [-n HOSTNAME] [-d CERTS_DIR] [-f] [-w]
                root_ca_cert

  positional arguments:
    root_ca_cert          Path to existing or new root CA file

  optional arguments:
    -h, --help            show this help message and exit
    -c CERTNAME, --certname CERTNAME
                        Name for root certificate
    -n HOSTNAME, --hostname HOSTNAME
                        Hostname certificate to create
    -d CERTS_DIR, --certs-dir CERTS_DIR
                        Directory for host certificates
    -f, --force           Overwrite certificates if they already exist
    -w, --wildcard_cert   add wildcard SAN to host: *.<host>, <host>



To create a new root CA certificate:

``certauth myrootca.pem --certname "My Test CA"``

To create a host certificate signed with CA certificate in directory ``certs_dir``:

``certauth myrootca.pem --hostname "example.com" -d ./certs_dir``

If the root cert doesn't exist, it'll be created automatically.
If ``certs_dir``, doesn't exist, it'll be created automatically also.

The cert for ``example.com`` will be created as ``certs_dir/example.com.pem``.
If it already exists, it will not be overwritten (unless ``-f`` option is used).

The ``-w`` option can be used to create a wildcard cert which has subject alternate names (SAN) for ``example.com`` and ``*.example.com``


History
=======

The CertificateAuthority functionality has evolved from certificate management originally found in the man-in-the-middle proxy `pymiproxy <https://github.com/allfro/pymiproxy>`_ by Nadeem Douba.

It was also extended in `warcprox <https://github.com/internetarchive/warcprox>`_ by `Noah Levitt <https://github.com/nlevitt>`_ of Internet Archive.

The CA functionality was also reused in `pywb <https://github.com/ikreymer/pywb>`_ and finally factored out into this separate package for modularity.

It is now also used by `wsgiprox <https://github.com/webrecorder/wsgiprox>`_ to provide a generalized HTTPS proxy wrapper to any WSGI application.