ctfe

package
v1.1.8 Latest Latest
Warning

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

 Go to latest Published: Mar 11, 2024 License: Apache-2.0 Imports: 38 Imported by: 78

Documentation

Overview

Package ctfe contains a usage example by providing an implementation of an RFC6962 compatible CT log server using a Trillian log server as backend storage via its GRPC API.

IMPORTANT: Only code rooted within this part of the tree should refer to the CT GitHub repository. Other parts of the system must not assume that the data they're processing is X.509 or CT related.

The CT repository can be found at: https://github.com/google/certificate-transparency

Index

Constants

View Source 
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")
)

Constants for entrypoint names, as exposed in statistics/logging.

View Source 
const CertificateQuotaUserPrefix = "@intermediate"

CertificateQuotaUserPrefix is prepended to all User quota ids association with intermediate certificates.

Variables

View Source 
var Entrypoints = []EntrypointName{AddChainName, AddPreChainName, GetSTHName, GetSTHConsistencyName, GetProofByHashName, GetEntriesName, GetRootsName, GetEntryAndProofName}

Entrypoints is a list of entrypoint names as exposed in statistics/logging.

View Source 
var (
	// MaxGetEntriesAllowed is the number of entries we allow in a get-entries request
	MaxGetEntriesAllowed int64 = 1000
)

Functions

func GetCTLogID 

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 

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 

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 added in v1.0.4 

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 added in v1.1.0 

func ParseBodyAsJSONChain(r *http.Request) (ct.AddChainRequest, error)

ParseBodyAsJSONChain tries to extract cert-chain out of request.

func QuotaUserForCert added in v1.0.19 

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 added in v1.0.4 

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 

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 added in v1.1.1 

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.

Types

type AppHandler 

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
}

AppHandler holds a logInfo and a handler function that uses it, and is an implementation of the http.Handler interface.

func (AppHandler) ServeHTTP 

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.

type CertValidationOpts 

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

CertValidationOpts contains various parameters for certificate chain validation

func NewCertValidationOpts added in v1.1.0 

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.

type DefaultMirrorSTHFactory added in v1.0.21 

type DefaultMirrorSTHFactory struct{}

DefaultMirrorSTHFactory creates DefaultMirrorSTHStorage instances.

func (DefaultMirrorSTHFactory) NewStorage added in v1.0.21 

func (f DefaultMirrorSTHFactory) NewStorage(logID [sha256.Size]byte) (MirrorSTHStorage, error)

NewStorage creates a dummy STH storage.

type DefaultMirrorSTHStorage added in v1.0.21 

type DefaultMirrorSTHStorage struct{}

DefaultMirrorSTHStorage is a dummy STH storage that always returns an error.

func (DefaultMirrorSTHStorage) GetMirrorSTH added in v1.0.21 

func (st DefaultMirrorSTHStorage) GetMirrorSTH(ctx context.Context, maxTreeSize int64) (*ct.SignedTreeHead, error)

GetMirrorSTH returns an error.

type DefaultRequestLog added in v1.0.6 

type DefaultRequestLog struct {
}

DefaultRequestLog is an implementation of RequestLog that does nothing except log the calls at a high level of verbosity.

func (*DefaultRequestLog) AddCertToChain added in v1.0.6 

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 (*DefaultRequestLog) AddDERToChain added in v1.0.6 

func (dlr *DefaultRequestLog) AddDERToChain(_ context.Context, d []byte)

AddDERToChain logs the raw bytes of a submitted certificate.

func (*DefaultRequestLog) FirstAndSecond added in v1.0.6 

func (dlr *DefaultRequestLog) FirstAndSecond(_ context.Context, f, s int64)

FirstAndSecond logs request parameters.

func (*DefaultRequestLog) IssueSCT added in v1.0.18 

func (dlr *DefaultRequestLog) IssueSCT(_ context.Context, sct []byte)

IssueSCT logs an SCT that will be issued to a client.

func (*DefaultRequestLog) LeafHash added in v1.0.6 

func (dlr *DefaultRequestLog) LeafHash(_ context.Context, lh []byte)

LeafHash logs request parameters.

func (*DefaultRequestLog) LeafIndex added in v1.0.6 

func (dlr *DefaultRequestLog) LeafIndex(_ context.Context, li int64)

LeafIndex logs request parameters.

func (*DefaultRequestLog) LogPrefix added in v1.0.6 

func (dlr *DefaultRequestLog) LogPrefix(_ context.Context, p string)

LogPrefix logs the prefix of the CT log that this request is for.

func (*DefaultRequestLog) Start added in v1.0.6 

func (dlr *DefaultRequestLog) Start(ctx context.Context) context.Context

Start logs the start of request processing.

