diff options
Diffstat (limited to 'vendor/github.com/google/certificate-transparency-go/README.md')
| -rw-r--r-- | vendor/github.com/google/certificate-transparency-go/README.md | 118 |
1 files changed, 47 insertions, 71 deletions
diff --git a/vendor/github.com/google/certificate-transparency-go/README.md b/vendor/github.com/google/certificate-transparency-go/README.md index 6b71eaa987..7284bb86d7 100644 --- a/vendor/github.com/google/certificate-transparency-go/README.md +++ b/vendor/github.com/google/certificate-transparency-go/README.md @@ -6,14 +6,14 @@ This repository holds Go code related to [Certificate Transparency](https://www.certificate-transparency.org/) (CT). The -repository requires Go version 1.9. +repository requires Go version 1.17. - [Repository Structure](#repository-structure) - [Trillian CT Personality](#trillian-ct-personality) - [Working on the Code](#working-on-the-code) + - [Running Codebase Checks](#running-codebase-checks) - [Rebuilding Generated Code](#rebuilding-generated-code) - [Updating Vendor Code](#updating-vendor-code) - - [Running Codebase Checks](#running-codebase-checks) ## Repository Structure @@ -29,57 +29,44 @@ The main parts of the repository are: [pre-certificates defined in RFC 6962](https://tools.ietf.org/html/rfc6962#section-3.1). - `tls` holds a library for processing TLS-encoded data as described in [RFC 5246](https://tools.ietf.org/html/rfc5246). - - `x509util` provides additional utilities for dealing with + - `x509util/` provides additional utilities for dealing with `x509.Certificate`s. - CT client libraries: - The top-level `ct` package (in `.`) holds types and utilities for working with CT data structures defined in [RFC 6962](https://tools.ietf.org/html/rfc6962). - `client/` and `jsonclient/` hold libraries that allow access to CT Logs - via entrypoints described in + via HTTP entrypoints described in [section 4 of RFC 6962](https://tools.ietf.org/html/rfc6962#section-4). + - `dnsclient/` has a library that allows access to CT Logs over + [DNS](https://github.com/google/certificate-transparency-rfcs/blob/master/dns/draft-ct-over-dns.md). - `scanner/` holds a library for scanning the entire contents of an existing CT Log. + - CT Personality for [Trillian](https://github.com/google/trillian): + - `trillian/` holds code that allows a Certificate Transparency Log to be + run using a Trillian Log as its back-end -- see + [below](#trillian-ct-personality). - Command line tools: - - `./client/ctclient` allows interaction with a CT Log + - `./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). - - CT Personality for [Trillian](https://github.com/google/trillian): - - `trillian/` holds code that allows a Certificate Transparency Log to be - run using a Trillian Log as its back-end -- see - [below](#trillian-ct-personality). + - 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](https://groups.google.com/a/chromium.org/g/ct-policy/c/IdbrdAcDQto/m/i5KPyzYwBAAJ). ## Trillian CT Personality The `trillian/` subdirectory holds code and scripts for running a CT Log based -on the [Trillian](https://github.com/google/trillian) general transparency Log. - -The main code for the CT personality is held in `trillian/ctfe`; this code -responds to HTTP requests on the -[CT API paths](https://tools.ietf.org/html/rfc6962#section-4) and translates -them to the equivalent gRPC API requests to the Trillian Log. - -This obviously relies on the gRPC API definitions at -`github.com/google/trillian`; the code also uses common libraries from the -Trillian project for: - - exposing monitoring and statistics via an `interface` and corresponding - Prometheus implementation (`github.com/google/trillian/monitoring/...`) - - dealing with cryptographic keys (`github.com/google/trillian/crypto/...`). - -The `trillian/integration/` directory holds scripts and tests for running the whole -system locally. In particular: - - `trillian/integration/ct_integration_test.sh` brings up local processes - running a Trillian Log server, signer and a CT personality, and exercises the - complete set of RFC 6962 API entrypoints. - - `trillian/integration/ct_hammer_test.sh` brings up a complete system and runs - a continuous randomized test of the CT entrypoints. - -These scripts require a local database instance to be configured as described -in the [Trillian instructions](https://github.com/google/trillian#mysql-setup). +on the [Trillian](https://github.com/google/trillian) general transparency Log, +and is [documented separately](trillian/README.md). ## Working on the Code @@ -90,48 +77,15 @@ dependencies and tools, described in the following sections. The for the required tools and scripts, as it may be more up-to-date than this document. -### Rebuilding Generated Code - -Some of the CT Go code is autogenerated from other files: - - - [Protocol buffer](https://developers.google.com/protocol-buffers/) message - definitions are converted to `.pb.go` implementations. - - A mock implementation of the Trillian gRPC API (in `trillian/mockclient`) is - created with [GoMock](https://github.com/golang/mock). - -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: - - - `mockgen` tool from https://github.com/golang/mock - - `protoc`, [Go support for protoc](https://github.com/golang/protobuf) (see - documentation linked from the - [protobuf site](https://github.com/google/protobuf)) - -and run the following: - -```bash -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](https://github.com/google/trillian#updating-vendor-code) -for how to update vendored subtrees. - - ### Running Codebase Checks The [`scripts/presubmit.sh`](scripts/presubmit.sh) script runs various tools -and tests over the codebase. +and tests over the codebase; please ensure this script passes before sending +pull requests for review. ```bash -# Install gometalinter and all linters -go get -u github.com/alecthomas/gometalinter -gometalinter --install +# Install golangci-lint +go install github.com/golangci/golangci-lint/cmd/golangci-lint@v1.46.1 # Run code generation, build, test and linters ./scripts/presubmit.sh @@ -140,5 +94,27 @@ gometalinter --install ./scripts/presubmit.sh --no-generate # Or just run the linters alone: -gometalinter --config=gometalinter.json ./... +golangci-lint run +``` + +### Rebuilding Generated Code + +Some of the CT Go code is autogenerated from other files: + +- [Protocol buffer](https://developers.google.com/protocol-buffers/) message + definitions are converted to `.pb.go` implementations. +- A mock implementation of the Trillian gRPC API (in `trillian/mockclient`) is + created with [GoMock](https://github.com/golang/mock). + +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`](./tools/tools.go) and `go.mod`). +- `protoc` tool: you'll need [version 3.12.4](https://github.com/protocolbuffers/protobuf/releases/tag/v3.12.4) installed, and `PATH` updated to include its `bin/` directory. + +With tools installed, run the following: + +```bash +go generate -x ./... # hunts for //go:generate comments and runs them ``` |