Package Verification
====================

Users can independently verify Shyft release artifacts before installing
them. Verification ensures that the packages:

* originate from the Shyft release signing authority
* have not been modified after signing
* correspond to the provenance metadata distributed with the release

The verification model used by Shyft is intentionally **distribution-neutral**.

Users may apply the same verification principles regardless of the Linux
distribution or packaging system they use.

The verification process relies on the Shyft OpenPGP signing key.
See :doc:`signing-keys` and :doc:`../security/index` for details about
key management and the underlying trust model.


General Verification Procedure
------------------------------

The verification process consists of four steps:

1. Import the Shyft release public key
2. Verify the provenance document
3. Verify package signatures using the native package tools of the distribution
4. Optionally verify SHA256 checksums recorded in the provenance document

These steps establish a verifiable chain of trust from the Shyft signing key
to the installed artifacts.


Import the Release Signing Key
------------------------------

Import the Shyft release key:

::

    gpg --import shyft-release-key.asc

Verify the key fingerprint:

::

    gpg --fingerprint

The fingerprint MUST match one of the keys listed in:

:doc:`signing-keys`

Users should verify this fingerprint through an independent channel before
trusting the key.


Verify the Provenance Document
------------------------------

Verify the signature of the provenance document:

::

    gpg --verify PROVENANCE.txt.asc PROVENANCE.txt

If verification succeeds, GPG will report a valid signature from the Shyft
release key.

The provenance document records metadata about the release, including:

* The source revision from which the artifacts were built
* The build procedure and environment
* Cryptographic hashes of the release artifacts

This allows users to trace the released packages back to their source and
verify the integrity of the complete build and release process.


Distribution-Specific Package Verification
------------------------------------------

After verifying the provenance document, the package signatures can be
verified using the native package tools provided by the distribution.


RPM-Based Distributions (Fedora, RHEL, Rocky, AlmaLinux)
--------------------------------------------------------

Import the release key into the RPM key database:

::

    rpm --import shyft-release-key.asc

Verify the packages:

::

    rpm -Kv *.rpm

A valid package will produce output similar to:

::

    Header OpenPGP signature: OK
    Header SHA256 digest: OK
    Payload SHA256 digest: OK

This confirms that the package header and payload match the signature
created by the Shyft release key.


Pacman-Based Distributions (Arch Linux)
---------------------------------------

Shyft also distributes native Arch Linux packages.

Arch Linux verifies package signatures using the pacman keyring.

First add the Shyft release key to the pacman keyring:

::

    sudo pacman-key --add shyft-release-key.asc

Locally sign the key:

::

    FPR_KEY=$(gpg --with-colons --show-keys shyft-release-key.asc | awk -F: '/^fpr:/ { print $10; exit }')
    sudo pacman-key --lsign-key "$FPR_KEY"

You can now verify package signatures during installation:

::

    pacman -U shyft-*.pkg.tar.zst

Pacman will automatically verify the package signature against the trusted
keyring before installation.


Optional Checksum Verification
------------------------------

The provenance file records cryptographic checksums for the release artifacts.

Users may verify these checksums independently:

::

    sha256sum *

The resulting hashes should match the values recorded in ``PROVENANCE.txt``.


Trust Chain Summary
-------------------

The Shyft verification model establishes the following trust chain:

::

    Shyft maintainer identity
        ↓
    OpenPGP signing key (verified fingerprint)
        ↓
    Signed provenance document
        ↓
    Signed package artifacts
        ↓
    Installed software

Each step is independently verifiable.


Why Multiple Verification Steps?
--------------------------------

Each verification step provides a different security guarantee.

* **GPG verification of PROVENANCE.txt**
  confirms the authenticity of the release metadata.

* **Package signature verification**
  confirms that the package contents match the signed release artifacts.

* **Checksum verification**
  confirms that the downloaded files match the provenance record.

Together, these steps link the installed artifacts back to the source
revision, build environment, and release process from which they were produced.


Operational Use
---------------

Operators deploying Shyft in security-sensitive environments may:

* Integrate verification into automated deployment pipelines
* Enforce signature verification in package managers
* Mirror verified artifacts into internal repositories
* Record verification results for audit purposes