README
¶
Key Transparency
Key Transparency provides a lookup service for generic records and a public, tamper-proof audit log of all record changes. While being publicly auditable, individual records are only revealed in response to queries for specific IDs.
Key Transparency can be used as a public key discovery service to authenticate users and provides a mechanism to keep the service accountable. It can be used by account owners to reliably see what keys have been associated with their account, and it can be used by senders to see how long an account has been active and stable before trusting it.
Key Transparency is inspired by CONIKS and Certificate Transparency. It is a work-in-progress with the following milestones under development.
Key Transparency Client
Setup
- Install Go 1.13.
go get github.com/google/keytransparency/cmd/keytransparency-client
Client operations
Generate a private key
PASSWORD=[[YOUR-KEYSET-PASSWORD]]
keytransparency-client authorized-keys create-keyset --password=${PASSWORD}
keytransparency-client authorized-keys list-keyset --password=${PASSWORD}
The create-keyset command will create a .keyset file in the user's working directory.
To specify custom directory use --keyset-file or -k shortcut.
NB A default for the Key Transparency server URL is being used here. The default value is "35.202.56.9:443". The flag --kt-url may be used to specify the URL of Key Transparency server explicitly.
Publish the public key
- Get an OAuth client ID and download the generated JSON file to
client_secret.json.
keytransparency-client post user@domain.com \
--client-secret=client_secret.json \
--insecure \
--password=${PASSWORD} \
--data='dGVzdA==' #Base64
Get and verify a public key
keytransparency-client get <email> --insecure --verbose
✓ Commitment verified.
✓ VRF verified.
✓ Sparse tree proof verified.
✓ Signed Map Head signature verified.
CT ✓ STH signature verified.
CT ✓ Consistency proof verified.
CT New trusted STH: 2016-09-12 15:31:19.547 -0700 PDT
CT ✓ SCT signature verified. Saving SCT for future inclusion proof verification.
✓ Signed Map Head CT inclusion proof verified.
keys:<key:"app1" value:"test" >
Verify key history
keytransparency-client history <email> --insecure
Revision |Timestamp |Profile
4 |Mon Sep 12 22:23:54 UTC 2016 |keys:<key:"app1" value:"test" >
Checks
Running the server
- OpenSSL
- Docker
- Docker Engine 1.17.6+
docker version -f '{{.Server.APIVersion}}' - Docker Compose 1.11.0+
docker-compose --version
- Docker Engine 1.17.6+
go get github.com/google/keytransparency/...
go get github.com/google/trillian/...
cd $(go env GOPATH)/src/github.com/google/keytransparency
./scripts/prepare_server.sh -f
docker-compose -f docker-compose.yml docker-compose.prod.yml up
- Watch it Run
Development and Testing
Key Transparency and its Trillian backend use a MySQL database, which must be setup in order for the Key Transparency tests to work.
docker-compose up -d db will launch the database in the background.
Directory structure
The directory structure of Key Transparency is as follows:
- cmd: binaries
- keytransparency-client: Key Transparency CLI client.
- keytransparency-sequencer: Key Transparency backend.
- keytransparency-server: Key Transparency frontend.
- core: main library source code. Core libraries do not import impl.
- adminserver: private api for creating new directories.
- api: gRPC API definitions.
- crypto: verifiable random function and commitment implementations.
- directory: interface for retrieving directory info from storage.
- keyserver: keyserver implementation.
- mutator: "smart contract" implementation.
- sequencer: mutation executor.
- deploy: deployment configs:
- docker: init helper.
- kubernetes: kube deploy configs.
- prometheus: monitoring docker module.
- docs: documentation.
- impl: environment specific modules:
- authentication: authentication policy grpc interceptor.
- authorization: OAuth and fake auth grpc interceptor.
- integration: environment specific integration tests.
- sql: mysql implementations of storage modules.
- scripts: scripts
- deploy: deploy to Google Compute Engine.
Support
Directories
¶
| Path | Synopsis |
|---|---|
|
cmd
|
|
|
core
|
|
|
adminserver
Package adminserver contains the KeyTransparencyAdmin implementation
|
Package adminserver contains the KeyTransparencyAdmin implementation |
|
api/monitor/v1/monitor_go_proto
Package monitor_go_proto is a reverse proxy.
|
Package monitor_go_proto is a reverse proxy. |
|
api/v1/keytransparency_go_proto
Package keytransparency_go_proto is a reverse proxy.
|
Package keytransparency_go_proto is a reverse proxy. |
|
client
Package client is a client for communicating with the Key Server.
|
Package client is a client for communicating with the Key Server. |
|
client/gobindclient
Package gobindclient contains a gobind friendly implementation of a KeyTransparency Client able to make GetUser requests to a KT server and verify the soundness of the responses.
|
Package gobindclient contains a gobind friendly implementation of a KeyTransparency Client able to make GetUser requests to a KT server and verify the soundness of the responses. |
|
client/hammer
Package hammer sends multiple requests to Key Transparency at the same time.
|
Package hammer sends multiple requests to Key Transparency at the same time. |
|
client/multi
Package multi contains utilities for multiplexing io operations.
|
Package multi contains utilities for multiplexing io operations. |
|
client/tracker
Package tracker tracks log roots and verifies consistency proofs between them.
|
Package tracker tracks log roots and verifies consistency proofs between them. |
|
crypto/commitments
Package commitments implements a cryptographic commitment.
|
Package commitments implements a cryptographic commitment. |
|
crypto/tinkio
Package tinkio provides io helper functions for tink.
|
Package tinkio provides io helper functions for tink. |
|
crypto/vrf
Package vrf defines the interface to a verifiable random function.
|
Package vrf defines the interface to a verifiable random function. |
|
crypto/vrf/p256
Package p256 implements a verifiable random function using curve p256.
|
Package p256 implements a verifiable random function using curve p256. |
|
directory
Package directory stores multi-tenancy configuration information.
|
Package directory stores multi-tenancy configuration information. |
|
frontend
Package frontend implements the KeyTransaprencyFrontend service.
|
Package frontend implements the KeyTransaprencyFrontend service. |
|
integration
Package integration exports a set of unit tests that can be run by impl/integration or any other specific instantiation of KeyTransparency.
|
Package integration exports a set of unit tests that can be run by impl/integration or any other specific instantiation of KeyTransparency. |
|
keyserver
Package keyserver implements a transparent key server for End to End.
|
Package keyserver implements a transparent key server for End to End. |
|
monitor
Package monitor implements the monitor service.
|
Package monitor implements the monitor service. |
|
monitorserver
Package monitorserver contains an implementation of a Monitor server which can be queried for monitoring results.
|
Package monitorserver contains an implementation of a Monitor server which can be queried for monitoring results. |
|
monitorstorage
Package monitorstorage holds data produced by the monitor
|
Package monitorstorage holds data produced by the monitor |
|
mutator
Package mutator defines the operations to transform mutations into changes in the map as well as operations to write and read mutations to and from the database.
|
Package mutator defines the operations to transform mutations into changes in the map as well as operations to write and read mutations to and from the database. |
|
mutator/entry
Package entry implements a simple replacement strategy as a mapper.
|
Package entry implements a simple replacement strategy as a mapper. |
|
sequencer
Package sequencer reads mutations and applies them to the Trillian Map.
|
Package sequencer reads mutations and applies them to the Trillian Map. |
|
sequencer/mapper
Package mapper contains a transformation pipeline from log messages to map revisions.
|
Package mapper contains a transformation pipeline from log messages to map revisions. |
|
sequencer/metadata
Package metadata helps enforce a consistent standard of meaning around the map metadata object.
|
Package metadata helps enforce a consistent standard of meaning around the map metadata object. |
|
sequencer/runner
Package runner executes the mapper pipeline.
|
Package runner executes the mapper pipeline. |
|
testutil
Package testutil provides helper functions for tests.
|
Package testutil provides helper functions for tests. |
|
water
Package water provides the watermark type.
|
Package water provides the watermark type. |
|
impl
|
|
|
authentication
Package authentication implements authentication mechanisms.
|
Package authentication implements authentication mechanisms. |
|
authorization
Package authorization contains the authorization module implementation.
|
Package authorization contains the authorization module implementation. |
|
memory
Package memory supplies fake in-memory implementations for testing purposes.
|
Package memory supplies fake in-memory implementations for testing purposes. |
|
sql
Package sql provides functions for interacting with MySQL.
|
Package sql provides functions for interacting with MySQL. |
|
sql/directory
Package directory implements the directory.Storage interface.
|
Package directory implements the directory.Storage interface. |
|
sql/mutationstorage
Package mutationstorage defines operations to write and read mutations to and from the database.
|
Package mutationstorage defines operations to write and read mutations to and from the database. |
|
sql/testdb
Package testdb supports opening ephemeral databases for testing.
|
Package testdb supports opening ephemeral databases for testing. |
Click to show internal directories.
Click to hide internal directories.