Merkle Tree Certificate Reference Implementation: API documentations

Design Philosophy

The primary role of this project is to be the reference implementation of the Merkle Tree Certificate. As such, all the code in this project is designed to be (hopefully) easily transcribed into other languages. This is why this project is written in Python instead of a lower level language. While this code is reasonably performant, due to the nature of Python, it is most likely to be many orders of magnitudes slower than an implementation in C or rust.

There is a tiny serialization and deserialization framework written to facilitate this goal. All of them are implemented in the mtc.base module and documented in Base Parsers. However, they are very specific to Python and employs a fair amount of pythonic hacks. If you aren’t interested in the Python-specific part, you can mostly just ignore them.

Dependencies

The only dependency of this project is cryptography.

High level functions

This package exposes the following high-level functions. If you only want to use the API from this library, these are all you need.

mtc.assertion.create_assertion(subject_info: bytes, *, ipv4_addrs: list[str] | tuple[str, ...] | None = None, ipv6_addrs: list[str] | tuple[str, ...] | None = None, dns_names: list[str] | tuple[str, ...] | None = None, dns_wild_cards: list[str] | tuple[str, ...] | None = None) → Assertion[source]

Creates an assertion as defined in section 4 of the specification.

Parameters:

  • subject_info – The subject info from TLS. This is most likely the public key for the subject.

  • ipv4_addrs – A list of possibly empty IPv4 address.

  • ipv6_addrs – A list of possibly empty IPv6 address.

  • dns_names – A list of possibly empty DNS names.

  • dns_wild_cards – A list of possibly empty DNS wildcards.

Returns:

an Assertion object

mtc.tree.create_merkle_tree(assertions: Sequence[Assertion], issuer_id: bytes, batch_number: int) → list[list[SHA256Hash]][source]

Build Merkle tree as defined by section 5.4.1 of the specification

Parameters:

  • assertions – a list of assertions to create merkle tree for

  • issuer_id – the issuer id, in bytes

  • batch_number – the batch number to create merkle tree for

Returns:

A NodesList that can be passed into other functions

mtc.certificate.create_merkle_tree_proofs(nodes: NodesList, issuer_id: bytes, batch_number: int, index: int) → Proof[source]

Creates all the proofs for a particular batch.

Parameters:

  • nodes – a NodesList as returned by mtc.tree.create_merkle_tree()

  • issuer_id – the issuer id, in bytes

  • batch_number – the batch number to create proofs for

Returns:

a Proof for the assertion

mtc.certificate.create_merkle_tree_proof(nodes: NodesList, issuer_id: bytes, batch_number: int, number_of_assertions_in_batch: int) → list[Proof][source]

Creates a single Proof for a particular batch.

Parameters:

  • nodes – a NodesList as returned by mtc.tree.create_merkle_tree()

  • issuer_id – the issuer id, in bytes

  • batch_number – the batch number to create a proof for

  • index – the index of the assertion in the batch

Returns:

a Proof for the assertion

mtc.certificate.create_signed_validity_window(nodes: NodesList, issuer_id: bytes, batch_number: int, private_key: ed25519.Ed25519PrivateKey, previous_validity_window: SignedValidityWindow | None = None)[source]
Parameters:

  • nodes – a NodesList as returned by mtc.tree.create_merkle_tree()

  • issuer_id – The issuer id, in bytes

  • batch_number – The batch number to be certified

  • private_key – The private key of the issuer

  • previous_validity_window – Optional. The validity window of the previous batch. This value must be None if the batch number is 0, and must not be None if the batch number is greater than 0. Additionally, the previous validity window must be signed using the same private key.

Returns:

a SignedValidityWindow for the batch

mtc.certificate.create_bikeshed_certificate(assertion: Assertion, proof: Proof)[source]

Creates a BikeshedCertificate

mtc.certificate.verify_certificate(certificate: BikeshedCertificate, signed_validity_window: SignedValidityWindow, issuer_id_bytes: bytes, public_key: Ed25519PublicKey)[source]

Verifies the certificate. Returns None on success. Raises ValueError if something is improperly formatted. Raises cryptography.exceptions.InvalidSignature if the signature on the validity window cannot be verified.

Parameters:

  • certificate – The certificate to be validated

  • signed_validity_window – The SignedValidityWindow currently in effect

  • issuer_id_bytes – The issuer id, in bytes

  • public_key – The public key of the issuer

Returns:

None

Interfaces

To learn more about the internal interfaces, check out Interfaces.