torchwood

package module
v0.9.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Feb 2, 2026 License: BSD-3-Clause Imports: 28 Imported by: 7

README

Torchwood

The Torchwood repository is a collection of open-source tooling for tlogs.

Documentation

Overview

Package torchwood implements a tlog client and various c2sp.org/signed-note, c2sp.org/tlog-cosignature, c2sp.org/tlog-checkpoint, and c2sp.org/tlog-tiles functions, including extensions to the golang.org/x/mod/sumdb/tlog and golang.org/x/mod/sumdb/note packages.

Index

Constants

View Source 
const TileHeight = 8
View Source 
const TileWidth = 1 << TileHeight

Variables

This section is empty.

Functions

func AppendTileEntry added in v0.6.0 

func AppendTileEntry(tile []byte, entry []byte) ([]byte, error)

AppendTileEntry appends the given entry to the entry bundle, according to c2sp.org/tlog-tiles.

func CheckHash added in v0.6.0 

func CheckHash(p HashProof, t int64, th tlog.Hash, i int64, h tlog.Hash) error

CheckHash verifies that p is a valid proof that the tree of size t with hash th has an i'th hash with hash h.

func CosignatureTimestamp 

func CosignatureTimestamp(sig note.Signature) (int64, error)

CosignatureTimestamp returns the timestamp of the cosignature, which is the time at which the witness signed the checkpoint, in seconds since the Unix epoch.

Witnesses can re-sign a checkpoint, but only if it's for the latest tree they have seen. Thus, the timestamp can be used to determine if a checkpoint is fresh.

func FormatProof added in v0.9.0 

func FormatProof(idx int64, p tlog.RecordProof, signedCheckpoint []byte) []byte

FormatProof formats a tlog record inclusion proof (a "spicy signature") for the record at index idx with proof p and signed checkpoint signedCheckpoint.

The returned byte slice is encoded according to c2sp.org/tlog-proof@v1.

func FormatProofWithExtraData added in v0.9.0 

func FormatProofWithExtraData(idx int64, extra []byte, p tlog.RecordProof, signedCheckpoint []byte) []byte

FormatProofWithExtraData formats a tlog record inclusion proof (a "spicy signature") for the record at index idx with proof p and signed checkpoint signedCheckpoint, including extra data.

The returned byte slice is encoded according to c2sp.org/tlog-proof@v1.

func NewVerifierFromSigner 

func NewVerifierFromSigner(skey string) (note.Verifier, error)

NewVerifierFromSigner constructs a new c2sp.org/signed-note note.Verifier from an encoded Ed25519 signer key, the same input as note.NewSigner.

func ParseTilePath 

func ParseTilePath(path string) (tlog.Tile, error)

ParseTilePath parses a tile coordinate path according to c2sp.org/tlog-tiles.

For the go.dev/design/25530-sumdb scheme, use tlog.ParseTilePath. For the c2sp.org/static-ct-api scheme, use filippo.io/sunlight/ParseTilePath.

func ProofExtraData added in v0.9.0 

func ProofExtraData(proof []byte) ([]byte, error)

ProofExtraData extracts the extra data from a tlog proof encoded according to c2sp.org/tlog-proof@v1. If no extra data is present, it returns an error.

The extra data is unauthenticated and must not be trusted.

func ReadSumDBEntry added in v0.6.0 

func ReadSumDBEntry(tile []byte) (entry []byte, rh tlog.Hash, rest []byte, err error)

ReadSumDBEntry splits the next entry from a tile according to the go.dev/design/25530-sumdb format, for use with WithCutEntry.

func ReadTileEntry added in v0.6.0 

func ReadTileEntry(tile []byte) (entry, rest []byte, err error)

ReadTileEntry reads the next entry from the entry bundle according to c2sp.org/tlog-tiles, and returns the remaining data in the tile.

func RightEdge 

func RightEdge(n int64) []int64

RightEdge returns the stored hash indexes of the right edge of a tree of size n. These are the same hashes that are combined into a tlog.TreeHash and allow producing record and tree proofs for any size bigger than n. See tlog.StoredHashIndex for the definition of stored hash indexes.

func TileHashReaderWithContext added in v0.6.0 

