1// Copyright 2019 The Grafeas Authors. All rights reserved. 2// 3// Licensed under the Apache License, Version 2.0 (the "License"); 4// you may not use this file except in compliance with the License. 5// You may obtain a copy of the License at 6// 7// http://www.apache.org/licenses/LICENSE-2.0 8// 9// Unless required by applicable law or agreed to in writing, software 10// distributed under the License is distributed on an "AS IS" BASIS, 11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 12// See the License for the specific language governing permissions and 13// limitations under the License. 14 15syntax = "proto3"; 16 17package grafeas.v1; 18 19import "grafeas/v1/common.proto"; 20 21option go_package = "google.golang.org/genproto/googleapis/grafeas/v1;grafeas"; 22option java_multiple_files = true; 23option java_package = "io.grafeas.v1"; 24option objc_class_prefix = "GRA"; 25 26// An attestation wrapper with a PGP-compatible signature. This message only 27// supports `ATTACHED` signatures, where the payload that is signed is included 28// alongside the signature itself in the same file. 29 30// Note kind that represents a logical attestation "role" or "authority". For 31// example, an organization might have one `Authority` for "QA" and one for 32// "build". This note is intended to act strictly as a grouping mechanism for 33// the attached occurrences (Attestations). This grouping mechanism also 34// provides a security boundary, since IAM ACLs gate the ability for a principle 35// to attach an occurrence to a given note. It also provides a single point of 36// lookup to find all attached attestation occurrences, even if they don't all 37// live in the same project. 38message AttestationNote { 39 // This submessage provides human-readable hints about the purpose of the 40 // authority. Because the name of a note acts as its resource reference, it is 41 // important to disambiguate the canonical name of the Note (which might be a 42 // UUID for security purposes) from "readable" names more suitable for debug 43 // output. Note that these hints should not be used to look up authorities in 44 // security sensitive contexts, such as when looking up attestations to 45 // verify. 46 message Hint { 47 // Required. The human readable name of this attestation authority, for 48 // example "qa". 49 string human_readable_name = 1; 50 } 51 52 // Hint hints at the purpose of the attestation authority. 53 Hint hint = 1; 54} 55 56message Jwt { 57 // The compact encoding of a JWS, which is always three base64 encoded strings 58 // joined by periods. For details, see: 59 // https://tools.ietf.org/html/rfc7515.html#section-3.1 60 string compact_jwt = 1; 61} 62 63// Occurrence that represents a single "attestation". The authenticity of an 64// attestation can be verified using the attached signature. If the verifier 65// trusts the public key of the signer, then verifying the signature is 66// sufficient to establish trust. In this circumstance, the authority to which 67// this attestation is attached is primarily useful for lookup (how to find 68// this attestation if you already know the authority and artifact to be 69// verified) and intent (for which authority this attestation was intended to 70// sign. 71message AttestationOccurrence { 72 // Required. The serialized payload that is verified by one or more 73 // `signatures`. 74 bytes serialized_payload = 1; 75 // One or more signatures over `serialized_payload`. Verifier implementations 76 // should consider this attestation message verified if at least one 77 // `signature` verifies `serialized_payload`. See `Signature` in common.proto 78 // for more details on signature structure and verification. 79 repeated Signature signatures = 2; 80 // One or more JWTs encoding a self-contained attestation. 81 // Each JWT encodes the payload that it verifies within the JWT itself. 82 // Verifier implementation SHOULD ignore the `serialized_payload` field 83 // when verifying these JWTs. 84 // If only JWTs are present on this AttestationOccurrence, then the 85 // `serialized_payload` SHOULD be left empty. 86 // Each JWT SHOULD encode a claim specific to the `resource_uri` of this 87 // Occurrence, but this is not validated by Grafeas metadata API 88 // implementations. The JWT itself is opaque to Grafeas. 89 repeated Jwt jwts = 3; 90} 91