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

---