Fuzzball Documentation
Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Toggle Dark/Light/Auto mode Back to homepage

SIF Image Decryption

The following syntax is appropriate for a secret that decrypts an encrypted SIF (Singularity Image Format) image. There are two forms, depending on how the image was encrypted.

Passphrase-Based Decryption

For SIF images encrypted with a passphrase:

type: sif-decryption-key
secret:
  passphrase: your-encryption-passphrase

PEM Key-Based Decryption

For SIF images encrypted with an RSA public/private key pair:

type: sif-decryption-key
secret:
  pem: |
    -----BEGIN RSA PRIVATE KEY-----
    MIIEpAIBAAKCAQEA2Z3qX5mNr8X...
    [... complete PEM private key content ...]
    -----END RSA PRIVATE KEY-----

Field Descriptions

The sif-decryption-key secret type provides credentials to decrypt encrypted SIF container images at runtime, allowing jobs to use protected container images without exposing the encryption keys in Fuzzfiles.

  • passphrase (optional): The passphrase used to decrypt the SIF image. Use this field for images encrypted with Apptainer’s passphrase-based encryption method.
  • pem (optional): The complete PEM-formatted RSA private key used to decrypt the SIF image that was encrypted with the corresponding RSA public key including the header and footer. Use this field for images encrypted with Apptainer’s PEM key-based encryption method.
passphrase and pem are mutually exclusive.

Usage

Decryption secrets are referenced in a workflow specification using the decryption-secret field of a job’s image configuration:

jobs:
  my-secure-job:
    image:
      uri: oras://registry.example.com/secure/app.sif:latest
      decryption-secret: secret://user/my-decryption-key
    script: |
      #!/bin/sh
      ./run-app.sh

See Secret Scope for the reference format and the scopes it accepts.

Creating the Decryption Secret

With the PEM private key that the image was encrypted against – see Using Encrypted SIF Images – create a YAML file (decryption_key_secret.yaml) holding it:

$ cat > decryption_key_secret.yaml <<EOF
type: sif-decryption-key
secret:
  pem: |
$(sed 's/^/    /' rsa_private.pem)
EOF

Upload the secret:

$ fuzzball secret create --scope user --from-file \
    secure-app-key decryption_key_secret.yaml

Security Considerations

  • Protect private keys. Never commit PEM private keys to version control, and never transmit them over an unencrypted channel.
  • Rotate keys. Rotating an encryption key requires re-encrypting every image built against it, so plan rotation alongside image rebuilds.
  • Choose the narrowest scope. Use user for personal development and testing, group for team projects and shared workflows, organization only when images must cross group boundaries, and cluster only for system images; the cluster scope requires administrator privileges.
  • Separate keys by project. A different decryption key per image or project limits the exposure if one key is compromised.

See also