Categorygithub.com/google/certificate-transparency-go
modulepackage
1.3.1
Repository: https://github.com/google/certificate-transparency-go.git
Documentation: pkg.go.dev
Versions
1
Dependencies
13
Dependents
295
Files
728 SLOC

# README

Certificate Transparency: Go Code

Go Report Card GoDoc CodeQL workflow

This repository holds Go code related to Certificate Transparency (CT). The repository requires Go version 1.22.

Support

Repository Structure

The main parts of the repository are:

  • Encoding libraries:
    • asn1/ and x509/ are forks of the upstream Go encoding/asn1 and crypto/x509 libraries. We maintain separate forks of these packages because CT is intended to act as an observatory of certificates across the ecosystem; as such, we need to be able to process somewhat-malformed certificates that the stricter upstream code would (correctly) reject. Our x509 fork also includes code for working with the pre-certificates defined in RFC 6962.
    • tls holds a library for processing TLS-encoded data as described in RFC 5246.
    • x509util/ provides additional utilities for dealing with x509.Certificates.
  • CT client libraries:
    • The top-level ct package (in .) holds types and utilities for working with CT data structures defined in RFC 6962.
    • client/ and jsonclient/ hold libraries that allow access to CT Logs via HTTP entrypoints described in section 4 of RFC 6962.
    • dnsclient/ has a library that allows access to CT Logs over DNS.
    • scanner/ holds a library for scanning the entire contents of an existing CT Log.
  • CT Personality for Trillian:
    • trillian/ holds code that allows a Certificate Transparency Log to be run using a Trillian Log as its back-end -- see below.
  • Command line tools:
    • ./client/ctclient allows interaction with a CT Log.
    • ./ctutil/sctcheck allows SCTs (signed certificate timestamps) from a CT Log to be verified.
    • ./scanner/scanlog allows an existing CT Log to be scanned for certificates of interest; please be polite when running this tool against a Log.
    • ./x509util/certcheck allows display and verification of certificates
    • ./x509util/crlcheck allows display and verification of certificate revocation lists (CRLs).
  • Other libraries related to CT:
    • ctutil/ holds utility functions for validating and verifying CT data structures.
    • loglist3/ has a library for reading v3 JSON lists of CT Logs.

Trillian CT Personality

The trillian/ subdirectory holds code and scripts for running a CT Log based on the Trillian general transparency Log, and is documented separately.

Working on the Code

Developers who want to make changes to the codebase need some additional dependencies and tools, described in the following sections.

Running Codebase Checks

The scripts/presubmit.sh script runs various tools and tests over the codebase; please ensure this script passes before sending pull requests for review.

# Install golangci-lint
go install github.com/golangci/golangci-lint/cmd/[email protected]

# Run code generation, build, test and linters
./scripts/presubmit.sh

# Run build, test and linters but skip code generation
./scripts/presubmit.sh  --no-generate

# Or just run the linters alone:
golangci-lint run

Rebuilding Generated Code

Some of the CT Go code is autogenerated from other files:

  • Protocol buffer message definitions are converted to .pb.go implementations.
  • A mock implementation of the Trillian gRPC API (in trillian/mockclient) is created with GoMock.

Re-generating mock or protobuffer files is only needed if you're changing the original files; if you do, you'll need to install the prerequisites:

  • tools written in go can be installed with a single run of go install (courtesy of tools.go and go.mod).
  • protoc tool: you'll need version 3.20.1 installed, and PATH updated to include its bin/ directory.

With tools installed, run the following:

go generate -x ./...  # hunts for //go:generate comments and runs them

# Packages

Package asn1 implements parsing of DER-encoded ASN.1 data structures, as defined in ITU-T Rec X.690.
Package client is a CT log client implementation and contains types and code for interacting with RFC6962-compliant CT Log instances.
Package ctpolicy contains structs describing CT policy requirements and corresponding logic.
Package ctutil contains utilities for Certificate Transparency.
Package fixchain holds code to help fix the validation chains for certificates.
Package jsonclient provides a simple client for fetching and parsing JSON CT structures from a log.
Package logid provides a type and accompanying helpers for manipulating log IDs.
Package loglist3 allows parsing and searching of the master CT Log list.
Package preload holds code for adding batches of certificates to CT logs.
Package scanner holds code for iterating through the contents of a CT log.
Package schedule provides support for periodically running a function.
Package submission contains code and structs for certificates submission proxy.
Package tls implements functionality for dealing with TLS-encoded data, as defined in RFC 5246.
Package x509 parses X.509-encoded keys and certificates.
Package x509util includes utility code for working with X.509 certificates from the x509 package.

# Functions

