// Copyright 2018 The Grafeas Authors. 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"; package grafeas.v1beta1.attestation; option go_package = "google.golang.org/genproto/googleapis/devtools/containeranalysis/v1beta1/attestation;attestation"; option java_multiple_files = true; option java_package = "io.grafeas.v1beta1.attestation"; option objc_class_prefix = "GRA"; // An attestation wrapper with a PGP-compatible signature. This message only // supports `ATTACHED` signatures, where the payload that is signed is included // alongside the signature itself in the same file. message PgpSignedAttestation { // The raw content of the signature, as output by GNU Privacy Guard (GPG) or // equivalent. Since this message only supports attached signatures, the // payload that was signed must be attached. While the signature format // supported is dependent on the verification implementation, currently only // ASCII-armored (`--armor` to gpg), non-clearsigned (`--sign` rather than // `--clearsign` to gpg) are supported. Concretely, `gpg --sign --armor // --output=signature.gpg payload.json` will create the signature content // expected in this field in `signature.gpg` for the `payload.json` // attestation payload. string signature = 1; // Type (for example schema) of the attestation payload that was signed. enum ContentType { // `ContentType` is not set. CONTENT_TYPE_UNSPECIFIED = 0; // Atomic format attestation signature. See // https://github.com/containers/image/blob/8a5d2f82a6e3263290c8e0276c3e0f64e77723e7/docs/atomic-signature.md // The payload extracted from `signature` is a JSON blob conforming to the // linked schema. SIMPLE_SIGNING_JSON = 1; } // Type (for example schema) of the attestation payload that was signed. // The verifier must ensure that the provided type is one that the verifier // supports, and that the attestation payload is a valid instantiation of that // type (for example by validating a JSON schema). ContentType content_type = 3; // This field is used by verifiers to select the public key used to validate // the signature. Note that the policy of the verifier ultimately determines // which public keys verify a signature based on the context of the // verification. There is no guarantee validation will succeed if the // verifier has no key matching this ID, even if it has a key under a // different ID that would verify the signature. Note that this ID should also // be present in the signature content above, but that is not expected to be // used by the verifier. oneof key_id { // The cryptographic fingerprint of the key used to generate the signature, // as output by, e.g. `gpg --list-keys`. This should be the version 4, full // 160-bit fingerprint, expressed as a 40 character hexidecimal string. See // https://tools.ietf.org/html/rfc4880#section-12.2 for details. // Implementations may choose to acknowledge "LONG", "SHORT", or other // abbreviated key IDs, but only the full fingerprint is guaranteed to work. // In gpg, the full fingerprint can be retrieved from the `fpr` field // returned when calling --list-keys with --with-colons. For example: // ``` // gpg --with-colons --with-fingerprint --force-v4-certs \ // --list-keys attester@example.com // tru::1:1513631572:0:3:1:5 // pub:...... // fpr:::::::::24FF6481B76AC91E66A00AC657A93A81EF3AE6FB: // ``` // Above, the fingerprint is `24FF6481B76AC91E66A00AC657A93A81EF3AE6FB`. string pgp_key_id = 2; } } // Note kind that represents a logical attestation "role" or "authority". For // example, an organization might have one `Authority` for "QA" and one for // "build". This Note is intended to act strictly as a grouping mechanism for // the attached Occurrences (Attestations). This grouping mechanism also // provides a security boundary, since IAM ACLs gate the ability for a principle // to attach an Occurrence to a given Note. It also provides a single point of // lookup to find all attached Attestation Occurrences, even if they don't all // live in the same project. message Authority { // This submessage provides human-readable hints about the purpose of the // Authority. Because the name of a Note acts as its resource reference, it is // important to disambiguate the canonical name of the Note (which might be a // UUID for security purposes) from "readable" names more suitable for debug // output. Note that these hints should NOT be used to look up authorities in // security sensitive contexts, such as when looking up Attestations to // verify. message Hint { // The human readable name of this Attestation Authority, for example "qa". string human_readable_name = 1; } // Hint hints at the purpose of the attestation authority. Hint hint = 1; } // Details of an attestation occurrence. message Details { // Attestation for the resource. Attestation attestation = 1; } // Occurrence that represents a single "attestation". The authenticity of an // Attestation can be verified using the attached signature. If the verifier // trusts the public key of the signer, then verifying the signature is // sufficient to establish trust. In this circumstance, the Authority to which // this Attestation is attached is primarily useful for look-up (how to find // this Attestation if you already know the Authority and artifact to be // verified) and intent (which authority was this attestation intended to sign // for). message Attestation { // The signature, generally over the `resource_url`, that verifies this // attestation. The semantics of the signature veracity are ultimately // determined by the verification engine. oneof signature { // A PGP signed attestation. PgpSignedAttestation pgp_signed_attestation = 1; } }