trustme


Nametrustme JSON
Version 1.1.0 PyPI version JSON
download
home_pagehttps://github.com/python-trio/trustme
Summary#1 quality TLS certs while you wait, for the discerning tester
upload_time2023-07-10 06:56:58
maintainer
docs_urlNone
authorNathaniel J. Smith
requires_python>=3.8
licenseMIT OR Apache-2.0
keywords
VCS
bugtrack_url
requirements No requirements were recorded.
Travis-CI No Travis.
coveralls test coverage No coveralls.
            .. note that this README gets 'include'ed into the main documentation

==============================================
 trustme: #1 quality TLS certs while you wait
==============================================

.. image:: https://vignette2.wikia.nocookie.net/jadensadventures/images/1/1e/Kaa%27s_hypnotic_eyes.jpg/revision/latest?cb=20140310173415
   :width: 200px
   :align: right

You wrote a cool network client or server. It encrypts connections
using `TLS
<https://en.wikipedia.org/wiki/Transport_Layer_Security>`__. Your test
suite needs to make TLS connections to itself.

Uh oh. Your test suite *probably* doesn't have a valid TLS
certificate. Now what?

``trustme`` is a tiny Python package that does one thing: it gives you
a `fake <https://martinfowler.com/bliki/TestDouble.html>`__
certificate authority (CA) that you can use to generate fake TLS certs
to use in your tests. Well, technically they're real certs, they're
just signed by your CA, which nobody trusts. But you can trust
it. Trust me.


Vital statistics
================

**Install:** ``pip install -U trustme``

**Documentation:** https://trustme.readthedocs.io

**Bug tracker and source code:** https://github.com/python-trio/trustme

**Tested on:** Python 3.8+, CPython and PyPy

**License:** MIT or Apache 2, your choice.

**Code of conduct:** Contributors are requested to follow our `code of
conduct
<https://github.com/python-trio/trustme/blob/master/CODE_OF_CONDUCT.md>`__
in all project spaces.


Cheat sheet
===========

Programmatic usage:

.. code-block:: python

   import trustme

   # ----- Creating certs -----

   # Look, you just created your certificate authority!
   ca = trustme.CA()

   # And now you issued a cert signed by this fake CA
   # https://en.wikipedia.org/wiki/Example.org
   server_cert = ca.issue_cert("test-host.example.org")

   # That's it!

   # ----- Using your shiny new certs -----

   # You can configure SSL context objects to trust this CA:
   ca.configure_trust(ssl_context)
   # Or configure them to present the server certificate
   server_cert.configure_cert(ssl_context)
   # You can use standard library or PyOpenSSL context objects here,
   # trustme is happy either way.

   # ----- or -----

   # Save the PEM-encoded data to a file to use in non-Python test
   # suites:
   ca.cert_pem.write_to_path("ca.pem")
   server_cert.private_key_and_cert_chain_pem.write_to_path("server.pem")

   # ----- or -----

   # Put the PEM-encoded data in a temporary file, for libraries that
   # insist on that:
   with ca.cert_pem.tempfile() as ca_temp_path:
       requests.get("https://...", verify=ca_temp_path)

Command line usage:

.. code-block:: console

   $ # Certs may be generated from anywhere. Here's where we are:
   $ pwd
   /tmp
   $ # ----- Creating certs -----
   $ python -m trustme
   Generated a certificate for 'localhost', '127.0.0.1', '::1'
   Configure your server to use the following files:
     cert=/tmp/server.pem
     key=/tmp/server.key
   Configure your client to use the following files:
     cert=/tmp/client.pem
   $ # ----- Using certs -----
   $ gunicorn --keyfile server.key --certfile server.pem app:app
   $ curl --cacert client.pem https://localhost:8000/
   Hello, world!


FAQ
===

**Should I use these certs for anything real?** Certainly not.

**Why not just use self-signed certificates?** These are more
realistic. You don't have to disable your certificate validation code
in your test suite, which is good because you want to test what you
run in production, and you would *never* disable your certificate
validation code in production, right? Plus, they're just as easy to
work with. Actually easier, in many cases.

