Skip to content
This repository has been archived by the owner on Oct 11, 2024. It is now read-only.

Latest commit

 

History

History
1018 lines (516 loc) · 40.5 KB

api.md

File metadata and controls

1018 lines (516 loc) · 40.5 KB

Protocol Documentation

Table of Contents

Top

v1/keytransparency.proto

BatchGetUserIndexRequest

BatchGetUserIndexRequest identifies a set of users.

Field Type Label Description
directory_id string directory_id identifies the directory in which the users live.
user_ids string repeated user_ids are the user identifiers

BatchGetUserIndexResponse

BatchGetUserIndexRequest identifies a single user.

Field Type Label Description
proofs BatchGetUserIndexResponse.ProofsEntry repeated proofs is a map from user_id to its VRF proof. Clients get the index by verifying the VRF proof.

BatchGetUserIndexResponse.ProofsEntry

Field Type Label Description
key string
value bytes

BatchGetUserRequest

BatchGetUserRequest contains multiple user_ids to fetch.

Field Type Label Description
directory_id string directory_id identifies the directory in which the users live.
user_ids string repeated user_ids are the user identifiers, the format for which is defined by the application.
last_verified LogRootRequest last_verified is the last log root the client verified. Omitting this field will omit the log consistency proof from the response.

BatchGetUserResponse

BatchGetUserResponse contains the leaf entries for a set of users at the most recently published revision.

Field Type Label Description
revision Revision revision is the most recently published revision.
map_leaves_by_user_id BatchGetUserResponse.MapLeavesByUserIdEntry repeated map_leaves_by_user_id is a map from user_id to the map leaf at the most recently published revision.

BatchGetUserResponse.MapLeavesByUserIdEntry

Field Type Label Description
key string
value MapLeaf

BatchListUserRevisionsRequest

BatchListUserRevisionsRequest contains a list of users and a range of revisions.

Field Type Label Description
directory_id string directory_id identifies the directory in which the users live.
user_ids string repeated user_ids are the user identifiers.
start_revision int64 start_revision is the starting revision.
end_revision int64 end_revision is the ending epoch.
page_size int32 page_size is the maximum number of entries to return. If page_size is unspecified, the server will decide how to paginate results.
page_token string page_token is a continuation token for paginating through results.
last_verified LogRootRequest last_verified is the last log root the client verified. Omitting this field will omit the log consistency proof from the response.

BatchListUserRevisionsResponse

BatchListUserRevisionsResponse contains multiple map leaves across multiple revisions.

Field Type Label Description
latest_log_root LogRoot latest_log_root contains the latest log root and its consistency proof.
map_revisions BatchMapRevision repeated map_revisions is a list of map revisions. At most page_size revisions will be returned.

BatchMapRevision

BatchMapRevision contains a set of map leaves at a speific revision.

Field Type Label Description
map_root MapRoot map_root contains the map root and its inclusion in the log.
map_leaves_by_user_id BatchMapRevision.MapLeavesByUserIdEntry repeated map_leaves_by_user_id contains a mapping from user_id to the map leaf at this revision.

BatchMapRevision.MapLeavesByUserIdEntry

Field Type Label Description
key string
value MapLeaf

BatchQueueUserUpdateRequest

BatchQueueUserUpdateRequest enqueues multiple changes to user profiles.

Field Type Label Description
directory_id string directory_id identifies the directory in which the users live.
updates EntryUpdate repeated updates contains user updates.

Committed

Committed represents the data committed to in a cryptographic commitment. commitment = HMAC_SHA512_256(key, data)

Field Type Label Description
key bytes key is the 16 byte random commitment key.
data bytes data is the data being committed to.

Entry

Entry is a signed change to a map entry. Entry contains a commitment to profile and a set of authorized update keys. Entry is placed in the verifiable map as leaf data.

Field Type Label Description
index bytes index is the location of this leaf in the sparse merkle tree.
commitment bytes commitment is a cryptographic commitment to arbitrary data.
authorized_keyset bytes authorized_keys is the tink keyset that validates the signatures on the next entry.
previous bytes previous contains the SHA256 hash of SignedEntry.Entry the last time it was modified.

EntryUpdate

