You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
user is a list of personality-defined strings. Trillian will treat them as /User/%{user}/... keys when checking and charging quota. If one or more of the specified users has insufficient quota, the request will be denied.
As an example, a Certificate Transparency frontend might set the following user strings when sending a QueueLeaves request to the Trillian log: - The requesting IP address. This would limit the number of requests per IP. - The "intermediate-<hash>" for each of the intermediate certificates in the submitted chain. This would have the effect of limiting the rate of submissions under a given intermediate/root. |
The proof field may be empty if the requested tree_size was larger than that available at the server (e.g. because there is skew between server instances, and an earlier client request was processed by a more up-to-date instance). In this case, the signed_log_root field will indicate the tree size that the server is aware of, and the proof field will be empty.
Logs can potentially contain leaves with duplicate hashes so it's possible for this to return multiple proofs. If the leaf index for a particular instance of the requested Merkle leaf hash is beyond the requested tree size, the corresponding proof entry will be missing.
The proof field may be empty if the requested tree_size was larger than that available at the server (e.g. because there is skew between server instances, and an earlier client request was processed by a more up-to-date instance). In this case, the signed_log_root field will indicate the tree size that the server is aware of, and the proof field will be empty.
proof is filled in with a consistency proof if first_tree_size in GetLatestSignedLogRootRequest is non-zero (and within the tree size available at the server).
Returned log leaves starting from the start_index of the request, in order. There may be fewer than request.count leaves returned, if the requested range extended beyond the size of the tree or if the server opted to return fewer leaves than requested.
LogLeaf describes a leaf in the Log's Merkle tree, corresponding to a single log entry.
Each leaf has a unique leaf index in the scope of this tree. Clients submitting new
leaf entries should only set the following fields:
merkle_leaf_hash holds the Merkle leaf hash over leaf_value. This is calculated by the Trillian server when leaves are added to the tree, using the defined hashing algorithm and strategy for the tree; as such, the client does not need to set it on leaf submissions.
leaf_value holds the data that forms the value of the Merkle tree leaf. The client should set this field on all leaf submissions, and is responsible for ensuring its validity (the Trillian server treats it as an opaque blob).
extra_data holds additional data associated with the Merkle tree leaf. The client may set this data on leaf submissions, and the Trillian server will return it on subsequent read operations. However, the contents of this field are not covered by and do not affect the Merkle tree hash calculations.
leaf_index indicates the index of this leaf in the Merkle tree. This field is returned on all read operations, but should only be set for leaf submissions in PREORDERED_LOG mode (for a normal log the leaf index is assigned by Trillian when the submitted leaf is integrated into the Merkle tree).
leaf_identity_hash provides a hash value that indicates the client's concept of which leaf entries should be considered identical.
This mechanism allows the client personality to indicate that two leaves should be considered "duplicates" even though their leaf_values differ.
If this is not set on leaf submissions, the Trillian server will take its value to be the same as merkle_leaf_hash (and thus only leaves with identical leaf_value contents will be considered identical).
For example, in Certificate Transparency each certificate submission is associated with a submission timestamp, but subsequent submissions of the same certificate should be considered identical. This is achieved by setting the leaf identity hash to a hash over (just) the certificate, whereas the Merkle leaf hash encompasses both the certificate and its submission time -- allowing duplicate certificates to be detected.
Continuing the CT example, for a CT mirror personality (which must allow dupes since the source log could contain them), the part of the personality which fetches and submits the entries might set leaf_identity_hash to H(leaf_index||cert).
TODO(pavelkalinnikov): Consider instead using H(cert) and allowing identity hash dupes in PREORDERED_LOG mode, for it can later be upgraded to LOG which will need to correctly detect duplicates with older entries when new ones get queued. |
| queue_timestamp | google.protobuf.Timestamp | | queue_timestamp holds the time at which this leaf was queued for inclusion in the Log, or zero if the entry was submitted without queuing. Clients should not set this field on submissions. |
| integrate_timestamp | google.protobuf.Timestamp | | integrate_timestamp holds the time at which this leaf was integrated into the tree. Clients should not set this field on submissions. |
Proof
Proof holds a consistency or inclusion proof for a Merkle tree, as returned
by the API.
leaf_index indicates the requested leaf index when this message is used for a leaf inclusion proof. This field is set to zero when this message is used for a consistency proof.
queued_leaf describes the leaf which is or will be incorporated into the Log. If the submitted leaf was already present in the Log (as indicated by its leaf identity hash), then the returned leaf will be the pre-existing leaf entry rather than the submitted leaf.
The leaf as it was stored by Trillian. Empty unless status.code is: - google.rpc.OK: the leaf data is the same as in the request. - google.rpc.ALREADY_EXISTS or 'google.rpc.FAILED_PRECONDITION: the leaf` is the conflicting one already in the log.
The status of adding the leaf. - google.rpc.OK: successfully added. - google.rpc.ALREADY_EXISTS: the leaf is a duplicate of an already existing one. Either leaf_identity_hash is the same in the LOG mode, or leaf_index in the PREORDERED_LOG. - google.rpc.FAILED_PRECONDITION: A conflicting entry is already present in the log, e.g., same leaf_index but different leaf_data.
TrillianLog
The TrillianLog service provides access to an append-only Log data structure
as described in the Verifiable Data
Structures paper.
The API supports adding new entries to the Merkle tree for a specific Log
instance (identified by its log_id) in two modes:
For a normal log, new leaf entries are queued up for subsequent
inclusion in the log, and the leaves are assigned consecutive leaf_index
values as part of that integration process.
For a 'pre-ordered log', new entries have an already-defined leaf
ordering, and leaves are only integrated into the Merkle tree when a
contiguous range of leaves is available.
The API also supports read operations to retrieve leaf contents, and to
provide cryptographic proofs of leaf inclusion and of the append-only nature
of the Log.
Each API request also includes a charge_to field, which allows API users
to provide quota identifiers that should be "charged" for each API request
(and potentially rejected with codes.ResourceExhausted).
Various operations on the API also allows for 'server skew', which can occur
when different API requests happen to be handled by different server instances
that may not all be up to date. An API request that is relative to a specific
tree size may reach a server instance that is not yet aware of this tree size;
in this case the server will typically return an OK response that contains:
a signed log root that indicates the tree size that it is aware of
GetInclusionProof returns an inclusion proof for a leaf with a given index in a particular tree.
If the requested tree_size is larger than the server is aware of, the response will include the latest known log root and an empty proof. |
| GetInclusionProofByHash | GetInclusionProofByHashRequest | GetInclusionProofByHashResponse | GetInclusionProofByHash returns an inclusion proof for any leaves that have the given Merkle hash in a particular tree.
If any of the leaves that match the given Merkle has have a leaf index that is beyond the requested tree size, the corresponding proof entry will be empty. |
| GetConsistencyProof | GetConsistencyProofRequest | GetConsistencyProofResponse | GetConsistencyProof returns a consistency proof between different sizes of a particular tree.
If the requested tree size is larger than the server is aware of, the response will include the latest known log root and an empty proof. |
| GetLatestSignedLogRoot | GetLatestSignedLogRootRequest | GetLatestSignedLogRootResponse | GetLatestSignedLogRoot returns the latest signed log root for a given tree, and optionally also includes a consistency proof from an earlier tree size to the new size of the tree.
If the earlier tree size is larger than the server is aware of, an InvalidArgument error is returned. |
| GetSequencedLeafCount | GetSequencedLeafCountRequest | GetSequencedLeafCountResponse | GetSequencedLeafCount returns the total number of leaves that have been integrated into the given tree.
DO NOT USE - FOR DEBUGGING/TEST ONLY
(Use GetLatestSignedLogRoot then de-serialize the Log Root and use use the tree size field within.) |
| GetEntryAndProof | GetEntryAndProofRequest | GetEntryAndProofResponse | GetEntryAndProof returns a log leaf and the corresponding inclusion proof to a specified tree size, for a given leaf index in a particular tree.
If the requested tree size is unavailable but the leaf is in scope for the current tree, the returned proof will be for the current tree size rather than the requested tree size. |
| InitLog | InitLogRequest | InitLogResponse | InitLog initializes a particular tree, creating the initial signed log root (which will be of size 0). |
| QueueLeaves | QueueLeavesRequest | QueueLeavesResponse | QueueLeaf adds a batch of leaves to the queue of pending leaves for a normal log. |
| AddSequencedLeaves | AddSequencedLeavesRequest | AddSequencedLeavesResponse | AddSequencedLeaves adds a batch of leaves with assigned sequence numbers to a pre-ordered log. The indices of the provided leaves must be contiguous. |
| GetLeavesByIndex | GetLeavesByIndexRequest | GetLeavesByIndexResponse | GetLeavesByIndex returns a batch of leaves whose leaf indices are provided in the request. |
| GetLeavesByRange | GetLeavesByRangeRequest | GetLeavesByRangeResponse | GetLeavesByRange returns a batch of leaves whose leaf indices are in a sequential range. |
| GetLeavesByHash | GetLeavesByHashRequest | GetLeavesByHashResponse | GetLeavesByHash returns a batch of leaves which are identified by their Merkle leaf hash values. |
GetLastInRangeByRevisionRequest specifies a range in the map at a revision.
The range is defined as the entire subtree below a particular point in the
Merkle tree. Another way of saying this is that the range matches all leaves
that share a common prefix of prefix_bits with prefix.
index is the location of this leaf. All indexes for a given Map must contain a constant number of bits. These are not numeric indices. Note that this is typically derived using a hash and thus the length of all indices in the map will match the number of bits in the hash function.
leaf_hash is the tree hash of leaf_value. This does not need to be set on SetMapLeavesRequest; the server will fill it in. For an empty leaf (len(leaf_value)==0), there may be two possible values for this hash: - If the leaf has never been set, it counts as an empty subtree and a nil value is used. - If the leaf has been explicitly set to a zero-length entry, it no longer counts as empty and the value of hasher.HashLeaf(index, nil) will be used.
inclusion holds the inclusion proof for this leaf in the map root. It holds one entry for each level of the tree; combining each of these in turn with the leaf's hash (according to the tree's hash strategy) reproduces the root hash. A nil entry for a particular level indicates that the node in question has an empty subtree beneath it (and so its associated hash value is hasher.HashEmpty(index, height) rather than hasher.HashChildren(l_hash, r_hash)).
The map revision to associate the leaves with. The request will fail if this revision already exists, does not match the current write revision, or is negative. If revision = 0 then the leaves will be written to the current write revision.
Metadata that the Map should associate with the new Map root after incorporating the leaf changes. The metadata will be reflected in the Map Root published for this revision. Map personalities should use metadata to persist any state needed later to continue mapping from an external data source.
The map revision to associate the leaves with. The request will fail if this revision already exists, does not match the current write revision, or is negative. If revision = 0 then the leaves will be written to the current write revision.
The map revision that the leaves will be published at. This may be accompanied by a proof that the write request has been included in an input log in the future.
TrillianMap
TrillianMap defines a service which provides access to a Verifiable Map as
defined in the Verifiable Data Structures paper.
GetLeaves returns an inclusion proof for each index requested. For indexes that do not exist, the inclusion proof will use nil for the empty leaf value.
GetLeavesByRevisionNoProof returns the requested map leaves without inclusion proofs. This API is designed for internal use where verification is not needed.
SetLeaves sets the values for the provided leaves, and returns the new map root if successful. Note that if a SetLeaves request fails for a server-side reason (i.e. not an invalid request), the API user is required to retry the request before performing a different SetLeaves request.
TrillianMapWrite defines a service to allow writes against a Verifiable Map
that will be readable via the TrillianMap service. The write API does not
expose any Merkle Tree properties. This allows key/value writes to be
decoupled from the Merkle Tree synthesis and publishing.
Creates a new tree. System-generated fields are not required and will be ignored if present, e.g.: tree_id, create_time and update_time. Returns the created tree, with all system-generated fields assigned.
key_hint is a hint to identify the public key for signature verification. key_hint is not authenticated and may be incorrect or missing, in which case all known public keys may be used to verify the signature. When directly communicating with a Trillian gRPC server, the key_hint will typically contain the LogID encoded as a big-endian 64-bit integer; however, in other contexts the key_hint is likely to have different contents (e.g. it could be a GUID, a URL + TreeID, or it could be derived from the public key itself).
map_root holds the TLS-serialization of the following structure (described in RFC5246 notation): Clients should validate signature with VerifySignedMapRoot before deserializing map_root. enum { v1(1), (65535)} Version; struct { opaque root_hash<0..128>; uint64 timestamp_nanos; uint64 revision; opaque metadata<0..65535>; } MapRootV1; struct { Version version; select(version) { case v1: MapRootV1; } } MapRoot;
Represents a tree, which may be either a verifiable log or map.
Readonly attributes are assigned at tree creation, after which they may not
be modified.
Note: Many APIs within the rest of the code require these objects to
be provided. For safety they should be obtained via Admin API calls and
not created dynamically.
Identifies the private key used for signing tree heads and entry timestamps. This can be any type of message to accommodate different key management systems, e.g. PEM files, HSMs, etc. Private keys are write-only: they're never returned by RPCs. The private_key message can be changed after a tree is created, but the underlying key must remain the same - this is to enable migrating a key from one provider to another.
If true, the tree has been deleted. Deleted trees may be undeleted during a certain time window, after which they're permanently deleted (and unrecoverable). Readonly.
Defines the way empty / node / leaf hashes are constructed incorporating
preimage protection, which can be application specific.
Name
Number
Description
UNKNOWN_HASH_STRATEGY
0
Hash strategy cannot be determined. Included to enable detection of mismatched proto versions being used. Represents an invalid value.
RFC6962_SHA256
1
Certificate Transparency strategy: leaf hash prefix = 0x00, node prefix = 0x01, empty hash is digest([]byte{}), as defined in the specification.
TEST_MAP_HASHER
2
Sparse Merkle Tree strategy: leaf hash prefix = 0x00, node prefix = 0x01, empty branch is recursively computed from empty leaf nodes. NOT secure in a multi tree environment. For testing only.
OBJECT_RFC6962_SHA256
3
Append-only log strategy where leaf nodes are defined as the ObjectHash. All other properties are equal to RFC6962_SHA256.
CONIKS_SHA512_256
4
The CONIKS sparse tree hasher with SHA512_256 as the hash algorithm.
CONIKS_SHA256
5
The CONIKS sparse tree hasher with SHA256 as the hash algorithm.
LogRootFormat
LogRootFormat specifies the fields that are covered by the
SignedLogRoot signature, as well as their ordering and formats.
Name
Number
Description
LOG_ROOT_FORMAT_UNKNOWN
0
LOG_ROOT_FORMAT_V1
1
MapRootFormat
MapRootFormat specifies the fields that are covered by the
SignedMapRoot signature, as well as their ordering and formats.
Name
Number
Description
MAP_ROOT_FORMAT_UNKNOWN
0
MAP_ROOT_FORMAT_V1
1
TreeState
State of the tree.
Name
Number
Description
UNKNOWN_TREE_STATE
0
Tree state cannot be determined. Included to enable detection of mismatched proto versions being used. Represents an invalid value.
ACTIVE
1
Active trees are able to respond to both read and write requests.
FROZEN
2
Frozen trees are only able to respond to read requests, writing to a frozen tree is forbidden. Trees should not be frozen when there are entries in the queue that have not yet been integrated. See the DRAINING state for this case.
DEPRECATED_SOFT_DELETED
3
Deprecated: now tracked in Tree.deleted.
DEPRECATED_HARD_DELETED
4
Deprecated: now tracked in Tree.deleted.
DRAINING
5
A tree that is draining will continue to integrate queued entries. No new entries should be accepted.
TreeType
Type of the tree.
Name
Number
Description
UNKNOWN_TREE_TYPE
0
Tree type cannot be determined. Included to enable detection of mismatched proto versions being used. Represents an invalid value.
LOG
1
Tree represents a verifiable log.
MAP
2
Tree represents a verifiable map.
PREORDERED_LOG
3
Tree represents a verifiable pre-ordered log, i.e., a log whose entries are placed according to sequence numbers assigned outside of Trillian.