tesseract

README

🌳 TesseraCT

TesseraCT is a Certificate Transparency (CT) log implementation. It implements static-ct-api using the Tessera library to store data, and is aimed at running production-grade CT logs.

At the moment, TesseraCT can run on Google Cloud Platform (GCP), Amazon Web Services (AWS), POSIX filesystems, or on vanilla S3+MySQL storage systems with different levels of maturity.

Table of contents

📣 Status
🛣 Roadmap
🕹 Usage
🧪 Public test instances
🗂 Repository structure
🙋 FAQ
:troll: History
🔧 Contributing
📄 License
👋 Contact

📣 Status

TesseraCT is under active development, and will reach alpha in 2025Q3 🚀.

Platform	Architecture	Our use-case	Performance	Binary	Deployment
GCP	Spanner + GCS + MIG	public staging logs	gcp	gcp	doc
GCP	Spanner + GCS + CloudRun	continuous integration	N/A	gcp	example
GCP	Spanner + GCS + GCE VM	codelab	gcp	gcp	doc
AWS	RDS + S3 + ECS	continuous integration	N/A	aws	example
AWS	RDS + S3 + EC2 VM	codelab	aws	aws	doc
POSIX	ZFS + VM	codelab, continuous integration	posix	posix	doc
Vanilla S3+MySQL	MinIO + MySQL + VM	one-off test	S3+MySQL	aws	doc

These deployments come with different levels of maturity depending on our use-case. Our primary focus so far has been on the GCP with Spanner + GCS + MIG configuration since we use it for our public staging logs. However, we believe all implementations are correct, and we'd love to hear your feedback on any of these implementations.

Read the FAQ to understand why we chose these platforms.

🛣 Roadmap

Our objective is to allow log operators to run production static-ct-api CT logs starting with temporal shards covering 2026 onwards.

At the moment, we are aiming for Beta in 2025Q3, and GA by the end of 2025.

#	Step	Status	Target release
1	Storage for GCP, AWS, and POSIX	✅	alpha
2	Lightweight CT compatible x509 fork	✅	alpha
3	static-ct-api APIs	✅	alpha
4	Basic Antispam	✅	alpha
5	Monitoring and metrics	✅	alpha
6	Secure key management #219	🔨	beta
7	Witnessing #443	🔨	beta
8	Structured logging #346	🔨	beta
9	CCADB based root update #212	🔨	beta
10	Client	🔨	1.0
11	Stable APIs	🔨	1.0

Current public library APIs are unlikely to change in any significant way, however the API is subject to minor breaking changes until we tag 1.0. Any feedback is welcome.

If you're interested in additional features, get in touch.

🕹 Usage

Getting Started

The most hands-on place to start is with one of the codelabs below. These codelabs will guide you through bringing up your own test TesseraCT deployment:

• GCP
• AWS
• POSIX
• S3+MySQL

We also run public test instances that you can interact with using static-ct-api.

You can also have a look at the main.go files under /cmd/tesseract/ to understand how to build a TesseraCT server.

Last, you can explore our documentation.

Running on a different platform

TesseraCT can theoretically run on any platform Tessera supports.

If you'd still like to run TesseraCT on a different platform that Tessera supports, have a look at Tessera's Getting Started guide, TesseraCT's main.go files under /cmd/tesseract/ and the architecture documentation.

We'd love to know what platform you're interested in using, come and talk to us!

🧪 Public test instances

The following logs are available for testing. These logs run in a staging environment and should not used for production use cases. They accept chains rolling up to roots trusted by major root programs.

These logs have been named after La Grande Arche de la Défense (The Great Arche of the Defense), a building in the outskirts of Paris, designed by Johan Otto von Spreckelsen and Erik Reitzel to celebrate the 200th anniversary of the French Revolution. It is shaped like a tesseract, and is covered with tiled (transparent!) windows.

"description": "Google staging 'Arche2025h1'",
"log_id": "v4vLUgreyaZJbsQJYM1zN+YKJbfu0ef6TGSJJcd2h2s=",
"key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEn7khjUQH1H3NJ/C8QmmBgzoNTptlH6hT5bgiQ6mQcYYg5KZoe4ZK4xCszXu4NH5NiLaDH0wHKsvg3RIQ+TTaag==",
"submission_url": "https://arche2025h1.staging.ct.transparency.dev/",
"monitoring_url": "https://storage.googleapis.com/static-ct-staging-arche2025h1-bucket/",
"mmd": 60,
"temporal_interval": {
  "start_inclusive": "2025-01-01T00:00:00Z",
  "end_exclusive": "2025-07-01T00:00:00Z"
}

