diff --git a/pep-0480.txt b/pep-0480.txt index 64e3ee4c7..821f71486 100644 --- a/pep-0480.txt +++ b/pep-0480.txt @@ -239,11 +239,13 @@ downloaded by clients. PyPI is trusted to make uploaded projects available to clients (PyPI signs the metadata for this part of the process), and developers sign the distributions that they upload to PyPI. -In order to delegate trust to a project, developers are required to submit a -public key to PyPI. PyPI takes the project's public key and adds it to parent +In order to delegate trust to a project, developers are required to submit at +least one public key to PyPI. Developers may submit multiple public keys for +the same project (for example, one key for each maintainer of the project). +PyPI takes all of the project's public keys and adds them to parent metadata that PyPI then signs. After the initial trust is established, developers are required to sign distributions that they upload to PyPI using -the public key's corresponding private key. The signed TUF metadata that +at least one public key's corresponding private key. The signed TUF metadata that developers upload to PyPI includes information like the distribution's file size and hash, which package managers use to verify distributions that are downloaded. @@ -368,7 +370,8 @@ A default, PyPI-mediated key management and package signing solution that is `transparent`__ to developers and does not require a key escrow (sharing of encrypted private keys with PyPI) is RECOMMENDED for the signing tools. Additionally, the signing tools SHOULD circumvent the sharing of private keys -across multiple machines of each developer. +across multiple machines of each developer. This means that the key management +solution SHOULD support multiple keys for each project. __ https://en.wikipedia.org/wiki/Transparency_%28human%E2%80%93computer_interaction%29 @@ -380,6 +383,8 @@ follow to upload a distribution to PyPI: 3. Optional: Add a new identity to the developer's PyPI user account from a second machine (after a password prompt). 4. Upload project. +5. Optional: Other maintainers associated with the project may log in and + enter a secondary password to add their identity to the project. Step 1 is the normal procedure followed by developers to `register a PyPI project`__. @@ -392,7 +397,7 @@ to PyPI, and signs the TUF metadata that is generated for the distribution. Optionally adding a new identity from a second machine, by simply entering a password, in step 3 also generates an encrypted private key file and uploads an Ed25519 public key to PyPI. Separate identities MAY be created to allow a -developer, or other project maintainers, to sign releases on multiple machines. +developer, to sign releases on multiple machines. An existing verified identity (its public key is contained in project metadata or has been uploaded to PyPI) signs for new identities. By default, project metadata has a signature threshold of "1" and other verified identities may @@ -402,11 +407,15 @@ Step 4 uploads the distribution file and TUF metadata to PyPI. The "Snapshot Process" section discusses in detail the procedure followed by developers to upload a distribution to PyPI. +Step 5 allows other maintainers to generate an encrypted key file, in a similar +manner to step 2. These keys SHOULD be uploaded to PyPI and added to the TUF +metadata. This key MAY be used to upload future releases of the project. + Generation of cryptographic files and signatures is transparent to the developers in the default case: developers need not be aware that packages are -automatically signed. However, the signing tools should be flexible; a single -project key may also be shared between multiple machines if manual key -management is preferred (e.g., ssh-copy-id). +automatically signed. However, the signing tools should be flexible; developers +may want to generate their own keys and handle the key management themselves. +In this case, the developers may simply upload their public key(s) to PyPI. The `repository`__ and `developer`__ TUF tools currently support all of the recommendations previously mentioned, except for the automated signing