Skip to content
Tutorials Center
My learning

Topics

Lesson 29 of 37 ยท Building and Registries

Image Signing and Trust Policy

Decide which images Podman may pull: policy.json requirements, reject and signedBy rules, Sigstore and GPG signatures, digest pinning and a safe supply-chain workflow.

Pulling an image means running someone else's code. How do you know the image you pulled is the one the publisher built, and not something swapped in a compromised registry or a typo-squatted name? Podman has a built-in answer: a signature policy that is checked on every pull, plus digests that pin exact content.

This lesson covers policy.json, what signed images are, how to sign and verify with Sigstore and GPG, and why digests are the simplest strong protection. Verification needs registries and keys, so commands are read-only; the stand-ins evaluate a policy and verify digests.

Tags can lie, digests cannot

A tag such as myapp:1.0 is a pointer. The registry owner (or an attacker with write access) can move it to different content at any time. A digest is the SHA-256 of the image manifest, so a reference like registry.example.com/myapp@sha256:... identifies exactly one image. If the bytes change, the digest changes, and the pull fails.

Terminal
podman pull registry.example.com/team/myapp@sha256:3b1f...
podman image inspect --format '{{.Digest}}' registry.example.com/team/myapp:1.0

The mechanism is ordinary hashing. This stand-in shows that any change to the content changes the digest, and what a pull "verifies":

Python Why digests protect you (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Digests protect integrity, but they do not tell you who published the image. Signatures answer that question.

The trust policy: policy.json

Every pull is checked against /etc/containers/policy.json (or ~/.config/containers/policy.json, which a user can create for themselves). The default file allows everything:

JSON
{
  "default": [{ "type": "insecureAcceptAnything" }],
  "transports": {
    "docker-daemon": { "": [{ "type": "insecureAcceptAnything" }] }
  }
}

A stricter policy rejects by default and allows chosen sources:

JSON
{
  "default": [{ "type": "reject" }],
  "transports": {
    "docker": {
      "docker.io/library": [{ "type": "insecureAcceptAnything" }],
      "registry.example.com/team": [
        {
          "type": "sigstoreSigned",
          "keyPath": "/etc/pki/containers/team.pub",
          "signedIdentity": { "type": "matchRepository" }
        }
      ]
    },
    "dir": { "": [{ "type": "insecureAcceptAnything" }] }
  }
}

The structure:

  • default: requirements for anything not matched below.
  • transports: how the image is accessed (docker for registries, dir, oci, docker-archive, containers-storage...).
  • Scopes under a transport: from specific to general. For docker, the scope is registry/namespace/repo, a prefix of it, or the registry alone. The most specific matching scope wins.
  • Requirement types: insecureAcceptAnything (no checks), reject, signedBy (a GPG signature from a given key), sigstoreSigned (a Sigstore signature, with keyPath, keyData or Fulcio/Rekor settings).

A request is accepted only if all requirements in the winning scope are satisfied.

Python Policy evaluator (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with input()), it gets the next line from this box.

Note how registry.example.com/team/scratch overrides its parent scope, and how an unlisted registry falls to default.

Signature formats

Sigstore signatures use keys (or short-lived certificates, "keyless") and are stored next to the image in the registry. Podman supports creating them on push and verifying them on pull:

Terminal
cosign generate-key-pair                              # creates cosign.key and cosign.pub
podman push --sign-by-sigstore-private-key ./cosign.key \
  localhost/myapp:1.0 docker://registry.example.com/team/myapp:1.0

Add the registry to /etc/containers/registries.d/ so Podman looks for and stores attached signatures:

YAML
docker:
  registry.example.com:
    use-sigstore-attachments: true

Then put sigstoreSigned with your public key in policy.json as shown above. Pulls from that scope now fail unless a valid signature exists.

GPG signatures (the "simple signing" format) use signedBy requirements and a keyring, with podman push --sign-by KEYID to create them and a lookaside URL in registries.d to store them. They are older and still supported; new setups typically choose Sigstore.

A safe supply-chain routine

  1. Prefer trusted sources: official or verified publishers, from fully qualified names (see Registries and Authentication).
  2. Pin digests in production Containerfiles, Compose files and Quadlet units (Image=registry.example.com/team/api@sha256:...). Update them deliberately, ideally with a bot that opens reviewable changes.
  3. Verify signatures with a strict policy.json for namespaces you control.
  4. Scan images for known vulnerabilities with a tool such as Trivy or Grype before deployment.
  5. Rebuild regularly so security fixes in base images reach your images.

Pinned digests do not receive security updates by themselves. Pinning trades automatic change for predictability; pair it with a routine that updates the pin and re-tests.

Checking what you pulled

Terminal
podman image inspect IMAGE --format '{{.Digest}} {{.Created}}'
podman image trust show           # summary of trust settings
podman pull --signature-policy ./strict.json IMAGE

podman image trust set and show give a command-line way to edit and display simple policy entries without hand-editing JSON.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. Why can a tag like myapp:1.0 change but a digest cannot?

    A tag is a movable pointer. A digest is the SHA-256 of the manifest, so different content gives a different digest.
  2. 2. In policy.json, which scope applies when several match an image?

    For docker, the longest matching scope wins; unmatched images use default.
  3. 3. Which requirement type checks a Sigstore signature?

    sigstoreSigned verifies Sigstore signatures; signedBy is for GPG.
  4. 4. What does a default of reject plus allow-listed scopes achieve?

    Everything not explicitly allowed is refused, which implements an allow list.

Summary

  • Tags move; digests pin exact content. Use digests where reproducibility and integrity matter.
  • policy.json decides what each pull must satisfy: reject, insecureAcceptAnything, signedBy, sigstoreSigned.
  • The most specific scope under a transport wins; everything else falls to default.
  • Sigstore signing uses podman push --sign-by-sigstore-private-key and registries.d attachments.
  • Combine trusted sources, digest pins, signature policy, scanning and regular rebuilds.

Next: Systemd Services and Auto-Update