|Title:||Surviving a Compromise of PyPI|
|Last-Modified:||2013-11-15 22:20:14 +1000 (Fri, 15 Nov 2013)|
|Author:||Trishank Karthik Kuppusamy <tk47 at students.poly.edu>, Donald Stufft <donald at stufft.io>, Justin Cappos <jcappos at poly.edu>|
|Discussions-To:||Distutils SIG <distutils-sig at python.org>|
- Responsibility Separation
- Metadata Management
- Key Management
- Appendix: Rejected Proposals
This PEP describes how the Python Package Index (PyPI ) may be integrated with The Update Framework  (TUF). TUF was designed to be a plug-and-play security add-on to a software updater or package manager. TUF provides end-to-end security like SSL, but for software updates instead of HTTP connections. The framework integrates best security practices such as separating responsibilities, adopting the many-man rule for signing packages, keeping signing keys offline, and revocation of expired or compromised signing keys.
The proposed integration will render modern package managers such as pip  more secure against various types of security attacks on PyPI and protect users against them. Even in the worst case where an attacker manages to compromise PyPI itself, the damage is controlled in scope and limited in duration.
Specifically, this PEP will describe how PyPI processes should be adapted to incorporate TUF metadata. It will not prescribe how package managers such as pip should be adapted to install or update with TUF metadata projects from PyPI.
In January 2013, the Python Software Foundation (PSF) announced  that the python.org wikis for Python, Jython, and the PSF were subjected to a security breach which caused all of the wiki data to be destroyed on January 5 2013. Fortunately, the PyPI infrastructure was not affected by this security breach. However, the incident is a reminder that PyPI should take defensive steps to protect users as much as possible in the event of a compromise. Attacks on software repositories happen all the time . We must accept the possibility of security breaches and prepare PyPI accordingly because it is a valuable target used by thousands, if not millions, of people.
Before the wiki attack, PyPI used MD5 hashes to tell package managers such as pip whether or not a package was corrupted in transit. However, the absence of SSL made it hard for package managers to verify transport integrity to PyPI. It was easy to launch a man-in-the-middle attack between pip and PyPI to change package contents arbitrarily. This can be used to trick users into installing malicious packages. After the wiki attack, several steps were proposed (some of which were implemented) to deliver a much higher level of security than was previously the case: requiring SSL to communicate with PyPI , restricting project names , and migrating from MD5 to SHA-2 hashes .
These steps, though necessary, are insufficient because attacks are still possible through other avenues. For example, a public mirror is trusted to honestly mirror PyPI, but some mirrors may misbehave due to malice or accident. Package managers such as pip are supposed to use signatures from PyPI to verify packages downloaded from a public mirror , but none are known to actually do so . Therefore, it is also wise to add more security measures to detect attacks from public mirrors or content delivery networks  (CDNs).
Even though official mirrors are being deprecated on PyPI , there remain a wide variety of other attack vectors on package managers . Among other things, these attacks can crash client systems, cause obsolete packages to be installed, or even allow an attacker to execute arbitrary code. In September 2013, we showed how the latest version of pip then was susceptible to these attacks and how TUF could protect users against them .
Finally, PyPI allows for packages to be signed with GPG keys , although no package manager is known to verify those signatures, thus negating much of the benefits of having those signatures at all. Validating integrity through cryptography is important, but issues such as immediate and secure key revocation or specifying a required threshold number of signatures still remain. Furthermore, GPG by itself does not immediately address the attacks mentioned above.
In order to protect PyPI against infrastructure compromises, we propose integrating PyPI with The Update Framework  (TUF).
In order to keep this PEP focused solely on the application of TUF on PyPI, the reader is assumed to already be familiar with the design principles of TUF . It is also strongly RECOMMENDED that the reader be familiar with the TUF specification .
- Projects: Projects are software components that are made available for integration. Projects include Python libraries, frameworks, scripts, plugins, applications, collections of data or other resources, and various combinations thereof. Public Python projects are typically registered on the Python Package Index .
- Releases: Releases are uniquely identified snapshots of a project .
- Distributions: Distributions are the packaged files which are used to publish and distribute a release .
- Simple index: The HTML page which contains internal links to the distributions of a project .
- Consistent snapshot: A set of TUF metadata and PyPI targets that capture the complete state of all projects on PyPI as they were at some fixed point in time.
- The consistent-snapshot (release) role: In order to prevent confusion due to the different meanings of the term "release" as employed by PEP 426  and the TUF specification , we rename the release role as the consistent-snapshot role.
- Continuous delivery: A set of processes with which PyPI produces consistent snapshots that can safely coexist and deleted independently .
- Developer: Either the owner or maintainer of a project who is allowed to update the TUF metadata as well as distribution metadata and data for the project.
- Online key: A key that MUST be stored on the PyPI server infrastructure. This is usually to allow automated signing with the key. However, this means that an attacker who compromises PyPI infrastructure will be able to read these keys.
- Offline key: A key that MUST be stored off the PyPI infrastructure. This prevents automated signing with the key. This means that an attacker who compromises PyPI infrastructure will not be able to immediately read these keys.
- Developer key: A private key for which its corresponding public key is registered with PyPI to say that it is responsible for directly signing for or delegating the distributions belonging to a project. For the purposes of this PEP, it is offline in the sense that the private key MUST not be stored on PyPI. However, the project is free to require certain developer keys to be online on its own infrastructure.
- Threshold signature scheme: A role could increase its resilience to key compromises by requiring that at least t out of n keys are REQUIRED to sign its metadata. This means that a compromise of t-1 keys is insufficient to compromise the role itself. We denote this property by saying that the role requires (t, n) keys.
Figure 1: A simplified overview of the roles in PyPI with TUF
Figure 1 shows a simplified overview of the roles that TUF metadata assume on PyPI. The top-level root role signs for the keys of the top-level timestamp, consistent-snapshot, targets and root roles. The timestamp role signs for a new and consistent snapshot. The consistent- snapshot role signs for the root, targets and all delegated targets metadata. The claimed role signs for all projects that have registered their own developer keys with PyPI. The recently-claimed role signs for all projects that recently registered their own developer keys with PyPI. Finally, the unclaimed role signs for all projects that have not registered developer keys with PyPI. The claimed, recently-claimed and unclaimed roles are numbered 1, 2, 3 respectively because a project will be searched for in each of those roles in that descending order: first in claimed, then in recently-claimed if necessary, and finally in unclaimed if necessary.
Every year, PyPI administrators are going to sign for root role keys. After that, automation will continuously sign for a timestamped, consistent snapshot of all projects. Every few months, PyPI administrators will move projects with vetted developer keys from the recently-claimed role to the claimed role. As we will soon see, they will sign for claimed with projects with offline keys.
This PEP does not require project developers to use TUF to secure their packages from attacks on PyPI. By default, all projects will be signed for by the unclaimed role. If a project wishes stronger security guarantees, then the project is strongly RECOMMENDED to register developer keys with PyPI so that it may sign for its own distributions. By doing so, the project must remain as a recently-claimed project until PyPI administrators have had an opportunity to vet the developer keys of the project, after which the project will be moved to the claimed role.
This PEP has not been designed to be backward-compatible for package managers that do not use the TUF security protocol to install or update a project from the PyPI described here. Instead, it is RECOMMENDED that PyPI maintain a backward-compatible API of itself that does NOT offer TUF so that older package managers that do not use TUF will be able to install or update projects from PyPI as usual but without any of the security offered by TUF. For the rest of this PEP, we will assume that PyPI will simultaneously maintain a backward-incompatible API of itself for package managers that MUST use TUF to securely install or update projects. We think that this approach represents a reasonable trade-off: older package managers that do not TUF will still be able to install or update projects without any TUF security from PyPI, and newer package managers that do use TUF will be able to securely install or update projects. At some point in the future, PyPI administrators MAY choose to permanently deprecate the backward-compatible version of itself that does not offer TUF metadata.
Unless a mirror, CDN or the PyPI repository has been compromised, the end-user will not be able to discern whether or not a package manager is using TUF to install or update a project from PyPI.
Recall that TUF requires four top-level roles: root, timestamp, consistent-snapshot and targets. The root role specifies the keys of all the top-level roles (including itself). The timestamp role specifies the latest consistent snapshot. The consistent-snapshot role specifies the latest versions of all TUF metadata files (other than timestamp). The targets role specifies available target files (in our case, it will be all files on PyPI under the /simple and /packages directories). In this PEP, each of these roles will serve their responsibilities without exception.
Our proposal offers two levels of security to developers. If developers opt in to secure their projects with their own developer keys, then their projects will be very secure. Otherwise, TUF will still protect them in many cases:
- Minimum security (no action by a developer): protects unclaimed and recently-claimed projects without developer keys from CDNs  or public mirrors, but not from some PyPI compromises. This is because continuous delivery requires some keys to be online. This level of security protects projects from being accidentally or deliberately tampered with by a mirror or a CDN because the mirror or CDN will not have any of the PyPI or developer keys required to sign for projects. However, it would not protect projects from attackers who have compromised PyPI because they will be able to manipulate the TUF metadata for unclaimed projects with the appropriate online keys.
- Maximum security (developer signs their project): protects projects with developer keys not only from CDNs or public mirrors, but also from some PyPI compromises. This is because many important keys will be offline. This level of security protects projects from being accidentally or deliberately tampered with by a mirror or a CDN for reasons identical to the minimum security level. It will also protect projects (or at least mitigate damages) from the most likely attacks on PyPI. For example: given access to online keys after a PyPI compromise, attackers will be able to freeze the distributions for these projects, but they will not be able to serve malicious distributions for these projects (not without compromising other offline keys which would entail more risk, time and energy). Details for the exact level of security offered is discussed in the section on key management.
In order to complete support for continuous delivery, we propose three delegated targets roles:
- claimed: Signs for the delegation of PyPI projects to their respective developer keys.
- recently-claimed: This role is almost identical to the claimed role and could technically be performed by the unclaimed role, but there are two important reasons why it exists independently: the first reason is to improve the performance of looking up projects in the unclaimed role (by moving metadata to the recently-claimed role instead), and the second reason is to make it easier for PyPI administrators to move recently-claimed projects to the claimed role.
- unclaimed: Signs for PyPI projects without developer keys.
The targets role MUST delegate all PyPI projects to the three delegated targets roles in the order of appearance listed above. This means that when pip downloads with TUF a distribution from a project on PyPI, it will first consult the claimed role about it. If the claimed role has delegated the project, then pip will trust the project developers (in order of delegation) about the TUF metadata for the project. Otherwise, pip will consult the recently-claimed role about the project. If the recently-claimed role has delegated the project, then pip will trust the project developers (in order of delegation) about the TUF metadata for the project. Otherwise, pip will consult the unclaimed role about the TUF metadata for the project. If the unclaimed role has not delegated the project, then the project is considered to be non-existent on PyPI.
A PyPI project MAY begin without registering a developer key. Therefore, the project will be signed for by the unclaimed role. After registering developer keys, the project will be removed from the unclaimed role and delegated to the recently-claimed role. After a probation period and a vetting process to verify the developer keys of the project, the project will be removed from the recently-claimed role and delegated to the claimed role.
The claimed role offers maximum security, whereas the recently-claimed and unclaimed role offer minimum security. All three roles support continuous delivery of PyPI projects.
The unclaimed role offers minimum security because PyPI will sign for projects without developer keys with an online key in order to permit continuous delivery.
The recently-claimed role offers minimum security because while the project developers will sign for their own distributions with offline developer keys, PyPI will sign with an online key the delegation of the project to those offline developer keys. The signing of the delegation with an online key allows PyPI administrators to continuously deliver projects without having to continuously sign the delegation whenever one of those projects registers developer keys.
Finally, the claimed role offers maximum security because PyPI will sign with offline keys the delegation of a project to its offline developer keys. This means that every now and then, PyPI administrators will vet developer keys and sign the delegation of a project to those developer keys after being reasonably sure about the ownership of the developer keys. The process for vetting developer keys is out of the scope of this PEP.
In this section, we examine the TUF metadata that PyPI must manage by itself, and other TUF metadata that must be safely delegated to projects. Examples of the metadata described here may be seen at our testbed mirror of PyPI-with-TUF .
The metadata files that change most frequently will be timestamp, consistent-snapshot and delegated targets (claimed, recently-claimed, unclaimed, project) metadata. The timestamp and consistent-snapshot metadata MUST be updated whenever root, targets or delegated targets metadata are updated. Observe, though, that root and targets metadata are much less likely to be updated as often as delegated targets metadata. Therefore, timestamp and consistent-snapshot metadata will most likely be updated frequently (possibly every minute) due to delegated targets metadata being updated frequently in order to drive continuous delivery of projects.
Consequently, the processes with which PyPI updates projects will have to be updated accordingly, the details of which are explained in the following subsections.
In an ideal world, metadata and data should be immediately updated and presented whenever a project is updated. In practice, there will be problems when there are many readers and writers who access the same metadata or data at the same time.
An important example at the time of writing is that, mirrors are very likely, as far as we can tell, to update in an inconsistent manner from PyPI as it is without TUF. Specifically, a mirror would update itself in such a way that project A would be from time T, whereas project B would be from time T+5, project C would be from time T+3, and so on where T is the time that the mirror first begun updating itself. There is no known way for a mirror to update itself such that it captures the state of all projects as they were at time T.
Adding TUF to PyPI will not automatically solve the problem. Consider what we call the "inverse replay" or "fast-forward" problem . Suppose that PyPI has timestamped a consistent snapshot at version 1. A mirror is later in the middle of copying PyPI at this snapshot. While the mirror is copying PyPI at this snapshot, PyPI timestamps a new snapshot at, say, version 2. Without accounting for consistency, the mirror would then find itself with a copy of PyPI in an inconsistent state which is indistinguishable from arbitrary metadata or target attacks. The problem would also apply when the mirror is substituted with a pip user.
Therefore, the problem can be summarized as such: there are problems of consistency on PyPI with or without TUF. TUF requires its metadata to be consistent with the data, but how would the metadata be kept consistent with projects that change all the time?
As a result, we will solve for PyPI the problem of producing a consistent snapshot that captures the state of all known projects at a given time. Each consistent snapshot can safely coexist with any other consistent snapshot and deleted independently without affecting any other consistent snapshot.
The gist of the solution is that every metadata or data file written to disk MUST include in its filename the cryptographic hash  of the file. How would this help clients which use the TUF protocol to securely and consistently install or update a project from PyPI?
Recall that the first step in the TUF protocol requires the client to download the latest timestamp metadata. However, the client would not know in advance the hash of the timestamp metadata file from the latest consistent snapshot. Therefore, PyPI MUST redirect all HTTP GET requests for timestamp metadata to the timestamp metadata file from the latest consistent snapshot. Since the timestamp metadata is the root of a tree of cryptographic hashes pointing to every other metadata or target file that are meant to exist together for consistency, the client is then able to retrieve any file from this consistent snapshot by deterministically including, in the request for the file, the hash of the file in the filename. Assuming infinite disk space and no hash collisions , a client may safely read from one consistent snapshot while PyPI produces another consistent snapshot.
In this simple but effective manner, we are able to capture a consistent snapshot of all projects and the associated metadata at a given time. The next subsection will explicate the implementation details of this idea.
Given a project, PyPI is responsible for updating, depending on the project, either the claimed, recently-claimed or unclaimed metadata as well as associated delegated targets metadata. Every project MUST upload its set of metadata and targets in a single transaction. We will call this set of files the project transaction. We will discuss later how PyPI MAY validate the files in a project transaction. For now, let us focus on how PyPI will respond to a project transaction. We will call this response the project transaction process. There will also be a consistent snapshot process that we will define momentarily; for now, it suffices to know that project transaction processes and the consistent snapshot process must coordinate with each other.
Also, every metadata and target file MUST include in its filename the hex digest  of its SHA-256  hash. For this PEP, it is RECOMMENDED that PyPI adopt a simple convention of the form filename.digest.ext, where filename is the original filename without a copy of the hash, digest is the hex digest of the hash, and ext is the filename extension.
When an unclaimed project uploads a new transaction, a project transaction process MUST add all new targets and relevant delegated unclaimed metadata. (We will see later in this section why the unclaimed role will delegate targets to a number of delegated unclaimed roles.) Finally, the project transaction process MUST inform the consistent snapshot process about new delegated unclaimed metadata.
When a recently-claimed project uploads a new a transaction, a project transaction process MUST add all new targets and delegated targets metadata for the project. If the project is new, then the project transaction process MUST also add new recently-claimed metadata with public keys and threshold number (which MUST be part of the transaction) for the project. Finally, the project transaction process MUST inform the consistent snapshot process about new recently-claimed metadata as well as the current set of delegated targets metadata for the project.
The process for a claimed project is slightly different. The difference is that PyPI administrators will choose to move the project from the recently-claimed role to the claimed role. A project transaction process MUST then add new recently-claimed and claimed metadata to reflect this migration. As is the case for a recently-claimed project, the project transaction process MUST always add all new targets and delegated targets metadata for the claimed project. Finally, the project transaction process MUST inform the consistent snapshot process about new recently-claimed or claimed metadata as well as the current set of delegated targets metadata for the project.
Project transaction processes SHOULD be automated, except when PyPI administrators move a project from the recently-claimed role to the claimed role. Project transaction processes MUST also be applied atomically: either all metadata and targets, or none of them, are added. The project transaction processes and consistent snapshot process SHOULD work concurrently. Finally, project transaction processes SHOULD keep in memory the latest claimed, recently-claimed and unclaimed metadata so that they will be correctly updated in new consistent snapshots.
All project transactions MAY be placed in a single queue and processed serially. Alternatively, the queue MAY be processed concurrently in order of appearance provided that the following rules are observed:
- No pair of project transaction processes must concurrently work on the same project.
- No pair of project transaction processes must concurrently work on unclaimed projects that belong to the same delegated unclaimed targets role.
- No pair of project transaction processes must concurrently work on new recently-claimed projects.
- No pair of project transaction processes must concurrently work on new claimed projects.
- No project transaction process must work on a new claimed project while another project transaction process is working on a new recently-claimed project and vice versa.
These rules MUST be observed so that metadata is not read from or written to inconsistently.
The consistent snapshot process is fairly simple and SHOULD be automated. The consistent snapshot process MUST keep in memory the latest working set of root, targets and delegated targets metadata. Every minute or so, the consistent snapshot process will sign for this latest working set. (Recall that project transaction processes continuously inform the consistent snapshot process about the latest delegated targets metadata in a concurrency-safe manner. The consistent snapshot process will actually sign for a copy of the latest working set while the actual latest working set in memory will be updated with information continuously communicated by project transaction processes.) Next, the consistent snapshot process MUST generate and sign new timestamp metadata that will vouch for the consistent-snapshot metadata generated in the previous step. Finally, the consistent snapshot process MUST add new timestamp and consistent-snapshot metadata representing the latest consistent snapshot.
A few implementation notes are now in order. So far, we have seen only that new metadata and targets are added, but not that old metadata and targets are removed. Practical constraints are such that eventually PyPI will run out of disk space to produce a new consistent snapshot. In that case, PyPI MAY then use something like a "mark-and-sweep" algorithm to delete sufficiently old consistent snapshots: in order to preserve the latest consistent snapshot, PyPI would walk objects beginning from the root (timestamp) of the latest consistent snapshot, mark all visited objects, and delete all unmarked objects. The last few consistent snapshots may be preserved in a similar fashion. Deleting a consistent snapshot will cause clients to see nothing thereafter but HTTP 404 responses to any request for a file in that consistent snapshot. Clients SHOULD then retry their requests with the latest consistent snapshot.
We do not consider updates to any consistent snapshot because hash collisions  are out of the scope of this PEP. In case a hash collision is observed, PyPI MAY wish to check that the file being added is identical to the file already stored. (Should a hash collision be observed, it is far more likely the case that the file is identical rather than being a genuine collision attack .) Otherwise, PyPI MAY either overwrite the existing file or ignore any write operation to an existing file.
All clients, such as pip using the TUF protocol, MUST be modified to download every metadata and target file (except for timestamp metadata) by including, in the request for the file, the hash of the file in the filename. Following the filename convention recommended earlier, a request for the file at filename.ext will be transformed to the equivalent request for the file at filename.digest.ext.
A claimed or recently-claimed project will need to upload in its transaction to PyPI not just targets (a simple index as well as distributions) but also TUF metadata. The project MAY do so by uploading a ZIP file containing two directories, /metadata/ (containing delegated targets metadata files) and /targets/ (containing targets such as the project simple index and distributions which are signed for by the delegated targets metadata).
Whenever the project uploads metadata or targets to PyPI, PyPI SHOULD check the project TUF metadata for at least the following properties:
- A threshold number of the developers keys registered with PyPI by that project MUST have signed for the delegated targets metadata file that represents the "root" of targets for that project (e.g. metadata/targets/ project.txt).
- The signatures of delegated targets metadata files MUST be valid.
- The delegated targets metadata files MUST NOT be expired.
- The delegated targets metadata MUST be consistent with the targets.
- A delegator MUST NOT delegate targets that were not delegated to itself by another delegator.
- A delegatee MUST NOT sign for targets that were not delegated to itself by a delegator.
- Every file MUST contain a unique copy of its hash in its filename following the filename.digest.ext convention recommended earlier.
If PyPI chooses to check the project TUF metadata, then PyPI MAY choose to reject publishing any set of metadata or targets that do not meet these requirements.
PyPI MUST enforce access control by ensuring that each project can only write to the TUF metadata for which it is responsible. It MUST do so by ensuring that project transaction processes write to the correct metadata as well as correct locations within those metadata. For example, a project transaction process for an unclaimed project MUST write to the correct target paths in the correct delegated unclaimed metadata for the targets of the project.
On rare occasions, PyPI MAY wish to extend the TUF metadata format for projects in a backward-incompatible manner. Note that PyPI will NOT be able to automatically rewrite existing TUF metadata on behalf of projects in order to upgrade the metadata to the new backward-incompatible format because this would invalidate the signatures of the metadata as signed by developer keys. Instead, package managers SHOULD be written to recognize and handle multiple incompatible versions of TUF metadata so that claimed and recently-claimed projects could be offered a reasonable time to migrate their metadata to newer but backward-incompatible formats.
The details of how each project manages its TUF metadata is beyond the scope of this PEP.
A mirror SHOULD have to maintain for its clients only one consistent snapshot which would represent the latest consistent snapshot from PyPI known to the mirror. The mirror would then serve all HTTP requests for metadata or targets by simply reading directly from this consistent snapshot directory.
The mirroring protocol itself is fairly simple. The mirror would ask PyPI for timestamp metadata from the latest consistent snapshot and proceed to copy the entire consistent snapshot from the timestamp metadata onwards. If the mirror encounters a failure to copy any metadata or target file while copying the consistent snapshot, it SHOULD retrying resuming the copy of that particular consistent snapshot. If PyPI has deleted that consistent snapshot, then the mirror SHOULD delete the failed consistent snapshot and try downloading the latest consistent snapshot instead.
The mirror SHOULD point users to a previous consistent snapshot directory while it is copying the latest consistent snapshot from PyPI. Only after the latest consistent snapshot has been completely copied SHOULD the mirror switch clients to the latest consistent snapshot. The mirror MAY then delete the previous consistent snapshot once it finds that no client is reading from the previous consistent snapshot.
The mirror MAY use extant file transfer software such as rsync  to mirror PyPI. In that case, the mirror MUST first obtain the latest known timestamp metadata from PyPI. The mirror MUST NOT immediately publish the latest known timestamp metadata from PyPI. Instead, the mirror MUST first iteratively transfer all new files from PyPI until there are no new files left to transfer. Finally, the mirror MUST publish the latest known timestamp it fetched from PyPI so that package managers such as pip may be directed to the latest consistent snapshot known to the mirror.
In order to be able to safely restore from static snapshots later in the event of a compromise, PyPI SHOULD maintain a small number of its own mirrors to copy PyPI consistent snapshots according to some schedule. The mirroring protocol can be used immediately for this purpose. The mirrors must be secured and isolated such that they are responsible only for mirroring PyPI. The mirrors can be checked against one another to detect accidental or malicious failures.
The root and targets role metadata SHOULD expire in a year, because these metadata files are expected to change very rarely.
The claimed role metadata SHOULD expire in three to six months, because this metadata is expected to be refreshed in that time frame. This time frame was chosen to induce an easier administration process for PyPI.
The timestamp, consistent-snapshot, recently-claimed and unclaimed role metadata SHOULD expire in a 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.
The expiry times for the delegated targets metadata of a project is beyond the scope of this PEP.
Due to the growing number of projects and distributions, the TUF metadata will also grow correspondingly.
For example, consider the unclaimed role. In August 2013, we found that the size of the unclaimed role metadata was about 42MB if the unclaimed role itself signed for about 220K PyPI targets (which are simple indices and distributions). We will not delve into details in this PEP, but TUF features a so-called "lazy bin walk " scheme which splits a large targets or delegated targets metadata file into many small ones. This allows a TUF client updater to intelligently download only a small number of TUF metadata files in order to update any project signed for by the unclaimed role. For example, applying this scheme to the previous repository resulted in pip downloading between 1.3KB and 111KB to install or upgrade a PyPI project via TUF.
From our findings as of the time of writing, PyPI SHOULD split all targets in the unclaimed role by delegating it to 1024 delegated targets role, each of which would sign for PyPI targets whose hashes fall into that "bin" or delegated targets role. We found that 1024 bins would result in the unclaimed role metadata and each of its binned delegated targets role metadata to be about the same size (40-50KB) for about 220K PyPI targets (simple indices and distributions).
It is possible to make the TUF metadata more compact by representing it in a binary format as opposed to the JSON text format. Nevertheless, we believe that a sufficiently large number of project and distributions will induce scalability challenges at some point, and therefore the unclaimed role will then still need delegations in order to address the problem. Furthermore, the JSON format is an open and well-known standard for data interchange.
Due to the large number of delegated target metadata files, compressed versions of consistent-snapshot metadata SHOULD also be made available.
In this section, we examine the kind of keys required to sign for TUF roles on PyPI. TUF is agnostic with respect to choices of digital signature algorithms. For the purpose of discussion, we will assume that most digital signatures will be produced with the well-tested and tried RSA algorithm . Nevertheless, we do NOT recommend any particular digital signature algorithm in this PEP because there are a few important constraints: firstly, cryptography changes over time; secondly, package managers such as pip may wish to perform signature verification in Python, without resorting to a compiled C library, in order to be able to run on as many systems as Python supports; finally, TUF recommends diversity of keys for certain applications, and we will soon discuss these exceptions.
The timestamp, consistent-snapshot, recently-claimed and unclaimed roles will need to support continuous delivery. Even though their respective keys will then need to be online, we will require that the keys be independent of each other. This allows for each of the keys to be placed on separate servers if need be, and prevents side channel attacks that compromise one key from automatically compromising the rest of the keys. Therefore, each of the timestamp, consistent-snapshot, recently-claimed and unclaimed roles MUST require (1, 1) keys.
The unclaimed role MAY delegate targets in an automated manner to a number of roles called "bins", as we discussed in the previous section. Each of the "bin" roles SHOULD share the same key as the unclaimed role, due simultaneously to space efficiency of metadata and because there is no security advantage in requiring separate keys.
The root role is critical for security and should very rarely be used. It is primarily used for key revocation, and it is the root of trust for all of PyPI. The root role signs for the keys that are authorized for each of the top-level roles (including itself). The keys belonging to the root role are intended to be very well-protected and used with the least frequency of all keys. We propose that every PSF board member own a (strong) root key. A majority of them can then constitute the quorum to revoke or endow trust in all top-level keys. Alternatively, the system administrators of PyPI (instead of PSF board members) could be responsible for signing for the root role. Therefore, the root role SHOULD require (t, n) keys, where n is the number of either all PyPI administrators or all PSF board members, and t > 1 (so that at least two members must sign the root role).
The targets role will be used only to sign for the static delegation of all targets to the claimed, recently-claimed and unclaimed roles. Since these target delegations must be secured against attacks in the event of a compromise, the keys for the targets role MUST be offline and independent from other keys. For simplicity of key management without sacrificing security, it is RECOMMENDED that the keys of the targets role are permanently discarded as soon as they have been created and used to sign for the role. Therefore, the targets role SHOULD require (1, 1) keys. Again, this is because the keys are going to be permanently discarded, and more offline keys will not help against key recovery attacks  unless diversity of keys is maintained.
Similarly, the claimed role will be used only to sign for the dynamic delegation of projects to their respective developer keys. Since these target delegations must be secured against attacks in the event of a compromise, the keys for the claimed role MUST be offline and independent from other keys. Therefore, the claimed role SHOULD require (t, n) keys, where n is the number of all PyPI administrators (in order to keep it manageable), and t ≥ 1 (so that at least one member MUST sign the claimed role). While a stronger threshold would indeed render the role more robust against a compromise of the claimed keys (which is highly unlikely assuming that the keys are independent and securely kept offline), we think that this trade-off is acceptable for the important purpose of keeping the maintenance overhead for PyPI administrators as little as possible. At the time of writing, we are keeping this point open for discussion by the distutils-sig community.
The number of developer keys is project-specific and thus beyond the scope of this PEP.
In order to support continuous delivery, the timestamp, consistent-snapshot, recently-claimed and unclaimed role keys MUST be online.
As explained in the previous section, the root, targets and claimed role keys MUST be offline for maximum security. Developers keys will be offline in the sense that the private keys MUST NOT be stored on PyPI, though some of them may be online on the private infrastructure of the project.
At the time of writing, we recommend that all RSA keys (both offline and online) SHOULD have a minimum key size of 3072 bits for data-protection lifetimes beyond 2030 .
Due to the threats of weak key generation and implementation weaknesses , the types of keys as well as the libraries used to generate them should vary within TUF on PyPI. Our current implementation of TUF supports multiple digital signature algorithms such as RSA (with OpenSSL  or PyCrypto ) and ed25519 . Furthermore, TUF supports the binding of other cryptographic libraries that it does not immediately support "out of the box", and so one MAY generate keys using other cryptographic libraries and use them for TUF on PyPI.
As such, the root role keys SHOULD be generated by a variety of digital signature algorithms as implemented by different cryptographic libraries.
Table 1: Attacks possible by compromising certain combinations of role keys
Table 1 summarizes the kinds of attacks rendered possible by compromising a threshold number of keys belonging to the TUF roles on PyPI. Except for the timestamp and consistent-snapshot roles, the pairwise interaction of role compromises may be found by taking the union of both rows.
In September 2013, we showed how the latest version of pip then was susceptible to these attacks and how TUF could protect users against them .
An attacker who compromises developer keys for a project and who is able to somehow upload malicious metadata and targets to PyPI will be able to serve malicious updates to users of that project (and that project alone). Note that compromising targets or any delegated targets role (except for project targets metadata) does not immediately endow the attacker with the ability to serve malicious updates. The attacker must also compromise the timestamp and consistent-snapshot roles (which are both online and therefore more likely to be compromised). This means that in order to launch any attack, one must be not only be able to act as a man-in-the-middle but also compromise the timestamp key (or the root keys and sign a new timestamp key). To launch any attack other than a freeze attack, one must also compromise the consistent-snapshot key.
Finally, a compromise of the PyPI infrastructure MAY introduce malicious updates to recently-claimed and unclaimed projects because the keys for those roles are online. However, attackers cannot modify claimed projects in such an event because targets and claimed metadata have been signed with offline keys. Therefore, it is RECOMMENDED that high-value projects register their developer keys with PyPI and sign for their own distributions.
By a key compromise, we mean that the key as well as PyPI infrastructure has been compromised and used to sign new metadata on PyPI.
If a threshold number of developer keys of a project have been compromised, then the project MUST take the following steps:
- The project metadata and targets MUST be restored to the last known good consistent snapshot where the project was not known to be compromised. This can be done by the developers repackaging and resigning all targets with the new keys.
- The project delegated targets metadata MUST have their version numbers incremented, expiry times suitably extended and signatures renewed.
Whereas PyPI MUST take the following steps:
- Revoke the compromised developer keys from the delegation to the project by the recently-claimed or claimed role. This is done by replacing the compromised developer keys with newly issued developer keys.
- A new timestamped consistent snapshot MUST be issued.
If a threshold number of timestamp, consistent-snapshot, recently-claimed or unclaimed keys have been compromised, then PyPI MUST take the following steps:
- Revoke the timestamp, consistent-snapshot and targets role keys from the root role. This is done by replacing the compromised timestamp, consistent-snapshot and targets keys with newly issued keys.
- Revoke the recently-claimed and unclaimed keys from the targets role by replacing their keys with newly issued keys. Sign the new targets role metadata and discard the new keys (because, as we explained earlier, this increases the security of targets metadata).
- Clear all targets or delegations in the recently-claimed role and delete all associated delegated targets metadata. Recently registered projects SHOULD register their developer keys again with PyPI.
- All targets of the recently-claimed and unclaimed roles SHOULD be compared with the last known good consistent snapshot where none of the timestamp, consistent-snapshot, recently-claimed or unclaimed keys were known to have been compromised. Added, updated or deleted targets in the compromised consistent snapshot that do not match the last known good consistent snapshot MAY be restored to their previous versions. After ensuring the integrity of all unclaimed targets, the unclaimed metadata MUST be regenerated.
- The recently-claimed and unclaimed metadata MUST have their version numbers incremented, expiry times suitably extended and signatures renewed.
- A new timestamped consistent snapshot MUST be issued.
This would preemptively protect all of these roles even though only one of them may have been compromised.
If a threshold number of the targets or claimed keys have been compromised, then there is little that an attacker could do without the timestamp and consistent-snapshot keys. In this case, PyPI MUST simply revoke the compromised targets or claimed keys by replacing them with new keys in the root and targets roles respectively.
If a threshold number of the timestamp, consistent-snapshot and claimed keys have been compromised, then PyPI MUST take the following steps in addition to the steps taken when either the timestamp or consistent-snapshot keys are compromised:
- Revoke the claimed role keys from the targets role and replace them with newly issued keys.
- All project targets of the claimed roles SHOULD be compared with the last known good consistent snapshot where none of the timestamp, consistent-snapshot or claimed keys were known to have been compromised. Added, updated or deleted targets in the compromised consistent snapshot that do not match the last known good consistent snapshot MAY be restored to their previous versions. After ensuring the integrity of all claimed project targets, the claimed metadata MUST be regenerated.
- The claimed metadata MUST have their version numbers incremented, expiry times suitably extended and signatures renewed.
If a threshold number of the timestamp, consistent-snapshot and targets keys have been compromised, then PyPI MUST take the union of the steps taken when the claimed, recently-claimed and unclaimed keys have been compromised.
If a threshold number of the root keys have been compromised, then PyPI MUST take the steps taken when the targets role has been compromised as well as replace all of the root keys.
It is also RECOMMENDED that PyPI sufficiently document compromises with security bulletins. These security bulletins will be most informative when users of pip with TUF are unable to install or update a project because the keys for the timestamp, consistent-snapshot or root roles are no longer valid. They could then visit the PyPI web site to consult security bulletins that would help to explain why they are no longer able to install or update, and then take action accordingly. When a threshold number of root keys have not been revoked due to a compromise, then new root metadata may be safely updated because a threshold number of existing root keys will be used to sign for the integrity of the new root metadata so that TUF clients will be able to verify the integrity of the new root metadata with a threshold number of previously known root keys. This will be the common case. Otherwise, in the worst case where a threshold number of root keys have been revoked due to a compromise, an end-user may choose to update new root metadata with out-of-band  mechanisms.
The complete file snapshot (CFS) scheme uses file system directories to store efficient consistent snapshots over time. In this scheme, every consistent snapshot will be stored in a separate directory, wherein files that are shared with previous consistent snapshots will be hard links  instead of copies.
The differential file  snapshot (DFS) scheme is a variant of the CFS scheme, wherein the next consistent snapshot directory will contain only the additions of new files and updates to existing files of the previous consistent snapshot. (The first consistent snapshot will contain a complete set of files known then.) Deleted files will be marked as such in the next consistent snapshot directory. This means that files will be resolved in this manner: First, set the current consistent snapshot directory to be the latest consistent snapshot directory. Then, any requested file will be seeked in the current consistent snapshot directory. If the file exists in the current consistent snapshot directory, then that file will be returned. If it has been marked as deleted in the current consistent snapshot directory, then that file will be reported as missing. Otherwise, the current consistent snapshot directory will be set to the preceding consistent snapshot directory and the previous few steps will be iterated until there is no preceding consistent snapshot to be considered, at which point the file will be reported as missing.
With the CFS scheme, the trade-off is the I/O costs of producing a consistent snapshot with the file system. As of October 2013, we found that a fairly modern computer with a 7200RPM hard disk drive required at least three minutes to produce a consistent snapshot with the "cp -lr" command on the ext3  file system. Perhaps the I/O costs of this scheme may be ameliorated with advanced tools or file systems such as ZFS  or btrfs .
While the DFS scheme improves upon the CFS scheme in terms of producing faster consistent snapshots, there are at least two trade-offs. The first is that a web server will need to be modified to perform the "daisy chain" resolution of a file. The second is that every now and then, the differential snapshots will need to be "squashed" or merged together with the first consistent snapshot to produce a new first consistent snapshot with the latest and complete set of files. Although the merge cost may be amortized over time, this scheme is not conceptually si
|||(1, 2, 3, 4) https://isis.poly.edu/~jcappos/papers/samuel_tuf_ccs_2010.pdf|
|||(1, 2) PEP 381, Mirroring infrastructure for PyPI, Ziadé, Löwis http://www.python.org/dev/peps/pep-0381/|
|||PEP 449, Removal of the PyPI Mirror Auto Discovery and Naming Scheme, Stufft http://www.python.org/dev/peps/pep-0449/|
|||(1, 2) https://mail.python.org/pipermail/distutils-sig/2013-September/022755.html|
|||(1, 2) https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt|
|||(1, 2, 3, 4, 5) PEP 426, Metadata for Python Software Packages 2.0, Coghlan, Holth, Stufft http://www.python.org/dev/peps/pep-0426/|
|||(1, 2) https://en.wikipedia.org/wiki/Collision_(computer_science)|
Nick Coghlan, Daniel Holth and the distutils-sig community in general for helping us to think about how to usably and efficiently integrate TUF with PyPI.
Roger Dingledine, Sebastian Hahn, Nick Mathewson, Martin Peck and Justin Samuel for helping us to design TUF from its predecessor Thandy of the Tor project.
Konstantin Andrianov, Geremy Condra, Vladimir Diaz, Zane Fisher, Justin Samuel, Tian Tian, Santiago Torres, John Ward, and Yuyu Zheng for helping us to develop TUF.
Vladimir Diaz, Monzur Muhammad and Sai Teja Peddinti for helping us to review this PEP.
Zane Fisher for helping us to review and transcribe this PEP.
This document has been placed in the public domain.