"description": "Google staging 'Arche2025h2'",
"log_id": "L2UYNygi6ysgrNQ0osu5ivLTWAzifbdx/LfHcYDhOi4=",
"key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEGbSp66Dmq0b3QILTYVpwRgMV9v4tYG2jqBFeWUyg46yW7QL0KbSOUZjN4PYK5dPxfamSkp8Z0JEGL7IA5X9aMg==",
"submission_url": "https://arche2025h2.staging.ct.transparency.dev/",
"monitoring_url": "https://storage.googleapis.com/static-ct-staging-arche2025h2-bucket/",
"mmd": 60,
"temporal_interval": {
  "start_inclusive": "2025-07-01T00:00:00Z",
  "end_exclusive": "2026-01-01T00:00:00Z"
}

"description": "Google staging 'Arche2026h1'",
"log_id": "J+sqNJffaHpkC2Q4TkhW/Nyj6H+NzWbzTtbxvkKB7fw=",
"key": "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEZ+3YKoZTMruov4cmlImbk4MckBNzEdCyMuHlwGgJ8BUrzFLlR5U0619xDDXIXespkpBgCNVQAkhMTTXakM6KMg==",
"submission_url": "https://arche2026h1.staging.ct.transparency.dev/",
"monitoring_url": "https://storage.googleapis.com/static-ct-staging-arche2026h1-bucket/",
"mmd": 60,
"temporal_interval": {
  "start_inclusive": "2026-01-01T00:00:00Z",
  "end_exclusive": "2026-07-01T00:00:00Z"
}

🗂 Repository structure

This repository contains:

1. Binaries: TesseraCT and auxiliary tools
2. Deployment configs: purely informative, DO NOT depend on them
3. Libraries: enabling the building of static-ct-api logs with Tessera: ctlog, storage, (internal)
4. Documentation
   • Configuration
     • GCP
     • AWS and S3+MySQL
     • POSIX
   • Performance
   • Architecture
   • Deployment
   • Codelabs
     • GCP
     • AWS
     • POSIX
     • S3+MySQL
   • Chain parsing with lax509

🙋 FAQ

TesseraWhat?

TesseraCT is the concatenation of Tessera and CT (Certificate Transparency), which also happens to be a 4-dimensional hypercube.

What's the difference between Tessera and TesseraCT?

Tessera is a Go library for building tile-based transparency logs (tlogs) on various deployment backends. TesseraCT is a service using the Tessera library with CT specific settings to implement Certificate Transparency logs complying with static-ct-api. TesseraCT supports a subset of Tessera's backends. A TesseraCT serving stack is composed of:

• one or multiple instances of a TesseraCT binary using the Tessera library, providing static-ct-api submission APIs
• Tessera's backend infrastructure
• static-ct-api monitoring APIs via direct access to Tessera's log storage system
• a minor additional storage system for chain issuers

Why these platforms?

After chatting with various CT log operators, we decided to focus on GCP, AWS, and to explore non-cloud-native deloyments. We welcome feedback on these and requests for additional backend implementations. If you have any, come and talk to us!

Which platform should I use?

graph TD
    A[Are you already running on:] --> B{GCP?}
    B -- Yes --> C[<a href="https://github.com/transparency-dev/tesseract/blob/main/docs/architecture.md#google-cloud-platform-gcp">Use TesseraCT for GCP</a>]
    B -- No --> D{AWS?}
    D -- Yes --> E[<a href="https://github.com/transparency-dev/tesseract/blob/main/docs/architecture.md#amazon-web-services-aws">Use TesseraCT for AWS</a>]
    D -- No --> F{S3 & MySQL on-prem?}
    F -- Yes --> G[<a href="https://github.com/transparency-dev/tesseract/blob/main/docs/architecture.md#vanilla-s3mysql">Use TesseraCT for Vanilla S3+MySQL</a>]
    F -- No --> H[<a href="https://github.com/transparency-dev/tesseract/blob/main/docs/architecture.md#posix-filesystems">Use TesseraCT for POSIX</a>]
    G -- I cannot --> I
    H -- I cannot --> I[<a href="https://github.com/transparency-dev/tesseract/blob/main/README.md#wave-contact">Get in touch</a>]

