Project:Portage/Repository verification

This page Article description::describes different methods used to ensure authenticity of the Gentoo ebuild repository.

Common bits
Please see Portage Security for more details than this page.

OpenPGP key propagation
In order for verification work correctly, the user has to have an up-to-date Infrastructure OpenPGP public key installed. Currently, this is done through the package. The key has a yearly expiration date, therefore the user needs to sync and upgrade the package before the previous key expires.

The key exchange process is therefore indirectly secured by a signature made using the previous key. To securely bootstrap the process, the user needs to verify the initial Gentoo repository snapshot against the included OpenPGP signature. The keys can be found on Release media signatures subpage of the Gentoo homepage (verify that the connection is secure and the server signature is good!).

Using it
Controlled by the  setting in.

Note that this requires using the correct repository: the main git repository has commits signed by each developer individually and this keyring is not (yet?) distributed to user machines.

There are two options:


 * Use a "sync" or "metadata" repository (https://anongit.gentoo.org/git/repo/sync/gentoo.git or identically https://github.com/gentoo-mirror/gentoo).
 * No action required other than setting  in.
 * Usually 20-30 minutes behind as CI runs on every commit.


 * Use the main git repository (https://anongit.gentoo.org/git/repo/gentoo.git) (not recommended!). This will require (see Gentoo ebuild tree from scratch):
 * Manual retrieval of GLSAs and news items.
 * Manually running or  after each repo sync.
 * Importing Gentoo developer keys for verification (can use if desired)

How does it work?
Portage verifies the latest commit, which will be signed automatically (not by a developer) once CI has passed, against provided by.

Security coverage
The whole git repository is covered.

Using it
Portage is configured to do this by default in stage3s. It's controlled by the  setting in.

How does it work?
The Gentoo repository snapshot tarballs come with detached OpenPGP signatures. Those signatures can be used to verify the whole snapshot before unpacking it, which occurs automatically, but users can do this manually if required.

If the tarball is unpacked on top of an existing repository, the tooling needs to ensure that stray files that are not present in the tarball are removed.

Security coverage
The whole snapshot file is covered by an OpenPGP signature, and therefore all files within it are.

How does it work?
The verification starts at the top-level Manifest, that is a file located in root directory of the ebuild repository. This file must contain a valid OpenPGP signature which is verified before any other file is read from the repository. If the signature passes verification, the Manifest tree is read recursively.

Each Manifest file specifies checksums for other data and/or Manifest files. The file is verified against those checksums before it can be used. The tooling also verifies that there are no stray files that are not listed in any of the Manifests but could influence the package manager behavior.

Security coverage
The top-level Manifest is covered by an OpenPGP signature. Every other file in the repository (including Manifests) is checked against a hash that is stored either in top-level Manifest or in other Manifest file. This means that indirectly every file is covered by the OpenPGP signature.

Q & A
By default, is the Gentoo repository verified?


 * Yes, by default, stage3s include the necessary OpenPGP keys, and Portage is pre-configured to verify syncs via both and  (including normal rsync mirrors, not just the daily rsync snapshots).

No action is required.

How is verification implemented in Portage?
 * Portage currently verifies by calling after syncing. The support for on-the-fly verification will eventually be integrated into Portage directly.

How does Portage know that the Gentoo repository is signed?
 * At this moment, we lack a proper way of determining whether we should expect a signed Manifest in a repository (how would we distinguish repository with no signed Manifest from repository where a malicious party removed it?). For this reason, we just enable verification for Gentoo in the default.

Can I create signed full-tree Manifests in my own repository?
 * Yes. Use the tool for this purpose.

Can I enable signature verification for my own repository?
 * Yes, but users have to explicitly specify:

They will also need to fetch the appropriate OpenPGP keys. We are going to look into providing a better solution.

'''I am using a local (private) rsync mirror. Will the verification work?'''
 * As long as it is propagating the unmodified rsync tree, it should work just fine. As a special case, the Manifests ignore changes to files and presence of, , and  directories. While we strongly discourage using them, the mirror can use them for its own purposes.

'''I am using a private rsync mirror with modified tree. What can I do?'''
 * The verification process can be halted by setting or by setting  . It is also possible to providing custom signatures but this is a more complex process, and so it is not covered in this short guide (it will involve using  as mentioned above for custom repositories to generate a new Metamanifest in the rsync tree, and referencing the new key for this specific repository in sync-openpgp-key-path in ).