Certificate Transparency: Go Code
This repository holds Go code related to
Certificate Transparency (CT). The
repository requires Go version 1.9.
Repository Structure
The main parts of the repository are:
- Encoding libraries:
asn1/andx509/are forks of the upstream Goencoding/asn1and
crypto/x509libraries. 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.
Ourx509fork also includes code for working with the
pre-certificates defined in RFC 6962.tlsholds 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
ctpackage (in.) holds types and utilities for working
with CT data structures defined in
RFC 6962. client/andjsonclient/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.
- The top-level
- 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/ctclientallows interaction with a CT Log../ctutil/sctcheckallows SCTs (signed certificate timestamps) from a CT
Log to be verified../scanner/scanlogallows an existing CT Log to be scanned for certificates
of interest; please be polite when running this tool against a Log../x509util/certcheckallows display and verification of certificates./x509util/crlcheckallows display and verification of certificate
revocation lists (CRLs).
- Other libraries related to CT:
ctutil/holds utility functions for validating and verifying CT data
structures.loglist/has a library for reading
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. The
Travis configuration for the codebase is also useful reference
for the required tools and scripts, as it may be more up-to-date than this
document.
In order for the go generate command to work properly, the code must
be checked out to the following location:
$GOPATH/src/github.com/google/certificate-transparency-go
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 get -u github.com/golangci/golangci-lint/cmd/golangci-lint
cd $GOPATH/src/github.com/golangci/golangci-lint/cmd/golangci-lint
go install -ldflags "-X 'main.version=$(git describe --tags)' -X 'main.commit=$(git rev-parse --short HEAD)' -X 'main.date=$(date)'"
cd -
# 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.goimplementations. - 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:
mockgentool from https://github.com/golang/mockprotoc, Go support for protoc (see
documentation linked from the
protobuf site)
and run the following:
go generate -x ./... # hunts for //go:generate comments and runs them
Updating Vendor Code
The codebase includes a couple of external projects under the vendor/
subdirectory, to ensure that builds use a fixed version (typically because the
upstream repository does not guarantee back-compatibility between the tip
master branch and the current stable release). See
instructions in the Trillian repo
for how to update vendored subtrees.