Release Trust Infrastructure¶

Purpose¶

This chapter defines the Shyft release trust infrastructure.

It describes how the organization establishes, maintains, and operates the cryptographic trust required for authenticated source history, controlled release signing, and downstream verification of released artifacts.

The procedures are intentionally practical. Although the reference implementation uses OpenPGP, Nitrokey hardware tokens, GnuPG, Git and standard Linux tooling, the architectural principles are independent of any specific technology.

Design Principles¶

The Shyft identity model is based on the following principles:

keep certification authorities offline;
use hardware-backed signing and authentication keys;
verify backups by offline restoration before trusting them;
separate organizational authority from individual identity.

Trust Model¶

Shyft separates organizational trust from personal identity by defining three distinct classes of OpenPGP keys.

Each class has a single purpose and follows different operational procedures.

Shyft Root Certification Key¶

The Shyft root certification key is the project’s trust anchor.

It exists solely to establish and maintain the trust chain for official Shyft release signing.

It is used only to:

certify Shyft artifact signing keys;
revoke or replace artifact signing keys when required;
support key rotation and recovery ceremonies.

The certification key is permanently kept offline and is never used for release signing, software development, authentication, or daily operations.

Shyft Artifact Signing Keys¶

Artifact signing keys are organizational role keys used exclusively for official Shyft release production.

Each signing key is certified by the Shyft root certification key and is authorized to sign release artifacts on behalf of the project.

Artifact signing keys may be delegated to trusted release operators or used within controlled signing ceremonies. In larger organizations, signing keys may remain permanently installed in dedicated signing systems or secured rooms under multi-person control.

Artifact signing keys are used only to sign:

release archives;
RPM packages;
pacman packages;
repository metadata;
other official distribution artifacts.

The private signing subkeys should reside on hardware-backed devices such as Nitrokey tokens or equivalent secure cryptographic hardware.

Developer Identity Keys¶

Developer identity keys establish accountability within the Shyft source development process.

Within Shyft they are used for:

Git commit signing;
Git tag signing;
SSH authentication to project Git services using hardware-backed keys.

Shyft recommends using hardware-backed SSH authentication, where the SSH authentication key resides on a cryptographic token such as a Nitrokey. When protected by a user PIN, remote Git operations require both possession of the hardware token and knowledge of the PIN, providing strong protection against credential theft and unauthorized repository access.

Developer identity keys establish trust in the project’s source history, but they are not part of the release signing infrastructure.

Shyft strongly recommends protecting developer identity keys using hardware-backed cryptographic tokens. Keys may either be generated directly on the hardware device, where the private key is non-exportable, or generated on a trusted offline workstation before being transferred to the hardware token.

In open-source projects these keys are typically owned and managed by the individual contributor. In corporate environments, they may instead be issued and managed by the organization as part of its identity and access management processes. Regardless of ownership, their role within the Shyft trust model remains the same: establishing the authenticity and accountability of the source history.

Key Role Overview¶

        flowchart TD

   subgraph ST["Source Trust"]
      DK[Developer identity key<br/>commit/tag/SSH]
      GIT[Signed Git history]
      SRC[Verified source tree]
      DK -->|signs| GIT
      GIT --> SRC
   end

   subgraph RT["Release Trust"]
      ROOT[Shyft root certification key<br/>offline certification workstation]
      SA[Artifact signing key A<br/>hardware-backed]
      SB[Artifact signing key B<br/>hardware-backed]
      REL[Official release artifacts<br/>RPM, pacman, metadata]

      ROOT -->|certifies| SA
      ROOT -->|certifies| SB
      SA -->|signs| REL
      SB -->|signs| REL
   end

   SRC -->|release ceremony| REL

Shyft source and release trust model¶

Official Release Definition¶

A Shyft release artifact is considered official when:

It is signed by an authorized Shyft artifact signing key.
That signing key is certified by the current Shyft root certification key.
The signing key is listed as authorized in the current release documentation.
The documented release procedure has been followed.

Provisioning Workstation¶

Purpose¶

The provisioning workstation is the root of trust for the Shyft certification infrastructure.

Following initial operating-system installation and provisioning, and before the root certification ceremony is performed, the workstation shall be permanently disconnected from all networks.

