1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
|
// 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;
import "google/devtools/containeranalysis/v1beta1/common/common.proto";
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 {
// Required. 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:...<SNIP>...
// fpr:::::::::24FF6481B76AC91E66A00AC657A93A81EF3AE6FB:
// ```
// Above, the fingerprint is `24FF6481B76AC91E66A00AC657A93A81EF3AE6FB`.
string pgp_key_id = 2;
}
}
// An attestation wrapper that uses the Grafeas `Signature` message.
// This attestation must define the `serialized_payload` that the `signatures`
// verify and any metadata necessary to interpret that plaintext. The
// signatures should always be over the `serialized_payload` bytestring.
message GenericSignedAttestation {
// Type of the attestation plaintext 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 in `plaintext` 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 = 1;
// The serialized payload that is verified by one or more `signatures`.
// The encoding and semantic meaning of this payload must match what is set in
// `content_type`.
bytes serialized_payload = 2;
// One or more signatures over `serialized_payload`. Verifier implementations
// should consider this attestation message verified if at least one
// `signature` verifies `serialized_payload`. See `Signature` in common.proto
// for more details on signature structure and verification.
repeated Signature signatures = 3;
}
// 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 {
// Required. 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 {
// Required. 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 {
// Required. 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;
GenericSignedAttestation generic_signed_attestation = 2;
}
}
|
