1// Copyright 2018 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.v1beta1.build; 18 19import "google/devtools/containeranalysis/v1beta1/provenance/provenance.proto"; 20 21option go_package = "cloud.google.com/go/containeranalysis/apiv1beta1/containeranalysispb;containeranalysispb"; 22option java_multiple_files = true; 23option java_package = "io.grafeas.v1beta1.build"; 24option objc_class_prefix = "GRA"; 25 26// Note holding the version of the provider's builder and the signature of the 27// provenance message in the build details occurrence. 28message Build { 29 // Required. Immutable. Version of the builder which produced this build. 30 string builder_version = 1; 31 32 // Signature of the build in occurrences pointing to this build note 33 // containing build details. 34 BuildSignature signature = 2; 35} 36 37// Message encapsulating the signature of the verified build. 38message BuildSignature { 39 // Public key of the builder which can be used to verify that the related 40 // findings are valid and unchanged. If `key_type` is empty, this defaults 41 // to PEM encoded public keys. 42 // 43 // This field may be empty if `key_id` references an external key. 44 // 45 // For Cloud Build based signatures, this is a PEM encoded public 46 // key. To verify the Cloud Build signature, place the contents of 47 // this field into a file (public.pem). The signature field is base64-decoded 48 // into its binary representation in signature.bin, and the provenance bytes 49 // from `BuildDetails` are base64-decoded into a binary representation in 50 // signed.bin. OpenSSL can then verify the signature: 51 // `openssl sha256 -verify public.pem -signature signature.bin signed.bin` 52 string public_key = 1; 53 54 // Required. Signature of the related `BuildProvenance`. In JSON, this is 55 // base-64 encoded. 56 bytes signature = 2; 57 58 // An ID for the key used to sign. This could be either an ID for the key 59 // stored in `public_key` (such as the ID or fingerprint for a PGP key, or the 60 // CN for a cert), or a reference to an external key (such as a reference to a 61 // key in Cloud Key Management Service). 62 string key_id = 3; 63 64 // Public key formats. 65 enum KeyType { 66 // `KeyType` is not set. 67 KEY_TYPE_UNSPECIFIED = 0; 68 // `PGP ASCII Armored` public key. 69 PGP_ASCII_ARMORED = 1; 70 // `PKIX PEM` public key. 71 PKIX_PEM = 2; 72 } 73 74 // The type of the key, either stored in `public_key` or referenced in 75 // `key_id`. 76 KeyType key_type = 4; 77} 78 79// Details of a build occurrence. 80message Details { 81 // Required. The actual provenance for the build. 82 grafeas.v1beta1.provenance.BuildProvenance provenance = 1; 83 84 // Serialized JSON representation of the provenance, used in generating the 85 // build signature in the corresponding build note. After verifying the 86 // signature, `provenance_bytes` can be unmarshalled and compared to the 87 // provenance to confirm that it is unchanged. A base64-encoded string 88 // representation of the provenance bytes is used for the signature in order 89 // to interoperate with openssl which expects this format for signature 90 // verification. 91 // 92 // The serialized form is captured both to avoid ambiguity in how the 93 // provenance is marshalled to json as well to prevent incompatibilities with 94 // future changes. 95 string provenance_bytes = 2; 96} 97