client

Documentation

Overview

Package client is a client for communicating with the Key Server. It wraps the gRPC APIs and verifies all responses.

Index

• Variables
• func CompressHistory(profiles map[uint64][]byte) (map[uint64][]byte, error)
• type Client
  • func New(ktClient pb.KeyTransparencyClient, directoryID string, ...) *Client
  • func NewFromConfig(ktClient pb.KeyTransparencyClient, config *pb.Directory) (*Client, error)
  • func (c *Client) BatchCreateMutation(ctx context.Context, users []*tpb.User) ([]*entry.Mutation, error)
  • func (c *Client) BatchCreateUser(ctx context.Context, users []*tpb.User, signers []*tink.KeysetHandle, ...) error
  • func (c *Client) BatchQueueUserUpdate(ctx context.Context, mutations []*entry.Mutation, signers []*tink.KeysetHandle, ...) error
  • func (c *Client) BatchVerifiedGetUser(ctx context.Context, userIDs []string) (map[string]*pb.MapLeaf, error)
  • func (c *Client) BatchVerifyGetUserIndex(ctx context.Context, userIDs []string) (map[string][]byte, error)
  • func (c *Client) CreateMutation(ctx context.Context, u *tpb.User) (*entry.Mutation, error)
  • func (c *Client) GetUser(ctx context.Context, userID string, opts ...grpc.CallOption) ([]byte, *types.LogRootV1, error)
  • func (c *Client) PaginateHistory(ctx context.Context, userID string, start, end int64) (map[uint64]*types.MapRootV1, map[uint64][]byte, error)
  • func (c *Client) QueueMutation(ctx context.Context, m *entry.Mutation, signers []*tink.KeysetHandle, ...) error
  • func (c *Client) RevisionMutations(ctx context.Context, revision *pb.Revision) ([]*pb.MutationProof, error)
  • func (c *Client) StreamRevisions(ctx context.Context, directoryID string, startRevision int64, ...) error
  • func (c *Client) Update(ctx context.Context, u *tpb.User, signers []*tink.KeysetHandle, ...) (*entry.Mutation, error)
  • func (c *Client) VerifiedGetLatestRevision(ctx context.Context) (*types.LogRootV1, *types.MapRootV1, error)
  • func (c *Client) VerifiedGetRevision(ctx context.Context, revision int64) (*types.LogRootV1, *types.MapRootV1, error)
  • func (c *Client) VerifiedGetUser(ctx context.Context, userID string) (*pb.MapLeaf, *types.LogRootV1, error)
  • func (c *Client) VerifiedListHistory(ctx context.Context, userID string, start int64, count int32) (map[*types.MapRootV1][]byte, int64, error)
  • func (c *Client) WaitForRevision(ctx context.Context, revision int64) error
  • func (c *Client) WaitForSTHUpdate(ctx context.Context, treeSize int64) error
  • func (c *Client) WaitForUserUpdate(ctx context.Context, m *entry.Mutation) (*entry.Mutation, error)
• type RealVerifier
  • func NewVerifier(vrf vrf.PublicKey, mapVerifier *tclient.MapVerifier, ...) *RealVerifier
  • func NewVerifierFromDirectory(config *pb.Directory) (*RealVerifier, error)
  • func (v *RealVerifier) Index(vrfProof []byte, directoryID, userID string) ([]byte, error)
  • func (v *RealVerifier) VerifyMapLeaf(directoryID, userID string, in *pb.MapLeaf, mapRoot *types.MapRootV1) error
  • func (v *RealVerifier) VerifyRevision(in *pb.Revision, trusted types.LogRootV1) (*types.LogRootV1, *types.MapRootV1, error)
• type RevisionMutations
• type Verifier

Variables

var (
	// ErrRetry occurs when an update has been queued, but the
	// results of the update differ from the one requested.
	// This indicates that a separate update was in-flight while
	// this update was being submitted. To continue, the client
	// should make a fresh update and try again.
	ErrRetry = status.Errorf(codes.FailedPrecondition, "client: update race condition - try again")
	// ErrWait occurs when an update has been queued, but no change has been
	// observed in the user's account yet.
	ErrWait = status.Errorf(codes.Unavailable, "client: update not present yet - wait some more")
	// ErrIncomplete occurs when the server indicates that requested revisions
	// are not available.
	ErrIncomplete = errors.New("incomplete account history")
	// ErrLogEmpty occurs when the Log.TreeSize < 1 which indicates
	// that the log of signed map roots is empty.
	ErrLogEmpty = errors.New("log is empty - directory initialization failed")
	// ErrNonContiguous occurs when there are holes in a list of map roots.
	ErrNonContiguous = errors.New("noncontiguous map roots")
	// Vlog is the verbose logger. By default it outputs to /dev/null.
	Vlog = log.New(ioutil.Discard, "", 0)
)