CreateX509MerkleTreeLeaf generates a MerkleTreeLeaf for an X509 cert.
IsPreIssuer indicates whether a certificate is a pre-cert issuer with the specific certificate transparency extended key usage.
LeafHashForLeaf returns the leaf hash for a Merkle tree leaf.
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).
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.
MerkleTreeLeafFromChain generates a MerkleTreeLeaf from a chain and timestamp.
MerkleTreeLeafFromRawChain generates a MerkleTreeLeaf from a chain (in DER-encoded form) and timestamp.
NewSignatureVerifier creates a new SignatureVerifier using the passed in PublicKey.
PublicKeyFromB64 parses a base64-encoded public key.
PublicKeyFromPEM parses a PEM formatted block and returns the public key contained within and any remaining unread bytes, or an error.
RawLogEntryFromLeaf converts a LeafEntry object (which has the raw leaf data after JSON parsing) into a RawLogEntry object (i.e.
SerializeSCTSignatureInput serializes the passed in sct and log entry into the correct format for signing.
SerializeSTHSignatureInput serializes the passed in STH into the correct format for signing.
TimestampToTime converts a timestamp in the style of RFC 6962 (milliseconds since UNIX epoch) to a Go Time.

# Constants

URI paths for Log requests; see section 4.
Certificate Transparency Log API endpoints; see section 4.
Experimental addition.
URI paths for Log requests; see section 4.
Certificate Transparency Log API endpoints; see section 4.
SignatureType constants from section 3.2.
URI paths for Log requests; see section 4.
Certificate Transparency Log API endpoints; see section 4.
URI paths for Log requests; see section 4.
Certificate Transparency Log API endpoints; see section 4.
URI paths for Log requests; see section 4.
Certificate Transparency Log API endpoints; see section 4.
URI paths for Log requests; see section 4.
Certificate Transparency Log API endpoints; see section 4.
URI paths for Log requests; see section 4.
Certificate Transparency Log API endpoints; see section 4.
URI paths for Log requests; see section 4.
Certificate Transparency Log API endpoints; see section 4.
LogEntryType constants from section 3.1.
Entry type for an SCT.
SignatureType constants from section 3.2.
RFC6962 section 2.1 requires a prefix byte on hash inputs for second preimage resistance.
RFC6962 section 2.1 requires a prefix byte on hash inputs for second preimage resistance.
CT Version constants from section 3.2.
LogEntryType constants from section 3.1.

# Variables

AllowVerificationWithNonCompliantKeys may be set to true in order to allow SignatureVerifier to use keys which are technically non-compliant with RFC6962.

# Structs

AddChainRequest represents the JSON request body sent to the add-chain and add-pre-chain POST methods from sections 4.1 and 4.2.
AddChainResponse represents the JSON response to the add-chain and add-pre-chain POST methods.
AddJSONRequest represents the JSON request body sent to the add-json POST method.
ASN1Cert type for holding the raw DER bytes of an ASN.1 Certificate (section 3.1).
CertificateChain holds a chain of certificates, as returned as extra data for get-entries (section 4.6).
CertificateChainHash is an extended CertificateChain type with the IssuanceChainHash field added to store the hash of the Entries field of CertificateChain.
CertificateTimestamp is the collection of data that the signature in an SCT is over; see section 3.2.
GetEntriesResponse represents the JSON response to the get-entries GET method from section 4.6.
GetEntryAndProofResponse represents the JSON response to the get-entry-and-proof GET method from section 4.8.
GetProofByHashResponse represents the JSON response to the get-proof-by-hash GET method from section 4.5.
GetRootsResponse represents the JSON response to the get-roots GET method from section 4.7.
GetSTHConsistencyResponse represents the JSON response to the get-sth-consistency GET method from section 4.4.
GetSTHResponse represents the JSON response to the get-sth GET method from section 4.3.
JSONDataEntry holds arbitrary data.
LeafEntry represents a leaf in the Log's Merkle tree, as returned by the get-entries GET method from section 4.6.
LogEntry represents the (parsed) contents of an entry in a CT log.
LogID holds the hash of the Log's public key (section 3.2).
MerkleTreeLeaf represents the deserialized structure of the hash input for the leaves of a log's Merkle tree; see section 3.4.
PreCert represents a Precertificate (section 3.2).
PrecertChainEntry holds an precertificate together with a validation chain for it; see section 3.1.
PrecertChainEntryHash is an extended PrecertChainEntry type with the IssuanceChainHash field added to store the hash of the CertificateChain field of PrecertChainEntry.
Precertificate represents the parsed CT Precertificate structure.
RawLogEntry represents the (TLS-parsed) contents of an entry in a CT log.
SignatureVerifier can verify signatures on SCTs and STHs.
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.
SignedTreeHead represents the structure returned by the get-sth CT method after base64 decoding; see sections 3.5 and 4.3.
TimestampedEntry is part of the MerkleTreeLeaf structure; see section 3.4.
TreeHeadSignature holds the data over which the signature in an STH is generated; see section 3.5.

# Type aliases

APIEndpoint is a string that represents one of the Certificate Transparency Log API endpoints.
AuditPath represents a CT inclusion proof (see sections 2.1.1 and 4.5).
ConsistencyProof represents a CT consistency proof (see sections 2.1.2 and 4.4).
CTExtensions is a representation of the raw bytes of any CtExtension structure (see section 3.2).
DigitallySigned is a local alias for tls.DigitallySigned so that we can attach a MarshalJSON method.
LeafInput represents a serialized MerkleTreeLeaf structure.
LogEntryType represents the LogEntryType enum from section 3.1: enum { x509_entry(0), precert_entry(1), (65535) } LogEntryType;.
MerkleLeafType represents the MerkleLeafType enum from section 3.4: enum { timestamped_entry(0), (255) } MerkleLeafType;.
MerkleTreeNode represents an internal node in the CT tree.
SHA256Hash represents the output from the SHA256 hash function.
SignatureType differentiates STH signatures from SCT signatures, see section 3.2.
Version represents the Version enum from section 3.2: enum { v1(0), (255) } Version;.