This includes:

wired Ethernet;
Wi-Fi;
Bluetooth;
cellular networking;
any other communication interface capable of communicating with another system.

Where practical, communication hardware should be physically removed or permanently disabled. External network adapters shall not be connected to the workstation.

The provisioning workstation is used only for:

Shyft root certification ceremonies;
artifact signing key ceremonies;
hardware token initialization;
subkey generation;
keytocard operations;
backup and restore verification;
certification and revocation ceremonies;
public key export and transition documentation.

It shall not be used for:

web browsing;
email;
software development;
release builds;
general-purpose administration.

When not in use, the workstation shall remain powered off and stored in a physically secure location.

Physical Security¶

The provisioning workstation is part of the project’s cryptographic trust anchor and shall be protected accordingly.

For the Shyft organization, physical access should be restricted to the designated key custodians.

Organizations adopting this model should store the workstation in a physically secured location with access controls appropriate to their security policy. Where separation of duties is required, organizations may enforce multi-person access or dual-control procedures for accessing the workstation and conducting certification ceremonies.

Lifecycle¶

Once the provisioning workstation has participated in the initial root certification ceremony, it becomes part of the project’s cryptographic trust anchor.

The provisioning workstation intentionally falls outside the lifecycle of ordinary enterprise workstations.

Its security depends on permanent physical isolation rather than continuous connection to software update infrastructure.

From this point onward, the workstation shall remain permanently offline and shall not receive routine operating-system or application updates.

This includes:

package updates;
firmware updates;
security patches;
feature upgrades.

Maintaining the integrity of the established trust anchor takes precedence over keeping the software current.

Any future replacement or reprovisioning of the workstation shall be treated as a new provisioning event and performed according to the documented certification procedures.

Reference Implementation¶

The following configuration is the Shyft reference implementation used for the procedures described in this document. It is intentionally simple, reproducible, and built entirely from standard Linux components.

Organizations adopting the Shyft trust model may choose different operating systems, hardware platforms, or storage layouts, provided the security requirements described in this chapter are preserved.

The reference implementation deliberately maintains two independent encrypted backups.

One remains with the provisioning workstation for routine ceremonies, while the second is stored at a separate secure location for disaster recovery. This provides resilience against both media failure and catastrophic loss of the workstation without expanding the offline trust boundary.

The reference workstation consists of:

Arch Linux;
minimal operating-system installation;
no graphical environment;
temporary wired networking during initial provisioning only;
permanent offline operation after provisioning;
physical removal or permanent disabling of Wi-Fi and Bluetooth where practical;
LUKS-encrypted system disk;
dedicated LUKS-encrypted ceremony backup disk;
dedicated removable LUKS-encrypted disaster-recovery backup device;
one dedicated unprivileged gpg user;
one administrative account (or root) used only for system maintenance.
dedicated USB-A to USB-c cables for nitro-keys;

Initial Arch Linux Setup¶

Install a minimal Arch Linux system.

Perform all operating-system installation, package installation, firmware updates, and other provisioning steps before the workstation becomes part of the Shyft certification infrastructure.

Once the provisioning workstation has been accepted for use in the first root certification ceremony, it shall remain permanently offline.

Use a LUKS-encrypted root disk. Leave the second disk unused during initial installation. It will later be used as a manually mounted ceremony backup disk.

Update the system:

pacman -Syu
reboot

Install only the required tools:

pacman -S gnupg vim less

Recommended local configuration:

hostname: arch-gpg;
strong password for root;
dedicated unprivileged user: gpg;
no graphical desktop;
no routine network use.

Verify Smartcard Access¶

Insert a Nitrokey or compatible OpenPGP smartcard and verify that GnuPG can see it:

gpg --card-status

Successful gpg --card-status confirms that the workstation is ready to communicate with supported OpenPGP hardware tokens.

Before the first root certification ceremony, disconnect the workstation from all networks and permanently disable or remove communication hardware according to the procedures described in the previous chapter.

Ceremony Backup Disk¶

The ceremony backup disk stores encrypted backups created during key ceremonies. It is mounted only for the duration of a ceremony and is immediately unmounted afterwards.

