proto/trillian.proto

// 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;
}