| Field | Type | Label | Description |
|---|---|---|---|
| log_id | int64 | ||
| leaves | LogLeaf | repeated | |
| charge_to | ChargeTo |
| Field | Type | Label | Description |
|---|---|---|---|
| results | QueuedLogLeaf | repeated | Same number and order as in the corresponding request. |
ChargeTo describes the user(s) associated with the request whose quota should be checked and charged.
| Field | Type | Label | Description |
|---|---|---|---|
| user | string | repeated | 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 QueueLeaf 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. |
| Field | Type | Label | Description |
|---|---|---|---|
| log_id | int64 | ||
| first_tree_size | int64 | ||
| second_tree_size | int64 | ||
| charge_to | ChargeTo |
| Field | Type | Label | Description |
|---|---|---|---|
| proof | Proof | 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. | |
| signed_log_root | SignedLogRoot |
| Field | Type | Label | Description |
|---|---|---|---|
| log_id | int64 | ||
| leaf_index | int64 | ||
| tree_size | int64 | ||
| charge_to | ChargeTo |
| Field | Type | Label | Description |
|---|---|---|---|
| proof | Proof | ||
| leaf | LogLeaf | ||
| signed_log_root | SignedLogRoot |
| Field | Type | Label | Description |
|---|---|---|---|
| log_id | int64 | ||
| leaf_hash | bytes | The leaf hash field provides the Merkle tree hash of the leaf entry to be retrieved. | |
| tree_size | int64 | ||
| order_by_sequence | bool | ||
| charge_to | ChargeTo |
| Field | Type | Label | Description |
|---|---|---|---|
| proof | Proof | repeated | 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. |
| signed_log_root | SignedLogRoot |
| Field | Type | Label | Description |
|---|---|---|---|
| log_id | int64 | ||
| leaf_index | int64 | ||
| tree_size | int64 | ||
| charge_to | ChargeTo |
| Field | Type | Label | Description |
|---|---|---|---|
| proof | Proof | 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. | |
| signed_log_root | SignedLogRoot |
| Field | Type | Label | Description |
|---|---|---|---|
| log_id | int64 | ||
| charge_to | ChargeTo | ||
| first_tree_size | int64 | If first_tree_size is non-zero, the response will include a consistency proof between first_tree_size and the new tree size (if not smaller). |
| Field | Type | Label | Description |
|---|---|---|---|
| signed_log_root | SignedLogRoot | ||
| proof | Proof | 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). |
| Field | Type | Label | Description |
|---|---|---|---|
| log_id | int64 | ||
| start_index | int64 | ||
| count | int64 | ||
| charge_to | ChargeTo |
| Field | Type | Label | Description |
|---|---|---|---|
| leaves | LogLeaf | repeated | 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. |
| signed_log_root | SignedLogRoot |
| Field | Type | Label | Description |
|---|---|---|---|
| log_id | int64 | ||
| charge_to | ChargeTo |
| Field | Type | Label | Description |
|---|---|---|---|
| created | SignedLogRoot |
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:
- leaf_value
- extra_data (optionally)
- leaf_identity_hash (optionally)
- leaf_index (iff the log is a PREORDERED_LOG)
| Field | Type | Label | Description |
|---|---|---|---|
| merkle_leaf_hash | bytes | 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 | bytes | 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 | bytes | 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 | int64 | 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 | bytes | 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. |
| Field | Type | Label | Description |
|---|---|---|---|
| log_id | int64 | ||
| leaf | LogLeaf | ||
| charge_to | ChargeTo |
| Field | Type | Label | Description |
|---|---|---|---|
| queued_leaf | QueuedLogLeaf | 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. |
QueuedLogLeaf provides the result of submitting an entry to the log. TODO(pavelkalinnikov): Consider renaming it to AddLogLeafResult or the like.
| Field | Type | Label | Description |
|---|---|---|---|
| leaf | LogLeaf | 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. |
|
| status | google.rpc.Status | 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. |
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
- an empty response otherwise.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| QueueLeaf | QueueLeafRequest | QueueLeafResponse | QueueLeaf adds a single leaf to the queue of pending leaves for a normal log. |
| GetInclusionProof | GetInclusionProofRequest | GetInclusionProofResponse | 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 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. | | 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). | | 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. | | GetLeavesByRange | GetLeavesByRangeRequest | GetLeavesByRangeResponse | GetLeavesByRange returns a batch of leaves whose leaf indices are in a sequential range. |
CreateTree request.
| Field | Type | Label | Description |
|---|---|---|---|
| tree | Tree | Tree to be created. See Tree and CreateTree for more details. |
DeleteTree request.
| Field | Type | Label | Description |
|---|---|---|---|
| tree_id | int64 | ID of the tree to delete. |
GetTree request.
| Field | Type | Label | Description |
|---|---|---|---|
| tree_id | int64 | ID of the tree to retrieve. |
ListTrees request. No filters or pagination options are provided.
| Field | Type | Label | Description |
|---|---|---|---|
| show_deleted | bool | If true, deleted trees are included in the response. |
ListTrees response. No pagination is provided, all trees the requester has access to are returned.
| Field | Type | Label | Description |
|---|---|---|---|
| tree | Tree | repeated | Trees matching the list request filters. |
UndeleteTree request.
| Field | Type | Label | Description |
|---|---|---|---|
| tree_id | int64 | ID of the tree to undelete. |
UpdateTree request.
| Field | Type | Label | Description |
|---|---|---|---|
| tree | Tree | Tree to be updated. | |
| update_mask | google.protobuf.FieldMask | Fields modified by the update request. For example: "tree_state", "display_name", "description". |
Trillian Administrative interface. Allows creation and management of Trillian trees.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| ListTrees | ListTreesRequest | ListTreesResponse | Lists all trees the requester has access to. |
| GetTree | GetTreeRequest | Tree | Retrieves a tree by ID. |
| CreateTree | CreateTreeRequest | Tree | 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. |
| UpdateTree | UpdateTreeRequest | Tree | Updates a tree. See Tree for details. Readonly fields cannot be updated. |
| DeleteTree | DeleteTreeRequest | Tree | Soft-deletes a tree. A soft-deleted tree may be undeleted for a certain period, after which it'll be permanently deleted. |
| UndeleteTree | UndeleteTreeRequest | Tree | Undeletes a soft-deleted a tree. A soft-deleted tree may be undeleted for a certain period, after which it'll be permanently deleted. |
Proof holds a consistency or inclusion proof for a Merkle tree, as returned by the API.
| Field | Type | Label | Description |
|---|---|---|---|
| leaf_index | int64 | 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. | |
| hashes | bytes | repeated |
SignedLogRoot represents a commitment by a Log to a particular tree.
Note that the signature itself is no-longer provided by Trillian since google#2452 . This functionality was intended to support a niche-use case but added significant complexity and was prone to causing confusion and misunderstanding for personality authors.
| Field | Type | Label | Description |
|---|---|---|---|
| log_root | bytes | log_root holds the TLS-serialization of the following structure (described in RFC5246 notation): |
enum { v1(1), (65535)} Version; struct { uint64 tree_size; opaque root_hash<0..128>; uint64 timestamp_nanos; uint64 revision; opaque metadata<0..65535>; } LogRootV1; struct { Version version; select(version) { case v1: LogRootV1; } } LogRoot;
A serialized v1 log root will therefore be laid out as:
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+-....--+ | ver=1 | tree_size |len| root_hash | +---+---+---+---+---+---+---+---+---+---+---+---+---+---+-....--+
+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ | timestamp_nanos | revision | +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
+---+---+---+---+---+-....---+ | len | metadata | +---+---+---+---+---+-....---+
(with all integers encoded big-endian). |
Represents a tree. 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.
| Field | Type | Label | Description |
|---|---|---|---|
| tree_id | int64 | ID of the tree. Readonly. | |
| tree_state | TreeState | State of the tree. Trees are ACTIVE after creation. At any point the tree may transition between ACTIVE, DRAINING and FROZEN states. | |
| tree_type | TreeType | Type of the tree. Readonly after Tree creation. Exception: Can be switched from PREORDERED_LOG to LOG if the Tree is and remains in the FROZEN state. | |
| display_name | string | Display name of the tree. Optional. | |
| description | string | Description of the tree, Optional. | |
| storage_settings | google.protobuf.Any | Storage-specific settings. Varies according to the storage implementation backing Trillian. | |
| max_root_duration | google.protobuf.Duration | Interval after which a new signed root is produced even if there have been no submission. If zero, this behavior is disabled. | |
| create_time | google.protobuf.Timestamp | Time of tree creation. Readonly. | |
| update_time | google.protobuf.Timestamp | Time of last tree update. Readonly (automatically assigned on updates). | |
| deleted | bool | 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. | |
| delete_time | google.protobuf.Timestamp | Time of tree deletion, if any. 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 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 |
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. |
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. |
| 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. |
| .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) |