loglist3

Documentation

Overview

Package loglist3 allows parsing and searching of the master CT Log list. It expects the log list to conform to the v3 schema.

Index

• Constants
• type Log
• type LogList
  • func NewFromJSON(llData []byte) (*LogList, error)
  • func NewFromSignedJSON(llData, rawSig []byte, pubKey crypto.PublicKey) (*LogList, error)
  • func (ll *LogList) Compatible(cert *x509.Certificate, certRoot *x509.Certificate, roots LogRoots) LogList
  • func (ll *LogList) FindLogByKey(key []byte) *Log
  • func (ll *LogList) FindLogByKeyHash(keyhash [sha256.Size]byte) *Log
  • func (ll *LogList) FindLogByKeyHashPrefix(prefix string) []*Log
  • func (ll *LogList) FindLogByName(name string) []*Log
  • func (ll *LogList) FindLogByURL(url string) *Log
  • func (ll *LogList) FuzzyFindLog(input string) []*Log
  • func (ll *LogList) RootCompatible(certRoot *x509.Certificate, roots LogRoots) LogList
  • func (ll *LogList) SelectByStatus(lstats []LogStatus) LogList
  • func (ll *LogList) TemporallyCompatible(cert *x509.Certificate) LogList
• type LogRoots
• type LogState
• type LogStates
  • func (ls *LogStates) Active() (*LogState, *ReadOnlyLogState)
  • func (ls *LogStates) LogStatus() LogStatus
  • func (ls *LogStates) String() string
• type LogStatus
  • func (i LogStatus) String() string
• type Operator
  • func (op *Operator) GoogleOperated() bool
• type PreviousOperator
• type ReadOnlyLogState
• type TemporalInterval
• type TreeHead

Constants

const (
	// LogListURL has the master URL for Google Chrome's log list.
	LogListURL = "https://www.gstatic.com/ct/log_list/v3/log_list.json"
	// LogListSignatureURL has the URL for the signature over Google Chrome's log list.
	LogListSignatureURL = "https://www.gstatic.com/ct/log_list/v3/log_list.sig"
	// AllLogListURL has the URL for the list of all known logs (which isn't signed).
	AllLogListURL = "https://www.gstatic.com/ct/log_list/v3/all_logs_list.json"
)

Types

type Log

type Log struct {
	// Description is a human-readable string that describes the log.
	Description string `json:"description,omitempty"`
	// LogID is the SHA-256 hash of the log's public key.
	LogID []byte `json:"log_id"`
	// Key is the public key with which signatures can be verified.
	Key []byte `json:"key"`
	// URL is the address of the HTTPS API.
	URL string `json:"url"`
	// DNS is the address of the DNS API.
	DNS string `json:"dns,omitempty"`
	// MMD is the Maximum Merge Delay, in seconds. All submitted
	// certificates must be incorporated into the log within this time.
	MMD int32 `json:"mmd"`
	// PreviousOperators is a list of previous operators and the timestamp
	// of when they stopped running the log.
	PreviousOperators []*PreviousOperator `json:"previous_operators,omitempty"`
	// State is the current state of the log, from the perspective of the
	// log list distributor.
	State *LogStates `json:"state,omitempty"`
	// TemporalInterval, if set, indicates that this log only accepts
	// certificates with a NotAfter date in this time range.
	TemporalInterval *TemporalInterval `json:"temporal_interval,omitempty"`
	// Type indicates the purpose of this log, e.g. "test" or "prod".
	Type string `json:"log_type,omitempty"`
}

Log describes a single CT log.

type LogList

type LogList struct {
	// IsAllLogs is set to true if the list contains all known logs, not
	// only usable ones.
	IsAllLogs bool `json:"is_all_logs,omitempty"`
	// Version is the version of the log list.
	Version string `json:"version,omitempty"`
	// LogListTimestamp is the time at which the log list was published.
	LogListTimestamp time.Time `json:"log_list_timestamp,omitempty"`
	// Operators is a list of CT log operators and the logs they operate.
	Operators []*Operator `json:"operators"`
}

LogList holds a collection of CT logs, grouped by operator.

func NewFromJSON

func NewFromJSON(llData []byte) (*LogList, error)

NewFromJSON creates a LogList from JSON encoded data.

func NewFromSignedJSON

func NewFromSignedJSON(llData, rawSig []byte, pubKey crypto.PublicKey) (*LogList, error)

NewFromSignedJSON creates a LogList from JSON encoded data, checking a signature along the way. The signature data should be provided as the raw signature data.

func (*LogList) Compatible

func (ll *LogList) Compatible(cert *x509.Certificate, certRoot *x509.Certificate, roots LogRoots) LogList

Compatible creates a new LogList containing only Logs matching the temporal, root-acceptance and Log-status conditions.

func (*LogList) FindLogByKey

func (ll *LogList) FindLogByKey(key []byte) *Log

FindLogByKey finds the log with the given DER-encoded key.

func (*LogList) FindLogByKeyHash

func (ll *LogList) FindLogByKeyHash(keyhash [sha256.Size]byte) *Log

FindLogByKeyHash finds the log with the given key hash.

func (*LogList) FindLogByKeyHashPrefix

func (ll *LogList) FindLogByKeyHashPrefix(prefix string) []*Log

FindLogByKeyHashPrefix finds all logs whose key hash starts with the prefix.

