[Catalog-sig] [Draft] Package signing and verification process

[Christian Heimes]

Hello,

I like to discuss my proposal for a package signing and verification
process. It's just a brief draft and not a final document. (Credits to
my friend Marcus Brinkmann for additional insights).


Package maintainer registers PGP key
------------------------------------

Package owners and maintainer that like to sign their packages must
register their PGP/GPG key in front. The key must be registered with a
public key server (e.g. launchpad) and must contain an identity that
corresponds with her email address. Also the key must follow certain
standards (no insecure algorithms / key length) and be valid (not
expired or revoked). A user can register multiple GPG keys.

process:
 - User must provide the full fingerprint (not the short key id).
 - PyPI retrieves the key from a key server.
 - PyPI verifies the key's properties.
 - PyPI sends an encrypted mail to the user which contains an
   activation link for the key.
 - User decrypts the mails with her private key and actives
   the key with the link.

result:
  PyPI has a verified GPG key of the package maintainer.


Package maintainer signs and uploads a package
-----------------------------------------------

The procedure doesn't change excepet that PyPI may revoke a signature
(more on that later). The upload process must use HTTPS and the SSL
server cert is validating against a CA cert bundle.

result:
  uploader has uploaded her content and signature through a
  safe channel that protects against password sniffing
  and reply attacks


PyPI accepts and validates upload
---------------------------------

As first step PyPI validates the signature and the user's key:

 - Is the signature valid and matches the uploaded content?
 - Does the signing key match a registered GPG key of the user?
 - Is the user's key still valid (expiration, revocation)
 - Is the timestamp of the signature within a sensible range
   (plus minus a couple of hours?)

result:
  PyPI has a validated signature that matches the user's
  settings. The time check adds an additional countermeasure
  against replay attacks,


PyPI signs the signature
------------------------

Here comes the tricky part of the process. Bare with me!

PyPI generates a metadata file that contains:

  - timestamp of the upload
  - metadata of the user (id, name, email ...)
  - metadata of the package (excerpt of PKG-INFO)
  - the user's signature of the uploaded content as ASCII armor

Then PyPI signs the metadata files with its OWN key. It's crucial to
acknowledge that PyPI does NOT sign the uploaded content! It just signs
the user's signature and the package + user metadata. PyPI's signature
does NOT state anything about the file's content or the correctness of
the containing code.

Why does PyPI sign the package then? PyPI is the only instance that can
verify the relationship between an uploader and a package's content.
PyPI's signature promises that PyPI trusts the user to upload and sign
the package *at this very moment*. With this signature a downloader can
verify that the uploader was a registered maintainer of the package at
this very moment. Without the PyPI signature a downloader would have to
trust a key for all available packages.

result:
  The combined file (inner layer: metadata, user's signature,
  outer layer: PyPI signature) certifies that the uploader
  has a relationship to the project on PyPI.


User installs package
---------------------

process:
 - <tool> retrieves the package and the combined signature file (PyPI's
signature, metadata file and embedded signature of the uploader)
 - <tool> optionally downloads missing GPG keys from PyPI
 - <tool> verifies PyPIs signature of the metadata file and then the
   uploader's signature of the content
 - on success <tool> install the package

The verification process needs some interaction with the downloader. She
must accept and establish a trust level with each key. This needs to be
discussed in detail.


Open points
-----------

- Should we allow multiple users for a single GPG key (e.g .team keys)?

- Should the tool chains use its own key rings for verification instead
  of the user's default keyring? A tool like
http://man.he.net/man8/apt-key might be useful.

- An uploader must be able to revoke her keys from PyPI without
  access to her private key.

- When a package owner removes a user from the maintainer list
  of a package she must be able to remove all signatures of a
  user, too.

- PyPI should have a hidden and well protected private key that is used
  to sign a transitional signing key. The signing key is used for a
  couple of months and then replaced by a new signing key
  (with grace periode).


Questions?

Christian