image/copy: Allow user to force digest algorithm in CLI ops like skopeo copy

Add support for forcing a specific digest algorithm (e.g., sha512) when
copying images. This allows users to override the default sha256 digest
algorithm used by most transports.

Key changes:
- Add BrokenSetForceDestinationDigestAlgorithm() API to configure digest forcing
  (marked as unstable/incomplete, will be renamed when feature is complete)
- Use digests.Options.Choose() throughout to validate and enforce digest choices
- Add updateManifestConfigDigest() helper using manifest abstraction layer
- Modify copyConfig() to return new config digest when algorithm changes
- Clean failures for unsupported combinations:
  * Multi-arch images (not yet implemented)
  * Docker schema1 manifests (only supports sha256)
  * zstd:chunked compression with non-sha256 (falls back to plain zstd)
  * PutBlobPartial when forcing different algorithm (disabled)
  * Blob reuse across digest algorithms (skipped with warning)

Signed-off-by: Lokesh Mandvekar <lsm5@redhat.com>

Author: lsm5

image/copy/blob.go

@@ -138,7 +138,10 @@ func (ic *imageCopier) copyBlobFromStream(ctx context.Context, srcReader io.Read
 		return types.BlobInfo{}, fmt.Errorf("Internal error writing blob %s, digest verification failed but was ignored", srcInfo.Digest)
 	}
 	if stream.info.Digest != "" && uploadedInfo.Digest != stream.info.Digest {
-		return types.BlobInfo{}, fmt.Errorf("Internal error writing blob %s, blob with digest %s saved with digest %s", srcInfo.Digest, stream.info.Digest, uploadedInfo.Digest)
+		// If algorithms match, the whole digest values must match
+		if stream.info.Digest.Algorithm() == uploadedInfo.Digest.Algorithm() {
+			return types.BlobInfo{}, fmt.Errorf("Internal error writing blob %s, blob with digest %s saved with digest %s", srcInfo.Digest, stream.info.Digest, uploadedInfo.Digest)
+		}
 	}
 	if digestingReader.validationSucceeded {
 		if err := compressionStep.recordValidatedDigestData(ic.c, uploadedInfo, srcInfo, encryptionStep, decryptionStep); err != nil {

image/copy/copy.go

@@ -167,6 +167,26 @@ type Options struct {
 	digestOptions digests.Options
 }
 
+// BrokenSetForceDestinationDigestAlgorithm forces the use of a specific digest algorithm when writing to the destination.
+//
+// UNSTABLE API: This API is incomplete and may be changed or removed at any time.
+// It currently only enforces the digest algorithm for a subset of transports and operations.
+// See https://github.com/containers/container-libs/pull/552 for implementation status.
+func (o *Options) BrokenSetForceDestinationDigestAlgorithm(algo digest.Algorithm) error {
+	if o.digestOptions.MustUseSet() != "" {
+		return fmt.Errorf("digest options are already configured")
+	}
+	if !algo.Available() {
+		return fmt.Errorf("digest algorithm %q is not available", algo.String())
+	}
+	digestOpts, err := digests.MustUse(algo)
+	if err != nil {
+		return fmt.Errorf("failed to set force-digest algorithm: %w", err)
+	}
+	o.digestOptions = digestOpts
+	return nil
+}
+
 // OptionCompressionVariant allows to supply information about
 // selected compression algorithm and compression level by the
 // end-user. Refer to EnsureCompressionVariantsExist to know
@@ -210,12 +230,13 @@ func Image(ctx context.Context, policyContext *signature.PolicyContext, destRef,
 	if options == nil {
 		options = &Options{}
 	}
-	// FIXME: Currently, digestsOptions is not implemented at all, and exists in the codebase
-	// only to allow gradually building the feature set.
-	// After c/image/copy consistently implements it, provide a public digest options API of some kind.
-	optionsCopy := *options
-	optionsCopy.digestOptions = digests.CanonicalDefault()
-	options = &optionsCopy
+	// FIXME: digestsOptions exists to gradually build the feature. Provide public API once fully implemented.
+	// Set default only if not configured by BrokenSetForceDestinationDigestAlgorithm
+	if options.digestOptions.MustUseSet() == "" {
+		optionsCopy := *options
+		optionsCopy.digestOptions = digests.CanonicalDefault()
+		options = &optionsCopy
+	}
 
 	if err := validateImageListSelection(options.ImageListSelection); err != nil {
 		return nil, err

image/copy/multiple.go

@@ -208,6 +208,12 @@ func (c *copier) copyMultipleImages(ctx context.Context) (copiedManifest []byte,
 		cannotModifyManifestListReason = "Instructed to preserve digests"
 	}
 
+	// FIXME: Multi-arch not supported yet; would need config digest updates for each instance.
+	// See https://github.com/containers/container-libs/pull/552#discussion_r2611627578
+	if c.options.digestOptions.MustUseSet() != "" {
+		return nil, fmt.Errorf("forcing digest algorithm with multi-arch images is not yet implemented")
+	}
+
 	// Determine if we'll need to convert the manifest list to a different format.
 	forceListMIMEType := c.options.ForceManifestMIMEType
 	switch forceListMIMEType {

image/copy/single.go

@@ -18,6 +18,7 @@ import (
 	"github.com/sirupsen/logrus"
 	"github.com/vbauerster/mpb/v8"
 	"go.podman.io/image/v5/docker/reference"
+	"go.podman.io/image/v5/internal/digests"
 	"go.podman.io/image/v5/internal/image"
 	"go.podman.io/image/v5/internal/pkg/platform"
 	"go.podman.io/image/v5/internal/private"
@@ -173,6 +174,21 @@ func (c *copier) copySingleImage(ctx context.Context, unparsedImage *image.Unpar
 		}
 	}
 
+	// FIXME: zstd:chunked requires sha256 for TOC/chunk digests; fall back to plain zstd with other algorithms.
+	if forcedAlgo := ic.c.options.digestOptions.MustUseSet(); forcedAlgo != "" && forcedAlgo != digest.SHA256 {
+		format := ic.compressionFormat
+		if format == nil {
+			format = defaultCompressionFormat
+		}
+		if format.Name() == compressiontypes.ZstdChunkedAlgorithmName {
+			if ic.requireCompressionFormatMatch {
+				return copySingleImageResult{}, fmt.Errorf("cannot combine zstd:chunked with forced digest algorithm %s (zstd:chunked currently only supports sha256); use plain zstd instead", forcedAlgo)
+			}
+			logrus.Warnf("Compression using zstd:chunked with forced digest algorithm %s is not supported (zstd:chunked uses sha256 for internal digests), using plain zstd instead", forcedAlgo)
+			ic.compressionFormat = &compression.Zstd
+		}
+	}
+
 	// Decide whether we can substitute blobs with semantic equivalents:
 	// - Don’t do that if we can’t modify the manifest at all
 	// - Ensure _this_ copy sees exactly the intended data when either processing a signed image or signing it.
@@ -200,6 +216,15 @@ func (c *copier) copySingleImage(ctx context.Context, unparsedImage *image.Unpar
 	if err != nil {
 		return copySingleImageResult{}, err
 	}
+
+	// Schema1 lacks separate config and only supports sha256; fail early with other algorithms.
+	if forcedAlgo := ic.c.options.digestOptions.MustUseSet(); forcedAlgo != "" && forcedAlgo != digest.SHA256 {
+		isSchema1 := ic.manifestConversionPlan.preferredMIMEType == manifest.DockerV2Schema1MediaType ||
+			ic.manifestConversionPlan.preferredMIMEType == manifest.DockerV2Schema1SignedMediaType
+		if isSchema1 {
+			return copySingleImageResult{}, fmt.Errorf("cannot force digest algorithm %s with Docker schema1 manifests (only sha256 is supported)", forcedAlgo)
+		}
+	}
 	// We set up this part of ic.manifestUpdates quite early, not just around the
 	// code that calls copyUpdatedConfigAndManifest, so that other parts of the copy code
 	// (e.g. the UpdatedImageNeedsLayerDiffIDs check just below) can make decisions based
@@ -592,12 +617,27 @@ func (ic *imageCopier) copyUpdatedConfigAndManifest(ctx context.Context, instanc
 		return nil, "", fmt.Errorf("reading manifest: %w", err)
 	}
 
-	if err := ic.copyConfig(ctx, pendingImage); err != nil {
+	newConfigDigest, err := ic.copyConfig(ctx, pendingImage)
+	if err != nil {
 		return nil, "", err
 	}
 
+	// FIXME: Single image only; multi-arch needs per-instance config digest updates.
+	// See https://github.com/containers/container-libs/pull/552#discussion_r2611627578
+	if newConfigDigest != nil {
+		man, err = ic.updateManifestConfigDigest(man, pendingImage, *newConfigDigest)
+		if err != nil {
+			return nil, "", fmt.Errorf("updating manifest config digest: %w", err)
+		}
+	}
+
 	ic.c.Printf("Writing manifest to image destination\n")
-	manifestDigest, err := manifest.Digest(man)
+	// Choose the digest algorithm based on digest options
+	manifestDigestAlgo, err := ic.c.options.digestOptions.Choose(digests.Situation{})
+	if err != nil {
+		return nil, "", fmt.Errorf("choosing manifest digest algorithm: %w", err)
+	}
+	manifestDigest, err := manifest.DigestWithAlgorithm(man, manifestDigestAlgo)
 	if err != nil {
 		return nil, "", err
 	}
@@ -611,13 +651,33 @@ func (ic *imageCopier) copyUpdatedConfigAndManifest(ctx context.Context, instanc
 	return man, manifestDigest, nil
 }
 
+// updateManifestConfigDigest updates the config digest in the manifest using the manifest abstraction layer.
+func (ic *imageCopier) updateManifestConfigDigest(manifestBlob []byte, src types.Image, newConfigDigest digest.Digest) ([]byte, error) {
+	_, mt, err := src.Manifest(context.Background())
+	if err != nil {
+		return nil, fmt.Errorf("getting manifest type: %w", err)
+	}
+
+	m, err := manifest.FromBlob(manifestBlob, mt)
+	if err != nil {
+		return nil, fmt.Errorf("parsing manifest: %w", err)
+	}
+
+	if err := m.UpdateConfigDigest(newConfigDigest); err != nil {
+		return nil, err
+	}
+
+	return m.Serialize()
+}
+
 // copyConfig copies config.json, if any, from src to dest.
-func (ic *imageCopier) copyConfig(ctx context.Context, src types.Image) error {
+// It returns the new config digest if it changed (due to digest algorithm forcing), or nil otherwise.
+func (ic *imageCopier) copyConfig(ctx context.Context, src types.Image) (*digest.Digest, error) {
 	srcInfo := src.ConfigInfo()
 	if srcInfo.Digest != "" {
 		if err := ic.c.concurrentBlobCopiesSemaphore.Acquire(ctx, 1); err != nil {
 			// This can only fail with ctx.Err(), so no need to blame acquiring the semaphore.
-			return fmt.Errorf("copying config: %w", err)
+			return nil, fmt.Errorf("copying config: %w", err)
 		}
 		defer ic.c.concurrentBlobCopiesSemaphore.Release(1)
 
@@ -645,13 +705,17 @@ func (ic *imageCopier) copyConfig(ctx context.Context, src types.Image) error {
 			return destInfo, nil
 		}()
 		if err != nil {
-			return err
+			return nil, err
 		}
 		if destInfo.Digest != srcInfo.Digest {
-			return fmt.Errorf("Internal error: copying uncompressed config blob %s changed digest to %s", srcInfo.Digest, destInfo.Digest)
+			// If algorithms match, the whole digest values must match
+			if destInfo.Digest.Algorithm() == srcInfo.Digest.Algorithm() {
+				return nil, fmt.Errorf("Internal error: copying uncompressed config blob %s changed digest to %s", srcInfo.Digest, destInfo.Digest)
+			}
+			return &destInfo.Digest, nil
 		}
 	}
-	return nil
+	return nil, nil
 }
 
 // diffIDResult contains both a digest value and an error from diffIDComputationGoroutine.
@@ -718,7 +782,14 @@ func (ic *imageCopier) copyLayer(ctx context.Context, srcInfo types.BlobInfo, to
 	// (e.g. if we know the DiffID of an encrypted compressed layer, it might not be necessary to pull, decrypt and decompress again),
 	// but it’s not trivially safe to do such things, so until someone takes the effort to make a comprehensive argument, let’s not.
 	encryptingOrDecrypting := toEncrypt || (isOciEncrypted(srcInfo.MediaType) && ic.c.options.OciDecryptConfig != nil)
-	canAvoidProcessingCompleteLayer := !diffIDIsNeeded && !encryptingOrDecrypting
+	// Forcing different digest requires processing full layer; PutBlobPartial incompatible.
+	forcingDifferentDigestAlgo := false
+	if forcedAlgo := ic.c.options.digestOptions.MustUseSet(); forcedAlgo != "" {
+		if srcInfo.Digest.Algorithm() != forcedAlgo {
+			forcingDifferentDigestAlgo = true
+		}
+	}
+	canAvoidProcessingCompleteLayer := !diffIDIsNeeded && !encryptingOrDecrypting && !forcingDifferentDigestAlgo
 
 	// Don’t read the layer from the source if we already have the blob, and optimizations are acceptable.
 	if canAvoidProcessingCompleteLayer {
@@ -743,19 +814,35 @@ func (ic *imageCopier) copyLayer(ctx context.Context, srcInfo types.BlobInfo, to
 			tocDigest = *d
 		}
 
-		reused, reusedBlob, err := ic.c.dest.TryReusingBlobWithOptions(ctx, srcInfo, private.TryReusingBlobOptions{
-			Cache:                   ic.c.blobInfoCache,
-			CanSubstitute:           canSubstitute,
-			EmptyLayer:              emptyLayer,
-			LayerIndex:              &layerIndex,
-			SrcRef:                  srcRef,
-			PossibleManifestFormats: append([]string{ic.manifestConversionPlan.preferredMIMEType}, ic.manifestConversionPlan.otherMIMETypeCandidates...),
-			RequiredCompression:     requiredCompression,
-			OriginalCompression:     srcInfo.CompressionAlgorithm,
-			TOCDigest:               tocDigest,
-		})
-		if err != nil {
-			return types.BlobInfo{}, "", fmt.Errorf("trying to reuse blob %s at destination: %w", srcInfo.Digest, err)
+		// FIXME: Blob reuse disabled when forcing different digest algorithm.
+		// Future: support cross-digest reuse via BlobInfoCache (like c/storage does).
+		canTryReuse := true
+		if forcedAlgo := ic.c.options.digestOptions.MustUseSet(); forcedAlgo != "" {
+			if srcInfo.Digest.Algorithm() != forcedAlgo {
+				logrus.Debugf("Skipping blob reuse for %s: digest algorithm %s doesn't match forced algorithm %s",
+					srcInfo.Digest, srcInfo.Digest.Algorithm(), forcedAlgo)
+				canTryReuse = false
+			}
+		}
+
+		reused := false
+		var reusedBlob private.ReusedBlob
+		if canTryReuse {
+			var err error
+			reused, reusedBlob, err = ic.c.dest.TryReusingBlobWithOptions(ctx, srcInfo, private.TryReusingBlobOptions{
+				Cache:                   ic.c.blobInfoCache,
+				CanSubstitute:           canSubstitute,
+				EmptyLayer:              emptyLayer,
+				LayerIndex:              &layerIndex,
+				SrcRef:                  srcRef,
+				PossibleManifestFormats: append([]string{ic.manifestConversionPlan.preferredMIMEType}, ic.manifestConversionPlan.otherMIMETypeCandidates...),
+				RequiredCompression:     requiredCompression,
+				OriginalCompression:     srcInfo.CompressionAlgorithm,
+				TOCDigest:               tocDigest,
+			})
+			if err != nil {
+				return types.BlobInfo{}, "", fmt.Errorf("trying to reuse blob %s at destination: %w", srcInfo.Digest, err)
+			}
 		}
 		if reused {
 			logrus.Debugf("Skipping blob %s (already present):", srcInfo.Digest)

image/copy/single_test.go

@@ -159,3 +159,22 @@ func TestComputeDiffID(t *testing.T) {
 	_, err = computeDiffID(reader, nil)
 	assert.Error(t, err)
 }
+
+func TestBrokenSetForceDestinationDigestAlgorithm(t *testing.T) {
+	opts := &Options{}
+
+	// First call should succeed
+	err := opts.BrokenSetForceDestinationDigestAlgorithm(digest.SHA256)
+	require.NoError(t, err)
+
+	// Second call should fail because digest options are already configured
+	err = opts.BrokenSetForceDestinationDigestAlgorithm(digest.SHA512)
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "digest options are already configured")
+
+	// Test with unavailable algorithm
+	opts2 := &Options{}
+	err = opts2.BrokenSetForceDestinationDigestAlgorithm("sha999")
+	assert.Error(t, err)
+	assert.Contains(t, err.Error(), "is not available")
+}

image/internal/image/docker_schema1.go

@@ -255,3 +255,8 @@ func (m *manifestSchema1) SupportsEncryption(context.Context) bool {
 func (m *manifestSchema1) CanChangeLayerCompression(mimeType string) bool {
 	return true // There are no MIME types in the manifest, so we must assume a valid image.
 }
+
+// UpdateConfigDigest updates the config descriptor's digest in the manifest.
+func (m *manifestSchema1) UpdateConfigDigest(newDigest digest.Digest) error {
+	return fmt.Errorf("cannot update config digest for schema1 manifest")
+}

image/internal/image/docker_schema2.go

@@ -412,3 +412,8 @@ func (m *manifestSchema2) SupportsEncryption(context.Context) bool {
 func (m *manifestSchema2) CanChangeLayerCompression(mimeType string) bool {
 	return m.m.CanChangeLayerCompression(mimeType)
 }
+
+// UpdateConfigDigest updates the config descriptor's digest in the manifest.
+func (m *manifestSchema2) UpdateConfigDigest(newDigest digest.Digest) error {
+	return m.m.UpdateConfigDigest(newDigest)
+}

image/internal/image/manifest.go

@@ -4,6 +4,7 @@ import (
 	"context"
 	"fmt"
 
+	"github.com/opencontainers/go-digest"
 	imgspecv1 "github.com/opencontainers/image-spec/specs-go/v1"
 	"go.podman.io/image/v5/docker/reference"
 	"go.podman.io/image/v5/manifest"
@@ -59,6 +60,9 @@ type genericManifest interface {
 	// algorithms depends not on the current format, but possibly on the target of a conversion (if UpdatedImage converts
 	// to a different manifest format).
 	CanChangeLayerCompression(mimeType string) bool
+	// UpdateConfigDigest updates the config descriptor's digest in the manifest.
+	// This returns an error if the manifest does not support config digest updates (e.g., schema1 manifests).
+	UpdateConfigDigest(newDigest digest.Digest) error
 }
 
 // manifestInstanceFromBlob returns a genericManifest implementation for (manblob, mt) in src.

image/internal/image/oci.go

@@ -8,6 +8,7 @@ import (
 	"slices"
 
 	ociencspec "github.com/containers/ocicrypt/spec"
+	"github.com/opencontainers/go-digest"
 	imgspecv1 "github.com/opencontainers/image-spec/specs-go/v1"
 	"go.podman.io/image/v5/docker/reference"
 	"go.podman.io/image/v5/internal/iolimits"
@@ -332,3 +333,8 @@ func (m *manifestOCI1) SupportsEncryption(context.Context) bool {
 func (m *manifestOCI1) CanChangeLayerCompression(mimeType string) bool {
 	return m.m.CanChangeLayerCompression(mimeType)
 }
+
+// UpdateConfigDigest updates the config descriptor's digest in the manifest.
+func (m *manifestOCI1) UpdateConfigDigest(newDigest digest.Digest) error {
+	return m.m.UpdateConfigDigest(newDigest)
+}

image/manifest/docker_schema1.go

@@ -176,6 +176,11 @@ func (m *Schema1) UpdateLayerInfos(layerInfos []types.BlobInfo) error {
 	return nil
 }
 
+// UpdateConfigDigest updates the config descriptor's digest in the manifest.
+func (m *Schema1) UpdateConfigDigest(newDigest digest.Digest) error {
+	return fmt.Errorf("cannot update config digest for schema1 manifest")
+}
+
 // Serialize returns the manifest in a blob format.
 // NOTE: Serialize() does not in general reproduce the original blob if this object was loaded from one, even if no modifications were made!
 func (m *Schema1) Serialize() ([]byte, error) {