Example setup for /dev/sdb1:

cryptsetup luksFormat --type luks2 /dev/sdb1
cryptsetup open /dev/sdb1 backup
mkfs.ext4 -L backup /dev/mapper/backup
mkdir -p /var/backup
mount /dev/mapper/backup /var/backup

For later ceremonies, open and mount it manually:

cryptsetup open /dev/sdb1 backup
mount /dev/mapper/backup /var/backup

Unmount and close it after the ceremony:

umount /var/backup
cryptsetup close backup

Disaster Recovery Backup Device¶

A second removable LUKS-encrypted backup device is maintained for disaster recovery purposes.

Its sole purpose is to store encrypted copies of the certification infrastructure, including the root certification key, revocation certificates, and other recovery material.

Unlike the ceremony backup disk, this device is intended to be stored at a physically separate secure location to protect against catastrophic events such as theft, fire, or other loss of the provisioning workstation.

The device is connected only while updating disaster-recovery backups.

After each update it shall be removed and returned to secure storage.

Like every storage device containing secret key material, the disaster recovery device shall remain permanently offline.

It shall never be connected to a computer that is, or later becomes, connected to any network.

Its use is restricted to dedicated provisioning workstations that permanently remain offline.

Example setup for /dev/sdc1:

cryptsetup luksFormat --type luks2 /dev/sdc1
cryptsetup open /dev/sdb1 backup3
mkfs.ext4 -L backup /dev/mapper/backup3
mkdir -p /var/backup3
mount /dev/mapper/backup3 /var/backup3

Optional Hardening¶

Organizations with elevated security requirements may deploy additional host hardening measures on the provisioning workstation.

Examples include:

USB device authorization (for example, usbguard);
Secure Boot;
TPM-backed measured boot;
BIOS/UEFI password protection;
chassis intrusion detection.

Such mechanisms should not compromise the long-term maintainability of the provisioning workstation or the ability to perform disaster recovery.

Root Key Ceremony¶

Purpose¶

The root key ceremony creates an offline certification key.

The Shyft root certification key shall never be transferred to a hardware token.

Its private key remains exclusively within the encrypted GnuPG home directory on the offline provisioning workstation and its verified offline backups.

Procedure¶

Generate the root key on the provisioning workstation:

gpg --expert --full-generate-key

Recommended choices:

ECC with custom capabilities;
certification capability only;
Ed25519 / Curve25519 where offered by GnuPG;
long validity period, for example 10 years;
strong passphrase.

When selecting custom capabilities, disable signing, encryption, and authentication. Leave only certification enabled.

Record the root key fingerprint:

gpg --fingerprint --fingerprint <ROOT-FPR>

GnuPG normally creates revocation material automatically during key generation. Ensure that revocation material and the full ~/.gnupg directory are included in the ceremony backup.

Backup Before Continuing¶

Before cross-signing, subkey generation, or other modifications, create a backup of the full GnuPG home directory.

The primary offline copy is the /home/gpg/.gnupg directory on the provisioning workstation. The secondary ceremony copy is stored on the encrypted backup disk.

Example backup script:

#!/bin/env bash
set -e

dt="$(date +%Y-%m-%dT%H-%M-%S)"
backup=/var/backup/ceremonies
ceremony_name=${1:-"root"}
ceremony_dir="${backup}/${dt}-${ceremony_name}"

mkdir -p "${ceremony_dir}"

# Stop agents so temporary sockets and agent state are not archived.
gpgconf --kill all

echo "Create backup of gnupg to ${ceremony_dir}"

tar --zstd --create --preserve-permissions --verbose         --file "${ceremony_dir}/gnupg.tar.zst"         --exclude='.gnupg/S.*'         --exclude='.gnupg/S.gpg-agent*'         --exclude='.gnupg/random_seed'         -C "$HOME" .gnupg

Restore Verification¶

A ceremony backup is not complete until it has been restored and inspected.

Example:

mkdir -p /tmp/verify-gpg
gpg --list-secret-keys --with-subkey-fingerprint >/tmp/verify-gpg/orig.txt
tar --zstd -xf /var/backup/ceremonies/<backup>/gnupg.tar.zst         -C /tmp/verify-gpg

