README
¶
Sunlight is a Certificate Transparency log implementation and monitoring API designed for scalability, ease of operation, and reduced cost.
Additional resources, including test logs, a formal specification of the monitoring API, and a comprehensive design document which explores the motivating tradeoffs are available at sunlight.dev.
Sunlight is based on the original Certificate Transparency design, on the Go Checksum Database developed with Russ Cox, and on the feedback of many individuals in the WebPKI community, and in particular of the Sigsum, Google TrustFabric, and ISRG teams. Sunlight's development was sponsored by Let's Encrypt.
Operating a Sunlight log
A Sunlight instance is a single Go process, serving one or more CT logs, configured with a YAML file. Config options are documented in detail on the Config struct.
There are three data storage locations with different properties involved in operating a Sunlight instance:
-
A global "lock backend" which provides a compare-and-swap primitive, where only the signed tree head of each log is stored, to prevent accidental operational mistakes such as running two Sunlight instances against the same configuration from causing a fatal log split.
This backend will always store trivial amounts of data, but it's important that a single global table/bucket/location is used.
Currently, DynamoDB, Tigris (S3-like API with ETag support), and local SQLite are supported.
-
A per-log object store bucket, where the public tiles, checkpoints, and issuers are uploaded. Monitors can fetch the tree contents directly from these buckets.
You should account for between 5GB and 10GB per million certificates, or between 5TB and 10TB for a six months shard at current (~75/s) submission rates.
We recommend enabling S3 Object Versioning (see #11) or overwriting protection (automatically enabled client-side on Tigris).
Currently, S3 and S3-compatible APIs are supported.
-
A per-log deduplication cache, to return existing SCTs for previously submitted (pre-)certificates.
Note that this can be a best-effort lookup, and it's ok to rollback a few entries on a regular basis, or even lose the cache in an emergency. The only consequence is that existing entries might be resubmitted, growing the size of the log.
You should account for approximately 50MB per million certificates, or approximately 50GB for a six months shard at current (~75/s) submission rates.
This is a local SQLite database, and it's designed to be backed up with Litestream.
Prometheus metrics are exposed publicly at /metrics. Logs are written to
stderr in human-readable format, and to stdout in JSON format.
A private HTTP debug server is also started on a random port on localhost. It
serves the net/http/pprof endpoints, as well as /debug/logson and
/debug/logsoff which enable and disable debug logging, respectively.
Documentation
¶
Index ¶
- Constants
- func AppendTileLeaf(t []byte, e *LogEntry) []byte
- func FormatCheckpoint(c Checkpoint) string
- func MarshalExtensions(e Extensions) ([]byte, error)
- func NewRFC6962Verifier(name string, key crypto.PublicKey) (note.Verifier, error)
- func RFC6962SignatureTimestamp(sig note.Signature) (int64, error)
- func TilePath(t tlog.Tile) string
- type Checkpoint
- type Extensions
- type LogEntry
Constants ¶
const TileHeight = 8
const TileWidth = 1 << TileHeight
Variables ¶
This section is empty.
Functions ¶
func AppendTileLeaf ¶
AppendTileLeaf appends a LogEntry to a data tile.
func FormatCheckpoint ¶
func FormatCheckpoint(c Checkpoint) string
func MarshalExtensions ¶
func MarshalExtensions(e Extensions) ([]byte, error)
func NewRFC6962Verifier ¶
NewRFC6962Verifier constructs a new note.Verifier that verifies a RFC 6962 TreeHeadSignature formatted according to c2sp.org/sunlight.
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)
type Extensions ¶
type Extensions struct {
LeafIndex int64
}
Extensions is the CTExtensions field of SignedCertificateTimestamp and TimestampedEntry, according to c2sp.org/sunlight.
func ParseExtensions ¶
func ParseExtensions(extensions []byte) (Extensions, error)
ParseExtensions parse a CTExtensions field, ignoring unknown extensions. It is an error if the leaf_index extension is missing.
type LogEntry ¶
type LogEntry struct {
// Certificate is either the TimestampedEntry.signed_entry, or the
// PreCert.tbs_certificate for Precertificates.
// It must be at most 2^24-1 bytes long.
Certificate []byte
// IsPrecert is true if LogEntryType is precert_entry. Otherwise, the
// following three fields are zero and ignored.
IsPrecert bool
// IssuerKeyHash is the PreCert.issuer_key_hash.
IssuerKeyHash [32]byte
// ChainFingerprints are the SHA-256 hashes of the certificates in the
// X509ChainEntry.certificate_chain or
// PrecertChainEntry.precertificate_chain.
ChainFingerprints [][32]byte
// PreCertificate is the PrecertChainEntry.pre_certificate.
// It must be at most 2^24-1 bytes long.
PreCertificate []byte
// LeafIndex is the zero-based index of the leaf in the log.
// It must be between 0 and 2^40-1.
LeafIndex int64
// Timestamp is the TimestampedEntry.timestamp.
Timestamp int64
}
func ReadTileLeaf ¶
ReadTileLeaf reads a LogEntry from a data tile, and returns the remaining data in the tile.
func (*LogEntry) MerkleTreeLeaf ¶
MerkleTreeLeaf returns a RFC 6962 MerkleTreeLeaf.
Source Files
Directories