Certified

An idiomatic framework for using certificates and cookies (macaroons/biscuits) within python web API-s.

We make the following design choices:

• mTLS - mutual transport layer certificates (x509) authenticate client and server to one another

• scopes - clients can "prove" they have access to a scope (e.g. admin) by including it within their 'certificatePolicies' at the handshake phase

• tokens/cookies - we rely on the datalog model of biscuits to exchange cookies that carry authorization proofs. Tokens, not certificates are used to delegate authorization.

• symmetry - symmetric ideas are used for setting up mutual identity verification (authentication) between client and server. This allows servers to act as clients in complex workflows, and clients to act as servers to run callbacks.

• key management - we prescribe a file layout for these. Key file-names serve as a short-hand for referencing a given client/server. See docs/keys.

How do I know who originated an API request -- what organization they come from, and what kinds of organizational policies they have been asked to follow?

How can I consistently apply my own site's security policy to API actions?

And -- the big question -- how can I, as a client using an API, obtain, manage, and send these credentials to servers I interact with?

The certified package has you covered.

See documentation for explanations and howto-s.

License

Certified is available under a 3-clause BSD-style license, available in the file LICENSE.

Portions of certified (as marked in the code) are derived from python-trio/trustme, and are made available under the MIT license -- as reproduced within those files.

Installation

As a user, install with

pip install .

For development

As a developer, install with:

make install

Add new dependencies using, e.g.:

uv add pydantic          # run-time dependency
uv add --optional docs mkdocs-material # documentation-generation dep.
uv add --dev mypy        # development dependency

Run tests with:

uv run mypy .
uv run pytest

Preview the documentation with:

uv run mkdocs serve &

Docs

Documentation was built using this guide -- which comes highly recommended.

Roadmap

• v0.8.1

  • use base64-encoded DER for storing keys in yaml files.

  • select certificate chain to send to server based on server name (test server configs.)

• v0.9.0

  • better logging

  • simpler introduction methodology

  • readthedocs integration

  • biscuit examples

• v0.10.0

  • more feature-ful 'message' function

  • add docs on how to use openssl to decode certificate contents

  • configurable biscuit_sec.Authorizor-based biscuit auth

  • better user experience with add-intro (now adds services)

  • better user experience with add-service (will look for json with ca_cert)

  • better user experience setting up org-level microservice certified set-org

• v1.0.0

  • replace httpx with aiohttp (has better test client/server support).

  • change servers to services where appropriate

• v1.1.0

  • fix biscuit_auth dependency version and change to uv packaging

• v1.2.0

  • CI and better test coverage

  • better documentation, esp. for known_services

  • support for --key_type secp256r1

• v1.2.1

  • interface for showing configuration contents

  • throw warning if id.crt does not contain the server's hostname in SAN (since this will usually result in a connection error from SSL)

• v 1.3.0

  • more helpful error messages

  • Demo presentations and lessons learned

  • CLI interface for biscuit creation / validation

• v1.4.0

  • add certificate serial numbers

  • save a log of all certificates signed and revoked utilize CSR-s? https://cryptography.io/en/latest/x509/tutorial/#creating-a-certificate-signing-request-csr

  • support nng TLS sockets

  • support GRPC library

• v1.5.0

  • key rotation features and docs

Technology to watch

• hardware certificate implementations (plug-ins?)

• OAuth2 integrations / biscuit adoption

List of Useful Microservices

• https://gitlab.com/frobnitzem/planner_api

• https://github.com/frobnitzem/psik_api

• https://gitlab.com/frobnitzem/signer

References

[openssl]: https://x509errors.org/guides/openssl "OpenSSL: TLS Guide" -- building a custom validator in C

Use of TLS/certs in services

more on custom attributes using openssl command

• https://stackoverflow.com/questions/36007663/how-to-add-custom-field-to-certificate-using-openssl

• https://stackoverflow.com/questions/17089889/openssl-x509v3-extended-key-usage -- config. file attributes

• https://superuser.com/questions/947061/openssl-unable-to-find-distinguished-name-in-config/1118045 -- use a complete config

More on JWT/cookies/macaroons/biscuits

o