gpg --homedir /tmp/verify-gpg/.gnupg         --list-secret-keys --with-subkey-fingerprint > backup.txt
diff orig.txt backup.txt  # should be equal

Remove the temporary verification directory after inspection:

gpgconf --homedir /tmp/verify-gpg --kill all
rm -rf /tmp/verify-gpg

Trust Transition¶

When replacing or rotating a Shyft root key, certify the new root key with the previous trusted Shyft key where possible.

Example:

gpg --local-user <OLD-SHYFT-KEY-FPR> --sign-key <NEW-SHYFT-ROOT-FPR>

Verify the certification:

gpg --check-sigs --with-fingerprint --keyid-format long <NEW-SHYFT-ROOT-FPR>

After certification, export the updated public key.

Public Key Export¶

The published Shyft public key bundle contains the current certification key and all currently authorized artifact signing subkeys.

Whenever a signing subkey is added, replaced, or revoked, the published public key bundle shall be regenerated and distributed to downstream users.

This allows consumers to verify newly signed artifacts while retaining the same Shyft certification key as their trust anchor.

gpg --armor --export <NEW-SHYFT-ROOT-FPR> > shyft-release.pub

The public export after certification is the key material that should be published and committed to the repository.

Artifact Signing Key Ceremony¶

Purpose¶

Artifact signing keys are Shyft-controlled role keys.

They are used for signing release artifacts and package repositories. They are not personal maintainer identity keys.

The Shyft root certification key certifies artifact signing keys.

Recommended Structure¶

An artifact signing key should use:

an offline certification root;
a signing subkey stored on a hardware token;
an authentication subkey stored on a hardware token where server access is required;
an encryption subkey only if there is a documented operational need.

Create Artifact Signing Identity¶

On the provisioning workstation:

gpg --expert --edit-key <ARTIFACT-ROOT-FPR>

Within the GnuPG editor:

addkey

Create:

signing subkey: Ed25519, sign only, for example 2 years;
authentication subkey: Ed25519, only if needed, authentication only, for example 2 years;
encryption subkey: Curve25519, only if needed.

During the ceremony, the operator will be prompted for the root GPG passphrase.

Remember to save, or quit(save implied), so that sign sub-keys are added to the root-key hierarchy.

Backup Before keytocard¶

Before moving subkeys to a Nitrokey, run the backup procedure again.

This protects against mistakes during the keytocard step.

Move Subkeys to Nitrokey¶

Initialize the Nitrokey according to Nitrokey Setup Notes.

Then move each selected subkey to the card:

gpg --edit-key <ARTIFACT-ROOT-FPR>

Inside the editor, select the subkey and run:

key <N>
keytocard

Choose the matching card slot:

signature key slot for signing subkeys;
authentication key slot for authentication subkeys;
encryption key slot for encryption subkeys.

During keytocard, the operator will normally be prompted for:

the root GPG key passphrase;
the Nitrokey User PIN.

For the Shyft provisioning workstation, the local ~/.gnupg directory is the offline primary copy. Do not rely on the Nitrokey as the only copy of the subkey. Preserve the workstation state and ceremony backup according to policy.

Important¶

After transferring the signing subkey to the hardware token using keytocard, exit the GnuPG editor without saving.

Saving the modified key removes the local copy of the transferred subkey from the provisioning workstation.

The provisioning workstation intentionally retains the offline recovery copy of every artifact signing subkey.

Verify the Token¶

Verify card status:

gpg --card-status

Verify signing:

echo "test" > test.txt
gpg --detach-sign test.txt
gpg --verify test.txt.sig test.txt

Verify SSH public key export for authentication subkeys:

gpg --export-ssh-key <AUTH-SUBKEY-FPR>

Publish Updated Public Key Bundle¶

Whenever the set of authorized artifact signing subkeys changes, the published Shyft public key bundle shall be regenerated.

This includes:

addition of a new signing subkey;
revocation of a signing subkey;
expiration replacement of a signing subkey.

Example:

gpg –armor –export <SHYFT-ROOT-FPR> > shyft-release-sign-YYYY-MM-DD.pub

The exported public key retains the same Shyft certification key fingerprint.

