Repository files navigation

You wrote a cool network client or server. It encrypts connectionsusingTLS. Your testsuite needs to make TLS connections to itself.

Uh oh. Your test suiteprobably doesn't have a valid TLScertificate. Now what?

trustme is a tiny Python package that does one thing: it gives youafakecertificate authority (CA) that you can use to generate fake TLS certsto use in your tests. Well, technically they're real certs, they'rejust signed by your CA, which nobody trusts. But you can trustit. Trust me.

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.10+, CPython and PyPy

License: MIT or Apache 2, your choice.

Code of conduct: Contributors are requested to follow ourcode ofconductin all project spaces.

Programmatic usage:

importtrustme# ----- 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.orgserver_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 certificateserver_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:withca.cert_pem.tempfile()asca_temp_path:requests.get("https://...",verify=ca_temp_path)

Command line usage:

$# Certs may be generated from anywhere. Here's where we are:$pwd/tmp$# ----- Creating certs -----$python -m trustmeGenerated a certificate for 'localhost', '127.0.0.1', '::1'Configure your server to use the following files:  cert=/tmp/server.pem  key=/tmp/server.keyConfigure 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!

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

Why not just use self-signed certificates? These are morerealistic. You don't have to disable your certificate validation codein your test suite, which is good because you want to test what yourun in production, and you wouldnever disable your certificatevalidation code in production, right? Plus, they're just as easy towork with. Actually easier, in many cases.

What if I want to test how my code handles some bizarre TLSconfiguration? We think trustme hits a sweet spot of ease-of-useand generality as it is. The defaults are carefully chosen to workon all major operating systems and be as fast as possible. We don'twant to turn trustme into a second-rate re-export of everything incryptography. If you have more complexneeds, consider using them directly, possibly starting from thetrustme code.

Will you automate installing CA cert into system trust store? No.mkcert already does thiswell, and we would not have anything to add.