VERIFY-SIG.ECLASS

Section: eclass-manpages (5)
Updated: Nov 2024
Index Return to Main Contents

NAME

verify-sig.eclass - Eclass to verify upstream signatures on distfiles

DESCRIPTION

verify-sig eclass provides a streamlined approach to verifying upstream signatures on distfiles. Its primary purpose is to permit developers to easily verify signatures while bumping packages. The eclass removes the risk of developer forgetting to perform the verification, or performing it incorrectly, e.g. due to additional keys in the local keyring. It also permits users to verify the developer's work.

To use the eclass, start by packaging the upstream's key as sec-keys/openpgp-keys-*. Then inherit the eclass, add detached signatures to SRC_URI and set VERIFY_SIG_OPENPGP_KEY_PATH. The eclass provides verify-sig USE flag to toggle the verification.

If you need to use signify, you may want to copy distfiles into WORKDIR to work around "Too many levels of symbolic links" error.

A more complete guide can be found at: https://mgorny.pl/articles/verify-sig-by-example.html

SUPPORTED EAPIS

7 8

EXAMPLE

Example use:

inherit verify-sig

SRC_URI="https://example.org/${P}.tar.gz
  verify-sig? ( https://example.org/${P}.tar.gz.sig )"
BDEPEND="
  verify-sig? ( sec-keys/openpgp-keys-example )"

VERIFY_SIG_OPENPGP_KEY_PATH=/usr/share/openpgp-keys/example.asc

FUNCTIONS

verify-sig_verify_detached <file> <sig-file> [<key-file>]

Read the detached signature from <sig-file> and verify <file> against it. <key-file> can either be passed directly, or it defaults to VERIFY_SIG_OPENPGP_KEY_PATH. The function dies if verification fails.

verify-sig_verify_message <file> <output-file> [<key-file>]

Verify that the file ('-' for stdin) contains a valid, signed PGP message and write the message into <output-file> ('-' for stdout). <key-file> can either be passed directly, or it defaults to VERIFY_SIG_OPENPGP_KEY_PATH. The function dies if verification fails. Note that using output from <output-file> is important as it prevents the injection of unsigned data.

verify-sig_verify_unsigned_checksums <checksum-file> <format> <files>

Verify the checksums for all files listed in the space-separated list <files> (akin to ${A}) using a <checksum-file>. <format> specifies the checksum file format. <checksum-file> can be "-" for stdin.

The following formats are supported:
- sha256 -- sha256sum (<hash> <filename>)
- openssl-dgst -- openssl dgst (<algo>(<filename>)=<hash>)

The function dies if one of the files does not match checksums or is missing from the checksum file.

Note that this function itself can only verify integrity of the files. In order to verify their authenticity, the <checksum-file> must be verified against a signature first, e.g. using verify-sig_verify_detached. If it contains inline signature, use verify-sig_verify_signed_checksums instead.

verify-sig_verify_signed_checksums <checksum-file> <algo> <files> [<key-file>]

Verify the checksums for all files listed in the space-separated list <files> (akin to ${A}) using a signed <checksum-file>. <algo> specifies the checksum algorithm (e.g. sha256). <key-file> can either be passed directly, or it defaults to VERIFY_SIG_OPENPGP_KEY_PATH.

The function dies if signature verification fails, the checksum file contains unsigned data, one of the files do not match checksums or are missing from the checksum file.

verify-sig_src_unpack

Default src_unpack override that verifies signatures for all distfiles if 'verify-sig' flag is enabled. The function dies if any of the signatures fails to verify or if any distfiles are not signed. Please write src_unpack() yourself if you need to perform partial verification.

ECLASS VARIABLES

VERIFY_SIG_METHOD ?= openpgp (SET BEFORE INHERIT)

Signature verification method to use. The allowed value are:

- minisig -- verify signatures with (base64) Ed25519 public key using app-crypt/minisign
- openpgp -- verify PGP signatures using app-crypt/gnupg (the default)
- sigstore -- verify signatures using dev-python/sigstore
- signify -- verify signatures with Ed25519 public key using app-crypt/signify

VERIFY_SIG_OPENPGP_KEY_PATH

Path to key bundle used to perform the verification. This is required when using default src_unpack. Alternatively, the key path can be passed directly to the verification functions.

The value of BROOT will be prepended to this path automatically.

This variable is also used for non-OpenPGP signatures. The name contains "OPENPGP" for historical reasons. It is not used for sigstore, since it uses a single trusted root.

VERIFY_SIG_CERT_IDENTITY

--cert-identity passed to sigstore invocation.

VERIFY_SIG_CERT_OIDC_ISSUER

--cert-oidc-issuer passed to sigstore invocation.

VERIFY_SIG_OPENPGP_KEYSERVER

Keyserver used to refresh keys. If not specified, the keyserver preference from the key will be respected. If no preference is specified by the key, the GnuPG default will be used.

Supported for OpenPGP only.

VERIFY_SIG_OPENPGP_KEY_REFRESH ?= no (USER VARIABLE)

Attempt to refresh keys via WKD/keyserver. Set it to "yes" in make.conf to enable. Note that this requires working Internet connection.

Supported for OpenPGP and sigstore.

MAINTAINERS

Michał Górny <[email protected]>

REPORTING BUGS

Please report bugs via https://bugs.gentoo.org/

FILES

verify-sig.eclass

This document was created by man2html, using the manual pages.
Time: 03:27:00 GMT, November 25, 2024