Only the certified operational signing subkeys change.

Downstream users should replace their local copy of the published Shyft public key bundle whenever a new version is announced.

Operational Signing Key Rotation¶

Purpose¶

Operational signing keys have a shorter lifetime than the Shyft root certification key.

Periodic replacement limits the operational lifetime of signing credentials while preserving a stable trust anchor.

Rotation Procedure¶

A rotation ceremony consists of:

generating a new signing subkey;
transferring the subkey to a hardware token;
verifying signing operations;
certifying the new signing subkey using the Shyft root certification key;
exporting the updated Shyft public key bundle;
publishing the updated public key bundle;
announcing the new signing key to downstream users.

After an appropriate transition period, expired or replaced signing subkeys may be revoked using the Shyft root certification key.

The updated public key bundle shall be published whenever the set of authorized operational signing keys changes.

Emergency Rotation¶

If a signing key is suspected to be compromised, the corresponding subkey shall be revoked immediately using the Shyft root certification key.

A replacement signing subkey shall then be generated, certified, transferred to a hardware token, and published as part of an updated Shyft public key bundle.

The Shyft root certification key remains unchanged during operational signing key replacement.

Revoke an Operational Signing Key¶

Operational signing keys may be revoked before their scheduled expiration if they are suspected to be compromised, lost, or no longer authorized for use.

The Shyft root certification key is used to issue the revocation.

On the provisioning workstation:

gpg --local-user <SHYFT-ROOT-FPR> \
    --edit-key <SHYFT-ROOT-FPR>

Within the GnuPG editor:

key <N>
revkey
save

The revocation becomes part of the Shyft public key.

After revocation, export the updated public key bundle:

gpg --armor --export <SHYFT-ROOT-FPR> \
    > shyft-release-YYYY-MM-DD.pub

Publish the updated public key bundle and announce the signing key revocation to downstream users.

Consumers should import the updated Shyft public key bundle before accepting future releases.

The fingerprint of the published shyft-release.pub remains unchanged, only the certified subkeys and their revocation status changes.

Developer Identity Keys in Daily Use¶

Purpose¶

This section describes the recommended operational use of developer identity keys during daily software development.

Unlike the Shyft release signing infrastructure, these operations are performed on the developer’s normal workstation using hardware-backed signing and authentication keys.

Developer identity keys provide authenticity and accountability for the Shyft source history. They do not authorize official Shyft releases. Official release artifacts are signed separately using dedicated Shyft artifact signing keys.

Developer identity keys are used for:

Git commit signing;
Git tag signing;
SSH authentication to project Git services.

Shyft recommends that both Git signing keys and SSH authentication keys are hardware-backed. For SSH authentication, this means that remote Git operations require possession of the hardware token and, when configured, knowledge of the user PIN.

GPG Agent Configuration¶

Enable SSH support in gpg-agent:

mkdir -p ~/.gnupg
chmod 700 ~/.gnupg
echo "enable-ssh-support" >> ~/.gnupg/gpg-agent.conf
gpgconf --kill gpg-agent

The gpg-agent process will be restarted automatically when next needed.

Shell Configuration¶

The shell must direct both GnuPG and OpenSSH to the correct agent sockets.

For Bash, append the following to ~/.bashrc:

# Interactive shells only.
[[ $- != *i* ]] && return

export GPG_TTY="$(tty)"
gpg-connect-agent updatestartuptty /bye >/dev/null

unset SSH_AGENT_PID

if [ "${gnupg_SSH_AUTH_SOCK_by:-0}" -ne "$$" ]; then
    export SSH_AUTH_SOCK="$(gpgconf --list-dirs agent-ssh-socket)"
fi

GPG_TTY allows GnuPG and pinentry to ask for the hardware-token PIN from the active terminal.

SSH_AUTH_SOCK directs OpenSSH to use gpg-agent instead of the standard ssh-agent. This allows SSH authentication to use the hardware-backed authentication subkey.

Open a new shell after changing ~/.bashrc.

Verify Hardware Token Access¶

Insert the Nitrokey or compatible OpenPGP hardware token and verify that GnuPG can see it:

gpg --card-status

Verify that the developer identity key and subkeys are visible:

