Project:Portage/Repository verification

This page describes differnet methods used to ensure authenticity of the Gentoo repository checkout.

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!).

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.

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
How is verification implemented in Portage?
 * The verification is currently done via calling after syncing. The support for on-the-fly verification will eventually be integrated into Portage.

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?
 * You can use the tool for this purpose.

Can I enable signature verification for my own repository?
 * Your 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's 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, your mirror can use them for its own purposes.

'''I am using a private rsync mirror with modified tree. What can I do?'''
 * You can disable the verification process by disabling USE=rsync-verify or by setting sync-rsync-verify-metamanifest = no. You could also look into providing your own signatures but this is a more complex process, and so it is not covered in this short guide.