func TileHashReaderWithContext(ctx context.Context, tree tlog.Tree, tr TileReader) tlog.HashReader

TileHashReaderWithContext returns a HashReader that satisfies requests by loading tiles of the given tree.

It is equivalent to tlog.TileHashReader, but passes the ctx argument to the TileReader methods.

func TilePath 

func TilePath(t tlog.Tile) string

TilePath returns a tile coordinate path describing t, according to c2sp.org/tlog-tiles.

For the go.dev/design/25530-sumdb scheme, use tlog.Tile.Path. For the c2sp.org/static-ct-api scheme, use filippo.io/sunlight/TilePath.

If t.Height is not TileHeight, TilePath panics.

func VerifyProof added in v0.9.0 

func VerifyProof(policy Policy, rh tlog.Hash, proof []byte) error

VerifyProof verifies a proof (a "spicy signature" encoded according to c2sp.org/tlog-proof@v1) for a record hash rh (generally produced with tlog.RecordHash).

If the note signatures do not satisfy the provided policy, an error wrapping *note.UnverifiedNoteError is returned. If the proof is valid but does not verify the record hash rh at the given index, a *VerifyRecordError is returned.

Types

type Checkpoint 

type Checkpoint struct {
	Origin string
	tlog.Tree

	// Extension is empty or a sequence of non-empty lines,
	// each terminated by a newline character.
	Extension string
}

A Checkpoint is a tree head to be formatted according to c2sp.org/checkpoint.

A checkpoint looks like this: 

example.com/origin
923748
nND/nri/U0xuHUrYSy0HtMeal2vzD9V4k/BO79C+QeI=

It can be followed by extra extension lines.

func ParseCheckpoint 

func ParseCheckpoint(text string) (Checkpoint, error)

ParseCheckpoint parses a c2sp.org/tlog-checkpoint payload without signatures.

func VerifyCheckpoint added in v0.9.0 

func VerifyCheckpoint(signedCheckpoint []byte, policy Policy) (Checkpoint, *note.Note, error)

VerifyCheckpoint parses and verifies a signed c2sp.org/tlog-checkpoint.

If the note signatures do not satisfy the provided policy, an error wrapping *note.UnverifiedNoteError is returned.

func (Checkpoint) String 

func (c Checkpoint) String() string

type Client added in v0.6.0 

type Client struct {
	// contains filtered or unexported fields
}

Client is a tlog client that fetches and authenticates tiles, and exposes log entries as a Go iterator or by their index.

func NewClient added in v0.6.0 

func NewClient(tr TileReader, opts ...ClientOption) (*Client, error)

NewClient creates a new Client that fetches tiles using the given TileReader. The TileReader would typically be a TileFetcher, optionally wrapped in a PermanentCache to cache tiles on disk.

func (*Client) AllEntries added in v0.7.0 

func (c *Client) AllEntries(ctx context.Context, tree tlog.Tree, start int64) iter.Seq2[int64, []byte]

AllEntries works like Client.Entries, but fetches all entries up to the size of the tree, including those in partial data tiles.

Callers that are tailing a growing log should instead use Client.Entries, and fetch a new tree every time iteration stops.

func (*Client) Entries added in v0.6.0 

func (c *Client) Entries(ctx context.Context, tree tlog.Tree, start int64) iter.Seq2[int64, []byte]

Entries returns an iterator that yields entries from the given tree, starting at the given index. The first item in the yielded pair is the overall entry index in the log, starting at start.

The provided tree should have been verified by the caller, for example by verifying the signatures on a Checkpoint.

Iteration may stop before the size of the tree to avoid fetching a partial data tile. Resuming with the same tree will yield the remaining entries, however clients tailing a growing log are encouraged to fetch the next checkpoint and use that as the tree argument. If this behavior is not desired, use Client.AllEntries instead.

Callers must check Client.Err after the iteration breaks.

func (*Client) Entry added in v0.6.0 

func (c *Client) Entry(ctx context.Context, tree tlog.Tree, index int64) ([]byte, tlog.RecordProof, error)

Entry returns a log entry by its index, and an inclusion proof in the tree.

