No description or website provided.
Go PureBasic Shell Protocol Buffer Makefile
Latest commit 2fecef5 Jan 18, 2017 @codingllama codingllama committed on GitHub Update trillian.pb.go (#304)
Permalink
Failed to load latest commit information.
crypto Fix a bunch of warnings and potential bugs (#252) Nov 29, 2016
docs Fix image links (#275) Dec 20, 2016
examples Make generate protoc work locally Jan 18, 2017
extension Document how extensions work (#272) (#282) Dec 22, 2016
integration integration/ct: parameterize & use multi-server test Jan 17, 2017
log Fix comment typos Jan 13, 2017
merkle Use path from node to root for inclusion proofs (#292) Jan 17, 2017
mockclient Implement RPC for query by raw hash (#239) Nov 30, 2016
monitoring Fix a bunch of warnings and potential bugs (#252) Nov 29, 2016
scripts Pass args to reset script (#294) Jan 17, 2017
server Add reflection to vmap Jan 17, 2017
storage Merge pull request #300 from google/queueleaf Jan 18, 2017
testdata testdata: Generate 20 leaf certificates Dec 9, 2016
testonly testonly: add toy gRPC load balancer for tests Jan 17, 2017
util store log/map ID in context, output in diagnostics Nov 16, 2016
vmap Move hashers.go into crypto/ (#209) Nov 4, 2016
.gitignore Ignore swap files (#295) Jan 17, 2017
.travis.yml travis: install local protoc and regen .pb.go Dec 21, 2016
AUTHORS Initial commit to add some basics to repo May 31, 2016
CONTRIBUTING.md Initial commit to add some basics to repo May 31, 2016
CONTRIBUTORS Add phad to CONTRIBUTORS Sep 30, 2016
LICENSE Initial commit to add some basics to repo May 31, 2016
README.md Fix broken table of content link to 'use-cases' (#277) Dec 20, 2016
gen.go Place protoc output locally Jan 18, 2017
trillian.pb.go Update trillian.pb.go (#304) Jan 18, 2017
trillian.proto Make generate protoc work locally Jan 18, 2017
trillian_api.pb.go Make generate protoc work locally Jan 18, 2017
trillian_api.proto Place protoc output locally Jan 18, 2017

README.md

Trillian: General Transparency

Build Status

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 two modes:

  • 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.
  • A Map mode that allows transparent storage of arbitrary key:value pairs. In this mode, the key's hash is used to designate a particular leaf of a deep Merkle tree, giving a sparse Merkle tree. (A Trillian Map is an unordered map; it does not allow enumeration of the Map's keys.)

Note that Trillian requires particular applications to provide their own personalities on top of the core transparent data store functionality; example code for a certificate transparency log and for a log-derived map are included to help with this.

Working with the Code

WARNING: The Trillian codebase is still under development, and is not yet suitable for production use. Everything here is subject to change without notice – including APIs, database schemas, and code layout.

Requirements

You must have Go 1.7.1 installed, and MySQL or MariaDB is required to provide the data storage layer.

Other dependency requirements are then handled by the Go tools (i.e. with go get -d -v -t ./...).

Building

If you're not with the Go program of working within its own directory tree, then:

% cd <your favourite directory for git repos>
% git clone https://github.com/google/trillian.git
% ln -s `pwd`/trillian $GOPATH/src/github.com/google  # you may have to make this directory first
% cd trillian
% go get -d -v -t ./...
% go build ./...

If you are with the Go program, then you know what to do.

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.
  • Some unit tests use mock implementations of interfaces; these are created from the real implementations by GoMock.

Re-generating mock or protobuffer files is only needed if you're changing the original files; if you do, run the following command:

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

You'll need to have the following tools installed to do this:

MySQL Setup

To run Trillian, including for any of the 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 to require a password for the root user
  • not to include the ONLY_FULL_GROUP_BY SQL mode (this is enabled by default for MySQL versions >= 5.7 but can be disabled, e.g. with SET GLOBAL sql_mode=(SELECT REPLACE(@@sql_mode,'ONLY_FULL_GROUP_BY',''));).

You can then set up the expected tables in a test database like so:

% ./scripts/resetdb.sh
Completely wipe and reset database 'test'.
Are you sure? y

Unit Tests

Assuming MySQL is running locally, the following command runs all of the unit tests for the code, and should complete successfully:

% go test -v ./...

Integration Test

Trillian also includes an integration test to confirm basic end-to-end functionality, which can be run with:

% ./integration/integration_test.sh

This test starts a Trillian server in Map mode, sets various key:value pairs and checks they can be retrieved.

Design

Design Overview

Trillian is primarily implemented as a gRPC service; this service receives get/set requests over gRPC and retrieves the corresponding Merkle tree data from a separate storage layer (currently using MySQL), ensuring that the cryptographic properties of the tree are preserved along the way.

The Trillian service is multi-tenanted – a single Trillian installation can support multiple Merkle trees in parallel, distinguished by their TreeId – and operates in one of two modes:

  • Log mode: an append-only collection of items.
  • Map mode: a collection of key:value pairs.

In either case, Trillian's key transparency property is that cryptographic proofs of inclusion/consistency are available for data items added to the service.

Personalities

The Trillian service expects to be paired with additional code that is specific to the particular application of the transparent store; this is known as a personality.

The primary purpose of a personality is to implement admission critera for the store, so that only particular types of data are added to the store. For example, a certificate transparency log only accepts data items that are valid certificates; a "CT Log" personality would police this, so that the Trillian service can process all incoming data blindly.

A personality may also perform canonicalization on incoming data, to convert equivalent formulations of the same underlying data to a single canonical format, avoiding needless duplication. (For example, keys in JSON dictionaries could be sorted, or Unicode string data could be normalized.)

The per-application personality is also responsible for providing an externally-visible interface, typically over HTTP[S].

Note that a personality may need to implement its own data store, seperate from Trillian. In particular, if the personality does not completely trust Trillian, it needs to store the various things that Trillian signs in order to be able to detect problems (and so the personality effectively also acts as a monitor for Trillian).

Map Mode

Trillian in Map mode can be thought of as providing a key:value store, together with cryptographic transparency guarantees for that data.

When running in Map mode, Trillian provides a straightforward gRPC API with the following available operations:

  • GetSignedMapRoot returns information about the current root of the Merkle tree representing the Map, including a revision (see below), hash value, timestamp and signature.
  • GetLeaves returns leaf information for a specified set of key values, optionally as of a particular revision. The returned leaf information also includes inclusion proof data.
  • SetLeaves requests inclusion of specified key:value pairs into the Map; these will appear as the next revision of the Map.

(Documentation may be out-of-date; please check the protocol buffer message definitions for the definitive current API.)

Each SetLeaves request includes a batch of updates to the Map; once all of these updates have been applied, the Map has a new revision, with a new tree head for that revision. To allow historical queries, the API allows queries of the Map as of a particular revision.

TODO: add description of per-personality Mappers

TODO: add description of distribution: how many instances run, how distributed, how synchronized (master election), mention use of transactions as a fallback (in case of errors in master election).

Map components

Log Mode

When running in Log mode, Trillian provides a gRPC API whose operations are similar to those available for Certificate Transparency logs (cf. RFC 6962). These include:

  • GetLastestSignedLogRoot returns information about the current root of the Merkle tree for the log, including the tree size, hash value, timestamp and signature.
  • GetLeavesByHash and GetLeavesByIndex return leaf information for particular leaves, specified either by their hash value or index in the log.
  • QueueLeaves requests inclusion of specified items into the log.
  • GetInclusionProof, GetInclusionProofByHash and GetConsistencyProof return inclusion and consistency proof data.

In Log mode, Trillian includes an additional Signer component; this component periodically processes pending queued items and adds them to the Merkle tree, creating a new signed tree head as a result.

Log components

TODO: add description of distribution: how many instances run, how distributed etc.

Logged Map

As it currently stands, it is not possible to reliably monitor or audit a Trillian Map instance; key:value pairs can be modified and subsequently reset without anyone noticing.

A future plan to deal with this is to create a Logged Map, which combines a Trillian Map with a Trillian Log so that all published revisions of the Map have their signed tree head data appended to the corresponding Map.

Use Cases

Certificate Transparency Log

The most obvious application for Trillian in Log mode is to provide a certificate transparency (RFC 6962) Log. To do this, the CT Log personality needs to include all of the certificate-specific processing – in particular, checking that an item that has been suggested for inclusion is indeed a valid certificate that chains to an accepted root.

Verifiable Log-Derived Map

One useful application for Trillian in Map mode is to provide a verifiable log-derived map (VLDM), as described in the Verifiable Data Structures white paper (which uses the term 'log-backed map'). To do this, a VLDM personality would monitor the additions of entries to a Log, potentially external, and would write some kind of corresponding key:value data to a Trillian Map.

Clients of the VLDM are then able to verify that the entries in the Map they are shown are also seen by anyone auditing the Log for correct operation, which in turn allows the client to trust the key/value pairs returned by the Map.

A concrete example of this might be a VLDM that monitors a certificate transparency Log and builds a corresponding Map from domain names to the set of certificates associated with that domain.

The following table summarizes properties of data structures laid in the Verifiable Data Structures white paper. “Efficiently” means that a client can and should perform this validation themselves. “Full audit” means that to validate correctly, a client would need to download the entire dataset, and is something that in practice we expect a small number of dedicated auditors to perform, rather than being done by each client.

Verifiable Log Verifiable Map Verifiable Log-Derived Map
Prove inclusion of value Yes, efficiently Yes, efficiently Yes, efficiently
Prove non-inclusion of value Impractical Yes, efficiently Yes, efficiently
Retrieve provable value for key Impractical Yes, efficiently Yes, efficiently
Retrieve provable current value for key Impractical No Yes, efficiently
Prove append-only Yes, efficiently No Yes, efficiently [1].
Enumerate all entries Yes, by full audit Yes, by full audit Yes, by full audit
Prove correct operation Yes, efficiently No Yes, by full audit
Enable detection of split-view Yes, efficiently Yes, efficiently Yes, efficiently
  • [1] -- although full audit is required to verify complete correct operation