Skip to main content

Tools for letting the macOS Keychain verify certs for python requests

Project description

MacSesh

This package allows the popular requests library to use the macOS keychain for validating a server, and for doing client cert auth. Its original use-case was for Mac admins wanting to use python requests and certs provided by an MDM for TLS, Specifically, client cert auth using SCEP profiles, and x509 payloads for server validation.

Installing

pip install MacSesh

If you want to install from a source distribution, clone and run below.

pip install .

Example Usage:

Validate using a trusted cert from the keychain:

>>> import macsesh
>>> sesh = macsesh.Session()
>>> response = sesh.get('https://nethack.org')

If you want to use the "basic" requests API without creating a session:

>>> macsesh.inject_into_requests()
>>> requests.get('https://en.wikipedia.org/wiki/Taco')  # Uses keychain

Client cert auth:

>>> import macsesh
>>> sesh = macsesh.Session()
>>> response = sesh.get('https://nethack.org', cert='My Identity Cert')

Validating a server

macsesh uses any of the trusted certs from keychains included in the current user's keychain search list, as well as the system roots. Typically, this search list consists of:

  • The user's default keychain at ~/Library/Keychains/login.keychain
  • The system keychain at /Library/Keychains/System.keychain
  • The System Roots keychain at /System/Library/Keychains/SystemRootCertificates.keychain.

Certs in the system roots are implicitly trusted. Certs from other keychains must be marked as trusted for this purpose or they won't be included.

When using macsesh, just leave the requests verify at its default of True and macsesh will do the rest.

Client cert auth

macsesh can also do client cert auth from the keychain, currently only with the SecureTransportAdapter. The other adapter types can do client cert auth as well of course, but they require the identity to be available on the filesystem just like regular requests.

To specify a certificate to use, provide the Common Name of the cert to requests' normal cert argument as in the example above. As the keychain may have multiple certs which match , macsesh performs some additional filtering.

  1. The query does a "subject contains" search with the CN provided, so for exmaple cert='taco' could match a CN of taco truck or taco party.
  2. After the "subject contains" search, macsesh will drop anything that is not an exact string match.
  3. The resulting certs may have been renewed, and the old certs are still in the keychain. macsesh sorts them by "not valid after" date and picks the one with the longest lifespan.

Advanced

Cleanup

If for some reason you want to revert to "normal" requests (probably using certifi), in the same python process, you'll need to remove this module's injected stuff from urllib3 or requests.

Remove the SSLContext if you used any of the Sessions: macsesh.extract_from_urllib3() Clean up after using the "basic" API: macsesh.extract_from_requests()

Any certs added to the keychains after starting a session will not be available. Digging down in and updating the SSLContext is rough; just make a new session if you have this need!

Choosing a session type

macsesh provides three different types of requests Session classes. While we probably only need the Session, the other two are included for posterity since they are interesting and potentially useful.

  1. If in doubt, use Session It uses the securetransport module contributed to urllib3 as a base SSLContext. Pip, for example, uses this on macOS. The securetransport module uses an entirely different SSLContext, using ctypes to connect to the macOS Security framework. macsesh then injects additional code into the urllib3 code to use the keychain instead of conforming to the OpenSSL approach of using paths to files. If you need to do client cert auth from keychain identities, this is the one you want.
  2. KeychainSession uses a custom SSLContext, requests Adapter, and requests Session, and injects the SSLContext into urllib3. The certs for validation are dumped from the keychain and held in memory. The goal of this approach is to use the minimum amount of messing about to achieve cert validation.
  3. SimpleKeychainSession circumvents the normal flow of session startup, and tells the SSLContext to load its trust information up front rather than waiting for a bunch of internal checks to decide the context needs to load the trust store. It uses the same method as the KeychainSession and functionally shouldn't be any different.

What about cert auth for SimpleKeychainSession and

KeychainSession?

I can try implementing looking up and retrieving certs by name for the other "strategies", but I'm not sure how much utility there is for that, as the keys would have to be exportable. At that point, just export them and use regular old requests.

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

MacSesh-0.3.1.tar.gz (7.9 kB view details)

Uploaded Source

Built Distributions

MacSesh-0.3.1-py3.9.egg (18.5 kB view details)

Uploaded Source

MacSesh-0.3.1-py3-none-any.whl (10.3 kB view details)

Uploaded Python 3

File details

Details for the file MacSesh-0.3.1.tar.gz.

File metadata

  • Download URL: MacSesh-0.3.1.tar.gz
  • Upload date:
  • Size: 7.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.62.3 importlib-metadata/4.11.0 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.9.9

File hashes

Hashes for MacSesh-0.3.1.tar.gz
Algorithm Hash digest
SHA256 aa0263441f015bbd146206a9e5b1dfbe27c2f14caa5bf7a6a8defa1178f03b6f
MD5 df27451e0e63be5879717584228ca0cc
BLAKE2b-256 9aac29c2c87482e9e2d54c162c928ac4cce8f0a28b37127017bc9844063a25bc

See more details on using hashes here.

File details

Details for the file MacSesh-0.3.1-py3.9.egg.

File metadata

  • Download URL: MacSesh-0.3.1-py3.9.egg
  • Upload date:
  • Size: 18.5 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.62.3 importlib-metadata/4.11.0 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.9.9

File hashes

Hashes for MacSesh-0.3.1-py3.9.egg
Algorithm Hash digest
SHA256 ae1a259282e3a55af01715f4f8780be7800e094a6e4716233262f5bc655b7065
MD5 de5aef92ee0c35e6e5330d210ce35397
BLAKE2b-256 b21a6b1f2b2acc0ef77fdc2d7295c5d7da0b4ad3d0ea5dcc7d3e4f13f77f1c39

See more details on using hashes here.

File details

Details for the file MacSesh-0.3.1-py3-none-any.whl.

File metadata

  • Download URL: MacSesh-0.3.1-py3-none-any.whl
  • Upload date:
  • Size: 10.3 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/3.8.0 pkginfo/1.8.2 readme-renderer/32.0 requests/2.27.1 requests-toolbelt/0.9.1 urllib3/1.26.8 tqdm/4.62.3 importlib-metadata/4.11.0 keyring/23.5.0 rfc3986/2.0.0 colorama/0.4.4 CPython/3.9.9

File hashes

Hashes for MacSesh-0.3.1-py3-none-any.whl
Algorithm Hash digest
SHA256 c3494f7f0887937ede8a41052380164874aca60a2e2507526311b827f5011c59
MD5 b3ac9589e96e9d82e047eaae72aa5bf3
BLAKE2b-256 e93a7815587b9ac36d5a38c08617a56dbcdd0e541c8184aebc5e10c89f3a363b

See more details on using hashes here.

Supported by

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