trillian

Trillian: General Transparency NoteTrillian is in maintenance mode. The next generation of transparency logs uses Tiled APIs and are better supported by Tessera. We recommend that any new log operators first try Tessera. Community contributions to Trillian are still welcome, but please file an issue and/or swing by the Slack first for discussion! Overview Support Using the Code MySQL Setup Integration Tests Working on the Code Rebuilding Generated Code Updating Dependencies Running Codebase Checks Design Design Overview Personalities Log Mode Use Cases Certificate Transparency Log Overview Trillian is an implementation of the concepts described in the Verifiable Data Structures white paper, which in turn is an extension and generalisation of the ideas which underpin Certificate Transparency. Trillian implements a Merkle tree whose contents are served from a data storage layer, to allow scalability to extremely large trees. On top of this Merkle tree, Trillian provides the following: An append-only Log mode, analogous to the original Certificate Transparency logs. In this mode, the Merkle tree is effectively filled up from the left, giving a dense Merkle tree. Note that Trillian requires particular applications to provide their own personalities on top of the core transparent data store functionality. Certificate Transparency (CT) is the most well-known and widely deployed transparency application, and an implementation of CT as a Trillian personality is available in the certificate-transparency-go repo. Other examples of Trillian personalities are available in the trillian-examples repo. Support Mailing list: https://groups.google.com/forum/#!forum/trillian-transparency Slack: https://transparency-dev.slack.com/ (invitation) Using the Code The Trillian codebase is stable and is used in production by multiple organizations, including many large-scale Certificate Transparency log operators. Given this, we do not plan to add any new features to this version of Trillian, and will try to avoid any further incompatible code and schema changes but cannot guarantee that they will never be necessary. The current state of feature implementation is recorded in the Feature implementation matrix. To build and test Trillian you need: Go 1.26 or later (go 1.26 matches cloudbuild, and is preferred for developers that will be submitting PRs to this project). To run many of the tests (and production deployment) you need: MySQL or MariaDB to provide the data storage layer; see the MySQL Setup section. Note that this repository uses Go modules to manage dependencies; Go will fetch and install them automatically upon build/test. To fetch the code, dependencies, and build Trillian, run the following: git clone https://github.com/google/trillian.git cd trillian go build ./... To build slimmer Trillian binaries that only include the storage and quota implementations that you need, consider specifying build tags. To build and run tests, use: go test ./... The repository also includes multi-process integration tests, described in the Integration Tests section below. MySQL Setup To run Trillian's integration tests you need to have an instance of MySQL running and configured to: listen on the standard MySQL port 3306 (so mysql --host=127.0.0.1 --port=3306 connects OK) not require a password for the root user You can then set up the expected tables in a test database like so: ./scripts/resetdb.sh Warning: about to destroy and reset database 'test' Are you sure? y > Resetting DB... > Reset Complete Integration Tests Trillian includes an integration test suite to confirm basic end-to-end functionality, which can be run with: ./integration/integration_test.sh This runs a multi-process test: A test that starts a Trillian server in Log mode, together with a signer, logs many leaves, and checks they are integrated correctly. Deployment You can find instructions on how to deploy Trillian in deployment and examples/deployment directories. Working on the Code Developers who want to make changes to the Trillian codebase need some additional dependencies and tools, described in the following sections. The Cloud Build configuration and the scripts it depends on are also a useful reference for the required tools and scripts, as it may be more up-to-date than this document. Anyone wanting to add a new storage and/or quota implementation should understand how Trillian uses build tags. Rebuilding Generated Code Some of the Trillian Go code is autogenerated from other files: gRPC message structures are originally provided as protocol buffer message definitions. See also, https://grpc.io/docs/protoc-installation/. Some unit tests use mock implementations of interfaces; these are created from the real implementations by GoMock. Some enums have string-conversion methods (satisfying the fmt.Stringer interface) created using the stringer tool (go get golang.org/x/tools/cmd/stringer). Re-generating mock or protobuffer files is only needed if you're changing the original files. The recommended way to do this is by using the Docker image used by the Cloud Build: docker build -f ./integration/cloudbuild/testbase/Dockerfile -t trillian-builder . docker run -it --mount type=bind,src="$(pwd)",target=/src trillian-builder /bin/bash -c "cd /src; ./scripts/install_deps.sh; go generate -x ./..." These commands first create a docker image from the Dockerfile in this repo, and then launch a container based on this image with the local directory mounted. The correct versions of the tools are determined using the go.mod file in this repo, and these tools are installed. Finally, all of the generated files are regenerated and Docker exits. Alternatively, you can install the prerequisites locally: a series of tools, using go install to ensure that the versions are compatible and tested: cd $(go list -f '{{ .Dir }}' github.com/google/trillian); \ go install github.com/golang/mock/mockgen; \ go install google.golang.org