**What if I want to test how my code handles some bizarre TLS
configuration?** We think trustme hits a sweet spot of ease-of-use
and generality as it is. The defaults are carefully chosen to work
on all major operating systems and be as fast as possible. We don't
want to turn trustme into a second-rate re-export of everything in
`cryptography <https://cryptography.io>`__. If you have more complex
needs, consider using them directly, possibly starting from the
trustme code.

**Will you automate installing CA cert into system trust store?** No.
`mkcert <https://github.com/FiloSottile/mkcert>`__ already does this
well, and we would not have anything to add.

            

Raw data

            {
    "_id": null,
    "home_page": "https://github.com/python-trio/trustme",
    "name": "trustme",
    "maintainer": "",
    "docs_url": null,
    "requires_python": ">=3.8",
    "maintainer_email": "",
    "keywords": "",
    "author": "Nathaniel J. Smith",
    "author_email": "njs@pobox.com",
    "download_url": "https://files.pythonhosted.org/packages/60/65/1e0fa6e1d336e4e50e41999699903ee216ac500c40ebb2578742d8f1c656/trustme-1.1.0.tar.gz",
    "platform": null,
    "description": ".. note that this README gets 'include'ed into the main documentation\n\n==============================================\n trustme: #1 quality TLS certs while you wait\n==============================================\n\n.. image:: https://vignette2.wikia.nocookie.net/jadensadventures/images/1/1e/Kaa%27s_hypnotic_eyes.jpg/revision/latest?cb=20140310173415\n   :width: 200px\n   :align: right\n\nYou wrote a cool network client or server. It encrypts connections\nusing `TLS\n<https://en.wikipedia.org/wiki/Transport_Layer_Security>`__. Your test\nsuite needs to make TLS connections to itself.\n\nUh oh. Your test suite *probably* doesn't have a valid TLS\ncertificate. Now what?\n\n``trustme`` is a tiny Python package that does one thing: it gives you\na `fake <https://martinfowler.com/bliki/TestDouble.html>`__\ncertificate authority (CA) that you can use to generate fake TLS certs\nto use in your tests. Well, technically they're real certs, they're\njust signed by your CA, which nobody trusts. But you can trust\nit. Trust me.\n\n\nVital statistics\n================\n\n**Install:** ``pip install -U trustme``\n\n**Documentation:** https://trustme.readthedocs.io\n\n**Bug tracker and source code:** https://github.com/python-trio/trustme\n\n**Tested on:** Python 3.8+, CPython and PyPy\n\n**License:** MIT or Apache 2, your choice.\n\n**Code of conduct:** Contributors are requested to follow our `code of\nconduct\n<https://github.com/python-trio/trustme/blob/master/CODE_OF_CONDUCT.md>`__\nin all project spaces.\n\n\nCheat sheet\n===========\n\nProgrammatic usage:\n\n.. code-block:: python\n\n   import trustme\n\n   # ----- Creating certs -----\n\n   # Look, you just created your certificate authority!\n   ca = trustme.CA()\n\n   # And now you issued a cert signed by this fake CA\n   # https://en.wikipedia.org/wiki/Example.org\n   server_cert = ca.issue_cert(\"test-host.example.org\")\n\n   # That's it!\n\n   # ----- Using your shiny new certs -----\n\n   # You can configure SSL context objects to trust this CA:\n   ca.configure_trust(ssl_context)\n   # Or configure them to present the server certificate\n   server_cert.configure_cert(ssl_context)\n   # You can use standard library or PyOpenSSL context objects here,\n   # trustme is happy either way.\n\n   # ----- or -----\n\n   # Save the PEM-encoded data to a file to use in non-Python test\n   # suites:\n   ca.cert_pem.write_to_path(\"ca.pem\")\n   server_cert.private_key_and_cert_chain_pem.write_to_path(\"server.pem\")\n\n   # ----- or -----\n\n   # Put the PEM-encoded data in a temporary file, for libraries that\n   # insist on that:\n   with ca.cert_pem.tempfile() as ca_temp_path:\n       requests.get(\"https://...\", verify=ca_temp_path)\n\nCommand line usage:\n\n.. code-block:: console\n\n   $ # Certs may be generated from anywhere. Here's where we are:\n   $ pwd\n   /tmp\n   $ # ----- Creating certs -----\n   $ python -m trustme\n   Generated a certificate for 'localhost', '127.0.0.1', '::1'\n   Configure your server to use the following files:\n     cert=/tmp/server.pem\n     key=/tmp/server.key\n   Configure your client to use the following files:\n     cert=/tmp/client.pem\n   $ # ----- Using certs -----\n   $ gunicorn --keyfile server.key --certfile server.pem app:app\n   $ curl --cacert client.pem https://localhost:8000/\n   Hello, world!\n\n\nFAQ\n===\n\n**Should I use these certs for anything real?** Certainly not.\n\n**Why not just use self-signed certificates?** These are more\nrealistic. You don't have to disable your certificate validation code\nin your test suite, which is good because you want to test what you\nrun in production, and you would *never* disable your certificate\nvalidation code in production, right? Plus, they're just as easy to\nwork with. Actually easier, in many cases.\n\n**What if I want to test how my code handles some bizarre TLS\nconfiguration?** We think trustme hits a sweet spot of ease-of-use\nand generality as it is. The defaults are carefully chosen to work\non all major operating systems and be as fast as possible. We don't\nwant to turn trustme into a second-rate re-export of everything in\n`cryptography <https://cryptography.io>`__. If you have more complex\nneeds, consider using them directly, possibly starting from the\ntrustme code.\n\n**Will you automate installing CA cert into system trust store?** No.\n`mkcert <https://github.com/FiloSottile/mkcert>`__ already does this\nwell, and we would not have anything to add.\n",
    "bugtrack_url": null,
    "license": "MIT OR Apache-2.0",
    "summary": "#1 quality TLS certs while you wait, for the discerning tester",
    "version": "1.1.0",
    "project_urls": {
        "Homepage": "https://github.com/python-trio/trustme"
    },
    "split_keywords": [],
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "e94babcebf9a03a05a82f48d9b63189c566727e1f72ddcc6dbfdd2314bb5cd08",
                "md5": "478d6704c59698d7238130e5c07c5108",
                "sha256": "ce105b68fb9f6d7ac7a9ee6e95bb2347a22ce4d3be78ef9a6494d5ef890e1e16"
            },
            "downloads": -1,
            "filename": "trustme-1.1.0-py3-none-any.whl",
            "has_sig": false,
            "md5_digest": "478d6704c59698d7238130e5c07c5108",
            "packagetype": "bdist_wheel",
            "python_version": "py3",
            "requires_python": ">=3.8",
            "size": 16447,
            "upload_time": "2023-07-10T06:56:56",
            "upload_time_iso_8601": "2023-07-10T06:56:56.783300Z",
            "url": "https://files.pythonhosted.org/packages/e9/4b/abcebf9a03a05a82f48d9b63189c566727e1f72ddcc6dbfdd2314bb5cd08/trustme-1.1.0-py3-none-any.whl",
            "yanked": false,
            "yanked_reason": null
        },
        {
            "comment_text": "",
            "digests": {
                "blake2b_256": "60651e0fa6e1d336e4e50e41999699903ee216ac500c40ebb2578742d8f1c656",
                "md5": "b47e6d89f255efca251f167a80a2656d",
                "sha256": "5375ad7fb427074bec956592e0d4ee2a4cf4da68934e1ba4bcf4217126bc45e6"
            },
            "downloads": -1,
            "filename": "trustme-1.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "b47e6d89f255efca251f167a80a2656d",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": ">=3.8",
            "size": 29611,
            "upload_time": "2023-07-10T06:56:58",
            "upload_time_iso_8601": "2023-07-10T06:56:58.225813Z",
            "url": "https://files.pythonhosted.org/packages/60/65/1e0fa6e1d336e4e50e41999699903ee216ac500c40ebb2578742d8f1c656/trustme-1.1.0.tar.gz",
            "yanked": false,
            "yanked_reason": null
        }
    ],
    "upload_time": "2023-07-10 06:56:58",
    "github": true,
    "gitlab": false,
    "bitbucket": false,
    "codeberg": false,
    "github_user": "python-trio",
    "github_project": "trustme",
    "travis_ci": false,
    "coveralls": false,
    "github_actions": true,
    "lcname": "trustme"
}
        
Elapsed time: 0.08868s