diff --git a/README.md b/README.md index 1e50254b0a..9ebb3a2dee 100644 --- a/README.md +++ b/README.md @@ -59,10 +59,14 @@ Other examples of Trillian personalities are available in the ## Using the Code -**WARNING**: The Trillian codebase is still under development, but the Log mode -is now being used in production by several organizations. We will try to avoid -any further incompatible code and schema changes but cannot guarantee that they -will never be necessary. +The Trillian codebase is stable and is used in production by multiple +organizations, including many large-scale +[Certificate Transparency](https://certificate.transparency.dev) log +operators. + +Given this, we do not plan to add any new features to this version of Trillian, +and will try to avoid any further incompatible code and schema changes but +cannot guarantee that they will never be necessary. The current state of feature implementation is recorded in the [Feature implementation matrix](docs/Feature_Implementation_Matrix.md). diff --git a/cmd/trillian_log_signer/main.go b/cmd/trillian_log_signer/main.go index 365505d315..6f479c159b 100644 --- a/cmd/trillian_log_signer/main.go +++ b/cmd/trillian_log_signer/main.go @@ -12,7 +12,14 @@ // See the License for the specific language governing permissions and // limitations under the License. -// The trillian_log_signer binary runs the log signing code. +// The trillian_log_signer binary runs the process which sequences new entries, +// integrates them into the corresponding log, and, finally, creates a new +// LogRoot with updated root hash. +// +// The naming of this binary originally came from the fact that it would +// also sign each of the new LogRoots, but that functionality was removed. +// Renaming the binary would likely cause some surprise for existing log +// operators and so the decision was taken to leave it as-is for now. package main import ( diff --git a/docs/Personalities.md b/docs/Personalities.md index 03e55ea202..66f906e594 100644 --- a/docs/Personalities.md +++ b/docs/Personalities.md @@ -76,26 +76,6 @@ as the tree leaf in the corresponding `QueueLeaves` request (it will have the same `LeafIdentityHash` but may differ in fields that are not covered by this hash, e.g. it may have an earlier timestamp). - -### Auditability - -If the personality and the Trillian core services are maintained by different -operators, then there may be an implicit trust boundary between the two at the -Trillian gRPC interface. - -If this is the case, then the personality may need to be responsible for -storing data that allows auditing of that trust boundary. - -For example, if an external monitor detects that a signed tree head is not -consistent with an earlier signed tree head, is there enough information -available to determine whether this is a problem with the personality or with -the Trillian service? - -If the personality maintains a store of the signed log roots provided by -Trillian, it can then use this to audit failure cases and assign blame -appropriately – effectively acting as a monitor for Trillian. - - ## Practical Responsibilities ### External API diff --git a/docs/TransparentLogging.md b/docs/TransparentLogging.md index fc32376e92..fe1df6e7fb 100644 --- a/docs/TransparentLogging.md +++ b/docs/TransparentLogging.md @@ -102,7 +102,7 @@ to be defined for each Log application. The first hash for a leaf in Log is the **Merkle Hash**; this is the hash value that percolates up the Merkle tree and is therefore incorporated into the -(signed) root hash for the Log; the cryptographic guarantees of the Log's Merkle +root hash for the Log; the cryptographic guarantees of the Log's Merkle tree only apply to data included in the Merkle hash. The default Merkle hash for a Trillian Log leaf is `SHA-256(0x00 | diff --git a/docs/api.md b/docs/api.md index 58de19951b..663d00147a 100644 --- a/docs/api.md +++ b/docs/api.md @@ -482,7 +482,7 @@ If any of the leaves that match the given Merkle has have a leaf index that is b | GetConsistencyProof | [GetConsistencyProofRequest](#trillian-GetConsistencyProofRequest) | [GetConsistencyProofResponse](#trillian-GetConsistencyProofResponse) | GetConsistencyProof returns a consistency proof between different sizes of a particular tree. If the requested tree size is larger than the server is aware of, the response will include the latest known log root and an empty proof. | -| GetLatestSignedLogRoot | [GetLatestSignedLogRootRequest](#trillian-GetLatestSignedLogRootRequest) | [GetLatestSignedLogRootResponse](#trillian-GetLatestSignedLogRootResponse) | GetLatestSignedLogRoot returns the latest signed log root for a given tree, and optionally also includes a consistency proof from an earlier tree size to the new size of the tree. +| GetLatestSignedLogRoot | [GetLatestSignedLogRootRequest](#trillian-GetLatestSignedLogRootRequest) | [GetLatestSignedLogRootResponse](#trillian-GetLatestSignedLogRootResponse) | GetLatestSignedLogRoot returns the latest log root for a given tree, and optionally also includes a consistency proof from an earlier tree size to the new size of the tree. If the earlier tree size is larger than the server is aware of, an InvalidArgument error is returned. | | GetEntryAndProof | [GetEntryAndProofRequest](#trillian-GetEntryAndProofRequest) | [GetEntryAndProofResponse](#trillian-GetEntryAndProofResponse) | GetEntryAndProof returns a log leaf and the corresponding inclusion proof to a specified tree size, for a given leaf index in a particular tree. @@ -666,6 +666,12 @@ by the API. ### SignedLogRoot SignedLogRoot represents a commitment by a Log to a particular tree. +Note that the signature itself is no-longer provided by Trillian since +https://github.com/google/trillian/pull/2452 . +This functionality was intended to support a niche-use case but added +significant complexity and was prone to causing confusion and +misunderstanding for personality authors. + | Field | Type | Label | Description | | ----- | ---- | ----- | ----------- | diff --git a/trillian.pb.go b/trillian.pb.go index 1af9c1c485..6855aca394 100644 --- a/trillian.pb.go +++ b/trillian.pb.go @@ -446,6 +446,12 @@ func (x *Tree) GetDeleteTime() *timestamppb.Timestamp { } // SignedLogRoot represents a commitment by a Log to a particular tree. +// +// Note that the signature itself is no-longer provided by Trillian since +// https://github.com/google/trillian/pull/2452 . +// This functionality was intended to support a niche-use case but added +// significant complexity and was prone to causing confusion and +// misunderstanding for personality authors. type SignedLogRoot struct { state protoimpl.MessageState sizeCache protoimpl.SizeCache diff --git a/trillian.proto b/trillian.proto index 6b03b350c1..78869ba962 100644 --- a/trillian.proto +++ b/trillian.proto @@ -174,6 +174,12 @@ message Tree { } // SignedLogRoot represents a commitment by a Log to a particular tree. +// +// Note that the signature itself is no-longer provided by Trillian since +// https://github.com/google/trillian/pull/2452 . +// This functionality was intended to support a niche-use case but added +// significant complexity and was prone to causing confusion and +// misunderstanding for personality authors. message SignedLogRoot { // log_root holds the TLS-serialization of the following structure (described // in RFC5246 notation): diff --git a/trillian_log_api.proto b/trillian_log_api.proto index e8056d9a64..74cbb96c3e 100644 --- a/trillian_log_api.proto +++ b/trillian_log_api.proto @@ -82,7 +82,7 @@ service TrillianLog { rpc GetConsistencyProof(GetConsistencyProofRequest) returns (GetConsistencyProofResponse) {} - // GetLatestSignedLogRoot returns the latest signed log root for a given tree, + // GetLatestSignedLogRoot returns the latest log root for a given tree, // and optionally also includes a consistency proof from an earlier tree size // to the new size of the tree. // diff --git a/trillian_log_api_grpc.pb.go b/trillian_log_api_grpc.pb.go index f2fe92d11c..32e2ff8b39 100644 --- a/trillian_log_api_grpc.pb.go +++ b/trillian_log_api_grpc.pb.go @@ -43,7 +43,7 @@ type TrillianLogClient interface { // If the requested tree size is larger than the server is aware of, // the response will include the latest known log root and an empty proof. GetConsistencyProof(ctx context.Context, in *GetConsistencyProofRequest, opts ...grpc.CallOption) (*GetConsistencyProofResponse, error) - // GetLatestSignedLogRoot returns the latest signed log root for a given tree, + // GetLatestSignedLogRoot returns the latest log root for a given tree, // and optionally also includes a consistency proof from an earlier tree size // to the new size of the tree. // @@ -182,7 +182,7 @@ type TrillianLogServer interface { // If the requested tree size is larger than the server is aware of, // the response will include the latest known log root and an empty proof. GetConsistencyProof(context.Context, *GetConsistencyProofRequest) (*GetConsistencyProofResponse, error) - // GetLatestSignedLogRoot returns the latest signed log root for a given tree, + // GetLatestSignedLogRoot returns the latest log root for a given tree, // and optionally also includes a consistency proof from an earlier tree size // to the new size of the tree. //