5. Key distributed in APKO image generation

How is the Key Distributed in Apko Image Generation?

When using Apko to build and sign images, the signing key (melange.rsa.pub) is typically embedded inside the container image in a structured way. This allows for verification while keeping the private key secure.

Here’s how the key distribution works in Apko:

---

1. Key Storage and Inclusion in Apko Images

During the signing process, the public key (melange.rsa.pub) is:

• Embedded into the container image under /usr/share/melange/keys/
• Used for verifying the signed index of APK packages inside the image

Key locations inside the image:

File/Directory	Purpose
/usr/share/melange/keys/melange.rsa.pub	Public key used for package verification
/var/lib/apk/	Contains signed APK package metadata
/etc/apk/repositories	Lists the repository sources (signed by this key)

---

2. Automatically Embedding the Key in Apko

When Apko builds an image, it automatically:

1. Uses the signing key to sign the package index.
2. Embeds the corresponding public key in the container for verification.
3. Ensures that the public key is available in /usr/share/melange/keys/ so the Alpine package manager (apk) can verify signatures.

Example Apko YAML Configuration (apko.yaml):

archs:
  - amd64
  - arm64

contents:
  repositories:
    - https://packages.example.com/alpine/
  keyring:
    - /usr/share/melange/keys/melange.rsa.pub  # Embedded public key
  packages:
    - busybox

entrypoint:
  command: "/bin/sh"

environment:
  PATH: "/usr/sbin:/usr/bin:/sbin:/bin"

Then, when you build the image:

apko build --signing-key melange.rsa apko.yaml my-image.tar

---

3. Verifying the Key in a Container

Once the image is built, you can verify the embedded public key:

Inside a running container:

docker run --rm -it myregistry.example.com/my-image:latest sh

# Check the public key inside the container
ls /usr/share/melange/keys/
cat /usr/share/melange/keys/melange.rsa.pub

Using melange verify for remote images:

melange verify myregistry.example.com/my-image:latest --key melange.rsa.pub

---

4. Key Distribution for External Verification

If verification needs to happen outside the container, the public key must be:

• Hosted in a repository (e.g., https://keys.example.com/melange.rsa.pub).
• Distributed alongside the image metadata (e.g., in an OCI artifact store).
• Passed explicitly to melange verify or cosign verify for validation.

---

Summary

Step	Key Usage
Signing	Private key (melange.rsa) signs packages and indexes
Embedding	Public key (melange.rsa.pub) stored in /usr/share/melange/keys/
Verification (inside image)	apk uses the embedded key to verify package integrity
Verification (outside image)	Public key must be downloaded separately or referenced manually

---