Skip to main content

#1 quality TLS certs while you wait, for the discerning tester

Project description

https://vignette2.wikia.nocookie.net/jadensadventures/images/1/1e/Kaa%27s_hypnotic_eyes.jpg/revision/latest?cb=20140310173415

You wrote a cool network client or server. It encrypts connections using TLS. 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 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 in all project spaces.

Cheat sheet

Programmatic usage:

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:

$ # 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. 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 already does this well, and we would not have anything to add.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

trustme-1.2.1.tar.gz (26.8 kB view details)

Uploaded Source

Built Distribution

trustme-1.2.1-py3-none-any.whl (16.5 kB view details)

Uploaded Python 3

File details

Details for the file trustme-1.2.1.tar.gz.

File metadata

  • Download URL: trustme-1.2.1.tar.gz
  • Upload date:
  • Size: 26.8 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.13.1

File hashes

Hashes for trustme-1.2.1.tar.gz
Algorithm Hash digest
SHA256 6528ba2bbc7f2db41f33825c8dd13e3e3eb9d334ba0f909713c8c3139f4ae47f
MD5 34fbfb5d2884e08e6fc82a5a53b69efd
BLAKE2b-256 4bc5931476f4cf1cd9e736f32651005078061a50dc164a2569fb874e00eb2786

See more details on using hashes here.

File details

Details for the file trustme-1.2.1-py3-none-any.whl.

File metadata

  • Download URL: trustme-1.2.1-py3-none-any.whl
  • Upload date:
  • Size: 16.5 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/6.0.1 CPython/3.13.1

File hashes

Hashes for trustme-1.2.1-py3-none-any.whl
Algorithm Hash digest
SHA256 d768e5fc57c86dfc5ec9365102e9b092541cd6954b35d8c1eea01a84f35a762a
MD5 38621a65b1e774117ff5d9272c3c5707
BLAKE2b-256 b5f3c34dbabf6da5eda56fe923226769d40e11806952cd7f46655dd06e10f018

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page