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)
- func NewerRevisionsToVerify(created, current, verified uint64) []uint64
- func OlderRevisionsToVerify(current, verified uint64) []uint64
- type Client
- func (c *Client) BatchCreateMutation(ctx context.Context, users []*User) ([]*entry.Mutation, error)
- func (c *Client) BatchCreateUser(ctx context.Context, users []*User, signers []tink.Signer, ...) error
- func (c *Client) BatchQueueUserUpdate(ctx context.Context, mutations []*entry.Mutation, signers []tink.Signer, ...) error
- func (c *Client) BatchVerifiedGetUser(ctx context.Context, userIDs []string) (*types.MapRootV1, 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 *User) (*entry.Mutation, error)
- func (c *Client) GetUser(ctx context.Context, userID string, opts ...grpc.CallOption) (*types.MapRootV1, []byte, 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.Signer, ...) error
- func (c *Client) RevisionMutations(ctx context.Context, mapRoot *types.MapRootV1) ([]*pb.MutationProof, error)
- func (c *Client) StreamRevisions(ctx context.Context, startRevision int64, out chan<- *types.MapRootV1) error
- func (c *Client) Update(ctx context.Context, u *User, signers []tink.Signer, opts ...grpc.CallOption) (*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.MapRootV1, error)
- func (c *Client) VerifiedGetUser(ctx context.Context, userID string) (*types.MapRootV1, *pb.MapLeaf, 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 ReduceMutationFn
- type RevisionMutations
- type User
- type VerifierInterface
Constants ¶
This section is empty.
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) )
Functions ¶
func CompressHistory ¶
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.
func NewerRevisionsToVerify ¶ added in v0.3.0
NewerRevisionsToVerify returns a list of revisions to perform append-only verifications against. The relying party / sender is assured that if there is an entity running the OlderRevisionsToVerify algorithm, they will have at least one revision in common.
`created` is the (earliest) revision a data item was found in the map.
It is OK to use the revision at which an item was fetched, but the algorithm will be more efficient if it starts with the revision at which an item was submitted to the map.
`verified` is the latest revision of a successfully verified consistency proof by this client.
When verified > created, previously verified revisions are omitted from the results.
`current` is the current revision of the map. Selected revisions will be <= current.
func OlderRevisionsToVerify ¶ added in v0.3.0
OlderRevisionsToVerify returns a list of revisions to perform append-only verifications against. The provider / data owner / data verifier periodically verifies that their data history contained in the current map revision contains all the data committed to in select previous revisions. The provider is assured that any relying party has verified that the data they have fetched is represented in at least one of the selected revisions.
`current` is the current revision of the map. `verified` is the latest verified revision for this particular data item.
TODO: Consier limiting the max period between checks to the expected value of other party lifetimes -- the maximum amount of time this algorithm can tollerate the other party being offline at an unknown point in the past. Currently this algorithm expects the relying party to keep its memory and be online at least once every `current = 2ⁱ` revisions. See Tests.
Types ¶
type Client ¶
type Client struct {
VerifierInterface
DirectoryID string
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 VerifierInterface) *Client
New creates a new client.
func NewFromConfig ¶
func NewFromConfig(ktClient pb.KeyTransparencyClient, config *pb.Directory, trackerFactory verifier.LogTrackerFactory) (*Client, error)
NewFromConfig creates a new client from a config
func (*Client) BatchCreateMutation ¶
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 []*User, signers []tink.Signer, 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.Signer, 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) ( *types.MapRootV1, map[string]*pb.MapLeaf, error)
BatchVerifiedGetUser returns verified leaf values by userID. Returns the MapRoot (revision) at which the values were fetched. This could be any MapRoot. TODO(gbelvin): Verify that the returned map root is indeed the latest map root.
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 ¶
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) ( *types.MapRootV1, []byte, 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.Signer, 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, mapRoot *types.MapRootV1) ([]*pb.MutationProof, error)
RevisionMutations fetches all the mutations in an revision
func (*Client) StreamRevisions ¶
func (c *Client) StreamRevisions(ctx context.Context, startRevision int64, out chan<- *types.MapRootV1) 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 *User, signers []tink.Signer, 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 ¶
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 requested map root.
func (*Client) VerifiedGetUser ¶
func (c *Client) VerifiedGetUser(ctx context.Context, userID string) (*types.MapRootV1, *pb.MapLeaf, 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 ¶
WaitForRevision waits until a given map revision is available.
func (*Client) WaitForSTHUpdate ¶
WaitForSTHUpdate blocks until the log root reported by the server has moved to at least treeSize or times out.
type ReduceMutationFn ¶
type ReduceMutationFn func(msgs []*pb.EntryUpdate, leaves []*pb.EntryUpdate, emit func(*pb.EntryUpdate), emitErr func(error))
ReduceMutationFn takes all the mutations for an index and an auxiliary input of existing mapleaf(s) returns a new map leaf. ReduceMutationFn must be idempotent, commutative, and associative. i.e. must produce the same output regardless of input order or grouping, and it must be safe to run multiple times.
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 User ¶
type User struct {
// UserID specifies the user.
UserID string
// PublicKeyData is the public key material for this account.
PublicKeyData []byte
// AuthorizedKeys is the tink keyset that validates the signatures on the next entry.
AuthorizedKeys *keyset.Handle
}
User represents plain account information that gets committed to and obfuscated in Entry.
type VerifierInterface ¶
type VerifierInterface interface {
verifier.LogTracker
// Index computes the index of a userID from a VRF proof, obtained from the server.
Index(vrfProof []byte, directoryID, userID string) ([]byte, error)
// VerifyMapRevision verifies that the map revision is correctly signed and included in the log.
VerifyMapRevision(lr *types.LogRootV1, smr *pb.MapRoot) (*types.MapRootV1, error)
// VerifyMapLeaf verifies everything about a MapLeaf.
VerifyMapLeaf(directoryID, userID string, in *pb.MapLeaf, smr *types.MapRootV1) error
// VerifyGetUser verifies the request and response to the GetUser API.
VerifyGetUser(req *pb.GetUserRequest, resp *pb.GetUserResponse) error
// VerifyBatchGetUser verifies the request and response to the BatchGetUser API.
VerifyBatchGetUser(req *pb.BatchGetUserRequest, resp *pb.BatchGetUserResponse) error
}
VerifierInterface is used to verify specific outputs from Key Transparency.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
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. |
|
Package hammer sends multiple requests to Key Transparency at the same time.
|
Package hammer sends multiple requests to Key Transparency at the same time. |
|
Package multi contains utilities for multiplexing io operations.
|
Package multi contains utilities for multiplexing io operations. |
|
Package tracker tracks log roots and verifies consistency proofs between them.
|
Package tracker tracks log roots and verifies consistency proofs between them. |