Portage Security

= Ensuring the security of your portage tree =

WIP: this is a work in progress.

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.

webrsync
Whenever you run 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.

What do I need to do?
You need to enable the feature as explained in the handbook

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  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  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 repo option.

What do I need to do?

 * 1) Trust the "repomirrorci@gentoo.org" PGP key. It should be the key that the latest  commit is signed with at all times.
 * 2) Add gentoo-mirror repo to your repos.conf
 * 3) enable the  option

How can I dispel doubt?

 * 1) Make yourself a local clone of the mirror
 * 2) Set your  to your local clone
 * 3) Add a commit on top of it
 * 4)  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.