PEP 458: Use 'signed repository metadata' terminology (#1308)

James Bennett pointed out that "package signing" is widely misunderstood
as referring specifically to end-to-end signing with individual
publisher keys, rather than to metdata signing in general.

This updates the title and abstract to instead use the term "signed
repository metadata", and also updates a few other sections that
still gave the impression that implementing PEP 458 would be
enough to give the full end-to-end signing support that is actually
covered in PEP 480.

pep-0458.txt

@@ -1,5 +1,5 @@
 PEP: 458
-Title: Secure PyPI downloads with package signing
+Title: Secure PyPI downloads with signed repository metadata
 Version: $Revision$
 Last-Modified: $Date$
 Author: Trishank Karthik Kuppusamy <karthik@trishank.com>,
@@ -28,12 +28,15 @@ that users get valid packages from PyPI. These changes should have minimal
 impact on other parts of the ecosystem. The PEP focuses on communication between
 PyPI and users, and so does not require any action by package developers.
 Developers will upload packages using the current process, and PyPI will
-automatically sign these packages. In order for the security mechanism to be
+automatically generate signed repository metadata for these packages.
+
+In order for the security mechanism to be
 effective, additional work will need to be done by PyPI consumers (like pip) to
 verify the signatures and metadata provided by PyPI. This verification can be
 transparent to users (unless it fails) and provides an automatic security
 mechanism. There is documentation for how to consume TUF metadata in the TUF
-repository. However, changes to PyPI consumers are not required, and can be done
+repository. However, changes to PyPI consumers are not a pre-requisite for
+publishing the metadata from PyPI, and can be done
 according to the timelines and priorities of individual projects.
 
 
@@ -43,7 +46,8 @@ Proposed TUF Integration
 
 This PEP proposes how The Update Framework [2]_ (TUF__) should be integrated with the
 Python Package Index (PyPI [1]_). TUF was designed to be a flexible
-security add-on to a software updater or package manager.  The framework
+security add-on to a software updater or package manager.  A full implementation
+of the framework
 integrates best security practices, such as separating role responsibilities,
 adopting the many-man rule for signing packages, keeping signing keys offline,
 and revocation of expired or compromised signing keys.  As a result, attackers
@@ -55,28 +59,31 @@ compromised.
 
 __ https://www.linuxfoundation.org/cloud-containers-virtualization/2017/10/cncf-host-two-security-projects-notary-tuf-specification/
 
-The proposed integration will allow modern package managers, such as pip [3]_ to
-be more secure against attacks on PyPI, and to better protect
-users from such attacks.  Specifically, this PEP describes how PyPI processes
+The initial integration proposed in this PEP will allow modern package managers,
+such as pip [3]_, to be more secure against attacks on PyPI mirrors and PyPI's
+own content distribution network, and to better protect users from such attacks.
+Specifically, this PEP describes how PyPI processes
 should be adapted to generate and incorporate TUF metadata (i.e., the minimum
-security model).  The minimum security model supports verification of PyPI
+security model).  This minimum security model supports verification of PyPI
 distributions that are signed with keys stored on PyPI. Distributions that are
-uploaded by developers are signed by PyPI, requiring no action from developers (other than
-uploading the distribution), and are immediately available for download.  The
-minimum security model also minimizes PyPI administrative responsibilities by
-automating much of the signing process.
+uploaded by developers are signed by PyPI, requiring no action from developers
+(other than uploading the distribution), and are immediately available for
+download.  The minimum security model also minimizes PyPI administrative
+responsibilities by automating much of the signing process.
 
-This PEP does not prescribe how package managers, such as pip, should be adapted
+There is no discussion in *this* PEP of support for project distributions that
+are signed by developers (maximum security model). This possible future extension
+is covered in detail in PEP 480 [21]_.  The maximum security model requires more PyPI
+administrative work (though no added work for clients), and also proposes
+an easy-to-use key management solution for developers/publishers, ideas on how
+to interface with a potential future build farm on PyPI infrastructure, and the
+feasibility of end-to-end signing.
+
+While it does provide implementation recommendations, this PEP does not
+prescribe exactly how package managers, such as pip, should be adapted
 to install or update projects from PyPI with TUF metadata.   Package managers
 interested in adopting TUF on the client side may consult its `library
-documentation`__, which was created for this purpose.  There is also no
-discussion in this PEP of support for project distributions that are signed by
-developers (maximum security model). This possible future extension is covered
-in detail in PEP 480 [21]_.  The maximum security model requires more PyPI
-administrative work (though no added work for clients), but it also proposes
-an easy-to-use key management solution for developers, ideas on how to interface
-with a potential future build farm on PyPI infrastructure, and the feasibility
-of end-to-end signing.
+documentation`__, which was created for this purpose.
 
 __ https://github.com/theupdateframework/tuf/tree/v0.11.1/tuf/client#updaterpy
 
@@ -114,12 +121,12 @@ replace the trusted private key, it is very challenging to recover from a
 repository compromise. In addition to the dangers of repository compromise,
 software repositories are vulnerable to an attacker on the network (MITM)
 intercepting and changing files. These and other attacks on software
-repositories are detailed here__. This PEP aims to protect users of PyPI from
-compromises of the integrity, consistency, and freshness properties of PyPI
-packages, and enhances compromise resilience by mitigating key risk and
+repositories are detailed here__.
+
+This PEP, together with the follow-up proposal in PEP 480, aims to protect users
+of PyPI from compromises of the integrity, consistency, and freshness properties
+of PyPI packages, and enhances compromise resilience by mitigating key risk and
 providing mechanisms to recover from a compromise of PyPI or its signing keys.
-In addition to protecting direct users of PyPI, this PEP aims to provide similar
-protection for users of PyPI mirrors.
 
 __ https://github.com/theupdateframework/pip/wiki/Attacks-on-software-repositories
 __ https://theupdateframework.github.io/security.html
@@ -180,6 +187,10 @@ security audits__.
 
 __ https://theupdateframework.github.io/audits.html
 
+The scope of *this* PEP is protecting users from compromises of PyPI mirrors,
+and PyPI's own TLS termination and content distribution infrastucture.
+Protection from compromises of PyPI itself is discussed in PEP 480.
+
 
 Threat Model
 ============
@@ -188,7 +199,7 @@ The threat model assumes the following:
 
 * Offline keys are safe and securely stored.
 
-* Attackers cannot compromise PyPI's trusted keys stored online.
+* Attackers *cannot* compromise PyPI's trusted keys stored online.
 
 * Attackers can respond to client requests.