Python-TUF Documentation

Python-TUF is a reference implementation of The Update Framework (TUF) specification v1.0. It provides three primary API layers for different use cases:

• tuf.api.metadata: A low-level API designed for safe access to TUF metadata and handling (de)serialization to and from files.
• tuf.ngclient: A high-level client implementation built on top of the metadata API, suitable for consuming updates.
• tuf.repository: A library for managing repositories, built on top of the metadata API. Note: This module is currently not considered part of the stable API.

The examples/ directory contains several practical implementations and usage patterns for the TUF Python library, categorized by their role in the update lifecycle:

• Repository examples: Demonstrates how to set up and manage a TUF repository.
• Client examples: Shows how to use the TUF client to securely fetch updates.
• Uploader tool examples: Demonstrates how to use tools to upload new software versions to a repository.
• Low-level Metadata API examples: Provides examples for interacting directly with TUF metadata structures.

The tuf.ngclient module provides a complete implementation of a TUF client. It is composed of three primary components depending on your integration needs:

• tuf.ngclient.updater: Implements the standard, detailed TUF client workflow. This is the primary entry point for most users looking to perform updates.
• tuf.ngclient.config: Provides optional configuration settings to customize the behavior of the updater.
• tuf.ngclient.fetcher: Provides low-level network I/O control. Use this if you need to implement custom logic for how metadata and targets are retrieved from a repository.

The FetcherInterface allows developers to provide custom implementations for downloading metadata and target files. This is particularly useful for integrating TUF into existing ecosystems that require specific HTTP configurations or custom download logic (such as pip).

By implementing the FetcherInterface, you can control how the Updater retrieves data from remote repositories.

Since the 1.0 release, python-tuf provides two stable, distinct APIs designed for developer ergonomics and flexibility:

1. Low-level interface: Used for the manual creation and consumption of TUF metadata.
2. Client implementation: A robust, pluggable client designed for end-users to consume updates securely.

These APIs were introduced during a significant refactoring effort to make the codebase leaner and more modular.

The python-tuf repository design is moving away from large, monolithic implementations (like the legacy repo.py or repository_tool.py) toward a minimal repository abstraction.

Instead of a library that makes all application-level decisions, the new design provides a tiny API that focuses on core, canonical TUF functionality (such as core snapshot updates) while leaving implementation-specific decisions to the developer. This allows the same core code to be used across diverse environments, from simple CLI tools to large-scale application servers.

Decisions left to the implementer (not the library):

• How targets are stored.
• Which versions of metadata are retained.
• When to load or unload metadata.
• When to bump metadata versions.
• Determining new expiry dates.
• Selecting which target versions are included in a new snapshot.

The Repository API requires a Keyring abstraction. This allows the repository to look up the appropriate private keys for signing roles without the repository implementation needing to know how keys are stored.

Common implementation patterns include:

• File-based keyring: For local development or testing.
• Environment-variable keyring: For use in CI/CD pipelines.
• Hardware/Secret Managers: For production environments.

When loading TUF metadata files, the library accepts and preserves unrecognized fields to ensure backward compatibility and prevent unintended file modifications.

If you read a metadata file containing fields not currently recognized by your version of the library and immediately write it back to disk, the file content (and its checksum) will remain unchanged. This behavior supports the extensibility of the TUF specification, allowing new fields to be introduced without breaking older clients.

Exceptions: Unrecognized fields are not supported in specific dictionary-based structures where the concept of an 'unrecognized field' is not applicable according to the specification. These include:

• keys
• roles
• meta
• hashes
• targets

The tuf project follows a best-effort support policy for older release series (specifically the 0.x series).

If you are using a version of tuf prior to 1.0.0:

• Bug Fixes: Bugs reported in these versions will likely not be addressed directly by maintainers.
• Contributions: Pull Requests (PRs) aimed at fixing bugs in the last release prior to 1.0.0 may be considered and merged, subject to standard review processes. However, expect potential delays in review due to limited developer resources.

The RepositorySimulator is a testing utility that allows you to simulate a TUF repository in memory. It is designed to help developers test complex security edge cases by providing control over metadata versions, signatures, and time-based properties without requiring actual network connections or file system access.

Key capabilities include:

• Modifying repository metadata.
• Signing and storing new role versions.
• Serving older versions of metadata to simulate update chains.
• Simulating remote metadata downloads.
• Modifying expiry dates and simulating time travel.

To audit the state of a simulated repository, you can use the --dump flag to write the in-memory repository contents to a temporary directory on the local filesystem. The directory structure will contain /metadata/... and /targets/... paths.