[gentoo-hardened] The state of ebuild signing in portage

[Joshua Brindle]

We understand that there is in general a continuum between security
and ease of use.  There is a certain level of provable security
that is absolutely required in order to make the claim that Gentoo
distributes its product in a secure fashion, which is provided by
this implementation.

This is the specifications under which the security system for
portage will be implemented. This is a document detailing what is
to be created and not what is presently available. User and
developer documentation will be built from this document when this 
functionality becomes available for testing. Ideas and comments are
welcome, however it should be clear that any potential additional
options would be implemented in parallel to this core initiative,
not in lieu of it. All comments should be well thought out and 
constructive.

Every effort has been taken to implement this in a manner friendly
to all user's needs ranging from no security to extensive
verification of Portage data.

Implementation:

* There will be an inner-keyring of senior developers holding keys.
  These keys are the master keys used to sign developer keys.
  They are not used to sign data in portage directly.

*** The exact number of keys and holders has not been decided but
    for a developer to be recognized by portage he will have to
    have his key signed by the lower bound of N/2 of the inner-ring
    keys. For example, if we have 5 inner keys then a developer
    will have to have a key signed by at least 2 of them.

* We will use GPG's web-of-trust mechanism for this verification.
  GPG gives us the flexibility to decide how many complete trust
  keys will be required to trust a developer key.

* The GPG trustdb will be set up on each user's machines, to
  prevent tampering upstream. The first time a user specifies to
  use GPG they will need to manually verify the fingerprints for
  each of the inner keys. This ensures that the inner keys were
  downloaded to the users machine and have not been tampered with.

* The developer keyring will be stored in the Portage tree. This
  ensures that each user has an up to date keyring anytime they
  sychronise their Portage tree.

* Each key is verified by ensuring it is signed by the proper
  number of keys from the inner keyring. This is done by GPG
  and has little overhead.

* Manifests in each of the package directories will contain the 
  signature. These manifests contain an all-inclusive list of the 
  digests for that particular package including each ebuild, each
  file in ./files/ and also the standard ebuild digests.

* Manifests are first verified for authenticity by GPG, and then
  each digest listed is verified. This ensures that no file in
  Portage has been tampered with.

* Key revocation will be done using public key servers. There will
  be M number of revocation keys, not necessarily the same number
  as verification keys.

* Each of these revocation keys will be on all available public key
  servers. To revoke a developers key the revocation key holders
  will add an alias to their keys on the public key servers. The
  use of public keyservers ensures that the keys are always
  available, and there is a good amount of mirroring among all
  public keyservers.

* A key is considered revoked if it has been added as an alias to
  upper bound of M/2 of the revocation keys.

* Portage will check for these revocations according to the
  verification option the user desires (listed below in the
  'User use' section).

Note: For more information about GnuPG's web of trust and how it
      works, please see the GNU Privacy Handbook:
      http://www.gnupg.org/gph/en/manual.html


Developer use:
--------------
* Each developer has one key used exclusively for ebuild signing.
* Each developer must have their key signed by at least the lower
  bound of N/2 inner-ring keys.
* Each developer should have a strong passphrase and good
  protection for their key.
* Developers will use repoman to digest and sign manifests.


User use:
---------
This protection will be implemented through several FEATURE flags.
All protection is completely optional and will be disabled by default.

* FEATURES="gpg"
  checks manifest signature and digests at doebuild() calls, 
  intercepting all sourcing of the ebuilds for cache creation and
  merge operations.

* FEATURES="strict"
  does additional checks on manifests that result in termination of 
  the merge if they fail. Missing manifests, files missing from the
  manifest, and additional files not included in the manifest will
  cause portage to exit with a failure notice.

* FEATURES="gpg strict"
  will be slightly more aggressive in checking files. It includes
  everything from the above two, failing on possible breaches.

* FEATURES="gpg severe"
  causes more frequent/aggressive checking for key revocations and
  forces a comprehensive check at sync time before any files are 
  sourced. It also implies strict.

* The inner keys will be downloaded independantly of the public
  keyservers and verified by the user. This will provide the
  maximum assurance that the keys are trustworthy.

*** To accommodate users behind restrictive firewalls, the inner
    public keys will also be included in rsync and webrsync
    snapshots. The fingerprints themselves will be available from 
    www.gentoo.org, published in newsgroups and mailing lists, and
    users will be encouraged to verify fingerprints from multiple 
    sources for maximum security.

Notes:
------
We have discussed several other implementations including server
side signing and have ascertained that this implementation has the
most benefits and protection for our users while putting minimal
strain on developers.

The benefits of this implementation include:

* Complete protection from the developer all the way to the user.
* Ability to revoke and isolate packages handled by a compromised key.
* Completely optional and configurable by each user.
* Ability to extend security by adding keys to your local trustdb
  thereby trusting your own or third party keys.


Joshua Brindle
Hardened Gentoo Project Leader


--
gentoo-hardened@g.o mailing list