Check an approved container image with Notation

Verify the publisher with Notation and check that the same container image digest is the one your KeySigner release owners approved.

Before you start

Notation, ORAS and KeySigner release history

  • Use a disposable image repository, a configured KeySigner test release workflow, the full approved OCI digest and the trusted publisher certificate.

Data and access

Shared or checked
Notation verifies the signed image digest and the trusted publisher. KeySigner’s approval record supplies the digest approved by its release owners.
Check separately
Verify both results. Publisher trust alone does not establish the release approval, and the approval alone does not verify the signature.
  1. Pin the image and record the approval

    Set IMAGE_REPOSITORY to the full registry and repository path and RELEASE_TAG to the test tag. Resolve the tag once and save the pinned reference. Submit that manifest digest to your KeySigner test release workflow. After the owners approve, record the request ID, source run and approved digest.

    IMAGE_DIGEST=$(oras resolve "$IMAGE_REPOSITORY:$RELEASE_TAG") &&
      IMAGE_AT_DIGEST="$IMAGE_REPOSITORY@$IMAGE_DIGEST"

    Check. The full digest on the approved request matches the pinned reference you recorded.

  2. Verify the publisher

    Use a strict Notation trust policy scoped to the test repository and the publisher’s approved certificate subject. Verify the pinned reference. Stop if the signature fails or the signer is outside your trust policy.

    notation verify "$IMAGE_AT_DIGEST"

    Check. Notation reports Successfully verified signature for the pinned digest under the configured policy.

  3. Check the approved digest

    In a scratch directory, fetch the manifest at that same digest and hash the saved file as is. Compare all 64 hexadecimal characters after sha256: on the approval. If the approved digest identifies a multi-platform index, use the index digest throughout. The release requester or an administrator can record the observed digest against the request.

    oras manifest fetch --output manifest.json "$IMAGE_AT_DIGEST" &&
      shasum -a 256 manifest.json

    Check. The downloaded manifest has the approved SHA-256. If you report it, KeySigner records a matching check.

  4. Rehearse a signed replacement

    In the disposable repository, point the test tag at a different image signed by the same publisher. Resolve the tag again and repeat the verification and digest comparison with the new pinned reference. Save the new manifest in a fresh scratch directory. Use the original KeySigner request when reporting the observed digest.

    Check. Notation accepts the separately signed image. KeySigner records Published bytes differ because the approval covers the original digest.

Check your result

Require both checks to pass for the same digest. Use that pinned reference in the deployment so a later tag change cannot change which image it pulls.

What we tested

Tested on . In a disposable Distribution 3.1.2 registry, Notation 1.3.2 verified each of two manifests under the same strict publisher policy. ORAS 1.4.0 fetched both manifests by digest and their SHA-256 hashes matched the registry references. In a local KeySigner release workflow, two owners approved the original digest. KeySigner recorded a match for that digest and a mismatch for the separately signed replacement after the test tag moved.

How to verify your setup

If you get stuck

Notation verifies the signature but KeySigner reports a different digest

Pause the deployment. Check whether the tag moved or the approval covers a multi-platform index while your workflow checked a platform manifest. If the new image is intended, request approval for its digest and verify that same reference again.

Report a problem with this guide

Explore all setup guides →