WIP: V1 of the trust root and the verification input. #5
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,86 @@ | ||
| // Copyright 2022 The Sigstore Authors. | ||
| // | ||
| // 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"; | ||
| package dev.sigstore.trustroot.v1; | ||
|
|
||
| import "sigstore_common.proto"; | ||
|
|
||
| option go_package = "github.com/sigstore/protobuf-specs/gen/pb-go/trustroot/v1"; | ||
| option java_package = "dev.sigstore.proto.trustroot.v1"; | ||
| option java_multiple_files = true; | ||
| option java_outer_classname = "TrustRootProto"; | ||
|
|
||
| // TransparencyLogInstance describes the immutable parameters from a | ||
| // transparency log. | ||
| // See https://www.rfc-editor.org/rfc/rfc9162.html#name-log-parameters | ||
| // for more details. | ||
| // The incluced parameters are the minimal set required to identify a log, | ||
| // and verify an inclusion promise. | ||
| message TransparencyLogInstance { | ||
kommendorkapten marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| // The base URL at which can be used to URLs for the client. | ||
| string base_url = 1; | ||
| // The hash algorithm used for the Merkle Tree. | ||
| dev.sigstore.common.v1.HashAlgorithm hash_algorithm = 2; | ||
| // The public key used to verify signatures generated by the log. | ||
| // This attribute contains the signature algorithm used by the log. | ||
| dev.sigstore.common.v1.PublicKey public_key = 3; | ||
|
There was a problem hiding this comment. Do we expect more than public_key being embedded in the TUF target? Today we only have the public_key in the TUF root, so just wondering if we're going to bake some of this information into our TUF targets? For example, we could serialize this into the TUF target for a given Rekor instance, so just wondering out loud. Jotted it down here, but applicable to CA below as well.
Member
Author
There was a problem hiding this comment. I can't say for sure, but I think so. As an example the |
||
| // The unique identifier for this transparency log. | ||
| dev.sigstore.common.v1.LogId log_id = 4; | ||
| } | ||
|
|
||
| // CertificateAuthority enlists the information required to identify which | ||
| // CA to use and perform signature verification. | ||
| message CertificateAuthority { | ||
| // The root certificate MUST be self-signed, and so the subject and | ||
| // issuer are the same. | ||
| dev.sigstore.common.v1.DistinguishedName subject = 1; | ||
| // The URI at which the CA can be accessed. | ||
| string uri = 2; | ||
| // The certificate chain for this CA. | ||
| dev.sigstore.common.v1.X509CertificateChain cert_chain = 3; | ||
| // The time the *entire* chain was valid. This is at max the | ||
| // longest interval when *all* certificates in the chain were valid, | ||
| // but it MAY be shorter. | ||
| dev.sigstore.common.v1.TimeRange valid_for = 4; | ||
| } | ||
|
|
||
| // TrustedRoot describes the client's complete set of trusted entities. | ||
| // How the TrustedRoot is populated is not specified, but can be a | ||
| // combination of many sources such as TUF repositories, files on disk etc. | ||
| // | ||
| // The TrustedRoot is not meant to be used for any artifact verification, only | ||
| // to capture the complete/global set of trusted verification materials. | ||
| // When verifying an artifact, based on the artifact and policies, a selection | ||
|
There was a problem hiding this comment. Just thinking out loud if CA & TransparencyInstance has enough information in there to write policies against. Both of them have a URI / base_url and CA has DistinguishedName, but just curious if that's enough and that's what one would use to filter out the instances that should be used for verification. There was a problem hiding this comment. I guess thinking that the one (only?) reason for having the TrustedRoot as a collection of all the everythings is that you can then pass it through some sort of policy machine which will distill it down to the verification materials before calling the actual verification with a subset of keys/authorities.
Member
Author
There was a problem hiding this comment.
Yes, that's the exact reasoning. Based on the scenarios I'm aware of, we should have enough data to confidently distill what exact "instance" of a CA or log to use:
What could possibly cause some confusion is that if a client is relying on a TUF multi root setup, where multiple TUF roots exposes targets for the log or CA with identical data. But this is an explicit confusion as I see it, and so the precondition that the client trusts the TUF root may not hold any more, then all bets are off, as the TUF repository may serve arbitrary data. But I don't think of this as a real problem. What the policy will protect against is e.g. where an artifact was signed with a certificate from the wrong CA given a policy, and for that I'd say we are good. There was a problem hiding this comment. Fantastic. Again just thinking of how the layer above this (policy-controller) will sort out the details. But, I guess that's my problem :)
Member
Author
There was a problem hiding this comment. I'm working a bit on that too, I hope that I can share some details on this later today! |
||
| // of keys/authorities are expected to be extracted and provided to the | ||
| // verification function. This way the set of keys/authorities kan be kept to | ||
| // a minimal set by the policy to gain better control over what signatures | ||
| // that are allowed. | ||
| message TrustedRoot { | ||
| // A set of trusted Rekor servers. | ||
| repeated TransparencyLogInstance tlogs = 1; | ||
| // A set of trusted certificate authorites (e.g Fulcio), and any | ||
| // intermediate certificates they provide. | ||
| // If a CA is issuing multiple intermediate certificate, each | ||
| // combination shall be represented as separate chain. I.e, a single | ||
| // root cert may appear in multiple chains but with different | ||
| // intermediate and/or leaf certificates. | ||
| // The certificates are intended to be used for verifying artifact | ||
| // signatures. | ||
| repeated CertificateAuthority certificate_authorities = 2; | ||
| // A set of trusted certificate transparency logs. | ||
| repeated TransparencyLogInstance ctlogs = 3; | ||
| // A set of trusted timestamping authorities. | ||
| repeated CertificateAuthority timestamp_authorities = 4; | ||
| } | ||
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,136 @@ | ||
| // Copyright 2022 The Sigstore Authors. | ||
| // | ||
| // 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"; | ||
| package dev.sigstore.verification.v1; | ||
|
|
||
| import "sigstore_common.proto"; | ||
| import "sigstore_trustroot.proto"; | ||
| import "sigstore_bundle.proto"; | ||
|
|
||
| option go_package = "github.com/sigstore/protobuf-specs/gen/pb-go/verification/v1"; | ||
| option java_package = "dev.sigstore.proto.verification.v1"; | ||
| option java_multiple_files = true; | ||
| option java_outer_classname = "VerificationProto"; | ||
|
|
||
| // The identity of a X.509 Certificate signer. | ||
| message CertificateIdentity { | ||
| // The X.509v3 issuer extension (OID 1.3.6.1.4.1.57264.1.1) | ||
| string issuer = 1; | ||
| dev.sigstore.common.v1.SubjectAlternativeName san = 2; | ||
| // An unordered list of OIDs that must be verified. | ||
| // All OID/values provided in this list MUST exactly match against | ||
| // the values in the certificate for verification to be successful. | ||
| repeated dev.sigstore.common.v1.ObjectIdentifierValuePair oids = 3; | ||
| } | ||
|
|
||
| message CertificateIdentities { | ||
| repeated CertificateIdentity identities = 1; | ||
| } | ||
|
|
||
| message PublicKeyIdentities { | ||
| repeated dev.sigstore.common.v1.PublicKey public_keys = 1; | ||
| } | ||
|
|
||
| // A light-weight set of options/policies for identifying trusted signers, | ||
| // used during verification of a single artifact. | ||
| message ArtifactVerificationOptions { | ||
| message TlogOptions { | ||
| // Number of transparency logs the entry must appear on. | ||
| int32 threshold = 1; | ||
| // Perform an online inclusion proof. | ||
| bool perform_online_verification = 2; | ||
kommendorkapten marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| // Disable verification for transparency logs. | ||
| bool disable = 3; | ||
| } | ||
| message CtlogOptions { | ||
| // The number of ct transparency logs the certificate must | ||
| // appear on. | ||
| int32 threshold = 1; | ||
| // Expect detached SCTs. | ||
| // This is not supported right now as we can't capture an | ||
| // detached SCT in the bundle. | ||
| bool detached_sct = 2; | ||
| // Disable ct transparency log verification | ||
| bool disable = 3; | ||
| } | ||
| message TimestampAuthorityOptions { | ||
| // The number of signed timestamps that are expected. | ||
| int32 threshold = 1; | ||
| // Disable signed timestamp verification. | ||
| bool disable = 2; | ||
| } | ||
|
|
||
| // At least one identity MUST be provided. Providing zero identities | ||
kommendorkapten marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| // is an error. If at least one provided identity is found as a | ||
| // signer, the verification is considered successful. | ||
| oneof signers { | ||
| CertificateIdentities certificate_identities = 1; | ||
| // To simplify verification implementation, the logic for | ||
| // bundle verification should be implemented as a | ||
| // higher-order function, where one of argument should be an | ||
| // interface over the set of trusted public keys, like this: | ||
| // `Verify(bytes artifact, bytes signature, string key_id)`. | ||
| // This way the caller is in full control of mapping the | ||
| // identified (or hinted) key in the bundle to one of the | ||
| // trusted keys, as this process is inherently application | ||
| // specific. | ||
| PublicKeyIdentities public_keys = 2; | ||
| } | ||
| // Optional options for artifact transparency log verification. | ||
| // If none is provided, the default verification options are: | ||
| // Threshold: 1 | ||
| // Online verification: false | ||
| // Disable: false | ||
| optional TlogOptions tlog_options = 3; | ||
| // Optional options for certificate transparency log verification. | ||
| // If none is provided, the default verification options are: | ||
| // Threshold: 1 | ||
| // Detached SCT: false | ||
| // Disable: false | ||
| optional CtlogOptions ctlog_options = 4; | ||
| // Optional options for certificate signed timestamp verification. | ||
| // If none is provided, the default verification options are: | ||
| // Threshold: 1 | ||
| // Disable: false | ||
| optional TimestampAuthorityOptions tsa_options = 5; | ||
| } | ||
|
|
||
| message Artifact { | ||
| oneof data { | ||
| // Location of the artifact | ||
| string artifact_uri = 1; | ||
| // The raw bytes of the artifact | ||
| bytes artifact = 2; | ||
| } | ||
| } | ||
|
|
||
| // Input captures all that is needed to call the bundle verification method, | ||
| // to verify a single artifact referenced by the bundle. | ||
| message Input { | ||
| // The verification materials provided during a bundle verification. | ||
| // The running process is usually preloaded with a "global" | ||
| // dev.sisgtore.trustroot.TrustedRoot.v1 instance. Prior to | ||
| // verifying an artifact (i.e a bundle), and/or based on current | ||
| // policy, some selection is expected to happen, to filter out the | ||
| // exact certificate authority to use, which transparency logs are | ||
| // relevant etc. The result should b ecaptured in the | ||
| // `artifact_trust_root`. | ||
| dev.sigstore.trustroot.v1.TrustedRoot artifact_trust_root = 1; | ||
| ArtifactVerificationOptions artifact_verification_options = 2; | ||
| dev.sigstore.bundle.v1.Bundle bundle = 3; | ||
| // If the bundle contains a message signature, the artifact must be | ||
| // provided. | ||
| optional Artifact artifact = 4; | ||
| } | ||
Uh oh!
There was an error while loading. Please reload this page.