1# Certificate Transparency: Go Code
2
3[](https://goreportcard.com/report/github.com/google/certificate-transparency-go)
4[](https://godoc.org/github.com/google/certificate-transparency-go)
5
6
7This repository holds Go code related to
8[Certificate Transparency](https://www.certificate-transparency.org/) (CT). The
9repository requires Go version 1.21.
10
11 - [Repository Structure](#repository-structure)
12 - [Trillian CT Personality](#trillian-ct-personality)
13 - [Working on the Code](#working-on-the-code)
14 - [Running Codebase Checks](#running-codebase-checks)
15 - [Rebuilding Generated Code](#rebuilding-generated-code)
16
17## Support
18
19- Slack: https://transparency-dev.slack.com/ ([invitation](https://join.slack.com/t/transparency-dev/shared_invite/zt-27pkqo21d-okUFhur7YZ0rFoJVIOPznQ))
20
21## Repository Structure
22
23The main parts of the repository are:
24
25 - Encoding libraries:
26 - `asn1/` and `x509/` are forks of the upstream Go `encoding/asn1` and
27 `crypto/x509` libraries. We maintain separate forks of these packages
28 because CT is intended to act as an observatory of certificates across the
29 ecosystem; as such, we need to be able to process somewhat-malformed
30 certificates that the stricter upstream code would (correctly) reject.
31 Our `x509` fork also includes code for working with the
32 [pre-certificates defined in RFC 6962](https://tools.ietf.org/html/rfc6962#section-3.1).
33 - `tls` holds a library for processing TLS-encoded data as described in
34 [RFC 5246](https://tools.ietf.org/html/rfc5246).
35 - `x509util/` provides additional utilities for dealing with
36 `x509.Certificate`s.
37 - CT client libraries:
38 - The top-level `ct` package (in `.`) holds types and utilities for working
39 with CT data structures defined in
40 [RFC 6962](https://tools.ietf.org/html/rfc6962).
41 - `client/` and `jsonclient/` hold libraries that allow access to CT Logs
42 via HTTP entrypoints described in
43 [section 4 of RFC 6962](https://tools.ietf.org/html/rfc6962#section-4).
44 - `dnsclient/` has a library that allows access to CT Logs over
45 [DNS](https://github.com/google/certificate-transparency-rfcs/blob/master/dns/draft-ct-over-dns.md).
46 - `scanner/` holds a library for scanning the entire contents of an existing
47 CT Log.
48 - CT Personality for [Trillian](https://github.com/google/trillian):
49 - `trillian/` holds code that allows a Certificate Transparency Log to be
50 run using a Trillian Log as its back-end -- see
51 [below](#trillian-ct-personality).
52 - Command line tools:
53 - `./client/ctclient` allows interaction with a CT Log.
54 - `./ctutil/sctcheck` allows SCTs (signed certificate timestamps) from a CT
55 Log to be verified.
56 - `./scanner/scanlog` allows an existing CT Log to be scanned for certificates
57 of interest; please be polite when running this tool against a Log.
58 - `./x509util/certcheck` allows display and verification of certificates
59 - `./x509util/crlcheck` allows display and verification of certificate
60 revocation lists (CRLs).
61 - Other libraries related to CT:
62 - `ctutil/` holds utility functions for validating and verifying CT data
63 structures.
64 - `loglist3/` has a library for reading
65 [v3 JSON lists of CT Logs](https://groups.google.com/a/chromium.org/g/ct-policy/c/IdbrdAcDQto/m/i5KPyzYwBAAJ).
66
67
68## Trillian CT Personality
69
70The `trillian/` subdirectory holds code and scripts for running a CT Log based
71on the [Trillian](https://github.com/google/trillian) general transparency Log,
72and is [documented separately](trillian/README.md).
73
74
75## Working on the Code
76
77Developers who want to make changes to the codebase need some additional
78dependencies and tools, described in the following sections.
79
80### Running Codebase Checks
81
82The [`scripts/presubmit.sh`](scripts/presubmit.sh) script runs various tools
83and tests over the codebase; please ensure this script passes before sending
84pull requests for review.
85
86```bash
87# Install golangci-lint
88go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.55.1
89
90# Run code generation, build, test and linters
91./scripts/presubmit.sh
92
93# Run build, test and linters but skip code generation
94./scripts/presubmit.sh --no-generate
95
96# Or just run the linters alone:
97golangci-lint run
98```
99
100### Rebuilding Generated Code
101
102Some of the CT Go code is autogenerated from other files:
103
104- [Protocol buffer](https://developers.google.com/protocol-buffers/) message
105 definitions are converted to `.pb.go` implementations.
106- A mock implementation of the Trillian gRPC API (in `trillian/mockclient`) is
107 created with [GoMock](https://github.com/golang/mock).
108
109Re-generating mock or protobuffer files is only needed if you're changing
110the original files; if you do, you'll need to install the prerequisites:
111
112- tools written in `go` can be installed with a single run of `go install`
113 (courtesy of [`tools.go`](./tools/tools.go) and `go.mod`).
114- `protoc` tool: you'll need [version 3.20.1](https://github.com/protocolbuffers/protobuf/releases/tag/v3.20.1) installed, and `PATH` updated to include its `bin/` directory.
115
116With tools installed, run the following:
117
118```bash
119go generate -x ./... # hunts for //go:generate comments and runs them
120```
View as plain text