func (*DefaultRequestLog) StartAndEnd added in v1.0.6 

func (dlr *DefaultRequestLog) StartAndEnd(_ context.Context, s, e int64)

StartAndEnd logs request parameters.

func (*DefaultRequestLog) Status added in v1.0.6 

func (dlr *DefaultRequestLog) Status(_ context.Context, s int)

Status logs the response HTTP status code after processing completes.

func (*DefaultRequestLog) TreeSize added in v1.0.6 

func (dlr *DefaultRequestLog) TreeSize(_ context.Context, ts int64)

TreeSize logs request parameters.

type EntrypointName 

type EntrypointName string

EntrypointName identifies a CT entrypoint as defined in section 4 of RFC 6962.

type FrozenSTHGetter added in v1.1.0 

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

FrozenSTHGetter is an STHGetter implementation returning a constant STH.

func (*FrozenSTHGetter) GetSTH added in v1.1.0 

func (sg *FrozenSTHGetter) GetSTH(ctx context.Context) (*ct.SignedTreeHead, error)

GetSTH returns the frozen STH.

type Instance added in v1.1.0 

type Instance struct {
	Handlers  PathHandlers
	STHGetter STHGetter
	// contains filtered or unexported fields
}

Instance is a set up log/mirror instance. It must be created with the SetUpInstance call.

func SetUpInstance 

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 (*Instance) GetPublicKey added in v1.1.5 

func (i *Instance) GetPublicKey() crypto.PublicKey

GetPublicKey returns the public key from the instance's signer.

func (*Instance) RunUpdateSTH added in v1.1.0 

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.

type InstanceOptions added in v1.0.5 

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
}

InstanceOptions describes the options for a log instance.

type LogBackendMap added in v1.0.21 

type LogBackendMap = map[string]*configpb.LogBackend

LogBackendMap is a map from log backend names to LogBackend objects.

func BuildLogBackendMap added in v1.0.21 

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 added in v1.0.4 

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.

type LogSTHGetter added in v1.0.21 

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

LogSTHGetter is an STHGetter implementation for regular (non-mirror) logs, i.e. logs that have their own key and actively sign STHs.

func (*LogSTHGetter) GetSTH added in v1.0.21 

func (sg *LogSTHGetter) GetSTH(ctx context.Context) (*ct.SignedTreeHead, error)

GetSTH retrieves and builds a tree head structure for the given log. nolint:staticcheck

type MirrorSTHGetter added in v1.0.21 

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

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.

func (*MirrorSTHGetter) GetSTH added in v1.0.21 

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.

type MirrorSTHStorage added in v1.0.21 

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)
}

MirrorSTHStorage provides STHs of a source log to be served from a mirror.

type PathHandlers 

type PathHandlers map[string]AppHandler

PathHandlers maps from a path to the relevant AppHandler instance.

type RequestLog added in v1.0.6 

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)
}

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 STHGetter added in v1.0.21 

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)
}

STHGetter provides latest STHs for a log.

type SignatureCache added in v1.0.21 

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

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).

func (*SignatureCache) GetSignature added in v1.0.21 

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 (*SignatureCache) SetSignature added in v1.0.21 

func (sc *SignatureCache) SetSignature(input []byte, sig ct.DigitallySigned)

SetSignature associates the signature with the given bytes input.

type ValidatedLogConfig added in v1.0.21 

type ValidatedLogConfig struct {
	Config        *configpb.LogConfig
	PubKey        crypto.PublicKey
	PrivKey       proto.Message
	KeyUsages     []x509.ExtKeyUsage
	NotAfterStart *time.Time
	NotAfterLimit *time.Time
	FrozenSTH     *ct.SignedTreeHead
}

ValidatedLogConfig represents the LogConfig with the information that has been successfully parsed as a result of validating it.

func ValidateLogConfig added in v1.0.21 

func ValidateLogConfig(cfg *configpb.LogConfig) (*ValidatedLogConfig, error)

ValidateLogConfig checks that a single log config is valid. In particular:

  • A mirror log has a valid public key and no private key.
  • A non-mirror log has a private, and optionally a public key (both valid).
  • Each of NotBeforeStart and NotBeforeLimit, if set, is a valid timestamp proto. If both are set then NotBeforeStart <= NotBeforeLimit.
  • Merge delays (if present) are correct.
  • Frozen STH (if present) is correct and signed by the provided public key.

Returns the validated structures (useful to avoid double validation).

Source Files

View all Source files

Directories

Path Synopsis
The ct_server binary runs the CT personality.
 The ct_server binary runs the CT personality.
Package testonly contains code and data that should only be used by tests.
 Package testonly contains code and data that should only be used by tests.

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.