1 // Copyright 2018 The Grafeas Authors. All rights reserved.
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
7 // http://www.apache.org/licenses/LICENSE-2.0
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.
17 package grafeas.v1beta1.attestation;
19 option go_package = "google.golang.org/genproto/googleapis/devtools/containeranalysis/v1beta1/attestation;attestation";
20 option java_multiple_files = true;
21 option java_package = "io.grafeas.v1beta1.attestation";
22 option objc_class_prefix = "GRA";
24 // An attestation wrapper with a PGP-compatible signature. This message only
25 // supports `ATTACHED` signatures, where the payload that is signed is included
26 // alongside the signature itself in the same file.
27 message PgpSignedAttestation {
28 // The raw content of the signature, as output by GNU Privacy Guard (GPG) or
29 // equivalent. Since this message only supports attached signatures, the
30 // payload that was signed must be attached. While the signature format
31 // supported is dependent on the verification implementation, currently only
32 // ASCII-armored (`--armor` to gpg), non-clearsigned (`--sign` rather than
33 // `--clearsign` to gpg) are supported. Concretely, `gpg --sign --armor
34 // --output=signature.gpg payload.json` will create the signature content
35 // expected in this field in `signature.gpg` for the `payload.json`
36 // attestation payload.
39 // Type (for example schema) of the attestation payload that was signed.
41 // `ContentType` is not set.
42 CONTENT_TYPE_UNSPECIFIED = 0;
43 // Atomic format attestation signature. See
44 // https://github.com/containers/image/blob/8a5d2f82a6e3263290c8e0276c3e0f64e77723e7/docs/atomic-signature.md
45 // The payload extracted from `signature` is a JSON blob conforming to the
47 SIMPLE_SIGNING_JSON = 1;
50 // Type (for example schema) of the attestation payload that was signed.
51 // The verifier must ensure that the provided type is one that the verifier
52 // supports, and that the attestation payload is a valid instantiation of that
53 // type (for example by validating a JSON schema).
54 ContentType content_type = 3;
56 // This field is used by verifiers to select the public key used to validate
57 // the signature. Note that the policy of the verifier ultimately determines
58 // which public keys verify a signature based on the context of the
59 // verification. There is no guarantee validation will succeed if the
60 // verifier has no key matching this ID, even if it has a key under a
61 // different ID that would verify the signature. Note that this ID should also
62 // be present in the signature content above, but that is not expected to be
63 // used by the verifier.
65 // The cryptographic fingerprint of the key used to generate the signature,
66 // as output by, e.g. `gpg --list-keys`. This should be the version 4, full
67 // 160-bit fingerprint, expressed as a 40 character hexidecimal string. See
68 // https://tools.ietf.org/html/rfc4880#section-12.2 for details.
69 // Implementations may choose to acknowledge "LONG", "SHORT", or other
70 // abbreviated key IDs, but only the full fingerprint is guaranteed to work.
71 // In gpg, the full fingerprint can be retrieved from the `fpr` field
72 // returned when calling --list-keys with --with-colons. For example:
74 // gpg --with-colons --with-fingerprint --force-v4-certs \
75 // --list-keys attester@example.com
76 // tru::1:1513631572:0:3:1:5
78 // fpr:::::::::24FF6481B76AC91E66A00AC657A93A81EF3AE6FB:
80 // Above, the fingerprint is `24FF6481B76AC91E66A00AC657A93A81EF3AE6FB`.
81 string pgp_key_id = 2;
85 // Note kind that represents a logical attestation "role" or "authority". For
86 // example, an organization might have one `Authority` for "QA" and one for
87 // "build". This Note is intended to act strictly as a grouping mechanism for
88 // the attached Occurrences (Attestations). This grouping mechanism also
89 // provides a security boundary, since IAM ACLs gate the ability for a principle
90 // to attach an Occurrence to a given Note. It also provides a single point of
91 // lookup to find all attached Attestation Occurrences, even if they don't all
92 // live in the same project.
94 // This submessage provides human-readable hints about the purpose of the
95 // Authority. Because the name of a Note acts as its resource reference, it is
96 // important to disambiguate the canonical name of the Note (which might be a
97 // UUID for security purposes) from "readable" names more suitable for debug
98 // output. Note that these hints should NOT be used to look up authorities in
99 // security sensitive contexts, such as when looking up Attestations to
102 // The human readable name of this Attestation Authority, for example "qa".
103 string human_readable_name = 1;
106 // Hint hints at the purpose of the attestation authority.
110 // Details of an attestation occurrence.
112 // Attestation for the resource.
113 Attestation attestation = 1;
116 // Occurrence that represents a single "attestation". The authenticity of an
117 // Attestation can be verified using the attached signature. If the verifier
118 // trusts the public key of the signer, then verifying the signature is
119 // sufficient to establish trust. In this circumstance, the Authority to which
120 // this Attestation is attached is primarily useful for look-up (how to find
121 // this Attestation if you already know the Authority and artifact to be
122 // verified) and intent (which authority was this attestation intended to sign
124 message Attestation {
125 // The signature, generally over the `resource_url`, that verifies this
126 // attestation. The semantics of the signature veracity are ultimately
127 // determined by the verification engine.
129 // A PGP signed attestation.
130 PgpSignedAttestation pgp_signed_attestation = 1;