github.com/bartle-stripe/trillian@v1.2.1/trillian.proto (about) 1 // Copyright 2016 Google Inc. All Rights Reserved. 2 // 3 // Licensed under the Apache License, Version 2.0 (the "License"); 4 // you may not use this file except in compliance with the License. 5 // You may obtain a copy of the License at 6 // 7 // http://www.apache.org/licenses/LICENSE-2.0 8 // 9 // Unless required by applicable law or agreed to in writing, software 10 // distributed under the License is distributed on an "AS IS" BASIS, 11 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12 // See the License for the specific language governing permissions and 13 // limitations under the License. 14 15 syntax = "proto3"; 16 17 option java_multiple_files = true; 18 option java_package = "com.google.trillian.proto"; 19 option java_outer_classname = "TrillianProto"; 20 option go_package = "github.com/google/trillian"; 21 22 package trillian; 23 24 import "crypto/keyspb/keyspb.proto"; 25 import "crypto/sigpb/sigpb.proto"; 26 import "google/protobuf/any.proto"; 27 import "google/protobuf/duration.proto"; 28 import "google/protobuf/timestamp.proto"; 29 30 31 // LogRootFormat specifies the fields that are covered by the 32 // SignedLogRoot signature, as well as their ordering and formats. 33 enum LogRootFormat { 34 LOG_ROOT_FORMAT_UNKNOWN = 0; 35 LOG_ROOT_FORMAT_V1 = 1; 36 } 37 38 // MapRootFormat specifies the fields that are covered by the 39 // SignedMapRoot signature, as well as their ordering and formats. 40 enum MapRootFormat { 41 MAP_ROOT_FORMAT_UNKNOWN = 0; 42 MAP_ROOT_FORMAT_V1 = 1; 43 } 44 45 46 // What goes in here? 47 // Things which are exposed through the public trillian APIs. 48 49 // Defines the way empty / node / leaf hashes are constructed incorporating 50 // preimage protection, which can be application specific. 51 enum HashStrategy { 52 // Hash strategy cannot be determined. Included to enable detection of 53 // mismatched proto versions being used. Represents an invalid value. 54 UNKNOWN_HASH_STRATEGY = 0; 55 56 // Certificate Transparency strategy: leaf hash prefix = 0x00, node prefix = 57 // 0x01, empty hash is digest([]byte{}), as defined in the specification. 58 RFC6962_SHA256 = 1; 59 60 // Sparse Merkle Tree strategy: leaf hash prefix = 0x00, node prefix = 0x01, 61 // empty branch is recursively computed from empty leaf nodes. 62 // NOT secure in a multi tree environment. For testing only. 63 TEST_MAP_HASHER = 2; 64 65 // Append-only log strategy where leaf nodes are defined as the ObjectHash. 66 // All other properties are equal to RFC6962_SHA256. 67 OBJECT_RFC6962_SHA256 = 3; 68 69 // The CONIKS sparse tree hasher with SHA512_256 as the hash algorithm. 70 CONIKS_SHA512_256 = 4; 71 } 72 73 // State of the tree. 74 enum TreeState { 75 // Tree state cannot be determined. Included to enable detection of 76 // mismatched proto versions being used. Represents an invalid value. 77 UNKNOWN_TREE_STATE = 0; 78 79 // Active trees are able to respond to both read and write requests. 80 ACTIVE = 1; 81 82 // Frozen trees are only able to respond to read requests, writing to a frozen 83 // tree is forbidden. Trees should not be frozen when there are entries 84 // in the queue that have not yet been integrated. See the DRAINING 85 // state for this case. 86 FROZEN = 2; 87 88 // Deprecated: now tracked in Tree.deleted. 89 DEPRECATED_SOFT_DELETED = 3 [deprecated = true]; 90 91 // Deprecated: now tracked in Tree.deleted. 92 DEPRECATED_HARD_DELETED = 4 [deprecated = true]; 93 94 // A tree that is draining will continue to integrate queued entries. 95 // No new entries should be accepted. 96 DRAINING = 5; 97 } 98 99 // Type of the tree. 100 enum TreeType { 101 // Tree type cannot be determined. Included to enable detection of mismatched 102 // proto versions being used. Represents an invalid value. 103 UNKNOWN_TREE_TYPE = 0; 104 105 // Tree represents a verifiable log. 106 LOG = 1; 107 108 // Tree represents a verifiable map. 109 MAP = 2; 110 111 // Tree represents a verifiable pre-ordered log, i.e., a log whose entries are 112 // placed according to sequence numbers assigned outside of Trillian. 113 PREORDERED_LOG = 3; 114 } 115 116 // Represents a tree, which may be either a verifiable log or map. 117 // Readonly attributes are assigned at tree creation, after which they may not 118 // be modified. 119 // 120 // Note: Many APIs within the rest of the code require these objects to 121 // be provided. For safety they should be obtained via Admin API calls and 122 // not created dynamically. 123 message Tree { 124 // ID of the tree. 125 // Readonly. 126 int64 tree_id = 1; 127 128 // State of the tree. 129 // Trees are ACTIVE after creation. At any point the tree may transition 130 // between ACTIVE, DRAINING and FROZEN states. 131 TreeState tree_state = 2; 132 133 // Type of the tree. 134 // Readonly after Tree creation. Exception: Can be switched from 135 // PREORDERED_LOG to LOG if the Tree is and remains in the FROZEN state. 136 TreeType tree_type = 3; 137 138 // Hash strategy to be used by the tree. 139 // Readonly. 140 HashStrategy hash_strategy = 4; 141 142 // Hash algorithm to be used by the tree. 143 // Readonly. 144 sigpb.DigitallySigned.HashAlgorithm hash_algorithm = 5; 145 146 // Signature algorithm to be used by the tree. 147 // Readonly. 148 sigpb.DigitallySigned.SignatureAlgorithm signature_algorithm = 6; 149 150 reserved 18; // Signature cipher suite (removed) 151 reserved 7; // DuplicatePolicy (removed) 152 153 // Display name of the tree. 154 // Optional. 155 string display_name = 8; 156 157 // Description of the tree, 158 // Optional. 159 string description = 9; 160 161 reserved 10; // create_time_millis_since_epoch (removed) 162 reserved 11; // update_time_millis_since_epoch (removed) 163 164 // Identifies the private key used for signing tree heads and entry 165 // timestamps. 166 // This can be any type of message to accommodate different key management 167 // systems, e.g. PEM files, HSMs, etc. 168 // Private keys are write-only: they're never returned by RPCs. 169 // The private_key message can be changed after a tree is created, but the 170 // underlying key must remain the same - this is to enable migrating a key 171 // from one provider to another. 172 google.protobuf.Any private_key = 12; 173 174 // Storage-specific settings. 175 // Varies according to the storage implementation backing Trillian. 176 google.protobuf.Any storage_settings = 13; 177 178 // The public key used for verifying tree heads and entry timestamps. 179 // Readonly. 180 keyspb.PublicKey public_key = 14; 181 182 // Interval after which a new signed root is produced even if there have been 183 // no submission. If zero, this behavior is disabled. 184 google.protobuf.Duration max_root_duration = 15; 185 186 // Time of tree creation. 187 // Readonly. 188 google.protobuf.Timestamp create_time = 16; 189 190 // Time of last tree update. 191 // Readonly (automatically assigned on updates). 192 google.protobuf.Timestamp update_time = 17; 193 194 // If true, the tree has been deleted. 195 // Deleted trees may be undeleted during a certain time window, after which 196 // they're permanently deleted (and unrecoverable). 197 // Readonly. 198 bool deleted = 19; 199 200 // Time of tree deletion, if any. 201 // Readonly. 202 google.protobuf.Timestamp delete_time = 20; 203 } 204 205 message SignedEntryTimestamp { 206 int64 timestamp_nanos = 1; 207 int64 log_id = 2; 208 sigpb.DigitallySigned signature = 3; 209 } 210 211 // SignedLogRoot represents a commitment by a Log to a particular tree. 212 message SignedLogRoot { 213 // Deprecated: TimestampNanos moved to LogRoot. 214 int64 timestamp_nanos = 1; 215 // Deprecated: RootHash moved to LogRoot. 216 bytes root_hash = 2; 217 // Deprecated: TreeSize moved to LogRoot. 218 int64 tree_size = 3; 219 // Deprecated: TreeRevision moved to LogRoot. 220 int64 tree_revision = 6; 221 222 // Deleted: Signature replaced by LogRootSignature. 223 reserved 4; 224 225 // Deleted: LogID is associated with the public key that validates signature. 226 reserved 5; 227 228 // key_hint is a hint to identify the public key for signature verification. 229 // key_hint is not authenticated and may be incorrect or missing, in which 230 // case all known public keys may be used to verify the signature. 231 // When directly communicating with a Trillian gRPC server, the key_hint will 232 // typically contain the LogID encoded as a big-endian 64-bit integer; 233 // however, in other contexts the key_hint is likely to have different 234 // contents (e.g. it could be a GUID, a URL + TreeID, or it could be 235 // derived from the public key itself). 236 bytes key_hint = 7; 237 238 // log_root holds the TLS-serialization of the following structure (described 239 // in RFC5246 notation): Clients should validate log_root_signature with 240 // VerifySignedLogRoot before deserializing log_root. 241 // enum { v1(1), (65535)} Version; 242 // struct { 243 // uint64 tree_size; 244 // opaque root_hash<0..128>; 245 // uint64 timestamp_nanos; 246 // uint64 revision; 247 // opaque metadata<0..65535>; 248 // } LogRootV1; 249 // struct { 250 // Version version; 251 // select(version) { 252 // case v1: LogRootV1; 253 // } 254 // } LogRoot; 255 bytes log_root = 8; 256 257 // log_root_signature is the raw signature over log_root. 258 bytes log_root_signature = 9; 259 } 260 261 // SignedMapRoot represents a commitment by a Map to a particular tree. 262 message SignedMapRoot { 263 reserved 1; // Deprecated: Was timestamp_nanos. Use map_root. 264 reserved 2; // Deprecated: Was root_hash. Use map_root. 265 reserved 3; // Deprecated: Was MapperMetadata. Use map_root. 266 reserved 5; // Deprecated: Was map_id. Use signature. 267 reserved 6; // Deprecated: Was map_revision. Use map_root. 268 reserved 7; // Deprecated: Was metadata Any. Use map_root. 269 reserved 8; // Deprecated: Was metadata bytes. Use map_root. 270 271 // map_root holds the TLS-serialization of the following structure (described 272 // in RFC5246 notation): Clients should validate signature with 273 // VerifySignedMapRoot before deserializing map_root. 274 // enum { v1(1), (65535)} Version; 275 // struct { 276 // opaque root_hash<0..128>; 277 // uint64 timestamp_nanos; 278 // uint64 revision; 279 // opaque metadata<0..65535>; 280 // } MapRootV1; 281 // struct { 282 // Version version; 283 // select(version) { 284 // case v1: MapRootV1; 285 // } 286 // } MapRoot; 287 bytes map_root = 9; 288 // Signature is the raw signature over MapRoot. 289 bytes signature = 4; 290 }