Merge pull request #2742 from mtrmac/digest-warning

Add warnings about direct use of ImageSource

image/unparsed.go

@@ -15,6 +15,9 @@ type UnparsedImage = image.UnparsedImage
 // UnparsedInstance returns a types.UnparsedImage implementation for (source, instanceDigest).
 // If instanceDigest is not nil, it contains a digest of the specific manifest instance to retrieve (when the primary manifest is a manifest list).
 //
+// This implementation of [types.UnparsedImage] ensures that [types.UnparsedImage.Manifest] validates the image
+// against instanceDigest if set, or, if not, a digest implied by src.Reference, if any.
+//
 // The UnparsedImage must not be used after the underlying ImageSource is Close()d.
 func UnparsedInstance(src types.ImageSource, instanceDigest *digest.Digest) *UnparsedImage {
 	return image.UnparsedInstance(src, instanceDigest)
@@ -33,6 +36,9 @@ func (uwr *unparsedWithRef) Reference() types.ImageReference {
 // UnparsedInstanceWithReference returns a types.UnparsedImage for wrappedInstance which claims to be a replacementRef.
 // This is useful for combining image data with other reference values, e.g. to check signatures on a locally-pulled image
 // based on a remote-registry policy.
+//
+// For the purposes of digest validation in [types.UnparsedImage.Manifest], what matters is the
+// reference originally used to create wrappedInstance, not replacementRef.
 func UnparsedInstanceWithReference(wrappedInstance types.UnparsedImage, replacementRef types.ImageReference) types.UnparsedImage {
 	return &unparsedWithRef{
 		UnparsedImage: unparsedimage.FromPublic(wrappedInstance),

internal/image/unparsed.go

@@ -30,6 +30,9 @@ type UnparsedImage struct {
 // UnparsedInstance returns a types.UnparsedImage implementation for (source, instanceDigest).
 // If instanceDigest is not nil, it contains a digest of the specific manifest instance to retrieve (when the primary manifest is a manifest list).
 //
+// This implementation of [types.UnparsedImage] ensures that [types.UnparsedImage.Manifest] validates the image
+// against instanceDigest if set, or, if not, a digest implied by src.Reference, if any.
+//
 // The UnparsedImage must not be used after the underlying ImageSource is Close()d.
 //
 // This is publicly visible as c/image/image.UnparsedInstance.
@@ -48,6 +51,9 @@ func (i *UnparsedImage) Reference() types.ImageReference {
 }
 
 // Manifest is like ImageSource.GetManifest, but the result is cached; it is OK to call this however often you need.
+//
+// Users of UnparsedImage are promised that this validates the image
+// against either i.instanceDigest if set, or against a digest included in i.src.Reference.
 func (i *UnparsedImage) Manifest(ctx context.Context) ([]byte, string, error) {
 	if i.cachedManifest == nil {
 		m, mt, err := i.src.GetManifest(ctx, i.instanceDigest)

types/types.go

@@ -242,6 +242,7 @@ type BlobInfoCache interface {
 //
 // WARNING: Various methods which return an object identified by digest generally do not
 // validate that the returned data actually matches that digest; this is the caller’s responsibility.
+// See the individual methods’ documentation for potentially more details.
 type ImageSource interface {
 	// Reference returns the reference used to set up this source, _as specified by the user_
 	// (not as the image itself, or its underlying storage, claims).  This can be used e.g. to determine which public keys are trusted for this image.
@@ -252,10 +253,17 @@ type ImageSource interface {
 	// It may use a remote (= slow) service.
 	// If instanceDigest is not nil, it contains a digest of the specific manifest instance to retrieve (when the primary manifest is a manifest list);
 	// this never happens if the primary manifest is not a manifest list (e.g. if the source never returns manifest lists).
+	//
+	// WARNING: This is a raw access to the data as provided by the source; if the reference contains a digest, or instanceDigest is set,
+	// callers must enforce the digest match themselves, typically by using image.UnparsedInstance to access the manifest instead
+	// of calling this directly. (Compare the generic warning applicable to all of the [ImageSource] interface.)
 	GetManifest(ctx context.Context, instanceDigest *digest.Digest) ([]byte, string, error)
 	// GetBlob returns a stream for the specified blob, and the blob’s size (or -1 if unknown).
 	// The Digest field in BlobInfo is guaranteed to be provided, Size may be -1 and MediaType may be optionally provided.
 	// May update BlobInfoCache, preferably after it knows for certain that a blob truly exists at a specific location.
+	//
+	// WARNING: This is a raw access to the data as provided by the source; callers must validate the contents
+	// against the blob’s digest themselves. (Compare the generic warning applicable to all of the [ImageSource] interface.)
 	GetBlob(context.Context, BlobInfo, BlobInfoCache) (io.ReadCloser, int64, error)
 	// HasThreadSafeGetBlob indicates whether GetBlob can be executed concurrently.
 	HasThreadSafeGetBlob() bool