containerz: add signed bundle transfer to Deploy RPC

containerz/containerz.proto

@@ -33,7 +33,7 @@ import "google/protobuf/timestamp.proto";
 import "google/rpc/status.proto";
 
 option go_package = "github.com/openconfig/gnoi/containerz";
-option (types.gnoi_version) = "0.2.0";
+option (types.gnoi_version) = "0.3.0";
 
 service Containerz {
   // Deploy sets a container image on the target. The container is sent as
@@ -43,10 +43,31 @@ service Containerz {
   // plugin, the target must save the file until StartPlugin is called. Whether
   // the registry is local or remote is target and deployment specific. A valid
   // container is one that has passed its checksum.
+  //
+  // When ImageTransfer.signed_bundle_size is non-zero, ImageTransfer must
+  // include signed_bundle whose length equals signed_bundle_size. After
+  // ImageTransferEnd the target verifies the signed bundle against the
+  // received image and then loads the image. The bundle format and signing
+  // mechanism are implementation-specific and opaque to this RPC. Typical
+  // Sigstore/cosign bundles are small enough to send in ImageTransfer
+  // without a separate streamed transfer.
+  //
+  // If signed_bundle_size is non-zero and the target does not support signed
+  // bundle transfer, the target must respond to ImageTransfer with
+  // image_transfer_error (google.rpc.Status code FAILED_PRECONDITION) before
+  // sending ImageTransferReady. The target must not accept image content in
+  // this case.
+  //
+  // When signed_bundle_size is zero, signed_bundle must be empty and behavior
+  // is unchanged; targets that do not implement signed bundle transfer remain
+  // compatible.
   // This RPC will return the following error codes in case of error:
   //    - ResourceExhausted if there isn't enough disk space to save the image.
-  //    - InvalidArgument sends more data than was advertised or if there is
-  //          no image file associated with this transfer.
+  //    - InvalidArgument sends more data than was advertised, if there is
+  //          no image file associated with this transfer, or if
+  //          signed_bundle_size does not match signed_bundle.
+  //    - FailedPrecondition if signed_bundle_size is non-zero but the target
+  //          does not support signed bundle transfer or verification fails.
   //    - Internal if the container runtime is unable to store the image.
   //    - Unavailable if the client is unable to receive responses from the
   //          server.
@@ -215,12 +236,31 @@ message ImageTransfer {
 
   // Indicates that the file to be transferred is a plugin.
   bool is_plugin = 5;
+
+  // Optional size (in bytes) of a signed bundle included in signed_bundle.
+  // When non-zero, signed_bundle must be present and its length must equal
+  // this value. The target uses this field to validate the advertised bundle
+  // size and to reserve disk space before accepting image content. The bundle
+  // contents and signing scheme are opaque to this RPC.
+  //
+  // When non-zero, the target must support signed bundle transfer and
+  // verification. If the target does not support this feature, it must reject
+  // the Deploy stream by sending image_transfer_error with code
+  // FAILED_PRECONDITION in response to ImageTransfer, before
+  // ImageTransferReady.
+  uint64 signed_bundle_size = 6;
+
+  // Optional signed bundle accompanying the container image. Present when
+  // signed_bundle_size is non-zero. Typical Sigstore/cosign bundles are on
+  // the order of 10KB and fit in a single ImageTransfer message.
+  bytes signed_bundle = 7;
 }
 
 // ImageTransferEnd indicates to the target that the client is finished sending
-// and therefore no more content will be sent. Any content sent after this
-// message should be discarded. This message serves as a signal to the target
-// to begin integrity verifications on the received data.
+// image content. If ImageTransfer.signed_bundle_size is zero, the target may
+// begin integrity verification on the received image data. If
+// signed_bundle_size is non-zero, the target must verify signed_bundle against
+// the received image before loading it.
 message ImageTransferEnd {
 }
 
@@ -229,6 +269,12 @@ message DeployResponse {
     ImageTransferReady image_transfer_ready = 1;
     ImageTransferProgress image_transfer_progress = 2;
     ImageTransferSuccess image_transfer_success = 3;
+    // Terminal error for the Deploy stream. Sent when the transfer or
+    // verification fails, or when ImageTransfer requests signed bundle
+    // transfer (signed_bundle_size non-zero) but the target does not support
+    // it. Unsupported signed bundle transfer must be reported here (code
+    // FAILED_PRECONDITION) in response to ImageTransfer, before
+    // ImageTransferReady.
     google.rpc.Status image_transfer_error = 4;
   }
 }