| // Copyright 2016 Google Inc. All Rights Reserved. |
| // |
| // Licensed under the Apache License, Version 2.0 (the "License"); |
| // you may not use this file except in compliance with the License. |
| // You may obtain a copy of the License at |
| // |
| // http://www.apache.org/licenses/LICENSE-2.0 |
| // |
| // Unless required by applicable law or agreed to in writing, software |
| // distributed under the License is distributed on an "AS IS" BASIS, |
| // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| // See the License for the specific language governing permissions and |
| // limitations under the License. |
| |
| syntax = "proto3"; |
| |
| option java_multiple_files = true; |
| option java_package = "com.google.trillian.proto"; |
| option java_outer_classname = "TrillianProto"; |
| option go_package = "github.com/google/trillian"; |
| |
| package trillian; |
| |
| import "crypto/keyspb/keyspb.proto"; |
| import "crypto/sigpb/sigpb.proto"; |
| import "google/protobuf/any.proto"; |
| import "google/protobuf/duration.proto"; |
| import "google/protobuf/timestamp.proto"; |
| |
| // LogRootFormat specifies the fields that are covered by the |
| // SignedLogRoot signature, as well as their ordering and formats. |
| enum LogRootFormat { |
| LOG_ROOT_FORMAT_UNKNOWN = 0; |
| LOG_ROOT_FORMAT_V1 = 1; |
| } |
| |
| // MapRootFormat specifies the fields that are covered by the |
| // SignedMapRoot signature, as well as their ordering and formats. |
| enum MapRootFormat { |
| MAP_ROOT_FORMAT_UNKNOWN = 0; |
| MAP_ROOT_FORMAT_V1 = 1; |
| } |
| |
| // What goes in here? |
| // Things which are exposed through the public trillian APIs. |
| |
| // Defines the way empty / node / leaf hashes are constructed incorporating |
| // preimage protection, which can be application specific. |
| enum HashStrategy { |
| // Hash strategy cannot be determined. Included to enable detection of |
| // mismatched proto versions being used. Represents an invalid value. |
| UNKNOWN_HASH_STRATEGY = 0; |
| |
| // Certificate Transparency strategy: leaf hash prefix = 0x00, node prefix = |
| // 0x01, empty hash is digest([]byte{}), as defined in the specification. |
| RFC6962_SHA256 = 1; |
| |
| // 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. |
| TEST_MAP_HASHER = 2; |
| |
| // Append-only log strategy where leaf nodes are defined as the ObjectHash. |
| // All other properties are equal to RFC6962_SHA256. |
| OBJECT_RFC6962_SHA256 = 3; |
| |
| // The CONIKS sparse tree hasher with SHA512_256 as the hash algorithm. |
| CONIKS_SHA512_256 = 4; |
| |
| // The CONIKS sparse tree hasher with SHA256 as the hash algorithm. |
| CONIKS_SHA256 = 5; |
| } |
| |
| // State of the tree. |
| enum TreeState { |
| // Tree state cannot be determined. Included to enable detection of |
| // mismatched proto versions being used. Represents an invalid value. |
| UNKNOWN_TREE_STATE = 0; |
| |
| // Active trees are able to respond to both read and write requests. |
| ACTIVE = 1; |
| |
| // 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. |
| FROZEN = 2; |
| |
| // Deprecated: now tracked in Tree.deleted. |
| DEPRECATED_SOFT_DELETED = 3 [deprecated = true]; |
| |
| // Deprecated: now tracked in Tree.deleted. |
| DEPRECATED_HARD_DELETED = 4 [deprecated = true]; |
| |
| // A tree that is draining will continue to integrate queued entries. |
| // No new entries should be accepted. |
| DRAINING = 5; |
| } |
| |
| // Type of the tree. |
| enum TreeType { |
| // Tree type cannot be determined. Included to enable detection of mismatched |
| // proto versions being used. Represents an invalid value. |
| UNKNOWN_TREE_TYPE = 0; |
| |
| // Tree represents a verifiable log. |
| LOG = 1; |
| |
| // Tree represents a verifiable map. |
| MAP = 2; |
| |
| // Tree represents a verifiable pre-ordered log, i.e., a log whose entries are |
| // placed according to sequence numbers assigned outside of Trillian. |
| PREORDERED_LOG = 3; |
| } |
| |
| // 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. |
| message Tree { |
| // ID of the tree. |
| // Readonly. |
| int64 tree_id = 1; |
| |
| // State of the tree. |
| // Trees are ACTIVE after creation. At any point the tree may transition |
| // between ACTIVE, DRAINING and FROZEN states. |
| TreeState tree_state = 2; |
| |
| // 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. |
| TreeType tree_type = 3; |
| |
| // Hash strategy to be used by the tree. |
| // Readonly. |
| HashStrategy hash_strategy = 4; |
| |
| // Hash algorithm to be used by the tree. |
| // Readonly. |
| sigpb.DigitallySigned.HashAlgorithm hash_algorithm = 5; |
| |
| // Signature algorithm to be used by the tree. |
| // Readonly. |
| sigpb.DigitallySigned.SignatureAlgorithm signature_algorithm = 6; |
| |
| reserved 18; // Signature cipher suite (removed) |
| reserved 7; // DuplicatePolicy (removed) |
| |
| // Display name of the tree. |
| // Optional. |
| string display_name = 8; |
| |
| // Description of the tree, |
| // Optional. |
| string description = 9; |
| |
| reserved 10; // create_time_millis_since_epoch (removed) |
| reserved 11; // update_time_millis_since_epoch (removed) |
| |
| // 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. |
| google.protobuf.Any private_key = 12; |
| |
| // Storage-specific settings. |
| // Varies according to the storage implementation backing Trillian. |
| google.protobuf.Any storage_settings = 13; |
| |
| // The public key used for verifying tree heads and entry timestamps. |
| // Readonly. |
| keyspb.PublicKey public_key = 14; |
| |
| // Interval after which a new signed root is produced even if there have been |
| // no submission. If zero, this behavior is disabled. |
| google.protobuf.Duration max_root_duration = 15; |
| |
| // Time of tree creation. |
| // Readonly. |
| google.protobuf.Timestamp create_time = 16; |
| |
| // Time of last tree update. |
| // Readonly (automatically assigned on updates). |
| google.protobuf.Timestamp update_time = 17; |
| |
| // 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. |
| bool deleted = 19; |
| |
| // Time of tree deletion, if any. |
| // Readonly. |
| google.protobuf.Timestamp delete_time = 20; |
| } |
| |
| message SignedEntryTimestamp { |
| int64 timestamp_nanos = 1; |
| int64 log_id = 2; |
| sigpb.DigitallySigned signature = 3; |
| } |
| |
| // SignedLogRoot represents a commitment by a Log to a particular tree. |
| message SignedLogRoot { |
| // Deleted: TimestampNanos moved to LogRoot. |
| reserved 1; |
| // Deleted: RootHash moved to LogRoot. |
| reserved 2; |
| // Deleted: TreeSize moved to LogRoot. |
| reserved 3; |
| // Deleted: Signature replaced by LogRootSignature. |
| reserved 4; |
| // Deleted: LogID is associated with the public key that validates signature. |
| reserved 5; |
| // Deleted: TreeRevision moved to LogRoot. |
| reserved 6; |
| |
| // 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). |
| bytes key_hint = 7; |
| |
| // log_root holds the TLS-serialization of the following structure (described |
| // in RFC5246 notation): Clients should validate log_root_signature with |
| // VerifySignedLogRoot before deserializing log_root. |
| // 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_hashlen | |
| // +---+---+---+---+---+---+---+---+---+---+---+---+---+---+-....--+ |
| // |
| // +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ |
| // | timestamp_nanos | revision | |
| // +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+ |
| // |
| // +---+---+---+---+---+-....---+ |
| // | len | metadata | |
| // +---+---+---+---+---+-....---+ |
| // |
| // (with all integers encoded big-endian). |
| bytes log_root = 8; |
| |
| // log_root_signature is the raw signature over log_root. |
| bytes log_root_signature = 9; |
| } |
| |
| // SignedMapRoot represents a commitment by a Map to a particular tree. |
| message SignedMapRoot { |
| reserved 1; // Deprecated: Was timestamp_nanos. Use map_root. |
| reserved 2; // Deprecated: Was root_hash. Use map_root. |
| reserved 3; // Deprecated: Was MapperMetadata. Use map_root. |
| reserved 5; // Deprecated: Was map_id. Use signature. |
| reserved 6; // Deprecated: Was map_revision. Use map_root. |
| reserved 7; // Deprecated: Was metadata Any. Use map_root. |
| reserved 8; // Deprecated: Was metadata bytes. Use map_root. |
| |
| // 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; |
| bytes map_root = 9; |
| // Signature is the raw signature over MapRoot. |
| bytes signature = 4; |
| } |
| |
| // Proof holds a consistency or inclusion proof for a Merkle tree, as returned |
| // by the API. |
| message Proof { |
| // 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. |
| int64 leaf_index = 1; |
| reserved 2; // Contained internal node details (removed) |
| repeated bytes hashes = 3; |
| } |