keytransparency

module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 3, 2020 License: Apache-2.0

README

Key Transparency

GoDoc Build Status Go Report Card codecov

Key Transparency Logo

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.

Key Transparency empowers account owners to reliably see what public 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 can add verifiable and user-friendly auditing to any scenario that involves authenticating users with public keys, including Universal Second Factor Security Keys and end-to-end encryption.

Project Status

Key Transparency is a work-in-progress with the following milestones under development.

Key Transparency Client

Setup
  1. Install Go 1.13.
  2. GO111MODULE=on go get github.com/google/keytransparency/cmd/keytransparency-client
Client operations

View a Directory's Public Keys

The Key Transparency server publishes a separate set of public keys for each directory that it hosts. By hosting multiple directories, a single domain can host directories for multiple apps or customers. A standardized pattern for discovering domains and directories is a TODO in issue #389.

Within a directory the server uses the following public keys to sign its responses:

  1. log.public_key signs the top-most Merkle tree root, covering the ordered list of map roots.
  2. map.public_key signs each snapshot of the key-value database in the form of a sparse Merkle tree.
  3. vrf.der signs outputs of the Verifiable Random Function which obscures the key values in the key-value database.

A directory's public keys can be retrieved over HTTPS/JSON with curl or over gRPC with grpcurl. The sandboxserver has been initialized with a domain named default.

$ curl -s https://sandbox.keytransparency.dev/v1/directories/default | json_pp
$ grpcurl -d '{"directory_id": "default"}' sandbox.keytransparency.dev:443 google.keytransparency.v1.KeyTransparency/GetDirectory
Show output 
{
   "directory_id" : "default",
   "log" : {
      "hash_algorithm" : "SHA256",
      "hash_strategy" : "RFC6962_SHA256",
      "public_key" : {
         "der" : "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEXPi4Ut3cRY3OCXWvcSnE/sk6tbDEgBeZapfEy/BIKfsMbj3hPLG+WEjzh1IP2TDirc9GpQ+r9HVGR81KqRpbjw=="
      },
      "signature_algorithm" : "ECDSA",
      "tree_id" : "4565568921879890247",
      "tree_type" : "PREORDERED_LOG"
   },
   "map" : {
      "hash_algorithm" : "SHA256",
      "hash_strategy" : "CONIKS_SHA256",
      "public_key" : {
         "der" : "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEgX6ITeFrqLmclqH+3XVhbaEeJO37vy1dZYRFxpKScERdeeu3XRirJszc5KJgaZs0LdvJqOccfNc2gJfInLGIuA=="
      },
      "signature_algorithm" : "ECDSA",
      "tree_id" : "5601540825264769688",
      "tree_type" : "MAP"
   },
   "max_interval" : "60s",
   "min_interval" : "1s",
   "vrf" : {
      "der" : "MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEvuqCkY9rM/jq/8hAoQn2PClvlNvVeV0MSUqzc67q6W+MzY/YZKmPLY5t/n/VUEqeSgwU+/sXgER3trsL6nZu+A=="
   }
}
Generate Update Signing Keys

Every update to a user record in key transparency must be signed by an authorized-key.

Update signatures are saved in the Merkle tree data structure, producing a record of who made each change to a user's account, allowing products to distinguish between changes signed by a user key, the provider's key, or a reset-provider's key.

Each account has an updatable policy that lists the current set of authorized public keys that are allowed to make updates to the user's record.

To create an initial set of update signing keys, run the authorized-keys create-keyset command. Keys will be saved in a .keyset file in the current working directory.

$ PASSWORD=[[YOUR-KEYSET-PASSWORD]]
$ keytransparency-client authorized-keys create-keyset --password=${PASSWORD}
Show output 
$ PASSWORD=[[YOUR-KEYSET-PASSWORD]]
$ keytransparency-client authorized-keys create-keyset --password=${PASSWORD}
$ keytransparency-client authorized-keys list-keyset --password=${PASSWORD}
My Authorized Keys:
primary_key_id:17445529 key_info:<type_url:"type.googleapis.com/google.crypto.tink.EcdsaPrivateKey" status:ENABLED key_id:17445529 output_prefix_type:TINK >
Publish the public key

Any number of protocols may be used to prove to the server that a client owns a userID. The sandbox server supports a fake authentication string and OAuth.

Create or fetch the public key for your specific application.

 openssl genpkey -algorithm X25519 -out xkey.pem
 openssl pkey -in xkey.pem -pubout
 -----BEGIN PUBLIC KEY-----
 MCowBQYDK2VuAyEAtCAsIMDyVUUooA5yhgRefcEr7edVOmyNCUaN1LCYl3s=
 -----END PUBLIC KEY-----

