RFC6962 section 2.1 requires a prefix byte on hash inputs for second preimage resistance.
const (
TreeLeafPrefix = byte(0x00)
TreeNodePrefix = byte(0x01)
)
URI paths for Log requests; see section 4. WARNING: Should match the API endpoints, with the "/ct/v1/" prefix. If changing these constants, may need to change those too.
const (
AddChainPath = "/ct/v1/add-chain"
AddPreChainPath = "/ct/v1/add-pre-chain"
GetSTHPath = "/ct/v1/get-sth"
GetEntriesPath = "/ct/v1/get-entries"
GetProofByHashPath = "/ct/v1/get-proof-by-hash"
GetSTHConsistencyPath = "/ct/v1/get-sth-consistency"
GetRootsPath = "/ct/v1/get-roots"
GetEntryAndProofPath = "/ct/v1/get-entry-and-proof"
AddJSONPath = "/ct/v1/add-json" // Experimental addition
)
AllowVerificationWithNonCompliantKeys may be set to true in order to allow SignatureVerifier to use keys which are technically non-compliant with RFC6962.
var AllowVerificationWithNonCompliantKeys = false
func IsPreIssuer(issuer *x509.Certificate) bool
IsPreIssuer indicates whether a certificate is a pre-cert issuer with the specific certificate transparency extended key usage.
func LeafHashForLeaf(leaf *MerkleTreeLeaf) ([sha256.Size]byte, error)
LeafHashForLeaf returns the leaf hash for a Merkle tree leaf.
func PublicKeyFromB64(b64PubKey string) (crypto.PublicKey, error)
PublicKeyFromB64 parses a base64-encoded public key.
func SerializeSCTSignatureInput(sct SignedCertificateTimestamp, entry LogEntry) ([]byte, error)
SerializeSCTSignatureInput serializes the passed in sct and log entry into the correct format for signing.
func SerializeSTHSignatureInput(sth SignedTreeHead) ([]byte, error)
SerializeSTHSignatureInput serializes the passed in STH into the correct format for signing.
func TimestampToTime(ts uint64) time.Time
TimestampToTime converts a timestamp in the style of RFC 6962 (milliseconds since UNIX epoch) to a Go Time.
APIEndpoint is a string that represents one of the Certificate Transparency Log API endpoints.
type APIEndpoint string
Certificate Transparency Log API endpoints; see section 4. WARNING: Should match the URI paths without the "/ct/v1/" prefix. If changing these constants, may need to change those too.
const (
AddChainStr APIEndpoint = "add-chain"
AddPreChainStr APIEndpoint = "add-pre-chain"
GetSTHStr APIEndpoint = "get-sth"
GetEntriesStr APIEndpoint = "get-entries"
GetProofByHashStr APIEndpoint = "get-proof-by-hash"
GetSTHConsistencyStr APIEndpoint = "get-sth-consistency"
GetRootsStr APIEndpoint = "get-roots"
GetEntryAndProofStr APIEndpoint = "get-entry-and-proof"
)
ASN1Cert type for holding the raw DER bytes of an ASN.1 Certificate (section 3.1).
type ASN1Cert struct {
Data []byte `tls:"minlen:1,maxlen:16777215"`
}
AddChainRequest represents the JSON request body sent to the add-chain and add-pre-chain POST methods from sections 4.1 and 4.2.
type AddChainRequest struct {
Chain [][]byte `json:"chain"`
}
AddChainResponse represents the JSON response to the add-chain and add-pre-chain POST methods. An SCT represents a Log's promise to integrate a [pre-]certificate into the log within a defined period of time.
type AddChainResponse struct {
SCTVersion Version `json:"sct_version"` // SCT structure version
ID []byte `json:"id"` // Log ID
Timestamp uint64 `json:"timestamp"` // Timestamp of issuance
Extensions string `json:"extensions"` // Holder for any CT extensions
Signature []byte `json:"signature"` // Log signature for this SCT
}
func (r *AddChainResponse) ToSignedCertificateTimestamp() (*SignedCertificateTimestamp, error)
ToSignedCertificateTimestamp creates a SignedCertificateTimestamp from the AddChainResponse.
AddJSONRequest represents the JSON request body sent to the add-json POST method. The corresponding response re-uses AddChainResponse. This is an experimental addition not covered by RFC6962.
type AddJSONRequest struct {
Data interface{} `json:"data"`
}
AuditPath represents a CT inclusion proof (see sections 2.1.1 and 4.5).
type AuditPath []MerkleTreeNode
CTExtensions is a representation of the raw bytes of any CtExtension structure (see section 3.2). nolint: revive
type CTExtensions []byte // tls:"minlen:0,maxlen:65535"`
CertificateChain holds a chain of certificates, as returned as extra data for get-entries (section 4.6).
type CertificateChain struct {
Entries []ASN1Cert `tls:"minlen:0,maxlen:16777215"`
}
CertificateTimestamp is the collection of data that the signature in an SCT is over; see section 3.2.
type CertificateTimestamp struct {
SCTVersion Version `tls:"maxval:255"`
SignatureType SignatureType `tls:"maxval:255"`
Timestamp uint64
EntryType LogEntryType `tls:"maxval:65535"`
X509Entry *ASN1Cert `tls:"selector:EntryType,val:0"`
PrecertEntry *PreCert `tls:"selector:EntryType,val:1"`
JSONEntry *JSONDataEntry `tls:"selector:EntryType,val:32768"`
Extensions CTExtensions `tls:"minlen:0,maxlen:65535"`
}
ConsistencyProof represents a CT consistency proof (see sections 2.1.2 and 4.4).
type ConsistencyProof []MerkleTreeNode
DigitallySigned is a local alias for tls.DigitallySigned so that we can attach a MarshalJSON method.
type DigitallySigned tls.DigitallySigned
func (d DigitallySigned) Base64String() (string, error)
Base64String returns the base64 representation of the DigitallySigned struct.
func (d *DigitallySigned) FromBase64String(b64 string) error
FromBase64String populates the DigitallySigned structure from the base64 data passed in. Returns an error if the base64 data is invalid.
func (d DigitallySigned) MarshalJSON() ([]byte, error)
MarshalJSON implements the json.Marshaller interface.
func (d *DigitallySigned) UnmarshalJSON(b []byte) error
UnmarshalJSON implements the json.Unmarshaler interface.
GetEntriesResponse represents the JSON response to the get-entries GET method from section 4.6.
type GetEntriesResponse struct {
Entries []LeafEntry `json:"entries"` // the list of returned entries
}
GetEntryAndProofResponse represents the JSON response to the get-entry-and-proof GET method from section 4.8. (The corresponding GET request has parameters 'leaf_index' and 'tree_size'.)
type GetEntryAndProofResponse struct {
LeafInput []byte `json:"leaf_input"` // the entry itself
ExtraData []byte `json:"extra_data"` // any chain provided when the entry was added to the log
AuditPath [][]byte `json:"audit_path"` // the corresponding proof
}
GetProofByHashResponse represents the JSON response to the get-proof-by-hash GET method from section 4.5. (The corresponding GET request has parameters 'hash' and 'tree_size'.)
type GetProofByHashResponse struct {
LeafIndex int64 `json:"leaf_index"` // The 0-based index of the end entity corresponding to the "hash" parameter.
AuditPath [][]byte `json:"audit_path"` // An array of base64-encoded Merkle Tree nodes proving the inclusion of the chosen certificate.
}
GetRootsResponse represents the JSON response to the get-roots GET method from section 4.7.
type GetRootsResponse struct {
Certificates []string `json:"certificates"`
}
GetSTHConsistencyResponse represents the JSON response to the get-sth-consistency GET method from section 4.4. (The corresponding GET request has parameters 'first' and 'second'.)
type GetSTHConsistencyResponse struct {
Consistency [][]byte `json:"consistency"`
}
GetSTHResponse represents the JSON response to the get-sth GET method from section 4.3.
type GetSTHResponse struct {
TreeSize uint64 `json:"tree_size"` // Number of certs in the current tree
Timestamp uint64 `json:"timestamp"` // Time that the tree was created
SHA256RootHash []byte `json:"sha256_root_hash"` // Root hash of the tree
TreeHeadSignature []byte `json:"tree_head_signature"` // Log signature for this STH
}
func (r *GetSTHResponse) ToSignedTreeHead() (*SignedTreeHead, error)
ToSignedTreeHead creates a SignedTreeHead from the GetSTHResponse.
JSONDataEntry holds arbitrary data.
type JSONDataEntry struct {
Data []byte `tls:"minlen:0,maxlen:1677215"`
}
LeafEntry represents a leaf in the Log's Merkle tree, as returned by the get-entries GET method from section 4.6.
type LeafEntry struct {
// LeafInput is a TLS-encoded MerkleTreeLeaf
LeafInput []byte `json:"leaf_input"`
// ExtraData holds (unsigned) extra data, normally the cert validation chain.
ExtraData []byte `json:"extra_data"`
}
LeafInput represents a serialized MerkleTreeLeaf structure.
type LeafInput []byte
LogEntry represents the (parsed) contents of an entry in a CT log. This is described in section 3.1, but note that this structure does *not* match the TLS structure defined there (the TLS structure is never used directly in RFC6962).
type LogEntry struct {
Index int64
Leaf MerkleTreeLeaf
// Exactly one of the following three fields should be non-empty.
X509Cert *x509.Certificate // Parsed X.509 certificate
Precert *Precertificate // Extracted precertificate
JSONData []byte
// Chain holds the issuing certificate chain, starting with the
// issuer of the leaf certificate / pre-certificate.
Chain []ASN1Cert
}
func LogEntryFromLeaf(index int64, leaf *LeafEntry) (*LogEntry, error)
LogEntryFromLeaf converts a LeafEntry object (which has the raw leaf data after JSON parsing) into a LogEntry object (which includes x509.Certificate objects, after TLS and ASN.1 parsing).
Note that this function may return a valid LogEntry object and a non-nil error value, when the error indicates a non-fatal parsing error.
LogEntryType represents the LogEntryType enum from section 3.1:
enum { x509_entry(0), precert_entry(1), (65535) } LogEntryType;
type LogEntryType tls.Enum // tls:"maxval:65535"
LogEntryType constants from section 3.1.
const (
X509LogEntryType LogEntryType = 0
PrecertLogEntryType LogEntryType = 1
)
func (e LogEntryType) String() string
LogID holds the hash of the Log's public key (section 3.2). TODO(pphaneuf): Users should be migrated to the one in the logid package.
type LogID struct {
KeyID [sha256.Size]byte
}
MerkleLeafType represents the MerkleLeafType enum from section 3.4:
enum { timestamped_entry(0), (255) } MerkleLeafType;
type MerkleLeafType tls.Enum // tls:"maxval:255"
TimestampedEntryLeafType is the only defined MerkleLeafType constant from section 3.4.
const TimestampedEntryLeafType MerkleLeafType = 0 // Entry type for an SCT
func (m MerkleLeafType) String() string
MerkleTreeLeaf represents the deserialized structure of the hash input for the leaves of a log's Merkle tree; see section 3.4.
type MerkleTreeLeaf struct {
Version Version `tls:"maxval:255"`
LeafType MerkleLeafType `tls:"maxval:255"`
TimestampedEntry *TimestampedEntry `tls:"selector:LeafType,val:0"`
}
func CreateX509MerkleTreeLeaf(cert ASN1Cert, timestamp uint64) *MerkleTreeLeaf
CreateX509MerkleTreeLeaf generates a MerkleTreeLeaf for an X509 cert
func MerkleTreeLeafForEmbeddedSCT(chain []*x509.Certificate, timestamp uint64) (*MerkleTreeLeaf, error)
MerkleTreeLeafForEmbeddedSCT generates a MerkleTreeLeaf from a chain and an SCT timestamp, where the leaf certificate at chain[0] is a certificate that contains embedded SCTs. It is assumed that the timestamp provided is from one of the SCTs embedded within the leaf certificate.
func MerkleTreeLeafFromChain(chain []*x509.Certificate, etype LogEntryType, timestamp uint64) (*MerkleTreeLeaf, error)
MerkleTreeLeafFromChain generates a MerkleTreeLeaf from a chain and timestamp.
func MerkleTreeLeafFromRawChain(rawChain []ASN1Cert, etype LogEntryType, timestamp uint64) (*MerkleTreeLeaf, error)
MerkleTreeLeafFromRawChain generates a MerkleTreeLeaf from a chain (in DER-encoded form) and timestamp.
func (m *MerkleTreeLeaf) Precertificate() (*x509.Certificate, error)
Precertificate returns the X.509 Precertificate contained within the MerkleTreeLeaf.
The returned precertificate is embedded in an x509.Certificate, but is in the form stored internally in the log rather than the original submitted form (i.e. it does not include the poison extension and any changes to reflect the final certificate's issuer have been made; see x509.BuildPrecertTBS).
func (m *MerkleTreeLeaf) X509Certificate() (*x509.Certificate, error)
X509Certificate returns the X.509 Certificate contained within the MerkleTreeLeaf.
MerkleTreeNode represents an internal node in the CT tree.
type MerkleTreeNode []byte
PreCert represents a Precertificate (section 3.2).
type PreCert struct {
IssuerKeyHash [sha256.Size]byte
TBSCertificate []byte `tls:"minlen:1,maxlen:16777215"` // DER-encoded TBSCertificate
}
PrecertChainEntry holds an precertificate together with a validation chain for it; see section 3.1.
type PrecertChainEntry struct {
PreCertificate ASN1Cert `tls:"minlen:1,maxlen:16777215"`
CertificateChain []ASN1Cert `tls:"minlen:0,maxlen:16777215"`
}
Precertificate represents the parsed CT Precertificate structure.
type Precertificate struct {
// DER-encoded pre-certificate as originally added, which includes a
// poison extension and a signature generated over the pre-cert by
// the pre-cert issuer (which might differ from the issuer of the final
// cert, see RFC6962 s3.1).
Submitted ASN1Cert
// SHA256 hash of the issuing key
IssuerKeyHash [sha256.Size]byte
// Parsed TBSCertificate structure, held in an x509.Certificate for convenience.
TBSCertificate *x509.Certificate
}
RawLogEntry represents the (TLS-parsed) contents of an entry in a CT log.
type RawLogEntry struct {
// Index is a position of the entry in the log.
Index int64
// Leaf is a parsed Merkle leaf hash input.
Leaf MerkleTreeLeaf
// Cert is:
// - A certificate if Leaf.TimestampedEntry.EntryType is X509LogEntryType.
// - A precertificate if Leaf.TimestampedEntry.EntryType is
// PrecertLogEntryType, in the form of a DER-encoded Certificate as
// originally added (which includes the poison extension and a signature
// generated over the pre-cert by the pre-cert issuer).
// - Empty otherwise.
Cert ASN1Cert
// Chain is the issuing certificate chain starting with the issuer of Cert,
// or an empty slice if Cert is empty.
Chain []ASN1Cert
}
func RawLogEntryFromLeaf(index int64, entry *LeafEntry) (*RawLogEntry, error)
RawLogEntryFromLeaf converts a LeafEntry object (which has the raw leaf data after JSON parsing) into a RawLogEntry object (i.e. a TLS-parsed structure).
func (rle *RawLogEntry) ToLogEntry() (*LogEntry, error)
ToLogEntry converts RawLogEntry to a LogEntry, which includes an x509-parsed (pre-)certificate.
Note that this function may return a valid LogEntry object and a non-nil error value, when the error indicates a non-fatal parsing error.
SHA256Hash represents the output from the SHA256 hash function.
type SHA256Hash [sha256.Size]byte
func PublicKeyFromPEM(b []byte) (crypto.PublicKey, SHA256Hash, []byte, error)
PublicKeyFromPEM parses a PEM formatted block and returns the public key contained within and any remaining unread bytes, or an error.
func (s SHA256Hash) Base64String() string
Base64String returns the base64 representation of this SHA256Hash.
func (s *SHA256Hash) FromBase64String(b64 string) error
FromBase64String populates the SHA256 struct with the contents of the base64 data passed in.
func (s SHA256Hash) MarshalJSON() ([]byte, error)
MarshalJSON implements the json.Marshaller interface for SHA256Hash.
func (s *SHA256Hash) UnmarshalJSON(b []byte) error
UnmarshalJSON implements the json.Unmarshaller interface.
SignatureType differentiates STH signatures from SCT signatures, see section 3.2.
enum { certificate_timestamp(0), tree_hash(1), (255) } SignatureType;
type SignatureType tls.Enum // tls:"maxval:255"
SignatureType constants from section 3.2.
const (
CertificateTimestampSignatureType SignatureType = 0
TreeHashSignatureType SignatureType = 1
)
func (st SignatureType) String() string
SignatureVerifier can verify signatures on SCTs and STHs
type SignatureVerifier struct {
PubKey crypto.PublicKey
}
func NewSignatureVerifier(pk crypto.PublicKey) (*SignatureVerifier, error)
NewSignatureVerifier creates a new SignatureVerifier using the passed in PublicKey.
func (s SignatureVerifier) VerifySCTSignature(sct SignedCertificateTimestamp, entry LogEntry) error
VerifySCTSignature verifies that the SCT's signature is valid for the given LogEntry.
func (s SignatureVerifier) VerifySTHSignature(sth SignedTreeHead) error
VerifySTHSignature verifies that the STH's signature is valid.
func (s SignatureVerifier) VerifySignature(data []byte, sig tls.DigitallySigned) error
VerifySignature verifies the given signature sig matches the data.
SignedCertificateTimestamp represents the structure returned by the add-chain and add-pre-chain methods after base64 decoding; see sections 3.2, 4.1 and 4.2.
type SignedCertificateTimestamp struct {
SCTVersion Version `tls:"maxval:255"`
LogID LogID
Timestamp uint64
Extensions CTExtensions `tls:"minlen:0,maxlen:65535"`
Signature DigitallySigned // Signature over TLS-encoded CertificateTimestamp
}
func (s SignedCertificateTimestamp) String() string
SignedTreeHead represents the structure returned by the get-sth CT method after base64 decoding; see sections 3.5 and 4.3.
type SignedTreeHead struct {
Version Version `json:"sth_version"` // The version of the protocol to which the STH conforms
TreeSize uint64 `json:"tree_size"` // The number of entries in the new tree
Timestamp uint64 `json:"timestamp"` // The time at which the STH was created
SHA256RootHash SHA256Hash `json:"sha256_root_hash"` // The root hash of the log's Merkle tree
TreeHeadSignature DigitallySigned `json:"tree_head_signature"` // Log's signature over a TLS-encoded TreeHeadSignature
LogID SHA256Hash `json:"log_id"` // The SHA256 hash of the log's public key
}
func (s SignedTreeHead) String() string
TimestampedEntry is part of the MerkleTreeLeaf structure; see section 3.4.
type TimestampedEntry struct {
Timestamp uint64
EntryType LogEntryType `tls:"maxval:65535"`
X509Entry *ASN1Cert `tls:"selector:EntryType,val:0"`
PrecertEntry *PreCert `tls:"selector:EntryType,val:1"`
JSONEntry *JSONDataEntry `tls:"selector:EntryType,val:32768"`
Extensions CTExtensions `tls:"minlen:0,maxlen:65535"`
}
TreeHeadSignature holds the data over which the signature in an STH is generated; see section 3.5
type TreeHeadSignature struct {
Version Version `tls:"maxval:255"`
SignatureType SignatureType `tls:"maxval:255"` // == TreeHashSignatureType
Timestamp uint64
TreeSize uint64
SHA256RootHash SHA256Hash
}
Version represents the Version enum from section 3.2:
enum { v1(0), (255) } Version;
type Version tls.Enum // tls:"maxval:255"
CT Version constants from section 3.2.
const (
V1 Version = 0
)
func (v Version) String() string
| Name | Synopsis |
|---|---|
| .. | |
| asn1 | Package asn1 implements parsing of DER-encoded ASN.1 data structures, as defined in ITU-T Rec X.690. |
| client | Package client is a CT log client implementation and contains types and code for interacting with RFC6962-compliant CT Log instances. |
| configpb | |
| ctclient | ctclient is a command-line utility for interacting with CT logs. |
| cmd | Package cmd implements subcommands of ctclient, the command-line utility for interacting with CT logs. |
| ctpolicy | Package ctpolicy contains structs describing CT policy requirements and corresponding logic. |
| ctutil | Package ctutil contains utilities for Certificate Transparency. |
| sctcheck | sctcheck is a utility to show and check embedded SCTs (Signed Certificate Timestamps) in certificates. |
| sctscan | sctscan is a utility to scan a CT log and check embedded SCTs (Signed Certificate Timestamps) in certificates in the log. |
| fixchain | Package fixchain holds code to help fix the validation chains for certificates. |
| chainfix | chainfix is a utility program for fixing the validation chains for certificates. |
| gossip | |
| minimal | |
| x509ext | Package x509ext holds extensions types and values for minimal gossip. |
| jsonclient | Package jsonclient provides a simple client for fetching and parsing JSON CT structures from a log. |
| logid | Package logid provides a type and accompanying helpers for manipulating log IDs. |
| loglist3 | Package loglist3 allows parsing and searching of the master CT Log list. |
| preload | Package preload holds code for adding batches of certificates to CT logs. |
| dumpscts | Dumpscts prints out SCTs written to a file by the preloader command in the ../preloader directory. |
| preloader | Binary preloader submits certificates that may not already be present in CT Logs. |
| scanner | Package scanner holds code for iterating through the contents of a CT log. |
| scanlog | Binary scanlog allows an existing CT Log to be scanned for certificates of interest. |
| schedule | Package schedule provides support for periodically running a function. |
| submission | Package submission contains code and structs for certificates submission proxy. |
| hammer | Hammer tool sends multiple add-pre-chain requests to Submission proxy at the same time. |
| server | The submission_server runs (pre-)certs multi-Log submission complying with CT-policy provided. |
| tls | Package tls implements functionality for dealing with TLS-encoded data, as defined in RFC 5246. |
| tools | Package tools tracks dependencies on binaries not otherwise referenced in this codebase. |
| trillian | |
| ctfe | 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. |
| configpb | |
| ct_server | The ct_server binary runs the CT personality. |
| testonly | Package testonly contains code and data that should only be used by tests. |
| integration | Package integration holds test-only code for running tests on an integrated system of the CT personality and a Trillian log. |
| ct_hammer | ct_hammer is a stress/load test for a CT log. |
| migrillian | Migrillian tool transfers certs from CT logs to Trillian pre-ordered logs in the same order. |
| configpb | |
| core | Package core provides transport-agnostic implementation of Migrillian tool. |
| mockclient | Package mockclient provides a mockable version of the Trillian log client API. |
| util | Package util provides general utility functions for the CT personality. |
| x509 | Package x509 parses X.509-encoded keys and certificates. |
| pkix | Package pkix contains shared, low level structures used for ASN.1 parsing and serialization of X.509 certificates, CRL and OCSP. |
| x509util | Package x509util includes utility code for working with X.509 certificates from the x509 package. |
| certcheck | certcheck is a utility to show and check the contents of certificates. |
| crlcheck | crlcheck is a utility to show and check the contents of certificate revocation lists (CRLs). |