Metadata-Version: 1.1
Name: certauth
Version: 1.3.0
Summary: Simple Certificate Authority for MITM proxies
Home-page: https://github.com/ikreymer/certauth
Author: Ilya Kreymer
Author-email: ikreymer@gmail.com
License: MIT
Description: 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.
        
        
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Web Environment
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3.2
Classifier: Programming Language :: Python :: 3.3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Topic :: Utilities
Provides: certauth
