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 a5067b51a52..f01409a64db 100644 --- a/pep-0458.txt +++ b/pep-0458.txt @@ -333,12 +333,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 @@ -397,8 +398,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 @@ -410,10 +411,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. @@ -512,13 +513,13 @@ unless diversity of keys is maintained. Online and Offline Keys Recommended for Each Role ------------------------------------------------- -In order to support continuous delivery, the *timestamp*, *snapshot*, *bins* -role keys MUST be online. +In order to support continuous delivery, the *timestamp*, *snapshot*, and +*bin-n* role keys MUST be online. -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. How Should Metadata be Generated?