keytransparency-client post user@domain.com \
--kt-url sandbox.keytransparency.dev:443 \
--fake-auth-userid user@domain.com \
--password=${PASSWORD} \
--verbose \
--logtostderr \
--data='MCowBQYDK2VuAyEAtCAsIMDyVUUooA5yhgRefcEr7edVOmyNCUaN1LCYl3s=' #Your public key in base64
Get and verify a public key
keytransparency-client get <email> --kt-url sandbox.keytransparency.dev:443 --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 user@domain.com --kt-url sandbox.keytransparency.dev:443
Revision |Timestamp                    |Profile
4        |Mon Sep 12 22:23:54 UTC 2016 |keys:<key:"app1" value:"test" >
Checks

Running the server locally with Docker Compose

Prerequisites

  • GoLang
  • OpenSSL
  • Docker
    • Docker Engine 1.17.6+ docker version -f '{{.Server.APIVersion}}'
    • Docker Compose 1.11.0+ docker-compose --version
go get github.com/google/keytransparency/...
cd $(go env GOPATH)/src/github.com/google/keytransparency

# Generate Private Keys
./scripts/gen_monitor_keys.sh -f
pushd genfiles
go run "$(go env GOROOT)/src/crypto/tls/generate_cert.go" --host localhost,127.0.0.1,::
popd

# Build Docker Images
export TRAVIS_COMMIT=$(git rev-parse HEAD)
docker-compose build --parallel

# Run
docker-compose -f docker-compose.yml docker-compose.prod.yml up -d

# Create directory
docker run -t --network kt_attachable gcr.io/key-transparency/init:${TRAVIS_COMMIT} sequencer:8080 -- curl -k -X POST https://sequencer:8080/v1/directories -d'{"directory_id":"default","min_interval":"1s","max_interval":"60s"}'
  1. Watch it Run
  1. Integration test for Docker Compose

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:

Support

Acknowledgements

Key Transparency would not have been possible without a whole host of collaborators including researchers, interns, and open source contributors.

Key Transparency was inspired by CONIKS and Certificate Transparency.

Directories

Path Synopsis
cmd
healthcheck
healthcheck makes a HTTP(S) request to the supplied url and exits with 0 (success) if the HTTP response code was in the 2xx range or 1 (unhealthy).
 healthcheck makes a HTTP(S) request to the supplied url and exits with 0 (success) if the HTTP response code was in the 2xx range or 1 (unhealthy).
keytransparency-client
keytransparency-client/cmd
keytransparency-monitor
keytransparency-sequencer
keytransparency-server
serverutil
Package serverutil provides helper functions to main.go files.
 Package serverutil provides helper functions to main.go files.
core
adminserver
Package adminserver contains the KeyTransparencyAdmin implementation
 Package adminserver contains the KeyTransparencyAdmin implementation
api
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.
client/verifier
crypto/commitments
Package commitments implements a cryptographic commitment.
 Package commitments implements a cryptographic commitment.
crypto/tinkio
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.
fake
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.
integration/storagetest
keyserver
Package keyserver implements a transparent key server for End to End.
 Package keyserver implements a transparent key server for End to End.
keyserver/readtoken_go_proto
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/election
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.
sequencer/sequencer_go_proto
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.
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.
authorization/authz_go_proto
integration
memory
Package memory supplies fake in-memory implementations for testing purposes.
 Package memory supplies fake in-memory implementations for testing purposes.
mysql
Package mysql provides functions for interacting with MySQL.
 Package mysql provides functions for interacting with MySQL.
mysql/directory
Package directory implements the directory.Storage interface.
 Package directory implements the directory.Storage interface.
mysql/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.
mysql/testdb
Package testdb supports opening ephemeral databases for testing.
 Package testdb supports opening ephemeral databases for testing.
spanner
spanner/batch
Package batch allows for reading and writing of batches of mutations.
 Package batch allows for reading and writing of batches of mutations.
spanner/directory
Package directory reads and writes Key Transparency Directory information.
 Package directory reads and writes Key Transparency Directory information.
spanner/mutations
Package mutations stores mutations by timestamp.
 Package mutations stores mutations by timestamp.
spanner/testutil
Package testutil helps with tests against Spanner.
 Package testutil helps with tests against Spanner.
internal
backoff
Package backoff allows retrying an operation with backoff.
 Package backoff allows retrying an operation with backoff.
forcemaster

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.