From 99dabd33dabfe3c6c159cb1a0355b5f97ec78682 Mon Sep 17 00:00:00 2001 From: Philippe Boneff Date: Wed, 26 Aug 2026 15:10:23 +0000 Subject: [PATCH 1/2] [MTC] Improve MTC Log docs --- cmd/mtc/log/README.md | 51 +++++++++++++++++++++++++++++++++ cmd/mtc/log/posix/README.md | 57 +++++++++++++++++++++++++++++++++++-- cmd/mtc/log/posix/main.go | 10 +++---- 3 files changed, 110 insertions(+), 8 deletions(-) create mode 100644 cmd/mtc/log/README.md diff --git a/cmd/mtc/log/README.md b/cmd/mtc/log/README.md new file mode 100644 index 000000000..7fa430f63 --- /dev/null +++ b/cmd/mtc/log/README.md @@ -0,0 +1,51 @@ +# MTC Log Package + +Package `log` provides the core logic and Go API for an MTC +([`draft-ietf-plants-merkle-tree-certs`](https://datatracker.ietf.org/doc/html/draft-ietf-plants-merkle-tree-certs)) +issuance log server using [c2sp.org/mtc-tlog](https://c2sp.org/mtc-tlog). It +does not implement ACME-related features, nor any CA business logic. + +It is meant to be used with a Tessera log. At the moment, it only works with a +[POSIX storage backend](/storage/posix/). + +## Functionalities + +This library: + - Logs + [`TBSCertificateLogEntry`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#log-entries) + and returns a corresponding + [`MTCProof`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certificate-format) + including cosignatures. + - Pushes entries to mirrors and serves checkpoints with their cosignatures. + - Publishes active [landmarks](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#section-6.4.3). + - Builds inclusion proofs to active landmark sizes. + + +## API Surface + +### Configuration + +- **`NewMTCLog(ctx, appender, opts)`**: Initializes an `MTCLog` instance backed + by a Tessera appender and configured with [`*Options`](./mtc.go). +- **`NewOptions()`**: Creates an `Options` builder to configure storage + backends, landmark intervals, maximum certificate lifetime, signers, and + subtree witness groups. Default options can be customized with corresponding + `With*` methods defined in [`mtc.go`](./mtc.go), such as + `WithMaxCertLifetime`. + +### MTC APIs + +- **`AddTBS(ctx, tbs)`**: Validates and appends a [`TBSCertificateLogEntry`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#log-entries) + to the log. Returns an [`AddTBSRsp`](https://github.com/search?q=repo%3Atransparency-dev%2Ftessera+symbol%3AAddTBSRsp+path%3Amtc.go&type=code) + containing the assigned leaf `Index` and a serialized [`MTCProof`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certificate-format) + (with subtree signatures) to construct a standalone certificate. +- **`ProofToLandmark(ctx, index)`**: Generates a TLS-encoded landmark-relative + [`MTCProof`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certificate-format) + for the given entry index. If the enclosing landmark is still pending + publication, returns a retry duration. + +### Reads + +- Log data is served as a [tlog-tiles](https://c2sp.org/tlog-tiles) log, + through the APIs of the Tessera storage driver used. +- Landmarks are served through the same read APIs, at `/landmarks`. diff --git a/cmd/mtc/log/posix/README.md b/cmd/mtc/log/posix/README.md index 86c06d9f4..7d3057372 100644 --- a/cmd/mtc/log/posix/README.md +++ b/cmd/mtc/log/posix/README.md @@ -1,14 +1,65 @@ # POSIX MTC Log -This directory contains an MTC (`draft-ietf-plants-merkle-tree-certs`) issuance -log server backed by Tessera's POSIX storage implementation. +This directory contains an MTC ([`draft-ietf-plants-merkle-tree-certs`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html)) +issuance log server backed by [Tessera's POSIX storage implementation](/storage/posix/). + +This document contains [Documentation](#documentation), and a [Codelab](#codelab). + +A matching POSIX Mirror implementation is available at [/cmd/mtc/mirror/posix](/cmd/mtc/mirror/posix). > [!WARNING] > This binary and the internal packages it uses are still under active > development, and should be considered experimental and not > production-ready. They remain outside the SemVer policy. -## Running +## Documentation + +### Main functionalities + +See [mtc/log/README.md](../). + +### API + +#### HTTP Endpoints + +The log server exposes the following HTTP endpoints: + +- `POST /add-tbs`: Submits a JSON-encoded [`TBSCertificateLogEntry`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#log-entries) + to append to the log. Returns HTTP 201 Created with a JSON-encoded + [`AddTBSRsp`](https://github.com/search?q=repo%3Atransparency-dev%2Ftessera+symbol%3AAddTBSRsp+path%3Amtc.go&type=code) + containing the assigned entry `index` and a TLS-encoded [`MTCProof`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certificate-format), + with subtree signatures. +- `GET /proof-to-landmark?index=`: Fetches a landmark-relative + [`MTCProof`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certificate-format) + for the given entry index. Returns HTTP 200 OK with a [`ProofToLandmarkRsp`](https://github.com/search?q=repo%3Atransparency-dev%2Ftessera+symbol%3AProofToLandmarkRsp+path%3Amtc.go&type=code), + containing a TLS-encoded [`MTCProof`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certificate-format), + or HTTP 202 Accepted with a `Retry-After` header if an enclosing landmark has + not been published yet. + +#### Log data and Landmarks + +Log data (checkpoints, tiles, leaves) and the `/landmarks` resource are +accessible through the underlying POSIX storage filesystem. + +### Configuration + +Inspect the [`main.go`](./main.go) file for a full list of flags. + +Notable MTC-related flags are: + +- `landmark_interval`: Interval between publishing landmarks. If 0, defaults + to CQRP recommended interval for max_cert_lifetime. +- `ca_id`: The CA ID as per [draft-ietf-plants-merkle-tree-certs Section 5.1](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html#name-certification-authority-ide) + (e.g. 32473.106) +- `log_number`: The issuance log number (strictly positive). +- `private_key`: Location of private key file. If unset, uses the contents of + the LOG_PRIVATE_KEY environment variable. +- `max_cert_lifetime`: Maximum validity duration allowed for submitted + certificate entries. +- `mirror_policy`: File containing the mirror policy in tlog-policy format. If + unset, no mirroring will be performed. + +## Codelab These instructions will help you bring up an MTC POSIX log, and send entries to it using the [Hammer](../hammer/hammer.go). If you'd like, you can also run a diff --git a/cmd/mtc/log/posix/main.go b/cmd/mtc/log/posix/main.go index 6236b1fa1..3353e75dc 100644 --- a/cmd/mtc/log/posix/main.go +++ b/cmd/mtc/log/posix/main.go @@ -43,7 +43,6 @@ var ( // Tessera settings storageDir = flag.String("storage_dir", "", "Path to root of log storage.") checkpointInterval = flag.Duration("checkpoint_interval", 1500*time.Millisecond, "Interval between publishing checkpoints when the log has grown") - landmarkInterval = flag.Duration("landmark_interval", 0, "Interval between publishing landmarks. If 0, defaults to CQRP recommended interval for max_cert_lifetime.") batchMaxSize = flag.Uint("batch_max_size", tessera.DefaultBatchMaxSize, "Maximum number of entries to process in a single sequencing batch.") batchMaxAge = flag.Duration("batch_max_age", tessera.DefaultBatchMaxAge, "Maximum age of entries in a single sequencing batch.") awaiterPollInterval = flag.Duration("awaiter_poll_interval", 100*time.Millisecond, "Interval between checkpoint polls by the publication awaiter.") @@ -56,10 +55,11 @@ var ( clientHTTPMaxIdlePerHost = flag.Int("client_http_max_idle_per_host", 10, "Maximum number of idle HTTP connections per host for outgoing requests.") // CA settings - caID = flag.String("ca_id", "32473.106", "The CA ID as per draft-ietf-plants-merkle-tree-certs section 5.1 (e.g. 32473.106)") - logNumber = flag.Uint64("log_number", 1, "The issuance log number (strictly positive)") - privKeyFile = flag.String("private_key", "", "Location of private key file. If unset, uses the contents of the LOG_PRIVATE_KEY environment variable.") - maxCertLifetime = flag.Duration("max_cert_lifetime", log.DefaultMaxCertLifetime, "Maximum validity duration allowed for submitted certificate entries.") + landmarkInterval = flag.Duration("landmark_interval", 0, "Interval between publishing landmarks. If 0, defaults to CQRP recommended interval for max_cert_lifetime.") + caID = flag.String("ca_id", "32473.106", "The CA ID as per draft-ietf-plants-merkle-tree-certs Section 5.1 (e.g. 32473.106)") + logNumber = flag.Uint64("log_number", 1, "The issuance log number (strictly positive)") + privKeyFile = flag.String("private_key", "", "Location of private key file. If unset, uses the contents of the LOG_PRIVATE_KEY environment variable.") + maxCertLifetime = flag.Duration("max_cert_lifetime", log.DefaultMaxCertLifetime, "Maximum validity duration allowed for submitted certificate entries.") ) func main() { From 5e12147d53d955b6939ab67b13c1a56f75352b94 Mon Sep 17 00:00:00 2001 From: Philippe Boneff Date: Wed, 26 Aug 2026 17:52:47 +0000 Subject: [PATCH 2/2] comments --- cmd/mtc/log/README.md | 8 ++++---- cmd/mtc/log/posix/README.md | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/cmd/mtc/log/README.md b/cmd/mtc/log/README.md index 7fa430f63..4c90329dc 100644 --- a/cmd/mtc/log/README.md +++ b/cmd/mtc/log/README.md @@ -27,10 +27,10 @@ This library: - **`NewMTCLog(ctx, appender, opts)`**: Initializes an `MTCLog` instance backed by a Tessera appender and configured with [`*Options`](./mtc.go). -- **`NewOptions()`**: Creates an `Options` builder to configure storage - backends, landmark intervals, maximum certificate lifetime, signers, and - subtree witness groups. Default options can be customized with corresponding - `With*` methods defined in [`mtc.go`](./mtc.go), such as +- **`NewOptions()`**: Creates an `Options` builder to configure the landmarks + storage backends, landmark intervals, maximum certificate lifetime, signers, + and subtree witness groups. Default options can be customized with + corresponding `With*` methods defined in [`mtc.go`](./mtc.go), such as `WithMaxCertLifetime`. ### MTC APIs diff --git a/cmd/mtc/log/posix/README.md b/cmd/mtc/log/posix/README.md index 7d3057372..79ff40fcf 100644 --- a/cmd/mtc/log/posix/README.md +++ b/cmd/mtc/log/posix/README.md @@ -3,7 +3,7 @@ This directory contains an MTC ([`draft-ietf-plants-merkle-tree-certs`](https://ietf-plants-wg.github.io/merkle-tree-certs/draft-ietf-plants-merkle-tree-certs.html)) issuance log server backed by [Tessera's POSIX storage implementation](/storage/posix/). -This document contains [Documentation](#documentation), and a [Codelab](#codelab). +This document contains [Documentation](#documentation) and a [Codelab](#codelab). A matching POSIX Mirror implementation is available at [/cmd/mtc/mirror/posix](/cmd/mtc/mirror/posix). @@ -16,7 +16,7 @@ A matching POSIX Mirror implementation is available at [/cmd/mtc/mirror/posix](/ ### Main functionalities -See [mtc/log/README.md](../). +See [mtc/log/README.md](../README.md). ### API @@ -53,7 +53,7 @@ Notable MTC-related flags are: (e.g. 32473.106) - `log_number`: The issuance log number (strictly positive). - `private_key`: Location of private key file. If unset, uses the contents of - the LOG_PRIVATE_KEY environment variable. + the `LOG_PRIVATE_KEY` environment variable. - `max_cert_lifetime`: Maximum validity duration allowed for submitted certificate entries. - `mirror_policy`: File containing the mirror policy in tlog-policy format. If