Skip to content

05 Signing

Signing is now managed globally through signer integrations instead of per-repository private key files. Create or import a key once, then bind repositories to that key with --key=<type>/<id> at creation time.

Current signer families:

  • OpenPGP (gpg, alias openpgp)
  • Jsign-backed (jks, spcpvk, safenet)
  • Apple Codesign (apple-codesign, CLI command rcodesign)

5.1 Prerequisites

  • A created repository target from 04 Creating Repositories.
  • CLI access with permission to create repositories and manage signing keys.
  • Either a private OpenPGP key available locally (for import), or user details for creating a new key.
  • For Jsign signer types, ensure jsign is installed in the Athene runtime image or host.
  • For Apple notarization workflows, ensure rcodesign is installed in the Athene runtime image or host.

5.2 Quick Start

Step 1: Create a brand new OpenPGP key in Athene

athene gpg create-key --name "Build Bot" --email "build@example.com"

Optional creation parameters:

  • --key-type (for example rsa, ed25519, default)
  • --size (for example 4096)
  • --validity (for example 1y, 90d, 0 for no expiry)
  • --passphrase

Example with optional parameters:

athene gpg create-key --name "Release Bot" --email "release@example.com" --key-type rsa --size 4096 --validity 1y --passphrase 'your-passphrase'

Step 2: Import an existing OpenPGP private key into Athene (alternative)

gpg --output - --export-secret-keys <KEYID> | athene gpg import-key

If the key is passphrase protected:

gpg --output - --export-secret-keys <KEYID> | athene gpg import-key --passphrase 'your-passphrase'

Step 3: List available signing keys

athene gpg list-keys

Step 4: Create a repository bound to a key

athene debian create-repository main --distribution=bookworm --components=main --key=gpg/<id>

Step 5: Fetch a public key for consumers

curl -fsSL http://localhost:19191/keys/gpg/<id>

5.3 Key Parameters Explained

  • Signer type (gpg or openpgp): integration namespace used in key references.
  • Key reference (--key=<type>/<id>): stored with the repository and reused for package/metadata signing.
  • Create key inputs: --name and --email are required; key algorithm, size, validity, and passphrase are optional.
  • Public key endpoint (/keys/<type>/<id>): returns ASCII-armored public key content for consumer trust setup.

Backend compatibility:

  • debian, rpm, and maven repository signing currently supports OpenPGP keys only (gpg/openpgp).
  • files repository signing supports OpenPGP and Jsign-based signer keys.

5.3.1 Jsign Signer Quick Reference

  • jks: references Java keystores (JKS/JCEKS/PKCS12) via Jsign.
  • spcpvk: references SPC certificate + PVK private key pairs via Jsign.
  • safenet: references SafeNet token-backed keys via Jsign and vendor middleware.
  • apple-codesign: references an Apple signing certificate and App Store Connect API key metadata for notarization.

Example key registration commands:

athene jks create-key --name "Windows CodeSign" --keystore /var/lib/athene/keys/codesign.p12 --storetype PKCS12 --storepass "changeit" --alias "codesign"
athene spcpvk create-key --name "Legacy SPC/PVK" --cert-file /var/lib/athene/keys/codesign.spc --pvk-file /var/lib/athene/keys/codesign.pvk --storepass "secret"
athene safenet create-key --name "HSM Token" --alias "token-cert" --storetype ETOKEN
athene rcodesign create-key --name "Apple Release" --cert-file /var/lib/athene/keys/apple-release.p12 --passphrase "changeit" --api-issuer-id "00000000-0000-0000-0000-000000000000" --api-key-id "DEADBEEF42" --api-private-key-file /var/lib/athene/keys/AuthKey_DEADBEEF42.p8

Example files repository using a Jsign key reference:

athene files create-repository binaries --layout=%p/%v/%p-%a-%v.%x --key=jks/<id>

Apple certificate + API key import (multipart, two file parts):

athene rcodesign import-key --name "Apple Release" --cert-file ./apple-release.p12 --passphrase "changeit" --api-issuer-id "00000000-0000-0000-0000-000000000000" --api-key-id "DEADBEEF42" --api-private-key-file ./AuthKey_DEADBEEF42.p8

For Apple signing workflows, use --passphrase for PKCS#12 certificate protection.

Ad-hoc sign + notarize + staple:

athene rcodesign sign ./MyApp.pkg ./MyApp.signed.pkg --key <id> --notarize --staple --wait --max-wait-seconds 900

Ad-hoc sign + notarize + staple when the certificate passphrase is not stored with the key:

athene rcodesign sign ./MyApp.pkg ./MyApp.signed.pkg --key <id> --passphrase "changeit" --notarize --staple --wait --max-wait-seconds 900

Tip

Keep repository names stable and rotate keys by creating a new key entry, then updating repository configuration or recreating repository definitions with a new --key reference.

5.4 Key Management Actions

  • Show public key:
athene gpg show-key <id>
  • Delete key:
athene gpg delete-key <id>
  • Create key:
athene gpg create-key --name "Build Bot" --email "build@example.com"

5.5 What You Should Have Before Chapter 06

  • At least one imported signing key.
  • At least one repository created with --key=<type>/<id>.
  • Verified public key download path under /keys/<type>/<id>.

5.6 Sign an Individual File

You can ask Athene to sign a single file and return the detached armored signature bytes.

Sign file to stdout (default):

athene gpg sign ./my-package.tar.gz --key <id>

Sign file and save to output path:

athene gpg sign ./my-package.tar.gz ./my-package.tar.gz.asc --key <id>

Sign from stdin and write to stdout:

cat ./my-package.tar.gz | athene gpg sign - - --key <id>

If the key passphrase is not stored server-side, provide it at sign time:

athene gpg sign ./my-package.tar.gz ./my-package.tar.gz.asc --key <id> --passphrase 'your-passphrase'

Notes:

  • Output path is optional; omitted or - means stdout.
  • Input path is optional; omitted or - means stdin.
  • If multiple keys exist, provide --key so Athene knows which key to use.

Next chapter: 06 Importing and Publishing Packages.