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";

package trillian;

import "github.com/google/trillian/crypto/keyspb/keyspb.proto";
import "github.com/google/trillian/crypto/sigpb/sigpb.proto";
import "google/protobuf/any.proto";
import "google/protobuf/duration.proto";
import "google/protobuf/timestamp.proto";

// 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.
  RFC_6962 = 1;
}

// 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.
  FROZEN = 2;

  // Tree was been deleted, therefore is invisible and acts similarly to a
  // non-existing tree for all requests.
  // A soft deleted tree may be undeleted while the soft-deletion period has not
  // passed.
  SOFT_DELETED = 3;

  // A hard deleted tree was been definitely deleted and cannot be recovered.
  // Acts an a non-existing tree for all read and write requests, but blocks the
  // tree ID from ever being reused.
  HARD_DELETED = 4;
}

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

// 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.
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 and FROZEN.
  // Deleted trees are set as SOFT_DELETED for a certain time period, after
  // which they'll automatically transition to HARD_DELETED.
  TreeState tree_state = 2;

  // Type of the tree.
  // Readonly.
  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 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.
  // TODO(RJPercival): Implement sufficient validation to allow this field to be
  // mutable. It should be mutable in the sense that the key can be migrated to
  // a different key management system, but the key itself should never change.
  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;
}

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 {
  // epoch nanoseconds, good until 2500ish
  int64 timestamp_nanos = 1;
  bytes root_hash = 2;
	// TreeSize is the number of entries in the tree.
  int64 tree_size = 3;
	// TODO(al): define serialized format for the signature scheme.
  sigpb.DigitallySigned signature = 4;

  int64 log_id = 5;
  int64 tree_revision = 6;
}

message MapperMetadata {
  bytes source_log_id = 1;
  int64 highest_fully_completed_seq = 2;
  int64 highest_partially_completed_seq = 3;
 }

// SignedMapRoot represents a commitment by a Map to a particular tree.
message SignedMapRoot {
  int64 timestamp_nanos = 1;
  bytes root_hash = 2;
  MapperMetadata metadata = 3;
	// TODO(al): define serialized format for the signature scheme.
  sigpb.DigitallySigned signature = 4;

  int64 map_id = 5;
  int64 map_revision = 6;
}