EntryUpdate contains the user entry update(s). EntryUpdate will be placed in a Log of mutations.

Field Type Label Description
user_id string user_id specifies the id for the user whose profile is being updated.
mutation SignedEntry mutation authorizes the change to entry.
committed Committed committed contains the data committed to in mutation.commitment.

GetLatestRevisionRequest

GetLatestRevisionRequest identifies a particular revision.

Field Type Label Description
directory_id string directory_id is the directory for which revisions are being requested.
last_verified LogRootRequest last_verified is the last log root the client verified. Omitting this field will omit the log consistency proof from the response.

GetRevisionRequest

GetRevisionRequest identifies a particular revision.

Field Type Label Description
directory_id string directory_id is the directory for which revisions are being requested.
revision int64 revision specifies the revision number in which mutations will be returned.
last_verified LogRootRequest last_verified is the last log root the client verified. Omitting this field will omit the log consistency proof from the response.

GetUserRequest

Gets the leaf entry for a user.

Field Type Label Description
directory_id string directory_id identifies the directory in which the user lives.
user_id string user_id is the user identifier, the format for which is defined by the application.
last_verified LogRootRequest last_verified is the last log root the client verified. Omitting this field will omit the log consistency proof from the response.

GetUserResponse

Contains the leaf entry for a user at the most recently published revision.

Field Type Label Description
revision Revision revision is the most recently published revision.
leaf MapLeaf leaf is the leaf entry for the requested user.

ListEntryHistoryRequest

ListEntryHistoryRequest gets a list of historical keys for a user.

Field Type Label Description
directory_id string directory_id identifies the directory in which the user lives.
user_id string user_id is the user identifier.
start int64 start is the starting revision.
page_size int32 page_size is the maximum number of entries to return. The server can return fewer entries than requested.
last_verified LogRootRequest last_verified is the last log root the client verified. Omitting this field will omit the log consistency proof from the response.

ListEntryHistoryResponse

ListEntryHistoryResponse requests a paginated history of keys for a user.

Field Type Label Description
values GetUserResponse repeated values represents the list of keys this user_id has contained over time.
next_start int64 next_start is the next page token to query for pagination. next_start is 0 when there are no more results to fetch.

ListMutationsRequest

ListMutationsRequest requests the mutations that created a given revision.

Field Type Label Description
directory_id string directory_id is the directory identifier.
revision int64 revision specifies the revision number.
page_token string page_token defines the starting point for pagination. To request the next page, pass next_page_token from the previous response. To start at the beginning, simply omit page_token from the request.
page_size int32 page_size is the maximum number of mutations to return in a single request. The server may choose a smaller page_size than the one requested.

TODO(gbelvin): Add field mask. |

ListMutationsResponse

ListMutationsResponse contains the mutations that produced an revision.

Field Type Label Description
mutations MutationProof repeated mutations contains the mutation object and the leaf value it operated on.
next_page_token string next_page_token is the next page token to query for pagination. An empty value means there are no more results to fetch.

ListUserRevisionsRequest

ListUserRevisionsRequest gets a list of historical keys for a user.

Field Type Label Description
directory_id string directory_id identifies the directory in which the user lives.
user_id string user_id is the user identifier.
start_revision int64 start_revision is the starting epoch.
end_revision int64 end_revision is the ending epoch.
page_size int32 page_size is the maximum number of entries to return. If page_size is unspecified, the server will decide how to paginate results.
page_token string page_token is a continuation token for paginating through results.
last_verified LogRootRequest last_verified is the last log root the client verified. Omitting this field will omit the log consistency proof from the response.

ListUserRevisionsResponse

ListUserRevisionsResponse requests a paginated history of keys for a user.

Field Type Label Description
latest_log_root LogRoot latest_log_root contains the latest log root and its consistency proof.
map_revisions MapRevision repeated map_revisions represents the list of keys this user_id has contained over time. At most page_size results will be returned.
next_page_token string next_page_token is a pagination token which will be set if more than page_size results are available. Clients can pass this value as the page_token in the next request in order to continue pagination.

LogRoot

LogRoot contains the latest log root and its consistency proof.

