Constants for entrypoint names, as exposed in statistics/logging.
const (
AddChainName = EntrypointName("AddChain")
AddPreChainName = EntrypointName("AddPreChain")
GetSTHName = EntrypointName("GetSTH")
GetSTHConsistencyName = EntrypointName("GetSTHConsistency")
GetProofByHashName = EntrypointName("GetProofByHash")
GetEntriesName = EntrypointName("GetEntries")
GetRootsName = EntrypointName("GetRoots")
GetEntryAndProofName = EntrypointName("GetEntryAndProof")
)
CertificateQuotaUserPrefix is prepended to all User quota ids association with intermediate certificates.
const CertificateQuotaUserPrefix = "@intermediate"
Entrypoints is a list of entrypoint names as exposed in statistics/logging.
var Entrypoints = []EntrypointName{AddChainName, AddPreChainName, GetSTHName, GetSTHConsistencyName, GetProofByHashName, GetEntriesName, GetRootsName, GetEntryAndProofName}
var (
// MaxGetEntriesAllowed is the number of entries we allow in a get-entries request
MaxGetEntriesAllowed int64 = 1000
)
func GetCTLogID(pk crypto.PublicKey) ([sha256.Size]byte, error)
GetCTLogID takes the key manager for a log and returns the LogID. (see RFC 6962 S3.2) In CT V1 the log id is a hash of the public key.
func IsPrecertificate(cert *x509.Certificate) (bool, error)
IsPrecertificate tests if a certificate is a pre-certificate as defined in CT. An error is returned if the CT extension is present but is not ASN.1 NULL as defined by the spec.
func LogConfigFromFile(filename string) ([]*configpb.LogConfig, error)
LogConfigFromFile creates a slice of LogConfig options from the given filename, which should contain text or binary-encoded protobuf configuration data.
func MultiLogConfigFromFile(filename string) (*configpb.LogMultiConfig, error)
MultiLogConfigFromFile creates a LogMultiConfig proto from the given filename, which should contain text or binary-encoded protobuf configuration data. Does not do full validation of the config but checks that it is non empty.
func ParseBodyAsJSONChain(r *http.Request) (ct.AddChainRequest, error)
ParseBodyAsJSONChain tries to extract cert-chain out of request.
func QuotaUserForCert(c *x509.Certificate) string
QuotaUserForCert returns a User quota id string for the passed in certificate. This is intended to be used for quota limiting by intermediate certificates, but the function does not enforce anything about the passed in cert.
Format returned is:
"CertificateQuotaUserPrefix Subject hex(SHA256(SubjectPublicKeyInfo)[0:5])"
See tests for examples.
func ToMultiLogConfig(cfg []*configpb.LogConfig, beSpec string) *configpb.LogMultiConfig
ToMultiLogConfig creates a multi backend config proto from the data loaded from a single-backend configuration file. All the log configs reference a default backend spec as provided.
func ValidateChain(rawChain [][]byte, validationOpts CertValidationOpts) ([]*x509.Certificate, error)
ValidateChain takes the certificate chain as it was parsed from a JSON request. Ensures all elements in the chain decode as X.509 certificates. Ensures that there is a valid path from the end entity certificate in the chain to a trusted root cert, possibly using the intermediates supplied in the chain. Then applies the RFC requirement that the path must involve all the submitted chain in the order of submission.
func ValidateLogConfigs(cfg []*configpb.LogConfig) error
ValidateLogConfigs checks that a config is valid for use with a single log server. The rules applied are:
1. All log configs must be valid (see ValidateLogConfig). 2. The prefixes of configured logs must all be distinct and must not be empty. 3. The set of tree IDs must be distinct.
AppHandler holds a logInfo and a handler function that uses it, and is an implementation of the http.Handler interface.
type AppHandler struct {
Info *logInfo
Handler func(context.Context, *logInfo, http.ResponseWriter, *http.Request) (int, error)
Name EntrypointName
Method string // http.MethodGet or http.MethodPost
}
func (a AppHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
ServeHTTP for an AppHandler invokes the underlying handler function but does additional common error and stats processing.
CertValidationOpts contains various parameters for certificate chain validation
type CertValidationOpts struct {
// contains filtered or unexported fields
}
func NewCertValidationOpts(trustedRoots *x509util.PEMCertPool, currentTime time.Time, rejectExpired bool, rejectUnexpired bool, notAfterStart *time.Time, notAfterLimit *time.Time, acceptOnlyCA bool, extKeyUsages []x509.ExtKeyUsage) CertValidationOpts
NewCertValidationOpts builds validation options based on parameters.
DefaultMirrorSTHFactory creates DefaultMirrorSTHStorage instances.
type DefaultMirrorSTHFactory struct{}
func (f DefaultMirrorSTHFactory) NewStorage(logID [sha256.Size]byte) (MirrorSTHStorage, error)
NewStorage creates a dummy STH storage.
DefaultMirrorSTHStorage is a dummy STH storage that always returns an error.
type DefaultMirrorSTHStorage struct{}
func (st DefaultMirrorSTHStorage) GetMirrorSTH(ctx context.Context, maxTreeSize int64) (*ct.SignedTreeHead, error)
GetMirrorSTH returns an error.
DefaultRequestLog is an implementation of RequestLog that does nothing except log the calls at a high level of verbosity.
type DefaultRequestLog struct {
}
func (dlr *DefaultRequestLog) AddCertToChain(_ context.Context, cert *x509.Certificate)
AddCertToChain logs some issuer / subject / timing fields from a certificate that is part of a submitted chain.
func (dlr *DefaultRequestLog) AddDERToChain(_ context.Context, d []byte)
AddDERToChain logs the raw bytes of a submitted certificate.
func (dlr *DefaultRequestLog) FirstAndSecond(_ context.Context, f, s int64)
FirstAndSecond logs request parameters.
func (dlr *DefaultRequestLog) IssueSCT(_ context.Context, sct []byte)
IssueSCT logs an SCT that will be issued to a client.
func (dlr *DefaultRequestLog) LeafHash(_ context.Context, lh []byte)
LeafHash logs request parameters.
func (dlr *DefaultRequestLog) LeafIndex(_ context.Context, li int64)
LeafIndex logs request parameters.
func (dlr *DefaultRequestLog) LogPrefix(_ context.Context, p string)
LogPrefix logs the prefix of the CT log that this request is for.
func (dlr *DefaultRequestLog) Start(ctx context.Context) context.Context
Start logs the start of request processing.
func (dlr *DefaultRequestLog) StartAndEnd(_ context.Context, s, e int64)
StartAndEnd logs request parameters.
func (dlr *DefaultRequestLog) Status(_ context.Context, s int)
Status logs the response HTTP status code after processing completes.
func (dlr *DefaultRequestLog) TreeSize(_ context.Context, ts int64)
TreeSize logs request parameters.
EntrypointName identifies a CT entrypoint as defined in section 4 of RFC 6962.
type EntrypointName string
FrozenSTHGetter is an STHGetter implementation returning a constant STH.
type FrozenSTHGetter struct {
// contains filtered or unexported fields
}
func (sg *FrozenSTHGetter) GetSTH(ctx context.Context) (*ct.SignedTreeHead, error)
GetSTH returns the frozen STH.
Instance is a set up log/mirror instance. It must be created with the SetUpInstance call.
type Instance struct {
Handlers PathHandlers
STHGetter STHGetter
// contains filtered or unexported fields
}
func SetUpInstance(ctx context.Context, opts InstanceOptions) (*Instance, error)
SetUpInstance sets up a log (or log mirror) instance using the provided configuration, and returns an object containing a set of handlers for this log, and an STH getter.
func (i *Instance) GetPublicKey() crypto.PublicKey
GetPublicKey returns the public key from the instance's signer.
func (i *Instance) RunUpdateSTH(ctx context.Context, period time.Duration)
RunUpdateSTH regularly updates the Instance STH so our metrics stay up-to-date with any tree head changes that are not triggered by us.
InstanceOptions describes the options for a log instance.
type InstanceOptions struct {
// Validated holds the original configuration options for the log, and some
// of its fields parsed as a result of validating it.
Validated *ValidatedLogConfig
// Client is a corresponding Trillian log client.
Client trillian.TrillianLogClient
// Deadline is a timeout for Trillian RPC requests.
Deadline time.Duration
// MetricFactory allows creating metrics.
MetricFactory monitoring.MetricFactory
// ErrorMapper converts an error from an RPC request to an HTTP status, plus
// a boolean to indicate whether the conversion succeeded.
ErrorMapper func(error) (int, bool)
// RequestLog provides structured logging of CTFE requests.
RequestLog RequestLog
// RemoteUser returns a string representing the originating host for the
// given request. This string will be used as a User quota key.
// If unset, no quota will be requested for remote users.
RemoteQuotaUser func(*http.Request) string
// CertificateQuotaUser returns a string representing the passed in
// intermediate certificate. This string will be user as a User quota key for
// the cert. Quota will be requested for each intermediate in an
// add-[pre]-chain request so as to allow individual issuers to be rate
// limited. If unset, no quota will be requested for intermediate
// certificates.
CertificateQuotaUser func(*x509.Certificate) string
// STHStorage provides STHs of a source log for the mirror. Only mirror
// instances will use it, i.e. when IsMirror == true in the config. If it is
// empty then the DefaultMirrorSTHStorage will be used.
STHStorage MirrorSTHStorage
// MaskInternalErrors indicates if internal server errors should be masked
// or returned to the user containing the full error message.
MaskInternalErrors bool
}
LogBackendMap is a map from log backend names to LogBackend objects.
type LogBackendMap = map[string]*configpb.LogBackend
func BuildLogBackendMap(lbs *configpb.LogBackendSet) (LogBackendMap, error)
BuildLogBackendMap returns a map from log backend names to the corresponding LogBackend objects. It returns an error unless all backends have unique non-empty names and specifications.
func ValidateLogMultiConfig(cfg *configpb.LogMultiConfig) (LogBackendMap, error)
ValidateLogMultiConfig checks that a config is valid for use with multiple backend log servers. The rules applied are the same as ValidateLogConfigs, as well as these additional rules:
1. The backend set must define a set of log backends with distinct (non empty) names and non empty backend specs. 2. The backend specs must all be distinct. 3. The log configs must all specify a log backend and each must be one of those defined in the backend set.
Also, another difference is that the tree IDs need only to be distinct per backend.
TODO(pavelkalinnikov): Replace the returned map with a fully fledged ValidatedLogMultiConfig that contains a ValidatedLogConfig for each log.
LogSTHGetter is an STHGetter implementation for regular (non-mirror) logs, i.e. logs that have their own key and actively sign STHs.
type LogSTHGetter struct {
// contains filtered or unexported fields
}
func (sg *LogSTHGetter) GetSTH(ctx context.Context) (*ct.SignedTreeHead, error)
GetSTH retrieves and builds a tree head structure for the given log. nolint:staticcheck
MirrorSTHGetter is an STHGetter implementation for mirror logs. It assumes no knowledge of the key, and returns STHs obtained from an external source represented by the MirrorSTHStorage interface.
type MirrorSTHGetter struct {
// contains filtered or unexported fields
}
func (sg *MirrorSTHGetter) GetSTH(ctx context.Context) (*ct.SignedTreeHead, error)
GetSTH returns a known source log's STH with as large TreeSize and/or timestamp as possible, but such that TreeSize <= Trillian log size. This is to ensure that the mirror doesn't expose a "future" state of the log before it is properly stored in Trillian.
MirrorSTHStorage provides STHs of a source log to be served from a mirror.
type MirrorSTHStorage interface {
// GetMirrorSTH returns an STH of TreeSize <= maxTreeSize. It does best
// effort to maximize the returned STH's TreeSize and/or Timestamp.
GetMirrorSTH(ctx context.Context, maxTreeSize int64) (*ct.SignedTreeHead, error)
}
PathHandlers maps from a path to the relevant AppHandler instance.
type PathHandlers map[string]AppHandler
RequestLog allows implementations to do structured logging of CTFE request parameters, submitted chains and other internal details that are useful for log operators when debugging issues. CTFE handlers will call the appropriate methods during request processing. The implementation is responsible for collating and storing the resulting logging information.
type RequestLog interface {
// Start will be called once at the beginning of handling each request.
// The supplied context will be the one used for request processing and
// can be used by the logger to set values on the returned context.
// The returned context should be used in all the following calls to
// this API. This is normally arranged by the request handler code.
Start(context.Context) context.Context
// LogPrefix will be called once per request to set the log prefix.
LogPrefix(context.Context, string)
// AddDERToChain will be called once for each certificate in a submitted
// chain. It's called early in request processing so the supplied bytes
// have not been checked for validity. Calls will be in order of the
// certificates as presented in the request with the root last.
AddDERToChain(context.Context, []byte)
// AddCertToChain will be called once for each certificate in the chain
// after it has been parsed and verified. Calls will be in order of the
// certificates as presented in the request with the root last.
AddCertToChain(context.Context, *x509.Certificate)
// FirstAndSecond will be called once for a consistency proof request with
// the first and second tree sizes involved (if they parse correctly).
FirstAndSecond(context.Context, int64, int64)
// StartAndEnd will be called once for a get entries request with the
// endpoints of the range requested (if they parse correctly).
StartAndEnd(context.Context, int64, int64)
// LeafIndex will be called once with the index of a leaf being requested
// by get entry and proof (if the request params parse correctly).
LeafIndex(context.Context, int64)
// TreeSize will be called once with the requested tree size for get entry
// and proof requests (if the request params parse correctly).
TreeSize(context.Context, int64)
// LeafHash will be called once for get proof by hash requests with the
// requested hash value (if the parameters parse correctly).
LeafHash(context.Context, []byte)
// IssueSCT will be called once when the server is about to issue an SCT to a
// client. This should not be called if the submission process fails before an
// SCT could be presented to a client, even if this is unrelated to
// the validity of the submitted chain. The SCT bytes will be in TLS
// serialized format.
IssueSCT(context.Context, []byte)
// Status will be called once to set the HTTP status code that was the
// the result after the request has been handled.
Status(context.Context, int)
}
STHGetter provides latest STHs for a log.
type STHGetter interface {
// GetSTH returns the latest STH for the log, as required by the RFC-6962
// get-sth endpoint: https://tools.ietf.org/html/rfc6962#section-4.3.
GetSTH(ctx context.Context) (*ct.SignedTreeHead, error)
}
SignatureCache is a one-entry cache that stores the last generated signature for a given bytes input. It helps to reduce the number of signing operations, and the number of distinct signatures produced for the same input (some signing methods are non-deterministic).
type SignatureCache struct {
// contains filtered or unexported fields
}
func (sc *SignatureCache) GetSignature(input []byte) (ct.DigitallySigned, bool)
GetSignature returns the latest signature for the given bytes input. If the input is not in the cache, it returns (_, false).
func (sc *SignatureCache) SetSignature(input []byte, sig ct.DigitallySigned)
SetSignature associates the signature with the given bytes input.
ValidatedLogConfig represents the LogConfig with the information that has been successfully parsed as a result of validating it.
type ValidatedLogConfig struct {
Config *configpb.LogConfig
PubKey crypto.PublicKey
PrivKey proto.Message
KeyUsages []x509.ExtKeyUsage
NotAfterStart *time.Time
NotAfterLimit *time.Time
FrozenSTH *ct.SignedTreeHead
}
func ValidateLogConfig(cfg *configpb.LogConfig) (*ValidatedLogConfig, error)
ValidateLogConfig checks that a single log config is valid. In particular:
Returns the validated structures (useful to avoid double validation).