diff --git a/pep-0458-2.png b/pep-0458-2.png index cb535f631bc..fe3e762142c 100644 Binary files a/pep-0458-2.png and b/pep-0458-2.png differ diff --git a/pep-0458.txt b/pep-0458.txt index d710fc88882..aa3c165328d 100644 --- a/pep-0458.txt +++ b/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