Abstract:

This document details the various methods employed by Gentoo to ensure the authenticity and integrity of its ebuild repository. It compares three primary verification mechanisms: git commit signing, signed snapshot tarballs (used by webrsync), and recursive signed Manifests (used by rsync). A common foundation for these methods is the use of OpenPGP keys, managed through the sec-keys/openpgp-keys-gentoo-release package, which requires regular updates. The document explains how each method works, its security coverage, and the necessary Portage configurations. It also addresses frequently asked questions regarding default verification status, implementation details, and using these verification techniques with custom or private repositories.

Gentoo Ebuild Repository Verification Methods

• Security comparison:

  • This section presents a table comparing rsync, git, and snapshots (webrsync) methods based on features like full tree verification, OpenPGP verification, out-of-the-box functionality, key refresh for revocation, and exclusion/replay attack detection, along with minimum required Portage versions.
  • Key Takeaway: Different methods offer varying levels of security features, with newer Portage versions generally providing more robust verification.

• Common bits:

  • OpenPGP key propagation:
    • Authenticity relies on an up-to-date Infrastructure OpenPGP public key, distributed via the sec-keys/openpgp-keys-gentoo-release package.
    • Keys have a yearly expiration, requiring users to sync and upgrade the package.
    • Important Detail: Initial bootstrapping requires verifying the Gentoo repository snapshot against signatures found on the Gentoo homepage (secure connection and server signature must be verified).
    • Key Takeaway: Maintaining up-to-date OpenPGP keys is crucial for all verification methods.

• git:

  • Using it:
    • Controlled by sync-git-verify-commit-signature = yes in repos.conf.
    • Recommended Option: Use a "sync" or "metadata" repository (e.g., https://github.com/gentoo-mirror/gentoo) which requires no extra action beyond setting the sync-uri. Commits are signed after CI passes.
    • Not Recommended Option: Using the main git repository (e.g., https://anongit.gentoo.org/git/repo/gentoo.git) requires manual steps like GLSA/news retrieval, running egencache, and importing developer keys.
  • How does it work?:
    • For sync/metadata repos: Portage verifies the latest CI-signed commit against /usr/share/openpgp-keys/gentoo-release.asc.
    • For regular git repos: Portage verifies the latest developer-signed commit against /usr/share/openpgp-keys/gentoo-developers.asc.
  • Security coverage:
    • The entire git repository is covered.
    • Key Takeaway: git verification checks commit signatures, ensuring the history and current state of the repository are authentic, with the sync/metadata repository being the user-friendlier option.

• Signed snapshot tarballs (webrsync):

  • Using it:
    • Default in stage3s. Controlled by sync-webrsync-verify-signature = yes in repos.conf.
  • How does it work?:
    • Snapshot tarballs come with detached OpenPGP signatures.
    • Portage automatically verifies the whole snapshot before unpacking.
    • Tooling ensures stray files not in the tarball are removed if unpacking over an existing repository.
  • Security coverage:
    • The entire snapshot file, and thus all files within it, are covered by the OpenPGP signature.
    • Key Takeaway: webrsync verifies a complete snapshot at a point in time, ensuring all its contents are authentic.

• Recursive signed Manifests (rsync):

  • How does it work?:
    • Verification starts at the top-level Manifest file in the repository's root.
    • This top-level Manifest must have a valid OpenPGP signature.
    • If the signature is valid, the Manifest tree is read recursively.
    • Each Manifest file contains checksums for other data files or Manifest files, which are verified before use.
    • Tooling also checks for stray files not listed in any Manifest.
  • Security coverage:
    • The top-level Manifest is directly covered by an OpenPGP signature.
    • All other files are indirectly covered by this signature through a chain of checksums in Manifest files.
    • Key Takeaway: rsync with signed Manifests provides granular, hierarchical verification of the entire repository, rooted in a single top-level signature.

• Q & A:

  • Default Verification: Yes, stage3s include necessary keys, and Portage is pre-configured to verify syncs via emerge-webrsync and emerge --sync. No user action is required by default.
  • Portage Implementation: Verification is currently done by calling app-portage/gemato after syncing; on-the-fly verification will eventually be integrated directly.
  • Repository Signing Detection: Currently, verification for the Gentoo repository is enabled by default in repos.conf as there's no standard way to detect if a repository should be signed.
  • Custom Repositories:
    • Users can create signed full-tree Manifests using app-portage/gemato.
    • To enable verification for a custom repo, users must set sync-rsync-verify-metamanifest = yes in repos.conf and fetch the appropriate OpenPGP keys.
  • Local/Private rsync Mirrors: Verification works if the mirror propagates the unmodified rsync tree. Manifests ignore changes to metadata/timestamp* files and the presence of distfiles, local, and packages directories.
  • Modified Private Mirrors: Verification can be disabled (USE=-rsync-verify or sync-rsync-verify-metamanifest = no) or custom signatures can be provided (a more complex process involving gemato and sync-openpgp-key-path).
  • Key Takeaway: Gentoo aims for secure-by-default repository syncing, with tools and configurations available for users with custom setups or private mirrors.