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
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.
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.
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.jsonCheck. The downloaded manifest has the approved SHA-256. If you report it, KeySigner records a matching check.
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.
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.