Portage Security

Ensuring the security of your portage tree

This page aims to answer the question "How can I dispel doubts regarding the security of the portage tree on my system?", that is, to ensure that the portage tree is entirely composed of code written by or reviewed by Gentoo developers.

This question is answered differently whether you use webrsync, rsync, git-mirror or canonical git repos directly.

Note
systemd-resolved from systemd before version 239 causes gpg keyserver refresh failures https://github.com/systemd/systemd/issues/8164

webrsync

Whenever you run emerge-webrsync with the appropriate settings, the downloaded tarball is always checked against gentoo release keys which are provided by app-crypt/gentoo-keys.

The only caveat is that this method doesn't do further checking after having unpacked the tarball so if your portage tree was compromised before the webrsync, it's possible that it's still compromised. If you're not sure about the state of your portage tree, wipe it out before doing emerge-webrsync.

What do I need to do?

You need to enable the webrsync-gpg feature as explained in the handbook

The public key used to verify signatures is provided by app-crypt/gentoo-keys. In the case it's not updated in a timely manner, you might want to manually update those keys, which you can do with:

root #gpg --homedir /var/lib/gentoo/gkeys/keyrings/gentoo/release --refresh-keys

How can I dispel doubt?

Seeing "Checking signature..." should be enough to dispel your doubts. You can also read the contents of `/usr/bin/emerge-webrsync` which is small enough to be easily audited.

If you're in hardcore mode, you'll have to set yourself a man-in-the-middle attack and check that verification fails.

What do I need to trust?

1. that the Gentoo's release keys haven't been compromised.
2. that the content on the file that SRC_URI point to in app-crypt/gentoo-keys is actually the Gentoo release keys
3. everything that is needed to trust in the "canonical git repos" method.

rsync

Portage 2.3.21+ supports recursive signed manifests checking. Project:Portage/Repository Verification explains how it works.

What do I need to do?

1. Ensure that portage has the rsync-verify flag
2. Make sure that you see stuff like "Using keys from ..." and "Valid OpenPGP signature found" when you do "emerge --sync"
3. Never miss errors during --sync. portage will not prevent you from running on a repo that has failed verification. This is an issue that is being worked on, but the work isn't completed yet.

How can I dispel doubt?

Simulate malicious injection:

1. Change an ebuild
2. Run gemato verify -K /usr/share/openpgp-keys/gentoo-release.asc /usr/portage
3. You should get a manifest mismatch error
4. Go a step further and update the manifest with "ebuild foobar-1.2.3.ebuild manifest"
5. Run gemato verify -K /usr/share/openpgp-keys/gentoo-release.asc /usr/portage
6. You will get a mismatch error
7. You can confirm that gemato saved you from doom by running "ebuild foobar-1.2.3.ebuild unpack". With the corrupted manifest being consistent with the corrupted ebuild, unpack will proceed unhindered. gemato saved you!

What do I need to trust?

Same thing as with webrsync. With repository verification, the integrity of rsync mirrors aren't an issue anymore so it's not less secure than webrsync.

git-mirror repo

The gentoo git mirror is a git repo that delivers the equivalent of the rsync method, that is, the content of the canonical git repo but with dtd, glsa, news, xml-schema informations attached and an up to date portage cache generated.

Every commit is signed by either the developer or the "repomirrorci@gentoo.org" PGP key, so you can ensure integrity through the recent sync-git-verify-commit-signature repo option.

What do I need to do?

1. Install app-crypt/openpgp-keys-gentoo-release.
2. Add gentoo-mirror repo to your repos.conf
3. enable the sync-git-verify-commit-signature option

How can I dispel doubt?

1. Make yourself a local clone of the mirror
2. Set your sync-uri to your local clone
3. Add a commit on top of it
4. emerge --sync should balk at you

What do I need to trust?

1. The integrity of the "repomirrorci@gentoo.org" PGP key.
2. The CI server isn't compromised (which would compromise the key).
3. everything that is needed to trust in the "canonical git repos" method.

canonical git repo

All methods above take their content from the same source: The canonical portage tree repo. Every commit in this repo is required so be signed by developers using PGP keys listed in Gentoo's LDAP. Those keys are listed in the Current Gentoo developers page.

Why don't we all use this instead of the methods above? Because this repo doesn't contain everything it needs to be fully functional. It needs to be augmented with data repos and a portage cache needs to be regenerated at each update (which can take a little while).

Despite this method being more hassle, it has the advantage of having a different trust model: you don't need to trust release keys and infra anymore (for portage tree updates). You directly trust developers and the strength of their PGP web of trust.

What do I need to do?

Follow instructions from Gentoo ebuild tree from scratch

What do I need to trust?

1. That the web of trust of Gentoo developers is strong.
2. That Gentoo developers have good practices regarding the security of their private PGP key.

The great thing about this trust model is that it doesn't rely on infrastructure integrity. Sure, a developer's key can be compromised but it's something that can easily be spotted (especially by the compromised developer. "hey! that commit isn't mine!") and integrity and trust is easy to bring back (review all recent commits by this developer and remove malicious ones). There is no single point of failure.

How can I dispel doubt?

Because this method requires that you set up your own verification processes, there shouldn't be much doubt left once you're done.