Document signing process.

pep-0381.txt

@@ -83,6 +83,59 @@ Examples:
 - /stats/months/2008-11.bz2
 - /stats/months/2008-10.bz2
 
+Mirror Authenticity
+===================
+
+With a distributed mirroring system, clients may want to verify that
+the mirrored copies are authentic. There are multiple threats to
+consider:
+
+1. the central index may get compromised
+2. the central index is assumed to be trusted, but the mirrors might
+   be tampered.
+3. a man in the middle between the central index and the end user,
+   or between a mirror and the end user might tamper with datagrams.
+
+This specification only deals with the second threat. Some provisions
+are made to detect man-in-the-middle attacks. To detect the first
+attack, package authors need to sign their packages using PGP keys, so
+that users verify that the package comes from the author they trust.
+
+The central index provides a DSA key at the URL /serverkey, in the PEM
+format as generated by "openssl dsa -pubout" (i.e. RFC 3280
+SubjectPublicKeyInfo, with the algorithm 1.3.14.3.2.12). This URL must
+*not* be mirrored, and clients must fetch the official serverkey from
+PyPI directly, or use the copy that came with the PyPI client software.
+Mirrors should still download the key, to detect a key rollover.
+
+For each package, a mirrored signature is provided at
+/serversig/<package>. This is the DSA signature of the parallel URL
+/simple/<package>, in DER form, using SHA-1 with DSA (i.e. as a RFC
+3279 Dsa-Sig-Value, created by algorithm 1.2.840.10040.4.3)
+
+Clients using a mirror need to perform the following steps to verify
+a package:
+
+1. download the /simple page, and compute its SHA-1 hash
+2. compute the DSA signature of that hash
+3. download the corresponding /serversig, and compare it (byte-for-byte)
+   with the value computed in step 2.
+4. compute and verify (against the /simple page) the MD-5 hashes
+   of all files they download from the mirror.
+
+An implementation of the verification algorithm is available from
+https://svn.python.org/packages/trunk/pypi/tools/verify.py
+
+Verification is not needed when downloading from central index, and
+should be avoided to reduce the computation overhead.
+
+About once a year, the key will be replaced with a new one. Mirrors
+will have to re-fetch all /serversig pages. Clients using mirrors need
+to find a trusted copy of the new server key. One way to obtain one
+is to download it from https://pypi.python.org/serverkey. To detect
+man-in-the-middle attacks, clients need to verify the SSL server
+certificate, which will be signed by the CACert authority.
+
 
 Special pages a mirror needs to provide
 =======================================