var (
	// ErrNilProof occurs when the provided GetUserResponse contains a nil proof.
	ErrNilProof = errors.New("nil proof")
)

Functions

func CompressHistory

func CompressHistory(profiles map[uint64][]byte) (map[uint64][]byte, error)

CompressHistory takes a map of data by revision number. CompressHistory returns only the revisions where the associated data changed. CompressHistory returns an error if the list of revisions is not contiguous.

Types

type Client

type Client struct {
	Verifier

	RetryDelay time.Duration
	// contains filtered or unexported fields
}

Client is a helper library for issuing updates to the key server. Client Responsibilities - Trust Model: - - Trusted Monitors - - Verify last X days - Gossip - What is the current value of the root? - - Gossip advancement: advance state between current and server. - Sender queries - Do queries match up against the gossip root? - - List trusted monitors. - Key Owner - - Periodically query own keys. Do they match the private keys I have? - - Sign key update requests.

func New

func New(ktClient pb.KeyTransparencyClient,
	directoryID string,
	retryDelay time.Duration,
	ktVerifier *RealVerifier) *Client

New creates a new client.

func NewFromConfig

func NewFromConfig(ktClient pb.KeyTransparencyClient, config *pb.Directory) (*Client, error)

NewFromConfig creates a new client from a config

func (*Client) BatchCreateMutation

func (c *Client) BatchCreateMutation(ctx context.Context, users []*tpb.User) ([]*entry.Mutation, error)

BatchCreateMutation fetches the current index and value for a list of users and prepares mutations.

func (*Client) BatchCreateUser

func (c *Client) BatchCreateUser(ctx context.Context, users []*tpb.User,
	signers []*tink.KeysetHandle, opts ...grpc.CallOption) error

BatchCreateUser inserts mutations for new users that do not currently have entries. Calling BatchCreate for a user that already exists will produce no change.

func (*Client) BatchQueueUserUpdate

func (c *Client) BatchQueueUserUpdate(ctx context.Context, mutations []*entry.Mutation,
	signers []*tink.KeysetHandle, opts ...grpc.CallOption) error

BatchQueueUserUpdate signs the mutations and sends them to the server.

func (*Client) BatchVerifiedGetUser

func (c *Client) BatchVerifiedGetUser(ctx context.Context, userIDs []string) (map[string]*pb.MapLeaf, error)

BatchVerifiedGetUser returns verified leaf values by userID.

func (*Client) BatchVerifyGetUserIndex

func (c *Client) BatchVerifyGetUserIndex(ctx context.Context, userIDs []string) (map[string][]byte, error)

BatchVerifyGetUserIndex fetches and verifies the indexes for a list of users.

func (*Client) CreateMutation

func (c *Client) CreateMutation(ctx context.Context, u *tpb.User) (*entry.Mutation, error)

CreateMutation fetches the current index and value for a user and prepares a mutation.

func (*Client) GetUser

func (c *Client) GetUser(ctx context.Context, userID string, opts ...grpc.CallOption) (
	[]byte, *types.LogRootV1, error)

GetUser returns an entry if it exists, and nil if it does not.

func (*Client) PaginateHistory

func (c *Client) PaginateHistory(ctx context.Context, userID string, start, end int64) (
	map[uint64]*types.MapRootV1, map[uint64][]byte, error)

PaginateHistory iteratively calls ListHistory to satisfy the start and end requirements. Returns a list of map roots and profiles at each revision.

func (*Client) QueueMutation

func (c *Client) QueueMutation(ctx context.Context, m *entry.Mutation, signers []*tink.KeysetHandle, opts ...grpc.CallOption) error

QueueMutation signs an entry.Mutation and sends it to the server.

func (*Client) RevisionMutations

func (c *Client) RevisionMutations(ctx context.Context, revision *pb.Revision) ([]*pb.MutationProof, error)

RevisionMutations fetches all the mutations in an revision

func (*Client) StreamRevisions

func (c *Client) StreamRevisions(ctx context.Context, directoryID string, startRevision int64, out chan<- *pb.Revision) error

StreamRevisions repeatedly fetches revisions and sends them to out until GetRevision returns an error other than NotFound or until ctx.Done is closed. When GetRevision returns NotFound, it waits one pollPeriod before trying again.

func (*Client) Update

func (c *Client) Update(ctx context.Context, u *tpb.User, signers []*tink.KeysetHandle, opts ...grpc.CallOption) (*entry.Mutation, error)

