diff --git a/cmd/mtc/log/posix/README.md b/cmd/mtc/log/posix/README.md index dbadffb1d..86c06d9f4 100644 --- a/cmd/mtc/log/posix/README.md +++ b/cmd/mtc/log/posix/README.md @@ -3,14 +3,20 @@ This directory contains an MTC (`draft-ietf-plants-merkle-tree-certs`) issuance log server backed by Tessera's POSIX storage implementation. -> [!WARNING] This binary and the internal packages it uses are still under -> active development, and should be considered experimental and not +> [!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 +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 +[Mirror](../../mirror/) alongside this log, and configure the log to use it. + ### Keys +#### Log Key Pair You will need an ML-DSA key pair to be used to sign log checkpoints. You can generate ML-DSA key pairs in the correct `vkey` format with the [`generate_keys`](https://github.com/transparency-dev/witness/blob/main/cmd/generate_keys/main.go) @@ -28,14 +34,86 @@ go run github.com/transparency-dev/witness/cmd/generate_keys@main \ --out_pub /tmp/mtc.pub ``` -> [!WARNING] Ensure that these keys are stored somewhere safe, and not in a -> location which could accidentally be made public when exporting the log data. +> [!WARNING] +> Ensure that these keys are stored somewhere safe, and not in a location +> which could accidentally be made public when exporting the log data. > If you're running this server in production, this key MUST be HSM-backed as > per Chrome's draft CQRP policy. -### Starting the log server +#### Mirror & Witness Cosigner Keys (Optional for Mirroring) +If you are running an MTC mirror alongside the log, you will also need a +separate cosigner key pairs for the mirror service: + +```bash +go run github.com/transparency-dev/witness/cmd/generate_keys@main \ + --mldsa \ + --origin "oid/1.3.6.1.4.1.32473.312202" \ + --out_priv /tmp/mirror.sec \ + --out_pub /tmp/mirror.pub +``` + +### Running with an MTC Mirror + +To run the log alongside an MTC mirror with a policy such that the log waits +for the mirror to catch up before publishing checkpoints: + +#### 1. Create the Mirror Configuration +The mirror requires a configuration file identifying the log to accept requests +from: + +```bash +cat < /tmp/mirror_config +logs/v0 + +vkey $(cat /tmp/mtc.pub) +origin oid/1.3.6.1.4.1.32473.106.0.1 +EOF +``` + +#### 2. Start the Mirror Server +Start the POSIX mirror server on port 6963: + +```bash +go run ./cmd/mtc/mirror/posix \ + --listen_addr="localhost:6963" \ + --storage_dir="/tmp/mtcmirror" \ + --config_path="/tmp/mirror_config" \ + --mirror_cosigner_path=/tmp/mirror.sec \ + --slog_level=-4 +``` + +#### 3. Create the Mirror Policy +The log uses a [c2sp.org/tlog-policy](https://c2sp.org/tlog-policy) file to +express the cosigner quorum to be reached. With this policy configured, the log +will send each new checkpoint and entries to the mirror. It will wait for its +cosignature before publishing a new checkpoint. It will also request a subtree +signature from them, which it includes in `AddTBS()` responses. + +```bash +cat < /tmp/mirror_policy +witness w1 $(cat /tmp/mirror.pub) http://localhost:6963/ +group g1 all w1 +quorum g1 +EOF +``` + +#### 4. Start the Log Server with Mirror Policy +Start the log server configured with `--mirror_policy`: + +```bash +go run ./cmd/mtc/log/posix \ + --listen_addr="localhost:6962" \ + --storage_dir="/tmp/mtclog" \ + --ca_id="32473.106" \ + --log_number=1 \ + --private_key=/tmp/mtc.sec \ + --mirror_policy="/tmp/mirror_policy" \ + --slog_level=-4 +``` + +### Running Standalone (Without Mirror) -An example command for starting the server is given below: +If running without a mirror or witness policy, start the log server with: ```bash go run ./cmd/mtc/log/posix \