393 lines
12 KiB
Protocol Buffer
393 lines
12 KiB
Protocol Buffer
/*
|
|
* Copyright 2024 Signal Messenger, LLC
|
|
* SPDX-License-Identifier: AGPL-3.0-only
|
|
*/
|
|
|
|
syntax = "proto3";
|
|
|
|
option java_multiple_files = true;
|
|
option java_package = "org.signal.keytransparency.client";
|
|
|
|
package kt_query;
|
|
|
|
/**
|
|
* An external-facing, read-only key transparency service used by Signal's chat server
|
|
* to look up and monitor identifiers.
|
|
* There are three types of identifier mappings stored by the key transparency log:
|
|
* - An ACI which maps to an ACI identity key
|
|
* - An E164-formatted phone number which maps to an ACI
|
|
* - A username hash which also maps to an ACI
|
|
* Separately, the log also stores and periodically updates a fixed value known as the `distinguished` key.
|
|
* Clients use the verified tree head from looking up this key for future calls to the Search and Monitor endpoints.
|
|
*/
|
|
service KeyTransparencyQueryService {
|
|
/**
|
|
* An endpoint used by clients to retrieve the most recent distinguished tree
|
|
* head, which should be used to derive consistency parameters for
|
|
* subsequent Search and Monitor requests. It should be the first key
|
|
* transparency RPC a client calls.
|
|
*/
|
|
rpc Distinguished(DistinguishedRequest) returns (DistinguishedResponse) {}
|
|
/**
|
|
* An endpoint used by clients to search for one or more identifiers in the transparency log.
|
|
* The server returns proof that the identifier(s) exist in the log.
|
|
*/
|
|
rpc Search(SearchRequest) returns (SearchResponse) {}
|
|
/**
|
|
* An endpoint that allows users to monitor a group of identifiers by returning proof that the log continues to be
|
|
* constructed correctly in later entries for those identifiers.
|
|
*/
|
|
rpc Monitor(MonitorRequest) returns (MonitorResponse) {}
|
|
}
|
|
|
|
message SearchRequest {
|
|
/**
|
|
* The ACI to look up in the log.
|
|
*/
|
|
bytes aci = 1;
|
|
/**
|
|
* The ACI identity key that the client thinks the ACI maps to in the log.
|
|
*/
|
|
bytes aci_identity_key = 2;
|
|
/**
|
|
* The username hash to look up in the log.
|
|
*/
|
|
optional bytes username_hash = 3;
|
|
/**
|
|
* The E164 to look up in the log along with associated data.
|
|
*/
|
|
optional E164SearchRequest e164_search_request = 4;
|
|
/**
|
|
* The tree head size(s) to prove consistency against.
|
|
*/
|
|
ConsistencyParameters consistency = 5;
|
|
}
|
|
|
|
/**
|
|
* E164SearchRequest contains the data that the user must provide when looking up an E164.
|
|
*/
|
|
message E164SearchRequest {
|
|
/**
|
|
* The E164 that the client wishes to look up in the transparency log.
|
|
*/
|
|
string e164 = 1;
|
|
/**
|
|
* The unidentified access key of the account associated with the provided E164.
|
|
*/
|
|
bytes unidentified_access_key = 2;
|
|
}
|
|
|
|
/**
|
|
* SearchResponse contains search proofs for each of the requested identifiers.
|
|
*/
|
|
message SearchResponse {
|
|
/**
|
|
* A signed representation of the log tree's current state along with some
|
|
* additional information necessary for validation such as a consistency proof and an auditor-signed tree head.
|
|
*/
|
|
FullTreeHead tree_head = 1;
|
|
/**
|
|
* The ACI search response is always provided.
|
|
*/
|
|
CondensedTreeSearchResponse aci = 2;
|
|
/**
|
|
* This response is only provided if all of the conditions are met:
|
|
* - the E164 exists in the log
|
|
* - its mapped ACI matches the one provided in the request
|
|
* - the account associated with the ACI is discoverable
|
|
* - the unidentified access key provided in E164SearchRequest matches the one on the account
|
|
*/
|
|
optional CondensedTreeSearchResponse e164 = 3;
|
|
/**
|
|
* This response is only provided if the username hash exists in the log and
|
|
* its mapped ACI matches the one provided in the request.
|
|
*/
|
|
optional CondensedTreeSearchResponse username_hash = 4;
|
|
}
|
|
|
|
/**
|
|
* The tree head size(s) to prove consistency against. A client's very first
|
|
* key transparency request should be looking up the "distinguished" key;
|
|
* in this case, both fields will be omitted since the client has no previous
|
|
* tree heads to prove consistency against.
|
|
*/
|
|
message ConsistencyParameters {
|
|
/**
|
|
* The non-distinguished tree head size to prove consistency against.
|
|
* This field may be omitted if the client is looking up an identifier
|
|
* for the first time.
|
|
*/
|
|
optional uint64 last = 1;
|
|
/**
|
|
* The distinguished tree head size to prove consistency against.
|
|
* This field may be omitted when the client is looking up the
|
|
* "distinguished" key for the very first time.
|
|
*/
|
|
optional uint64 distinguished = 2;
|
|
}
|
|
|
|
/**
|
|
* DistinguishedRequest looks up the most recent distinguished key in the
|
|
* transparency log.
|
|
*/
|
|
message DistinguishedRequest {
|
|
/**
|
|
* The tree size of the client's last verified distinguished request. With the
|
|
* exception of a client's very first request, this field should always be
|
|
* set.
|
|
*/
|
|
optional uint64 last = 1;
|
|
}
|
|
|
|
/**
|
|
* DistinguishedResponse contains the tree head and search proof for the most
|
|
* recent `distinguished` key in the log.
|
|
*/
|
|
message DistinguishedResponse {
|
|
/**
|
|
* A signed representation of the log tree's current state along with some
|
|
* additional information necessary for validation such as a consistency proof and an auditor-signed tree head.
|
|
*/
|
|
FullTreeHead tree_head = 1;
|
|
/**
|
|
* This search response is always provided.
|
|
*/
|
|
CondensedTreeSearchResponse distinguished = 2;
|
|
}
|
|
|
|
message CondensedTreeSearchResponse {
|
|
/**
|
|
* A proof that is combined with the original requested identifier and the VRF public key
|
|
* and outputs whether the proof is valid, and if so, the commitment index.
|
|
*/
|
|
bytes vrf_proof = 1;
|
|
/**
|
|
* A proof that the binary search for the given identifier was done correctly.
|
|
*/
|
|
SearchProof search = 2;
|
|
/**
|
|
* A 32-byte value computed based on the log position of the identifier
|
|
* and a random 32 byte key that is only known by the key transparency service.
|
|
* It is provided so that clients can recompute and verify the commitment.
|
|
*/
|
|
bytes opening = 3;
|
|
/**
|
|
* The new or updated value that the identifier maps to.
|
|
*/
|
|
UpdateValue value = 4;
|
|
}
|
|
|
|
message FullTreeHead {
|
|
/**
|
|
* A representation of the log tree's current state signed by the key transparency service.
|
|
*/
|
|
TreeHead tree_head = 1;
|
|
/**
|
|
* A consistency proof between the current tree size and the requested tree size.
|
|
*/
|
|
repeated bytes last = 2;
|
|
/**
|
|
* A consistency proof between the current tree size and the requested distinguished tree size.
|
|
*/
|
|
repeated bytes distinguished = 3;
|
|
/**
|
|
* A list of tree heads signed by third-party auditors.
|
|
*/
|
|
repeated FullAuditorTreeHead full_auditor_tree_heads = 4;
|
|
}
|
|
|
|
/**
|
|
* TreeHead represents the key transparency service's view of the transparency log.
|
|
*/
|
|
message TreeHead {
|
|
/**
|
|
* The number of entries in the log tree.
|
|
*/
|
|
uint64 tree_size = 1;
|
|
/**
|
|
* The time in milliseconds since epoch when the tree head signature was generated.
|
|
*/
|
|
int64 timestamp = 2;
|
|
/**
|
|
* A list of the key transparency service's signatures over the transparency log. Since the
|
|
* signed data structure assumes one auditor, the key transparency service generates
|
|
* one signature per auditor.
|
|
*/
|
|
repeated Signature signatures = 3;
|
|
}
|
|
|
|
/**
|
|
* The key transparency service provides one Signature per auditor.
|
|
*/
|
|
message Signature {
|
|
/**
|
|
* The public component of the Ed25519 key pair that the auditor used to sign its view
|
|
* of the transparency log. This value allows clients to identify the corresponding signature.
|
|
*/
|
|
bytes auditor_public_key = 1;
|
|
/**
|
|
* The key transparency service's signature over the transparency log using the
|
|
* the given public auditor key.
|
|
*/
|
|
bytes signature = 2;
|
|
}
|
|
|
|
/**
|
|
* AuditorTreeHead represents an auditor's view of the transparency log.
|
|
*/
|
|
message AuditorTreeHead {
|
|
/**
|
|
* The number of entries in the auditor's view of the transparency log.
|
|
*/
|
|
uint64 tree_size = 1;
|
|
/**
|
|
* The time in milliseconds since epoch when the auditor's signature was generated.
|
|
*/
|
|
int64 timestamp = 2;
|
|
/**
|
|
* The auditor's signature computed over its view of the transparency log's current state
|
|
* and long-term log configuration.
|
|
*/
|
|
bytes signature = 3;
|
|
}
|
|
|
|
message FullAuditorTreeHead {
|
|
/**
|
|
* A representation of the log tree state signed by a third-party auditor.
|
|
*/
|
|
AuditorTreeHead tree_head = 1;
|
|
/**
|
|
* The root hash of the log tree when the auditor produced the tree head signature.
|
|
* Provided if the auditor tree head size is smaller than the size of the most recent
|
|
* tree head provided to the user.
|
|
*/
|
|
optional bytes root_value = 2;
|
|
/**
|
|
* A consistency proof between the auditor tree head and the most recent tree head.
|
|
* Provided if the auditor tree head size is smaller than the size of the most recent
|
|
* tree head provided by the key transparency service to the user.
|
|
*/
|
|
repeated bytes consistency = 3;
|
|
/**
|
|
* The public component of the Ed25519 key pair that the third-party auditor used to generate
|
|
* a signature. This value allows clients to identify the auditor tree head and signature.
|
|
*/
|
|
bytes public_key = 4;
|
|
}
|
|
|
|
/**
|
|
* A ProofStep represents one "step" or log entry in the binary search
|
|
* and can be used to calculate a log tree leaf hash.
|
|
*/
|
|
message ProofStep {
|
|
/**
|
|
* Provides the data needed to recompute the prefix tree root hash corresponding to the given log entry.
|
|
*/
|
|
PrefixSearchResult prefix = 1;
|
|
/**
|
|
* A cryptographic hash of the update used to calculate the log tree leaf hash.
|
|
*/
|
|
bytes commitment = 2;
|
|
}
|
|
|
|
message SearchProof {
|
|
/**
|
|
* The position in the log tree of the first occurrence of the requested identifier.
|
|
*/
|
|
uint64 pos = 1;
|
|
/**
|
|
* The steps of a binary search through the entries of the log tree for the given identifier version.
|
|
* Each ProofStep corresponds to a log entry and provides the information necessary to recompute a log tree
|
|
* leaf hash.
|
|
*/
|
|
repeated ProofStep steps = 2;
|
|
/**
|
|
* A batch inclusion proof for all log tree leaves involved in the binary search for the given identifier.
|
|
*/
|
|
repeated bytes inclusion = 3;
|
|
}
|
|
|
|
|
|
message UpdateValue {
|
|
/**
|
|
* The new mapped value for an identifier or the "distinguished" key.
|
|
*/
|
|
bytes value = 1;
|
|
}
|
|
|
|
message PrefixSearchResult {
|
|
/**
|
|
* A proof from a prefix tree that indicates a search was done correctly for a given identifier.
|
|
* The elements of this array are the copath of the prefix tree leaf node in bottom-to-top order.
|
|
*/
|
|
repeated bytes proof = 1;
|
|
/**
|
|
* The version of the requested identifier in the prefix tree.
|
|
*/
|
|
uint32 counter = 2;
|
|
}
|
|
|
|
message MonitorRequest {
|
|
AciMonitorRequest aci = 1;
|
|
optional UsernameHashMonitorRequest username_hash = 2;
|
|
optional E164MonitorRequest e164 = 3;
|
|
ConsistencyParameters consistency = 4;
|
|
}
|
|
|
|
message AciMonitorRequest {
|
|
bytes aci = 1;
|
|
uint64 entry_position = 2;
|
|
bytes commitment_index = 3;
|
|
}
|
|
|
|
message UsernameHashMonitorRequest {
|
|
bytes username_hash = 1;
|
|
uint64 entry_position = 2;
|
|
bytes commitment_index = 3;
|
|
}
|
|
|
|
message E164MonitorRequest {
|
|
string e164 = 1;
|
|
uint64 entry_position = 2;
|
|
bytes commitment_index = 3;
|
|
}
|
|
|
|
message MonitorProof {
|
|
/**
|
|
* Generated based on the monitored entry provided in MonitorRequest.entries. Each ProofStep
|
|
* corresponds to a log tree entry that exists in the search path to each monitored entry
|
|
* and that came *after* that monitored entry. It proves that the log tree has been constructed
|
|
* correctly at that later entry. This list also includes any remaining entries
|
|
* along the "frontier" of the log tree which proves that the very last entry in the log
|
|
* has been constructed correctly.
|
|
*/
|
|
repeated ProofStep steps = 1;
|
|
}
|
|
|
|
message MonitorResponse {
|
|
/**
|
|
* A signed representation of the log tree's current state along with some
|
|
* additional information necessary for validation such as a consistency proof and an auditor-signed tree head.
|
|
*/
|
|
FullTreeHead tree_head = 1;
|
|
/**
|
|
* A proof that the MonitorRequest's ACI continues to be constructed correctly in later entries of the log tree.
|
|
*/
|
|
MonitorProof aci = 2;
|
|
/**
|
|
* A proof that the username hash continues to be constructed correctly in later entries of the log tree.
|
|
* Will be absent if the request did not include a UsernameHashMonitorRequest.
|
|
*/
|
|
optional MonitorProof username_hash = 3;
|
|
/**
|
|
* A proof that the e164 continues to be constructed correctly in later entries of the log tree.
|
|
* Will be absent if the request did not include a E164MonitorRequest.
|
|
*/
|
|
optional MonitorProof e164 = 4;
|
|
/**
|
|
* A batch inclusion proof that the log entries involved in the binary search for each of the entries
|
|
* being monitored in the request are included in the current log tree.
|
|
*/
|
|
repeated bytes inclusion = 5;
|
|
}
|