Merge pull request python#1 from mnm678:bins_offline

pep-0458.txt

@@ -335,12 +335,13 @@ details of signing repository files and the types of keys used for each role.
 
 Figure 2: An overview of the role metadata available on PyPI.
 
-The roles that change most frequently are *timestamp*, *snapshot* and delegated
-roles (*bins* and its delegated roles).  The *timestamp* and *snapshot*
+The roles that change most frequently are *timestamp*, *snapshot* and roles
+delegated to by *bins* (i.e., *bin-n*).  The *timestamp* and *snapshot*
 metadata MUST be updated whenever *root*, *targets* or delegated metadata are
 updated.  Observe, though, that *root* and *targets* metadata are much less
-likely to be updated as often as delegated metadata.  Therefore, *timestamp*
-and *snapshot* metadata will most likely be updated frequently (possibly every
+likely to be updated as often as delegated metadata.  Similarly, the *bins* role
+will only be updated when new bins are added.  Therefore, *timestamp*,
+*snapshot*, and *bin-n* metadata will most likely be updated frequently (possibly every
 minute) due to delegated metadata being updated frequently in order to support
 continuous delivery of projects.  Continuous delivery is a set of processes
 that PyPI uses produce snapshots that can safely coexist and be deleted
@@ -399,8 +400,8 @@ not have any of the keys required to sign for projects.  However, it does not
 protect projects from attackers who have compromised PyPI, since attackers can
 manipulate TUF metadata using the keys stored online.
 
-This PEP proposes that the *bins* role (and its delegated roles) sign for all
-PyPI projects with an online key.  The *targets* role, which only signs with an
+This PEP proposes that the *bin-n* roles sign for all
+PyPI projects with online keys.  The *targets* role, which only signs with an
 offline key, MUST delegate all PyPI projects to the *bins* role.  This means
 that when a package manager such as pip (i.e., using TUF) downloads a
 distribution from a project on PyPI, it will consult the *bins* role about the
@@ -412,10 +413,10 @@ PyPI.
 Metadata Expiry Times
 ---------------------
 
-The *root* and *targets* role metadata SHOULD expire in one year, because these
+The metadata for the *root*, *targets*, and *bins* roles SHOULD each expire in one year, because these
 two metadata files are expected to change very rarely.
 
-The *timestamp*, *snapshot*, and *bins* metadata SHOULD expire in one day
+The *timestamp*, *snapshot*, and *bin-n* metadata SHOULD each expire in one day
 because a CDN or mirror SHOULD synchronize itself with PyPI every day.
 Furthermore, this generous time frame also takes into account client clocks
 that are highly skewed or adrift.
@@ -545,10 +546,10 @@ monitoring, and auditing.
 Managing offline keys
 ----------------------
 
-As explained in the previous section, the *root* and *targets* role keys MUST
-be offline for maximum security: these keys will be offline in the sense that
-their private keys MUST NOT be stored on PyPI, though some of them MAY be
-online in the private infrastructure of the project.
+As explained in the previous section, the *root*, *targets*, and *bins* role
+keys MUST be offline for maximum security: these keys will be offline in the
+sense that their private keys MUST NOT be stored on PyPI, though some of them
+MAY be online in the private infrastructure of the project.
 
 There SHOULD be an offline key ceremony to generate, backup, and store these
 keys in in such a manner that the private keys can be read only by the Python