:troll: History

TesseraCT is the successor to Trillian's CTFE. It was built upon its codebase, and introduces these main changes:

• API: TesseraCT implements static-ct-api rather than RFC6962.
• Backend implementation: TesseraCT uses Tessera rather than Trillian. This means that TesseraCT integrates entries faster, is cheaper to maintain, requires running a single binary rather than 3, and does not need additional services for leader election.
• Single tenancy: One TesseraCT instance serves a single CT log, as opposed to the CTFE which could serve multiple logs per instance. To run multiple logs, simply bring up multiple independent TesseraCT stacks. For reliability, each log can still be served by multiple TesseraCT instances.
• Configuration: TesseraCT is fully configured using flags, and does not need a proto config anymore.
• Chain parsing: TesseraCT uses internal/lax509 to validate certificate chains. It is built on top of Go's standard crypto/x509 library, with a minimal set of CT specific enhancements. It does not use the full crypto/x509 fork that the CTFE was using. This means that TesseraCT can benefit from the good care and attention given to crypto/x509. As a result, a very small number of chains do not validate anymore, head over to internal/lax509's README for additional details.

🔧 Contributing

See CONTRIBUTING.md for details.

📄 License

This repo is licensed under the Apache 2.0 license, see LICENSE for details.

👋 Contact

Are you interested in running a TesseraCT instance? Do you have a feature request? you can find us here:

• GitHub issues
• Slack (invitation)
• Mailing list

Documentation

Index

• func NewLogHandler(ctx context.Context, origin string, signer crypto.Signer, ...) (http.Handler, error)
• type ChainValidationConfig

Functions

func NewLogHandler

func NewLogHandler(ctx context.Context, origin string, signer crypto.Signer, cfg ChainValidationConfig, cs storage.CreateStorage, httpDeadline time.Duration, maskInternalErrors bool, pathPrefix string) (http.Handler, error)

NewLogHandler creates a Tessera based CT log pluged into HTTP handlers.

HTTP server handlers implement static-ct-api submission APIs: https://c2sp.org/static-ct-api#submission-apis. It populates the data served via monitoring APIs (https://c2sp.org/static-ct-api#submission-apis) but it _does not_ implement monitoring APIs itself. Monitoring APIs should be served independently, either through the storage's system serving infrastructure directly (GCS over HTTPS for instance), or with an independent serving stack of your choice.

Types

type ChainValidationConfig

type ChainValidationConfig struct {
	// RootsPEMFile is the path to the file containing root certificates that
	// are acceptable to the log. The certs are served through get-roots
	// endpoint.
	RootsPEMFile string
	// RejectExpired controls if true then the certificate validity period will be
	// checked against the current time during the validation of submissions.
	// This will cause expired certificates to be rejected.
	RejectExpired bool
	// RejectUnexpired controls if TesseraCT rejects certificates that are
	// either currently valid or not yet valid.
	// TODO(phboneff): evaluate whether we need to keep this one.
	RejectUnexpired bool
	// ExtKeyUsages lists Extended Key Usage values that newly submitted
	// certificates MUST contain. By default all are accepted. The
	// values specified must be ones known to the x509 package, comma separated.
	ExtKeyUsages string
	// RejectExtensions lists X.509 extension OIDs that newly submitted
	// certificates MUST NOT contain. Empty by default. Values must be
	// specificed in dotted string form (e.g. "2.3.4.5").
	RejectExtensions string
	// NotAfterStart defines the start of the range of acceptable NotAfter
	// values, inclusive.
	// Leaving this unset implies no lower bound to the range.
	NotAfterStart *time.Time
	// NotAfterLimit defines the end of the range of acceptable NotAfter values,
	// exclusive.
	// Leaving this unset implies no upper bound to the range.
	NotAfterLimit *time.Time
	// AcceptSHA1 specifies whether cert chains using SHA-1 based signing algorithms
	// are allowed.
	// CAUTION: This is a temporary solution and it will eventually be removed.
	// DO NOT depend on it.
	AcceptSHA1 bool
}

ChainValidationConfig contains parameters to configure chain validation.