forked from google/trillian
-
Notifications
You must be signed in to change notification settings - Fork 0
/
trillian.proto
316 lines (267 loc) · 10.8 KB
/
trillian.proto
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
// 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_hash |
// +---+---+---+---+---+---+---+---+---+---+---+---+---+---+-....--+
//
// +---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+---+
// | 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;
}