Update creates and submits a mutation for a user, and waits for it to appear. Returns codes.FailedPrecondition if there was a race condition.

func (*Client) VerifiedGetLatestRevision

func (c *Client) VerifiedGetLatestRevision(ctx context.Context) (*types.LogRootV1, *types.MapRootV1, error)

VerifiedGetLatestRevision fetches the latest revision from the key server. It also verifies the consistency from the last seen revision. Returns the latest log root and the latest map root.

func (*Client) VerifiedGetRevision

func (c *Client) VerifiedGetRevision(ctx context.Context, revision int64) (*types.LogRootV1, *types.MapRootV1, error)

VerifiedGetRevision fetches the requested revision from the key server. It also verifies the consistency of the latest log root against the last seen log root. Returns the latest log root and the requested map root.

func (*Client) VerifiedGetUser

func (c *Client) VerifiedGetUser(ctx context.Context, userID string) (*pb.MapLeaf, *types.LogRootV1, error)

VerifiedGetUser fetches and verifies the results of GetUser.

func (*Client) VerifiedListHistory

func (c *Client) VerifiedListHistory(ctx context.Context, userID string, start int64, count int32) (
	map[*types.MapRootV1][]byte, int64, error)

VerifiedListHistory performs one list history operation, verifies and returns the results.

func (*Client) WaitForRevision

func (c *Client) WaitForRevision(ctx context.Context, revision int64) error

WaitForRevision waits until a given map revision is available.

func (*Client) WaitForSTHUpdate

func (c *Client) WaitForSTHUpdate(ctx context.Context, treeSize int64) error

WaitForSTHUpdate blocks until the log root reported by the server has moved to at least treeSize or times out.

func (*Client) WaitForUserUpdate

func (c *Client) WaitForUserUpdate(ctx context.Context, m *entry.Mutation) (*entry.Mutation, error)

WaitForUserUpdate waits for the mutation to be applied or the context to timeout or cancel.

type RealVerifier

type RealVerifier struct {
	*tclient.MapVerifier
	*tclient.LogVerifier
	// contains filtered or unexported fields
}

RealVerifier is a client helper library for verifying request and responses. Implements Verifier.

func NewVerifier

func NewVerifier(vrf vrf.PublicKey,
	mapVerifier *tclient.MapVerifier,
	logVerifier *tclient.LogVerifier) *RealVerifier

NewVerifier creates a new instance of the client verifier.

func NewVerifierFromDirectory

func NewVerifierFromDirectory(config *pb.Directory) (*RealVerifier, error)

NewVerifierFromDirectory creates a new instance of the client verifier from a config.

func (*RealVerifier) Index

func (v *RealVerifier) Index(vrfProof []byte, directoryID, userID string) ([]byte, error)

Index computes the index from a VRF proof.

func (*RealVerifier) VerifyMapLeaf

func (v *RealVerifier) VerifyMapLeaf(directoryID, userID string,
	in *pb.MapLeaf, mapRoot *types.MapRootV1) error

VerifyMapLeaf verifies pb.MapLeaf:

• Verify commitment.
• Verify VRF and index.
• Verify map inclusion proof.

func (*RealVerifier) VerifyRevision

func (v *RealVerifier) VerifyRevision(in *pb.Revision, trusted types.LogRootV1) (*types.LogRootV1, *types.MapRootV1, error)

VerifyRevision verifies that revision is correctly signed and included in the append only log. VerifyRevision also verifies that revision.LogRoot is consistent with the last trusted SignedLogRoot.

type RevisionMutations

type RevisionMutations struct {
	Revision  *pb.Revision
	Mutations []*pb.MutationProof
}

RevisionMutations contains all the mutations needed to advance the map from revision-1 to revision.

type Verifier

type Verifier interface {
	// Index computes the index of a userID from a VRF proof, obtained from the server.
	Index(vrfProof []byte, directoryID, userID string) ([]byte, error)
	// VerifyMapLeaf verifies everything about a MapLeaf.
	VerifyMapLeaf(directoryID, userID string, in *pb.MapLeaf, smr *types.MapRootV1) error
	// VerifyRevision verifies that revision is correctly signed and included in the append only log.
	// VerifyRevision also verifies that revision.LogRoot is consistent with the last trusted SignedLogRoot.
	VerifyRevision(revision *pb.Revision, trusted types.LogRootV1) (*types.LogRootV1, *types.MapRootV1, error)
	// VerifySignedMapRoot verifies the signature on the SignedMapRoot.
	VerifySignedMapRoot(smr *trillian.SignedMapRoot) (*types.MapRootV1, error)
}

Verifier is used to verify specific outputs from Key Transparency.