This is Gentoo's testing wiki. It is a non-operational environment and its textual content is outdated.
Please visit our production wiki at https://wiki.gentoo.org
Project:Portage/Repository Verification
This page describes differnet methods used to ensure authenticity of the Gentoo repository checkout.
Security comparison
| Feature | present? (min. Portage version) | ||
|---|---|---|---|
| rsync | git | snapshots | |
| full tree verification | Yes (2.3.21+) | patch in review | Yes |
| proper OpenPGP verification | Yes (2.3.21+) | patch in review | Yes (2.3.22+) |
| works out of the box? | Yes (2.3.21+) | TBD | requires manual setup |
| refreshes key to detect revocation | Yes (2.3.21+) | patch in review | No |
| exclusion/replay attack detection | patch in review | No | No |
Common bits
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 app-crypt/openpgp-keys-gentoo-release 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!).
Signed snapshot tarballs (webrsync)
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.
Recursive signed Manifests (rsync)
How does it work?
The verification starts at the top-level Manifest, that is a Manifest 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 app-portage/gemato 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 repos.conf.
Can I create signed full-tree Manifests in my own repository?
- You can use the app-portage/gemato tool for this purpose.
Can I enable signature verification for my own repository?
- Your users have to explicitly specify: FILE
repos.conf[myrepo] sync-rsync-verify-metamanifest = yes
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 metadata/timestamp* files and presence of distfiles, local and packages 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.