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.
Raw data
{
"_id": null,
"home_page": "https://github.com/ikreymer/certauth",
"name": "certauth",
"maintainer": "",
"docs_url": null,
"requires_python": "",
"maintainer_email": "",
"keywords": "",
"author": "Ilya Kreymer",
"author_email": "ikreymer@gmail.com",
"download_url": "https://files.pythonhosted.org/packages/5c/ff/48bdb93555bf93708100be50622ba6ff93d7026e9e172b9e8ab92c2ae8f1/certauth-1.3.0.tar.gz",
"platform": "",
"description": "Certificate Authority Certificate Maker Tools\n=============================================\n\n.. image:: https://travis-ci.org/ikreymer/certauth.svg?branch=master\n :target: https://travis-ci.org/ikreymer/certauth\n.. image:: https://coveralls.io/repos/ikreymer/certauth/badge.svg?branch=master\n :target: https://coveralls.io/r/ikreymer/certauth?branch=master\n\nThis package provides a small library, built on top of ``pyOpenSSL``, which allows for creating a custom certificate authority certificate,\nand genereating on-demand dynamic host certs using that CA certificate.\n\nIt is most useful for use with a man-in-the-middle HTTPS proxy, for example, for recording or replaying web content.\n\nTrusting the CA created by this tool should be used with caution in a controlled setting to avoid security risks.\n\n\nCertificateAuthority API\n============================\n\nThe ``CertificateAuthority`` class provides an interface to manage a root CA and generate dynamic host certificates suitable\nfor use with the native Python ``ssl`` library as well as pyOpenSSL ``SSL`` module.\n\nThe class provides several options for storing the root CA and generated host CAs.\n\n\nFile-based Certificate Cache\n~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code:: python\n\n ca = CertificateAuthority('My Custom CA', 'my-ca.pem', cert_cache='/tmp/certs')\n filename = ca.cert_for_host('example.com')\n\nIn this configuration, the root CA is stored at ``my-ca.pem`` and dynamically generated certs\nare placed in ``/tmp/certs``. The ``filename`` returned would be ``/tmp/certs/example.com.pem`` in this example.\n\nThis 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.\n\nNote that the dynamically created certs are never deleted by ``certauth``, it remains up to the user to handle cleanup occasionally if desired.\n\n\nIn-memory Certificate Cache\n~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\n.. code:: python\n\n ca = CertificateAuthority('My Custom CA', 'my-ca.pem', cert_cache=50)\n cert, key = ca.load_cert('example.com')\n\nThis configuration stores the root CA at ``my-ca.pem`` but uses an in-memory certificate cache for dynamically created certs. \nThese certs are stored in an LRU cache, configured to keep at most 50 certs.\n\nThe ``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>`_\n\n.. code:: python\n\n context = SSl.Context(...)\n context.use_privatekey(key)\n context.use_certificate(cert)\n\n\nCustom Cache\n~~~~~~~~~~~~\n\nA custom cache implementations which stores and retrieves per-host certificates can also be provided:\n\n.. code:: python\n\n ca = CertificateAuthority('My Custom CA', 'my-ca.pem', cert_cache=CustomCache())\n cert, key = ca.load_cert('example.com')\n\n class CustomCache:\n def __setitem__(self, host, cert_string):\n # store cert_string for host\n\n def get(self, host):\n # return cached cert_string, if available\n cert_string = ...\n return cert_string\n\n\nWildcard Certs\n~~~~~~~~~~~~~~\n\nTo reduce the number of certs generated, it is convenient to generate wildcard certs.\n\n.. code:: python\n\n cert, key = ca.load_cert('example.com', wildcard=True)\n\nThis will generate a cert for ``*.example.com``.\n\nTo automatically generate a wildcard cert for parent domain, use:\n\n.. code:: python\n\n cert, key = ca.load_cert('test.example.com', wildcard=True, wildcard_for_parent=True)\n\nThis will also generate a cert for ``*.example.com``\n\nStarting with 1.3.0, ``certauth`` uses ``tldextract`` to determine the tld for a given host,\nand will not use a parent domain if it is itself a tld suffix.\n\nFor example, calling:\n\n.. code:: python\n\n cert, key = ca.load_cert('example.co.uk', wildcard=True, wildcard_for_parent=True)\n\nwill now result in a cert for ``*.example.co.uk``, not ``*.co.uk``.\n\n\nCLI Usage Examples\n==================\n\n``certauth`` also includes a simple command-line API for certificate creation and management.\n\n::\n\n usage: certauth [-h] [-c CERTNAME] [-n HOSTNAME] [-d CERTS_DIR] [-f] [-w]\n root_ca_cert\n\n positional arguments:\n root_ca_cert Path to existing or new root CA file\n\n optional arguments:\n -h, --help show this help message and exit\n -c CERTNAME, --certname CERTNAME\n Name for root certificate\n -n HOSTNAME, --hostname HOSTNAME\n Hostname certificate to create\n -d CERTS_DIR, --certs-dir CERTS_DIR\n Directory for host certificates\n -f, --force Overwrite certificates if they already exist\n -w, --wildcard_cert add wildcard SAN to host: *.<host>, <host>\n\n\n\nTo create a new root CA certificate:\n\n``certauth myrootca.pem --certname \"My Test CA\"``\n\nTo create a host certificate signed with CA certificate in directory ``certs_dir``:\n\n``certauth myrootca.pem --hostname \"example.com\" -d ./certs_dir``\n\nIf the root cert doesn't exist, it'll be created automatically.\nIf ``certs_dir``, doesn't exist, it'll be created automatically also.\n\nThe cert for ``example.com`` will be created as ``certs_dir/example.com.pem``.\nIf it already exists, it will not be overwritten (unless ``-f`` option is used).\n\nThe ``-w`` option can be used to create a wildcard cert which has subject alternate names (SAN) for ``example.com`` and ``*.example.com``\n\n\nHistory\n=======\n\nThe 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.\n\nIt was also extended in `warcprox <https://github.com/internetarchive/warcprox>`_ by `Noah Levitt <https://github.com/nlevitt>`_ of Internet Archive.\n\nThe CA functionality was also reused in `pywb <https://github.com/ikreymer/pywb>`_ and finally factored out into this separate package for modularity.\n\nIt is now also used by `wsgiprox <https://github.com/webrecorder/wsgiprox>`_ to provide a generalized HTTPS proxy wrapper to any WSGI application.\n\n\n\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "Simple Certificate Authority for MITM proxies",
"version": "1.3.0",
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"md5": "47e52893ff8357145d6d70d4aa0dc9c7",
"sha256": "f84b8c7075d0e445614d5ec4662056511453f19228cf4fcf8278cccae17b316b"
},
"downloads": -1,
"filename": "certauth-1.3.0-py2.py3-none-any.whl",
"has_sig": false,
"md5_digest": "47e52893ff8357145d6d70d4aa0dc9c7",
"packagetype": "bdist_wheel",
"python_version": "py2.py3",
"requires_python": null,
"size": 10595,
"upload_time": "2019-08-07T01:30:56",
"upload_time_iso_8601": "2019-08-07T01:30:56.566440Z",
"url": "https://files.pythonhosted.org/packages/18/6a/748f61932188f9bfc7685089d9a83b36e239b828aeb610661871d4342917/certauth-1.3.0-py2.py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"md5": "bd9803e4c911a9ba67bde96514067f93",
"sha256": "7862d5deff0b33d2fb28d36861ba63d91c82d700bfdfc4bd848a8711ca72b8fb"
},
"downloads": -1,
"filename": "certauth-1.3.0.tar.gz",
"has_sig": false,
"md5_digest": "bd9803e4c911a9ba67bde96514067f93",
"packagetype": "sdist",
"python_version": "source",
"requires_python": null,
"size": 10798,
"upload_time": "2019-08-07T01:30:58",
"upload_time_iso_8601": "2019-08-07T01:30:58.294438Z",
"url": "https://files.pythonhosted.org/packages/5c/ff/48bdb93555bf93708100be50622ba6ff93d7026e9e172b9e8ab92c2ae8f1/certauth-1.3.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2019-08-07 01:30:58",
"github": true,
"gitlab": false,
"bitbucket": false,
"github_user": "ikreymer",
"github_project": "certauth",
"travis_ci": true,
"coveralls": true,
"github_actions": false,
"appveyor": true,
"tox": true,
"lcname": "certauth"
}
JSON