Field Type Label Description
log_root trillian.SignedLogRoot log_root is the latest globally consistent log root.
log_consistency bytes repeated log_consistency proves that log_root is consistent with previously seen roots.

LogRootRequest

LogRootRequest contains the information needed to request and verify LogRoot.

Field Type Label Description
root_hash bytes root_hash is the root hash of the last log root the client verified.
tree_size int64 tree_size is the tree size of the last log root the client verified.

MapLeaf

Leaf entry for a user.

Field Type Label Description
vrf_proof bytes vrf_proof is the proof for the VRF on user_id.
map_inclusion trillian.MapLeafInclusion map_inclusion is an inclusion proof for the map leaf in an accompanying trillian.SignedMapRoot. If the leaf is non-empty, its leaf.leaf_value stores a serialized Entry proto.
committed Committed committed contains the data and nonce used to make a cryptographic commitment, which is stored in the commitment field of the serialized Entry proto from map_inclusion. Note: committed can also be found serialized in map_inclusion.leaf.extra_data.

MapRevision

MapRevision contains a map leaf at a speific revision.

Field Type Label Description
map_root MapRoot map_root contains the map root and its inclusion in the log.
map_leaf MapLeaf map_leaf contains a leaf and its inclusion proof to map_root.

MapRoot

MapRoot contains the map root and its inclusion proof in the log.

Field Type Label Description
map_root trillian.SignedMapRoot map_root contains the signed map root for the sparse Merkle Tree.
log_inclusion bytes repeated log_inclusion proves that map_root is part of log_root at index=map_root.MapRevision.

MapperMetadata

MapperMetadata tracks the mutations that have been mapped so far. It is embedded in the Trillian SignedMapHead.

Field Type Label Description
highest_fully_completed_seq int64

MutationProof

MutationProof contains the information necessary to compute the new leaf value. It contains a) the old leaf value with it's inclusion proof and b) the mutation. The new leaf value is computed via: Mutate(leaf_value, mutation)

Field Type Label Description
mutation SignedEntry mutation contains the information needed to modify the old leaf. The format of a mutation is specific to the particular Mutate function being used.
leaf_proof trillian.MapLeafInclusion leaf_proof contains the leaf and its inclusion proof for a particular map revision.

Revision

Revision represents a snapshot of the entire key directory and a diff of what changed between this revision and the previous revision.

Field Type Label Description
directory_id string directory_id is the directory identifier.
map_root MapRoot map_root contains the map root and its inclusion in the log.
latest_log_root LogRoot latest_log_root contains the most recent log root and its consistency proof to the client's last seen log root.

SignedEntry

SignedEntry is a cryptographically signed Entry. SignedEntry will be storead as a trillian.Map leaf.

Field Type Label Description
entry bytes entry contains a serialized Entry.
signatures bytes repeated signatures on entry. Must be signed by keys from both previous and current revisions. The first proves ownership of new revision key, and the second proves that the correct owner is making this change. The signature scheme is specified by the authorized_keys tink.Keyset.

UpdateEntryRequest

UpdateEntryRequest updates a user's profile.

Field Type Label Description
directory_id string directory_id identifies the directory in which the user lives.
entry_update EntryUpdate entry_update contains the user submitted update.

KeyTransparency

The KeyTransparency API represents a directory of public keys.

The API has a collection of directories: /v1/directories/

  • Each directory has a single sparse merkle tree, append only log, and other public key material that is needed to verify server responses.

Each Directory has a collection of snapshots called revisions: /v1/directories/*/revisions/

  • Each Revision contains the root of the sparse merkle tree and the changes that occurred that revision and the previous.

Each Revision has a collection of mutations: /v1/directories/*/revisions/*/mutations/.

  • Each mutation contains the leafvalue of the previous revision that it operated on.
  • The full set of mutations for an revision allows the receiver to compute the Merkle Tree Root of this revision from the previous revision.

Each Directory has a collection of Users: /v1/directories/*/users/

  • Each User contains public key material, permissions for who is allowed to change that user, and signatures indicating who made the last change.

Each User also has a collection of historical values for user: /v1/directories/*/users/*/history

