Signing and Trusting Custom Packages on Arch Linux with pacman-key

Why pacman refuses your custom package

When you build a .pkg.tar.zst file outside the official repositories, pacman treats it as unsigned by default. During pacman -Syu or pacman -U it checks each package’s GPG signature against the trusted keyring. If a signature is missing or the signing key is not trusted, the transaction aborts with an error like "signature is unknown trust". This protects the rolling‑release system from unverified binaries.

Creating a signature for your package

First, you need a GPG key dedicated to signing packages. If you already have one, export its public part; otherwise generate a new key with gpg --full-generate-key. To sign a package file, create a detached signature:

# Replace with your package path and key ID
cd ~/packages
gpg --detach-sign --default-key YOUR_KEY_ID my-package-1.0-1-x86_64.pkg.tar.zst
# This produces my-package-1.0-1-x86_64.pkg.tar.zst.sig

Where to run: any terminal where you have read access to the package file. No special privileges are needed for the signing step.

Importing and trusting your signing key

Pacman will only accept the signature if the signing key is present in its keyring and trusted. Import the public key (either from a keyserver or from a file) and then set its trust level:

# Import from a keyserver (replace KEYID with the 8‑byte or 16‑byte hex ID)
sudo pacman-key --recv-keys KEYID
# Alternatively, add a key file you exported earlier
# sudo pacman-key --add /path/to/your-key.asc

# Locally sign the key to mark it as trusted
sudo pacman-key --lsign-key KEYID

Required permissions: pacman-key modifies the system keyring, so you need root or sudo. The --lsign-key operation writes to the local trust database and does not affect the global keyring.

Meaningful placeholders: replace YOUR_KEY_ID with the key’s fingerprint or ID, and KEYID with the same identifier used for importing.

Expected check: after the key is locally signed, pacman-key --list-keys will show a trust value of "ultimate" for that key.

Relevant risks: marking a key as ultimately trusted means any package signed with that key will be accepted. Verify the key fingerprint out‑of‑band (e.g., via the project’s website or a secure channel) before trusting it.

Worked example: installing your signed package

Assuming you have the signed package and its signature file in ~/packages:

# 1. Verify the signature manually (optional, for confidence)
gpg --verify ~/packages/my-package-1.0-1-x86_64.pkg.tar.zst.sig \
       ~/packages/my-package-1.0-1-x86_64.pkg.tar.zst

# 2. Import and trust your signing key (run once)
sudo pacman-key --recv-keys 9FA80F3FEEA16F2C  # example ID
sudo pacman-key --lsign-key 9FA80F3FEEA16F2C

# 3. Install the package
sudo pacman -U ~/packages/my-package-1.0-1-x86_64.pkg.tar.zst

Where to run: a terminal with sudo access. The gpg --verify step is optional but useful for confirming the signature before involving pacman.

Expected check: pacman will output lines similar to "checking package integrity" and "signed with trusted key" during the install. If the key is not trusted, the transaction will abort.

Trade‑offs and limitations

• System clock skew: GPG signatures embed creation and expiration timestamps. If the system clock is significantly wrong, pacman may treat a valid signature as expired. Keep the clock synchronized (timedatectl set-ntp true) before key operations.
• Keyring refreshes: Running pacman-key --refresh-keys updates the Arch keyring but does **not** remove locally set ownertrust values. Your trusted key remains trusted unless it is removed from the keyring.
• AUR packages: Most AUR helpers build and install packages without invoking pacman’s signature verification, so those packages remain unsigned. If your policy requires signed binaries everywhere, you must either sign AUR builds yourself or avoid the AUR.
• Not a substitute for official review: Signing your own package does not subject it to the Arch Linux quality‑control process, dependency auditing, or security‑update tracking.

Actionable closing

After installation, you can confirm that pacman accepted the signature by inspecting the log:

grep "my-package" /var/log/pacman.log | grep "signed with trusted key"

If you see a matching line, the package was installed with a valid signature. For a quick sanity check, run pacman -Qs my-package to verify the package is present in the local database.

By following these steps you can safely integrate your own binaries into Arch’s package‑management workflow while preserving the integrity guarantees that pacman provides.