Verifying Rhino Container Image Signatures

Rhino container images are cryptographically signed to prove authenticity and integrity. This guide explains how to verify that images you receive were built and published by Rhino. 

What You Need

Setup (One-Time)

1. Install Notation and oras

Follow the official installation guides for your platform:

• Notation: notaryproject.dev
• oras: oras.land

Verify installation:

notation version
oras version

2. Add Rhino Root Certificate to Trust Store

Download our root container signing CA rhino-signing-root-ca.pem

Add it to your Notation trust store: 

notation cert add --type ca --store rhino /path/to/rhino-signing-root-ca.pem 

Verify it was added: 

notation cert ls 

You should see the Rhino root CA listed under ca/rhino. 

3. Configure Trust Policy 

If you already have a Notation trust policy (notation policy show), add the following entry to your existing trustPolicies array:

{
  "name": "rhino-images",
  "registryScopes": ["*"],
  "signatureVerification": {
    "level": "strict"
  },
  "trustStores": ["ca:rhino"],
  "trustedIdentities": ["*"]
}

If this is your first trust policy, create a new file with the full structure: 

{
  "version": "1.0",
  "trustPolicies": [
    {
      "name": "rhino-images",
      "registryScopes": ["*"],
      "signatureVerification": {
        "level": "strict"
      },
      "trustStores": ["ca:rhino"],
      "trustedIdentities": ["*"]
    }
  ]
}

Import the policy:

notation policy import /path/to/trustpolicy.json

Verify:

notation policy show

Loading Rhino Images Into Your Registry

Rhino release images are delivered as OCI layout bundles. These bundles contain the container images along with their associated signatures, SBOMs, and build provenance attestations. 

Import from OCI Bundle

# Import a single image with all referrers (signatures, SBOM, provenance)
oras copy --from-oci-layout --recursive /path/to/rhino-release-bundle:<tag> <your-registry>/<image>:<tag>

Verify Import

After importing, confirm that referrers are present: 

oras discover <your-registry>/<image>:<tag>

 You should see entries for application/vnd.cncf.notary.signature (signatures) and potentially application/spdx+json (SBOM) and application/vnd.in-toto+json (provenance). 

Verifying Images

After loading images into your registry, verify their signatures: 

# Resolve tag to digest
oras resolve <your-registry>/rhino/backend:<tag>

# Verify the signature
notation verify <your-registry>/rhino/backend@<digest>

Successful output example:

Successfully verified signature for <your-registry>/rhino/backend@<digest>

What Gets Verified

When you run notation verify, Notation checks: 

1. Integrity: the image hasn't been modified since signing 
2. Authenticity: the signature was produced by a key chaining to the Rhino root CA 
3. Identity: the signing certificate matches the trustedIdentities in your policy

Verifying Referrer Artifacts (SBOM, Provenance)

Rhino also signs the SBOM and build provenance attestations attached to each image. To discover and verify them: 

# List referrers (SBOM, provenance, signatures)
oras discover <registry>/<image>@<digest>

# Verify a specific referrer by its digest
notation verify <registry>/<image>@<referrer-digest>

Troubleshooting

No signature found

Error: signature verification failed: no signature is associated with "<image>"

The image has no Rhino signature attached. Common causes: 

• Images were imported with docker load instead of oras copy --recursive
• The image is a third-party image not signed by Rhino

Registry authentication failure

Error: unable to retrieve signature from registry

Notation needs to be authenticated to your registry to pull signature artifacts. Ensure you are logged in: 

notation login <your-registry>

Untrusted identity

Error: signature verification failed: signing certificate does not match any trusted identity

Your trust policy restricts which signing identities are accepted. If you customized trustedIdentities, verify it matches the Rhino signing certificate subject. Using "trustedIdentities": ["*"] accepts any certificate chaining to the Rhino root CA. 

Expired certificate

Error: signature verification failed: certificate has expired

The signing certificate has expired. Contact Rhino support for updated trust material.

Frequently Asked Questions (FAQ)

What credentials do I need to verify?

You only need credentials to your organization's container registry to verify. Verification will also use Notation CLI and the Rhino root certificate.

Can I verify in an air-gapped environment?

Yes. Import the OCI bundle with oras copy --from-oci-layout --recursive, then verify locally. No network calls beyond your own registry. 

What about third-party images (redis, busybox, etc.)?

Images sourced from Docker Hardened Images (DHI) registry are neither built nor signed by Rhino. Refer to Docker's documentation for verifying DHI trust material. 

What if I used docker pull instead of oras copy?

docker pull does not preserve OCI referrer artifacts (signatures, SBOM, provenance). Use oras copy --recursive for signature-preserving transfers.