The provided tree should have been verified by the caller, for example by verifying the signatures on a Checkpoint.

func (*Client) Err added in v0.6.0 

func (c *Client) Err() error

Err returns the error encountered by the latest Client.Entries call.

type ClientOption added in v0.6.0 

type ClientOption func(*Client)

ClientOption is a function that configures a Client.

func WithCutEntry added in v0.6.0 

func WithCutEntry(cut func(tile []byte) (entry []byte, rh tlog.Hash, rest []byte, err error)) ClientOption

WithCutEntry configures the function to split the next entry from a data tile (a.k.a. entry bundle).

The entry is surfaced by the Entries method, the record hash is used to check inclusion in the tree, and the rest is passed to the next invocation of cut.

The input tile is never empty. cut must not modify the tile.

By default, the c2sp.org/tlog-tiles#log-entries format is used, as implemented by ReadTileEntry. For the go.dev/design/25530-sumdb format, use ReadSumDBEntry. For the c2sp.org/static-ct-api format, use filippo.io/sunlight.Client instead.

func WithSumDBEntries deprecated added in v0.6.0 

func WithSumDBEntries() ClientOption

WithSumDBEntries configures the function to split the next entry from a tile according to the go.dev/design/25530-sumdb format.

Deprecated: use WithCutEntry with ReadSumDBEntry instead.

func WithTimeout added in v0.6.0 

func WithTimeout(d time.Duration) ClientOption

WithTimeout configures the maximum duration the Client.Entries loop will block waiting for each next extry. The default is 5 minutes.

type CosignatureSigner 

type CosignatureSigner struct {
	// contains filtered or unexported fields
}

CosignatureSigner is a note.Signer that produces timestamped cosignatures according to c2sp.org/tlog-cosignature.

func NewCosignatureSigner 

func NewCosignatureSigner(name string, key crypto.Signer) (*CosignatureSigner, error)

NewCosignatureSigner constructs a new CosignatureSigner from an Ed25519 private key.

func (*CosignatureSigner) KeyHash 

func (s *CosignatureSigner) KeyHash() uint32

func (*CosignatureSigner) Name 

func (s *CosignatureSigner) Name() string

func (*CosignatureSigner) Sign 

func (s *CosignatureSigner) Sign(msg []byte) ([]byte, error)

func (*CosignatureSigner) Verifier 

func (s *CosignatureSigner) Verifier() *CosignatureVerifier

type CosignatureVerifier 

type CosignatureVerifier struct {
	// contains filtered or unexported fields
}

CosignatureVerifier is a note.Verifier that verifies cosignatures according to c2sp.org/tlog-cosignature.

func NewCosignatureVerifier added in v0.7.0 

func NewCosignatureVerifier(vkey string) (*CosignatureVerifier, error)

NewCosignatureVerifier constructs a new CosignatureVerifier from a c2sp.org/signed-note vkey string.

func (*CosignatureVerifier) KeyHash 

func (v *CosignatureVerifier) KeyHash() uint32

func (*CosignatureVerifier) Name 

func (v *CosignatureVerifier) Name() string

func (*CosignatureVerifier) String 

func (v *CosignatureVerifier) String() string

String returns the vkey encoding of the verifier, according to c2sp.org/signed-note.

func (*CosignatureVerifier) Verify 

func (v *CosignatureVerifier) Verify(msg, sig []byte) bool

type HashProof added in v0.6.0 

type HashProof []tlog.Hash

A HashProof is a verifiable proof that a particular tree head contains a particular sub-tree hash. A tlog.RecordProof is a special case of a HashProof where the sub-tree has height 0.

func ProveHash added in v0.6.0 

func ProveHash(t, i int64, r tlog.HashReader) (HashProof, error)

ProveHash returns the proof that the tree of size t contains the hash with tlog.StoredHashIndex i.

type PermanentCache added in v0.6.0 

type PermanentCache struct {
	// contains filtered or unexported fields
}

PermanentCache is a TileReader that caches verified, non-partial tiles in a filesystem directory. It passes through ReadEndpoint calls without caching.

func NewPermanentCache added in v0.6.0 

func NewPermanentCache(tr TileReader, dir string, opts ...PermanentCacheOption) (*PermanentCache, error)