Method Name Request Type Response Type Description
GetDirectory GetDirectoryRequest Directory GetDirectory returns the information needed to verify the specified directory.
GetRevision GetRevisionRequest Revision GetRevision returns a SignedMapRoot by the by the requested revision number along with its inclusion proof in the log and the log's consistency proofs.
GetLatestRevision GetLatestRevisionRequest Revision GetLatestRevision returns the latest SignedMapRoot along with its inclusion proof in the log and the log's consistency proofs.
GetRevisionStream GetRevisionRequest Revision stream GetRevisionStream streams new revisions from a requested starting point and continues as new revisions are created.
ListMutations ListMutationsRequest ListMutationsResponse ListMutations returns a list of mutations in a specific revision.
ListMutationsStream ListMutationsRequest MutationProof stream ListMutationsStream is a streaming list of mutations in a specific revision.
GetUser GetUserRequest GetUserResponse GetUser returns a user's leaf entry in the Merkle Tree.
BatchGetUser BatchGetUserRequest BatchGetUserResponse BatchGetUser returns a batch of user leaf entries in the Merkle tree at the same revision.
BatchGetUserIndex BatchGetUserIndexRequest BatchGetUserIndexResponse BatchGetUserIndex returns the VRF proof for a set of userIDs.
ListEntryHistory ListEntryHistoryRequest ListEntryHistoryResponse ListEntryHistory returns a list of historic GetUser values.

Clients verify their account history by observing correct values for their account over time. | | ListUserRevisions | ListUserRevisionsRequest | ListUserRevisionsResponse | ListUserRevisions returns a list of historic leaf values for a user.

Clients verify their account history by observing correct values for their account over time. | | BatchListUserRevisions | BatchListUserRevisionsRequest | BatchListUserRevisionsResponse | BatchListUserRevisions returns a list of revisions for multiple users. | | QueueEntryUpdate | UpdateEntryRequest | .google.protobuf.Empty | QueueUserUpdate enqueues an update to a user's profile.

Clients should poll GetUser until the update appears, and retry if no update appears after a timeout. | | BatchQueueUserUpdate | BatchQueueUserUpdateRequest | .google.protobuf.Empty | BatchQueueUserUpdate enqueues a list of user profiles. |

Top

v1/admin.proto

CreateDirectoryRequest

CreateDirectoryRequest creates a new directory

Field Type Label Description
directory_id string
min_interval google.protobuf.Duration
max_interval google.protobuf.Duration
vrf_private_key google.protobuf.Any The private_key fields allows callers to set the private key.
log_private_key google.protobuf.Any
map_private_key google.protobuf.Any

DeleteDirectoryRequest

DeleteDirectoryRequest deletes a directory

Field Type Label Description
directory_id string

Directory

Directory contains information on a single directory

Field Type Label Description
directory_id string DirectoryId can be any URL safe string.
log trillian.Tree Log contains the Log-Tree's info.
map trillian.Tree Map contains the Map-Tree's info.
vrf keyspb.PublicKey Vrf contains the VRF public key.
min_interval google.protobuf.Duration min_interval is the minimum time between revisions.
max_interval google.protobuf.Duration max_interval is the maximum time between revisions.
deleted bool Deleted indicates whether the directory has been marked as deleted. By its presence in a response, this directory has not been garbage collected.

GarbageCollectRequest

GarbageCollect request.

Field Type Label Description
before google.protobuf.Timestamp Soft-deleted directories with a deleted timestamp before this will be fully deleted.

GarbageCollectResponse

Field Type Label Description
directories Directory repeated

GetDirectoryRequest

GetDirectoryRequest specifies the directory to retrieve information for.

Field Type Label Description
directory_id string
show_deleted bool showDeleted requests directories that have been marked for deletion but have not been garbage collected.

InputLog

InputLog is an input log for a directory.

Field Type Label Description
directory_id string
log_id int64
writable bool writable controls whether new log items will be sent to this log. writable is not set by ListInputLogs.

ListDirectoriesRequest

ListDirectories request. No pagination options are provided.

Field Type Label Description
show_deleted bool showDeleted requests directories that have been marked for deletion but have not been garbage collected.

ListDirectoriesResponse

ListDirectories response contains directories.

Field Type Label Description
directories Directory repeated

ListInputLogsRequest

