Project:Portage/Repository verification
This page describes different methods used to ensure authenticity of the Gentoo ebuild repository.
Security comparison
| Feature | Present? (min. Portage version) | ||
|---|---|---|---|
| rsync | git | snapshots | |
| Full tree verification | Yes (2.3.21+) | Yes (2.3.25+) | Yes |
| Proper OpenPGP verification | Yes (2.3.21+) | Yes (2.3.25+) | Yes (2.3.22+) |
| Works out of the box? | Yes (2.3.21+) | Yes (2.3.25+) | Yes (3.0.47+) |
| Refreshes key to detect revocation | Yes (2.3.21+) | Yes (2.3.25+) | Yes (3.0.47+) |
| Exclusion/replay attack detection | Yes (2.3.25+) | No | No |
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 sec-keys/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!).
git
Using it
Controlled by the sync-git-verify-commit-signature = yes setting in repos.conf.
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
sync-uri = https://github.com/gentoo-mirror/gentoo.gitin repos.conf. - Usually 20-30 minutes behind as CI runs on every commit.
- No action required other than setting
- 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 egencache or pmaint regen after each repo sync.
- Importing Gentoo developer keys for verification (can use sec-keys/openpgp-keys-gentoo-developers if desired)
How does it work?
For the sync/metadata repository: Portage verifies the latest commit, which will be signed automatically (not by a developer) once CI has passed, against /usr/share/openpgp-keys/gentoo-release.asc provided by sec-keys/openpgp-keys-gentoo-release.
For the regular git repository: Portage verifies the latest commit, which will be signed by a dveloper, against /usr/share/openpgp-keys/gentoo-developers.asc provided by sec-keys/openpgp-keys-gentoo-developers.
Security coverage
The whole git repository is covered.
Signed snapshot tarballs (webrsync)
Using it
Portage is configured to do this by default in stage3s. It's controlled by the sync-webrsync-verify-signature = yes setting in repos.conf.
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.
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
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 emerge-webrsync and emerge --sync (including normal rsync mirrors and the daily rsync snapshots).
No action is required.
How is verification implemented in Portage?
- Portage currently verifies by calling app-portage/gemato 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 repos.conf.
Can I create signed full-tree Manifests in my own repository?
- Yes. Use the app-portage/gemato tool for this purpose.
Can I enable signature verification for my own repository?
- Yes, but users have to explicitly specify:
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 is 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, 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 (
USE=-rsync-verify) or by settingsync-rsync-verify-metamanifest = no. 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 gemato 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 repos.conf).