gpg --list-secret-keys --with-subkey-fingerprint

The output should show the public identity and available secret subkeys. For hardware-backed keys, GnuPG typically shows that the private subkey material is stored on a card.

Git Signing¶

Git commit and tag signing provide cryptographic provenance for the Shyft source history.

Configure Git to sign commits and tags using the developer signing subkey.

Global configuration:

git config --global user.signingkey <SIGNING-SUBKEY-FPR>
git config --global commit.gpgsign true
git config --global tag.gpgsign true

Repository-local configuration:

cd shyft
git config user.signingkey <SIGNING-SUBKEY-FPR>
git config commit.gpgsign true
git config tag.gpgsign true

Use repository-local configuration when the same development machine is used with several Git identities.

Create a signed test commit in a temporary repository if needed:

mkdir -p /tmp/shyft-gpg-test
cd /tmp/shyft-gpg-test
git init
git config user.signingkey <SIGNING-SUBKEY-FPR>
git config commit.gpgsign true
echo test > test.txt
git add test.txt
git commit -m "test signed commit"

Verify the signature:

git log --show-signature -1

Signed Tags¶

Create a signed tag:

git tag -s test-signed-tag -m "test signed tag"

Verify the signed tag:

git tag --verify test-signed-tag

Remove the test tag when finished:

git tag -d test-signed-tag

SSH Authentication with GPG Agent¶

Shyft recommends hardware-backed SSH authentication for project Git services. The SSH authentication key should reside on a hardware token such as a Nitrokey.

Export the SSH public key from the authentication subkey:

gpg --export-ssh-key <AUTH-SUBKEY-FPR>

A minimal SSH configuration for GitLab may look like this:

Host shyft-git
    HostName gitlab.com
    User git

Verify that OpenSSH can see the key exposed by gpg-agent:

echo "$SSH_AUTH_SOCK"
ssh-add -L

The listed SSH public key should match the key exported with gpg --export-ssh-key.

Verify GitLab authentication:

ssh -T git@gitlab.com

If a host alias is used:

ssh -T shyft-git

The first authentication attempt should prompt for the hardware-token PIN if the PIN is not already cached by gpg-agent.

Recommended Hardware Configuration¶

Where supported by the hardware token, Shyft recommends requiring explicit user presence for signing and authentication operations.

Depending on the token and firmware, this may be implemented as:

PIN entry;
touch confirmation;
vendor-specific confirmation policy;
OpenPGP card signature PIN enforcement.

The exact configuration depends on the selected hardware token. The important security property is that private key use should require interaction with the hardware token and should not be silently available to software running on the developer workstation.

Verification Checklist¶

Before relying on a developer identity key for Shyft work, verify that:

gpg --card-status detects the hardware token;
gpg --list-secret-keys --with-subkey-fingerprint shows the expected signing and authentication subkeys;
Git can create a signed commit;
git log --show-signature verifies the commit signature;
Git can create and verify a signed tag;
ssh-add -L shows the hardware-backed SSH authentication key;
ssh -T git@gitlab.com or the configured Git host succeeds.

Troubleshooting¶

If Git signing fails, verify that the hardware token is inserted and visible:

gpg --card-status
gpg --list-secret-keys --with-subkey-fingerprint

Restart GnuPG components:

gpgconf --kill all
gpgconf --launch gpg-agent

If pinentry appears in the wrong terminal, refresh the startup TTY:

export GPG_TTY="$(tty)"
gpg-connect-agent updatestartuptty /bye >/dev/null

If SSH authentication does not use the hardware-backed key, verify that SSH_AUTH_SOCK points to the GnuPG SSH socket:

echo "$SSH_AUTH_SOCK"
gpgconf --list-dirs agent-ssh-socket
ssh-add -L

If another SSH agent is still active, unset SSH_AGENT_PID and reload the shell configuration:

unset SSH_AGENT_PID
source ~/.bashrc

If the key does not appear in ssh-add -L, verify that the authentication subkey exists and that SSH support is enabled in ~/.gnupg/gpg-agent.conf.

Source Trust and Release Trust¶

Developer identity keys establish trust in the source history.

They do not sign official Shyft release artifacts and are not certified by the Shyft root certification key as release-authorizing identities.