NewPermanentCache creates a new PermanentCache that caches tiles in the given directory. The directory must exist.

func (*PermanentCache) ReadEndpoint added in v0.6.0 

func (c *PermanentCache) ReadEndpoint(ctx context.Context, path string) (data []byte, err error)

ReadEndpoint passes through to the underlying TileReader.

func (*PermanentCache) ReadTiles added in v0.6.0 

func (c *PermanentCache) ReadTiles(ctx context.Context, tiles []tlog.Tile) (data [][]byte, err error)

ReadTiles implements TileReader.

func (*PermanentCache) SaveTiles added in v0.6.0 

func (c *PermanentCache) SaveTiles(tiles []tlog.Tile, data [][]byte)

SaveTiles implements TileReader.

type PermanentCacheOption added in v0.6.0 

type PermanentCacheOption func(*PermanentCache)

PermanentCacheOption is a function that configures a PermanentCache.

func WithPermanentCacheLogger added in v0.6.0 

func WithPermanentCacheLogger(log *slog.Logger) PermanentCacheOption

WithPermanentCacheLogger configures the logger used by the PermanentCache. By default, log lines are discarded.

func WithPermanentCacheTilePath added in v0.6.0 

func WithPermanentCacheTilePath(tilePath func(tlog.Tile) string) PermanentCacheOption

WithPermanentCacheTilePath configures the function used to generate the tile path from a tlog.Tile. By default, PermanentCache uses the c2sp.org/tlog-tiles scheme implemented by TilePath. For the go.dev/design/25530-sumdb scheme, use tlog.Tile.Path. For the c2sp.org/static-ct-api scheme, use filippo.io/sunlight.TilePath.

type Policy added in v0.9.0 

type Policy interface {
	// Check returns nil if the provided signatures satisfy the policy.
	//
	// The signatures must already have been verified with their respective
	// verifiers, and would usually be obtained from [note.Note.Sigs].
	Check(origin string, sigs []note.Signature) error

	// Verifier implements [note.Verifiers], returning the Verifier for any of
	// the cosigners in the policy.
	Verifier(name string, hash uint32) (note.Verifier, error)
}

Policy encodes the requirements for a set of (co)signatures on a c2sp.org/tlog-checkpoint.

The Verifier method allows the policy to be passed in as the known parameter to note.Open, while the Check method must be applied to note.Note.Sigs and [Checkpoint.Origin] after note.Open and ParseCheckpoint.

func OriginPolicy added in v0.9.0 

func OriginPolicy(origin string) Policy

OriginPolicy returns a Policy that enforces the provided origin string.

This is usually combined with a SingleVerifierPolicy for the log's public key Verifier, using ThresholdPolicy with a threshold of 2-of-2.

func ParsePolicy added in v0.9.0 

func ParsePolicy(p []byte) (Policy, error)

ParsePolicy parses a Policy from the provided byte slice.

The policy format is EXPERIMENTAL and may change in future releases. It is based on the Sigsum policy format but it uses vkeys instead of raw public keys. It is compatible with Tessera witness policies. It currently requires the checkpoint origin to match the log vkey name.

func SingleVerifierPolicy added in v0.9.0 

func SingleVerifierPolicy(v note.Verifier) Policy

SingleVerifierPolicy returns a Policy that requires a single verifier to have signed the note. The origin is not restricted.

func ThresholdPolicy added in v0.9.0 

func ThresholdPolicy(n int, policies ...Policy) Policy

ThresholdPolicy returns a Policy that requires at least n of the provided policies to be satisfied.

It panics if n is less than zero or greater than the number of polcies.

type TileArchiveFS added in v0.8.0 

type TileArchiveFS struct {
	// contains filtered or unexported fields
}

TileArchiveFS is an fs.FS that reads tiles and accessory files from a collection of zip files, numbered 000.zip, 001.zip, ...

Each zip file contains the corresponding level 2 tile, and all the full tiles below it. All other files (higher-level tiles, partial tiles on the right edge, checkpoint, etc.) are expected to be present in every zip file.

It supports both c2sp.org/tlog-tiles and c2sp.org/static-ct-api tile layouts, but not go.dev/design/25530-sumdb.

