helloworld

README

helloworld

This is a basic example of how to use Trillian to implement the operations needed for a verifiable log. This means providing instantiations for two different actors:

• A personality, which acts a front-end for the (Trillian) log. In CT, for example, the personality is CTFE.
• A client, which interfaces with the personality; in Trillian, the client should never talk to the log directly. In CT, for example, the client might be an individual browser or a monitor.

This example intentionally avoids defining any interface between the client and personality, leaving only the gRPC interface between the personality and the (Trillian) log. In a real deployment it would be necessary to define an interface between the client and the personality, for example a RESTful API or gRPC.

In order to run the tests, it is necessary to first have a Trillian log running. Follow one of the two steps below:

Manual

Set up MySQL or MariaDB using MySQL setup. Then, in one terminal, run the following commands:

go run github.com/google/trillian/cmd/trillian_log_server --rpc_endpoint="localhost:50054" --http_endpoint="localhost:50055" &
go run github.com/google/trillian/cmd/trillian_log_signer --sequencer_interval="1s" --batch_size=500 --rpc_endpoint="localhost:50056" --http_endpoint="localhost:50057" --num_sequencers=1 --force_master &
# Trillian services are now running

export TREE_ID=$(go run github.com/google/trillian/cmd/createtree --admin_server=localhost:50054)

Docker

docker compose up -d
# Wait a second for MySQL to start up between these commands
curl https://raw.githubusercontent.com/google/trillian/master/storage/mysql/schema/storage.sql | docker exec -i helloworld-db-1 mysql -pzaphod -Dtest

Running the tests

After setting up the trillian environment using the Manual or Docker instructions:

Now, in another terminal run go build and then go test --tree_id=${TREE_ID}.
This runs three tests.

1. TestAppend ensures that checkpoints update properly on the personality side when new entries are appended to the log.
2. TestUpdate ensures that these updated checkpoints can be accepted by the client, after they are proved consistent with previous checkpoints.
3. TestIncl ensures that the client can be convinced about whether or not entries are in the log.

Documentation

Overview

Package helloworld runs a simple client, designed to interact with a personality.

Index

• type Client
  • func NewClient(prsn Personality, nv note.Verifier) Client
  • func (c *Client) UpdateChkpt(chkptNewRaw personality.SignedCheckpoint, pf *trillian.Proof) error
  • func (c Client) VerIncl(entry []byte, pf *trillian.Proof) bool
• type Personality

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is a verifier that maintains a checkpoint as state.

func NewClient

func NewClient(prsn Personality, nv note.Verifier) Client

NewClient creates a new client with an empty checkpoint and a given personality to talk to. In real usage, a client should persist this checkpoint across different runs to ensure consistency.

func (*Client) UpdateChkpt

func (c *Client) UpdateChkpt(chkptNewRaw personality.SignedCheckpoint, pf *trillian.Proof) error

UpdateChkpt allows a client to update its stored checkpoint. In a real use case it would be important for the client to check the signature contained in the checkpoint before verifying consistency.

func (Client) VerIncl

func (c Client) VerIncl(entry []byte, pf *trillian.Proof) bool

VerIncl allows the client to check inclusion of a given entry.

type Personality

type Personality interface {
	// Append stores an entry in the log and, once it is there, returns a
	// new checkpoint that commits to the new entry (in addition to all
	// previous ones).
	Append(ctx context.Context, entry []byte) (personality.SignedCheckpoint, error)

	// ProveIncl proves the inclusion of a given entry in a given checkpoint size.
	// It is the job of the client to verify this inclusion proof in order to convince
	// itself that the entry really has been included in the log.
	ProveIncl(ctx context.Context, cpSize uint64, entry []byte) (*trillian.Proof, error)

	// UpdateChkpt provides a new checkpoint along with a consistency proof to it
	// from the specified older checkpoint size.
	// Again, it is the job of the client to verify this consistency proof.
	UpdateChkpt(ctx context.Context, oldCPSize uint64) (personality.SignedCheckpoint, *trillian.Proof, error)
}

Personality is the front-end for the Trillian log.