Official Shyft release artifacts are signed by dedicated organizational artifact signing keys using the release procedures described elsewhere in this chapter.

Package Manager Trust¶

Package managers such as RPM and pacman verify package signatures against the public keys in their local trust database.

They do not evaluate the OpenPGP certification chain or establish trust in the publisher. That trust must be established before the public key is imported into the package manager.

Consumer Trust Bootstrap¶

Before importing the Shyft release key into a package manager, the consumer should:

Obtain the current shyft-release.pub public key bundle.
Verify the fingerprint of the Shyft root certification key using an independent trusted source.
Verify that the published public key bundle contains the expected certified operational signing subkeys.
Import the verified public key bundle into the package manager.

After this one-time trust establishment, package managers automatically verify the signatures on all subsequently installed packages.

Example Verification¶

Inspect the public key bundle:

gpg --import shyft-release.pub
gpg --list-keys --with-subkey-fingerprint
gpg --check-sigs

The output should show:

the expected Shyft root certification key fingerprint;
the currently authorized operational signing subkeys;
any revoked operational signing subkeys.

Import into RPM:

sudo rpm --import shyft-release.pub

Import into pacman:

sudo pacman-key --add shyft-release.pub
sudo pacman-key --lsign-key <SHYFT-ROOT-FPR>

Operational Signing Key Updates¶

The Shyft root certification key is intended to remain stable over its lifetime.

Operational signing subkeys may be added, rotated, or revoked without changing the Shyft root certification key.

Whenever Shyft announces an updated shyft-release.pub bundle, downstream users should import the updated bundle before installing newly signed releases.

Updating the public key bundle extends the set of trusted operational signing keys while preserving the original Shyft trust anchor.

Recovery and Key Rotation¶

Operational Signing Token Loss¶

Loss of a hardware token does not necessarily imply compromise of the corresponding operational signing key. However, the key shall be considered unavailable until its status has been determined.

If recovery cannot be assured, the organization shall:

cease using the affected signing key;
provision a replacement hardware token;
generate a replacement operational signing subkey;
certify the new signing subkey using the organization’s root certification key;
publish an updated shyft-release.pub bundle;
announce the signing key transition to downstream users.

The organization root certification key remains unchanged.

Compromised Operational Signing Key¶

If an operational signing key is believed to be compromised, the organization shall:

cease signing immediately;
revoke the affected signing subkey;
generate and certify a replacement signing subkey;
publish an updated shyft-release.pub bundle;
announce the revocation and replacement.

The organization root certification key remains unchanged.

Compromised Root Certification Key¶

Compromise of the organization root certification key is a high-severity event.

The organization shall:

publish the root key revocation certificate;
establish a new root certification key;
generate new operational signing keys;
certify the new operational signing keys;
publish a new shyft-release.pub bundle;
publish a trust transition statement;
update release documentation accordingly.

Such an event is expected to be exceptionally rare.

Backup Recovery¶

The certification infrastructure depends upon verified offline backups.

If the provisioning workstation is lost due to hardware failure, theft, fire, or other catastrophic event, recovery is performed by restoring the verified offline backup onto a replacement provisioning workstation.

Every backup shall be verified by restoration before it is considered suitable for disaster recovery.

Loss of Recoverability¶

Loss of recoverability is distinct from compromise.

If backup media become unreadable or cryptographic recovery material is lost, availability of the certification infrastructure may be affected even though the confidentiality of the key material remains intact.

Such events should be documented accurately without implying disclosure unless there is evidence that secret key material has been exposed.

Relationship to the Release Process¶

This document defines:

the organizational trust model;
the certification infrastructure;
operational signing key management;
developer identity key management;
consumer trust establishment.

The release procedure references this document when performing release signing, operational signing key rotation, trust verification, and publication of updated public key bundles.

Release documentation remains responsible for release approval, artifact production, testing, versioning, and publication.

References¶

The Shyft key management model follows established security principles for offline certification authorities, hardware-backed cryptographic keys, software release signing, and software supply-chain provenance.

This document intentionally focuses on practical operational procedures. General background information and external references are provided elsewhere in the Shyft security documentation.