func (*LogList) FindLogByName

func (ll *LogList) FindLogByName(name string) []*Log

FindLogByName returns all logs whose names contain the given string.

func (*LogList) FindLogByURL

func (ll *LogList) FindLogByURL(url string) *Log

FindLogByURL finds the log with the given URL.

func (*LogList) FuzzyFindLog

func (ll *LogList) FuzzyFindLog(input string) []*Log

FuzzyFindLog tries to find logs that match the given unspecified input, whose format is unspecified. This generally returns a single log, but if text input that matches multiple log descriptions is provided, then multiple logs may be returned.

func (*LogList) RootCompatible

func (ll *LogList) RootCompatible(certRoot *x509.Certificate, roots LogRoots) LogList

RootCompatible creates a new LogList containing only the logs of original LogList that are compatible with the provided cert, according to the passed in collection of per-log roots. Logs that are missing from the collection are treated as always compatible and included, even if an empty cert root is passed in. Cert-root when provided is expected to be CA-cert.

func (*LogList) SelectByStatus

func (ll *LogList) SelectByStatus(lstats []LogStatus) LogList

SelectByStatus creates a new LogList containing only logs with status provided from the original.

func (*LogList) TemporallyCompatible

func (ll *LogList) TemporallyCompatible(cert *x509.Certificate) LogList

TemporallyCompatible creates a new LogList containing only the logs of original LogList that are compatible with the provided cert, according to NotAfter and TemporalInterval matching. Returns empty LogList if nil-cert is provided.

type LogRoots

type LogRoots map[string]*x509util.PEMCertPool

LogRoots maps Log-URLs (stated at LogList) to the pools of their accepted root-certificates.

type LogState

type LogState struct {
	// Timestamp is the time when the state began.
	Timestamp time.Time `json:"timestamp"`
}

LogState contains details on the current state of a CT log.

type LogStates

type LogStates struct {
	// Pending indicates that the log is in the "pending" state.
	Pending *LogState `json:"pending,omitempty"`
	// Qualified indicates that the log is in the "qualified" state.
	Qualified *LogState `json:"qualified,omitempty"`
	// Usable indicates that the log is in the "usable" state.
	Usable *LogState `json:"usable,omitempty"`
	// ReadOnly indicates that the log is in the "readonly" state.
	ReadOnly *ReadOnlyLogState `json:"readonly,omitempty"`
	// Retired indicates that the log is in the "retired" state.
	Retired *LogState `json:"retired,omitempty"`
	// Rejected indicates that the log is in the "rejected" state.
	Rejected *LogState `json:"rejected,omitempty"`
}

LogStates are the states that a CT log can be in, from the perspective of a user agent. Only one should be set - this is the current state.

func (*LogStates) Active

func (ls *LogStates) Active() (*LogState, *ReadOnlyLogState)

Active picks the set-up state. If multiple states are set (not expected) picks one of them.

func (*LogStates) LogStatus

func (ls *LogStates) LogStatus() LogStatus

LogStatus method returns Log-status enum value for descriptive struct.

func (*LogStates) String

func (ls *LogStates) String() string

String method returns printable name of the state.

type LogStatus

type LogStatus int

LogStatus indicates Log status.

const (
	UndefinedLogStatus LogStatus = iota
	PendingLogStatus
	QualifiedLogStatus
	UsableLogStatus
	ReadOnlyLogStatus
	RetiredLogStatus
	RejectedLogStatus
)

LogStatus values

func (LogStatus) String

func (i LogStatus) String() string

type Operator

type Operator struct {
	// Name is the name of the CT log operator.
	Name string `json:"name"`
	// Email lists the email addresses that can be used to contact this log
	// operator.
	Email []string `json:"email"`
	// Logs is a list of CT logs run by this operator.
	Logs []*Log `json:"logs"`
}

Operator holds a collection of CT logs run by the same organisation. It also provides information about that organisation, e.g. contact details.

func (*Operator) GoogleOperated

func (op *Operator) GoogleOperated() bool

GoogleOperated returns whether Operator is considered to be Google.

type PreviousOperator

type PreviousOperator struct {
	// Name is the name of the CT log operator.
	Name string `json:"name"`
	// EndTime is the time at which the operator stopped running a log.
	EndTime time.Time `json:"end_time"`
}

PreviousOperator holds information about a log operator and the time at which they stopped running a log.

type ReadOnlyLogState

type ReadOnlyLogState struct {
	LogState
	// FinalTreeHead is the root hash and tree size at which the CT log was
	// made read-only. This should never change while the log is read-only.
	FinalTreeHead TreeHead `json:"final_tree_head"`
}

ReadOnlyLogState contains details on the current state of a read-only CT log.

type TemporalInterval

type TemporalInterval struct {
	// StartInclusive is the beginning of the time range.
	StartInclusive time.Time `json:"start_inclusive"`
	// EndExclusive is just after the end of the time range.
	EndExclusive time.Time `json:"end_exclusive"`
}

TemporalInterval is a time range.

type TreeHead

type TreeHead struct {
	// SHA256RootHash is the root hash of the CT log's Merkle tree.
	SHA256RootHash []byte `json:"sha256_root_hash"`
	// TreeSize is the size of the CT log's Merkle tree.
	TreeSize int64 `json:"tree_size"`
}

TreeHead is the root hash and tree size of a CT log.