See also https://github.com/geomys/ct-archive/blob/main/README.md#archival-format.

func NewTileArchiveFS added in v0.8.0 

func NewTileArchiveFS(f fs.FS) *TileArchiveFS

NewTileArchiveFS creates a new TileArchiveFS that reads zip files from the root of the given fs.FS. f.Open must return files that implement io.ReaderAt.

func (*TileArchiveFS) Close added in v0.8.0 

func (tf *TileArchiveFS) Close() error

func (*TileArchiveFS) Open added in v0.8.0 

func (tf *TileArchiveFS) Open(name string) (fs.File, error)

Open implements fs.FS.

type TileFS added in v0.8.0 

type TileFS struct {
	// contains filtered or unexported fields
}

TileFS is a TileReader that reads tiles from a fs.FS.

func NewTileFS added in v0.8.0 

func NewTileFS(f fs.FS, opts ...TileFSOption) (*TileFS, error)

NewTileFS creates a new TileFS that reads tiles from the given fs.FS. By default, it expects tiles to be laid out according to c2sp.org/tlog-tiles.

func (*TileFS) ReadEndpoint added in v0.8.0 

func (f *TileFS) ReadEndpoint(ctx context.Context, path string) (data []byte, err error)

ReadEndpoint fetches an arbitrary path.

func (*TileFS) ReadTiles added in v0.8.0 

func (f *TileFS) ReadTiles(ctx context.Context, tiles []tlog.Tile) (data [][]byte, err error)

ReadTiles implements TileReader.

func (*TileFS) SaveTiles added in v0.8.0 

func (f *TileFS) SaveTiles(tiles []tlog.Tile, data [][]byte)

SaveTiles implements TileReader. It does nothing.

type TileFSOption added in v0.8.0 

type TileFSOption func(*TileFS)

TileFSOption is a function that configures a TileFS.

func WithGzipDataTiles added in v0.8.0 

func WithGzipDataTiles() TileFSOption

WithGzipDataTiles configures the TileFS to transparently decompress gzip-compressed data tiles.

func WithTileFSTilePath added in v0.8.0 

func WithTileFSTilePath(tilePath func(tlog.Tile) string) TileFSOption

WithTileFSTilePath configures the function used to generate the tile path from a tlog.Tile. By default, TileFS uses the c2sp.org/tlog-tiles scheme implemented by TilePath. For the go.dev/design/25530-sumdb scheme, use tlog.Tile.Path. For the c2sp.org/static-ct-api scheme, use filippo.io/sunlight.TilePath.

type TileFetcher added in v0.6.0 

type TileFetcher struct {
	// contains filtered or unexported fields
}

TileFetcher is a TileReader that fetches tiles from a remote server.

func NewTileFetcher added in v0.6.0 

func NewTileFetcher(base string, opts ...TileFetcherOption) (*TileFetcher, error)

NewTileFetcher creates a new TileFetcher that fetches tiles from the given base URL. By default, it fetches tiles according to c2sp.org/tlog-tiles.

func (*TileFetcher) ReadEndpoint added in v0.6.0 

func (f *TileFetcher) ReadEndpoint(ctx context.Context, path string) (data []byte, err error)

ReadEndpoint fetches an arbitrary path.

It retries 429 and 5xx responses, and network errors.

func (*TileFetcher) ReadTiles added in v0.6.0 

func (f *TileFetcher) ReadTiles(ctx context.Context, tiles []tlog.Tile) (data [][]byte, err error)

ReadTiles implements TileReader.

It retries 429 and 5xx responses, and network errors.

func (*TileFetcher) SaveTiles added in v0.6.0 

func (f *TileFetcher) SaveTiles(tiles []tlog.Tile, data [][]byte)

SaveTiles implements TileReader. It does nothing.

type TileFetcherOption added in v0.6.0 

type TileFetcherOption func(*TileFetcher)

TileFetcherOption is a function that configures a TileFetcher.

func WithConcurrencyLimit added in v0.6.0 

func WithConcurrencyLimit(limit int) TileFetcherOption

WithConcurrencyLimit configures the maximum number of concurrent requests made by the TileFetcher. By default, there is no limit.