Field Type Label Description
directory_id string
filter_writable bool filter_writable will only return writable logs when set.

ListInputLogsResponse

Field Type Label Description
logs InputLog repeated

UndeleteDirectoryRequest

UndeleteDirectoryRequest deletes a directory

Field Type Label Description
directory_id string

KeyTransparencyAdmin

The KeyTransparencyAdmin API provides the following resources:

  • Directories Namespaces on which which Key Transparency operates. A directory determines a unique Trillian map to use. It also determines the authentication policies for users and apps within a directory.
    • /v1/directories
Method Name Request Type Response Type Description
ListDirectories ListDirectoriesRequest ListDirectoriesResponse ListDirectories returns a list of all directories this Key Transparency server operates on.
GetDirectory GetDirectoryRequest Directory GetDirectory returns the confiuration information for a given directory.
CreateDirectory CreateDirectoryRequest Directory CreateDirectory creates a new Trillian log/map pair. A unique directoryId must be provided. To create a new directory with the same name as a previously deleted directory, a user must wait X days until the directory is garbage collected.
DeleteDirectory DeleteDirectoryRequest .google.protobuf.Empty DeleteDirectory marks a directory as deleted. Directories will be garbage collected after X days.
UndeleteDirectory UndeleteDirectoryRequest .google.protobuf.Empty UndeleteDirectory marks a previously deleted directory as active if it has not already been garbage collected.
ListInputLogs ListInputLogsRequest ListInputLogsResponse ListInputLogs returns a list of input logs for a directory.
CreateInputLog InputLog InputLog CreateInputLog returns a the created log.
UpdateInputLog InputLog InputLog UpdateInputLog updates the write bit for an input log.
GarbageCollect GarbageCollectRequest GarbageCollectResponse Fully delete soft-deleted directories that have been soft-deleted before the specified timestamp.

Top

v1/frontend.proto

QueueKeyUpdateRequest

QueueKeyUpdateRequest enqueues an update to a user's identity keys.

Field Type Label Description
directory_id string directory_id identifies the directory in which the user lives.
user_id string user_id specifies the id for the user whose keys are being updated.
key_data bytes key_data is the key data to store.

KeyTransparencyFrontend

Manages user keys stored in Key Transparency with a client-friendly API. This service is operated by the application provider, and is authorized to make key changes on users' behalves.

Method Name Request Type Response Type Description
QueueKeyUpdate QueueKeyUpdateRequest .google.protobuf.Empty Enqueues an update to a user's identity keys.

Scalar Value Types

.proto Type Notes C++ Java Python Go C# PHP Ruby
double double double float float64 double float Float
float float float float float32 float float Float
int32 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint32 instead. int32 int int int32 int integer Bignum or Fixnum (as required)
int64 Uses variable-length encoding. Inefficient for encoding negative numbers – if your field is likely to have negative values, use sint64 instead. int64 long int/long int64 long integer/string Bignum
uint32 Uses variable-length encoding. uint32 int int/long uint32 uint integer Bignum or Fixnum (as required)
uint64 Uses variable-length encoding. uint64 long int/long uint64 ulong integer/string Bignum or Fixnum (as required)
sint32 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int32s. int32 int int int32 int integer Bignum or Fixnum (as required)
sint64 Uses variable-length encoding. Signed int value. These more efficiently encode negative numbers than regular int64s. int64 long int/long int64 long integer/string Bignum
fixed32 Always four bytes. More efficient than uint32 if values are often greater than 2^28. uint32 int int uint32 uint integer Bignum or Fixnum (as required)
fixed64 Always eight bytes. More efficient than uint64 if values are often greater than 2^56. uint64 long int/long uint64 ulong integer/string Bignum
sfixed32 Always four bytes. int32 int int int32 int integer Bignum or Fixnum (as required)
sfixed64 Always eight bytes. int64 long int/long int64 long integer/string Bignum
bool bool boolean boolean bool bool boolean TrueClass/FalseClass
string A string must always contain UTF-8 encoded or 7-bit ASCII text. string String str/unicode string string string String (UTF-8)
bytes May contain any arbitrary sequence of bytes. string ByteString str []byte ByteString string String (ASCII-8BIT)