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 bymtc.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 bymtc.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 bymtc.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.