This post describes the steps needed to set up signature verification on a git-based non-official Gentoo ebuild repository.

Overview #

The path from source code to installed software on Gentoo is described on the following diagram:

For example, the operator of the local machine would like to install newsboat.

First(1), the machine needs to fetch a version of Gentoo ebuild repository which will contain the ebuild for newsboat. Ebuilds (wiki) are small text files containing instructions for the Gentoo package manager(portage) to:

1. Where to download the source code from
2. How to unpack it
3. How to install it
4. Which other dependencies to install

When portage executes instructions from the ebuild, it (2) fetches the source code from URL specified in the ebuild file and (3) compiles and installs them on the local system.

What is being verified #

The operator of the local machine has little influence on the processes involving producing and publishing the code – both the code of the software and the ebuilds being put in Gentoo repository. These processes are set up and controlled by the corresponding projects. When publishing the code for public consumption, projects will sign the release with a key, which signals that all processes followed before the publishing (committing, testing, etc.) were followed.

The operator can verify that the code that is published is indeed signed by the corresponding parties. It is important to note, that this verification only checks the authorship of the code fetched by portage, not that the code itself is correct or bug-free.

Generally the verification of code follows the “Marking and verifying signatures” process from gnupg.org. However, portage has additional features that can check the key against public keyservers before verification to make sure that the key has not been revoked or expired.

Verifying Gentoo repository #

When setting up a repository in Gentoo, the operator can specify a set of values outlined on the Gentoo wiki page. Depending on the exact mechanism through which the repository is being fetched (rsync, git, snapshots) there are different ways to set up the key verification. Those ways are outlined on “Repository verification page” (link).

Verifying the source code #

To provide an overview of how portage verifies the downloaded source code, first a quick look into how portage works.

When installing software, portage follows a set of phases. Those phases are effectively implemented as a set of bash functions that are called in specific order. Portage also has the concept of eclasses, which provide a way to augment the default portage functionality by writing own functions, which can be invoked (explicitly or implicitly) in those phase functions.

Gentoo default repository has a special eclass called “verify-sig”, which allows portage to verify the signature of the software code at the point when it is being installed. It typically happens in src_unpack:

Verify-sig is intended to work with software code that follows some model of versioning or releases¹ and typically adds a dependency on the public key which is packaged separately.

Non-official Gentoo overlay verification #

TL;DR #

To set up the verification of an overlay you own and publish as git repo you need:

• Signing key with the email on a domain you own
• Git commits should be signed by that key
• Key is published on WKD on the same domain

Background #

Gentoo allows to add custom ebuild repositories to provide ebuilds for additional packages not found in the main repo. Such repositories are typically called overlays. An overlay may be added either from official list of overlays through eselect-repository or by creating a separate file or entry in /etc/portage/repos.conf (depending on whether repos.conf is a file or a directory).

It is important to note, that the overlays added through eselect repository command may be retrieved from gentoo-mirror set of repositories. The commits in those mirrors are done automatically and not signed.

Repository configuration #

When registering an overlay locally, it is possible to specify a set of parameters that will tell portage how exactly to fetch this overlay. For example, if you do not care for the whole history of the repository, you can set clone-depth = 0, which will tell portage to get only the newest commit of an overlay published as a git repo. The full list of parameters is available in man 5 portage.

To set up the verification of git repository, two parameters are important:

• sync-git-verify-commit-signature – when set to “yes”, tells portage that it should verify the signature on the checked out commit of the overlay
• sync-openpgp-key-path – portage will use the public key in this location to verify the overlay

Verification process #

When the parameters above are set, portage will:

• Pull the overlay repository
• Create a gpg sandbox using gemato and import the key from sync-openpgp-key-path
• Gemato will try to check that key for revocation using web key directory (WKD)
• If the key is verified, overlay commit signature is checked against the key

WKD #

The domain used for WKD is the same as the one specified in emails in key file. In case of the official Gentoo repository, the repository is signed by Gentoo release key and checked against Gentoo WKD available on gentoo.org.

For a non-official overlay, it is necessary to have control over content that is hosted on the domain in the email. The exact setup procedure depends on the web server, but the general information is outlined in [WKDHosting article](https://wiki.gnupg.org/WKDHosting on gnupg.org).

Example #

An example of such verification is provided in my nitratesky overlay. The key itself is published in WKD on vtimofeenko.com