func WithHTTPClient added in v0.6.0 

func WithHTTPClient(hc *http.Client) TileFetcherOption

WithHTTPClient configures the HTTP client used by the TileFetcher.

Note that TileFetcher may need to make multiple parallel requests to the same host, more than the default MaxIdleConnsPerHost.

func WithTileFetcherLogger added in v0.6.0 

func WithTileFetcherLogger(log *slog.Logger) TileFetcherOption

WithTileFetcherLogger configures the logger used by the TileFetcher. By default, log lines are discarded.

func WithTilePath added in v0.6.0 

func WithTilePath(tilePath func(tlog.Tile) string) TileFetcherOption

WithTilePath configures the function used to generate the tile path from a tlog.Tile. By default, TileFetcher uses the c2sp.org/tlog-tiles scheme implemented by TilePath. For the go.dev/design/25530-sumdb scheme, use tlog.Tile.Path. For the c2sp.org/static-ct-api scheme, use filippo.io/sunlight.TilePath.

func WithUserAgent added in v0.6.0 

func WithUserAgent(ua string) TileFetcherOption

WithUserAgent configures the User-Agent header used by the TileFetcher. By default, the User-Agent is "filippo.io/torchwood.Client".

type TileReader added in v0.6.0 

type TileReader interface {
	// ReadTiles returns the data for each requested tile.
	// See [tlog.TileReader.ReadTiles] for details.
	ReadTiles(ctx context.Context, tiles []tlog.Tile) (data [][]byte, err error)

	// SaveTiles informs the TileReader that the tile data has been confirmed.
	// See [tlog.TileReader.SaveTiles] for details.
	SaveTiles(tiles []tlog.Tile, data [][]byte)

	// ReadEndpoint fetches an arbitrary endpoint at the given path, such as
	// "checkpoint", if supported.
	ReadEndpoint(ctx context.Context, path string) (data []byte, err error)
}

TileReader is an interface equivalent to tlog.TileReader, but with a context parameter for cancellation, a fixed TileHeight, and a method to fetch arbitrary additional endpoints, if available.

type TileReaderWithContext deprecated added in v0.6.0 

type TileReaderWithContext = TileReader

TileReaderWithContext is an obsolete name for TileReader.

Deprecated: use TileReader instead.

type VerifyRecordError added in v0.9.0 

type VerifyRecordError struct {
	Index int64
	Extra []byte
}

VerifyRecordError is returned by VerifyProof when the inclusion proof does not verify. It can be used to diagnose the issue or print a better error message. All of its fields are unauthenticated and must not be trusted.

func (*VerifyRecordError) Error added in v0.9.0 

func (e *VerifyRecordError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
Package bastion runs a reverse proxy service that allows un-addressable applications (for example those running behind a firewall or a NAT, or where the operator doesn't wish to take the DoS risk of being reachable from the Internet) to accept HTTP requests.
 Package bastion runs a reverse proxy service that allows un-addressable applications (for example those running behind a firewall or a NAT, or where the operator doesn't wish to take the DoS risk of being reachable from the Internet) to accept HTTP requests.
cmd
age-keylookup command
age-keyserver command
age-keyserver-keygen command
litebastion command
Command litebastion runs a reverse proxy service that allows un-addressable applications (for example those running behind a firewall or a NAT, or where the operator doesn't wish to take the DoS risk of being reachable from the Internet) to accept HTTP requests.
 Command litebastion runs a reverse proxy service that allows un-addressable applications (for example those running behind a firewall or a NAT, or where the operator doesn't wish to take the DoS risk of being reachable from the Internet) to accept HTTP requests.
litewitness command
spicy command
sumdb-warmup command
witnessctl command
internal
slogconsole
witness
Package prefix implements a compressed binary Merkle trie, or prefix tree: an append-only compressed key-value accumulator based on a sparse binary Merkle tree.
 Package prefix implements a compressed binary Merkle trie, or prefix tree: an append-only compressed key-value accumulator based on a sparse binary Merkle tree.
prefixsqlite
Package tesserax implements additional functions for use with the tessera package.
 Package tesserax implements additional functions for use with the tessera package.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.