go-tuf/v2

go-tuf/v2 is a lightweight Go library providing a framework for securing software update systems based on The Update Framework (TUF) specification. It is designed to protect against supply chain attacks and repository compromises.

Key capabilities include:

• Metadata Management: Creation, reading, writing, signing, and verifying of TUF metadata (supporting ED25519, RSA, and ECDSA).
• Delegation Support: Top-level role delegation, target delegation (standard and hash bin), and succinct hash bin delegations.
• Client APIs: A standard TUF client API via the updater package and a multi-repository client API via the multirepo package (implementing TAP 4).
• Resilience: Support for unrecognized fields in metadata to ensure forward compatibility and data preservation.

The tuf-client is a command-line interface tool that implements the client workflow specified by The Update Framework (TUF). It allows users to securely query for available targets and download them, ensuring all downloaded files are verified against signed metadata.

Key features:

• Secure target downloading via signed metadata verification.
• Three primary commands: init, get, and reset.
• Most commands require the --url or -u flag to specify the TUF repository metadata location.

The multirepo package implements TAP 4 (Multiple repository consensus on entrusted targets). In this architecture, a client bootstraps its trust by using a single trusted repository to obtain a map.json file and the root files for multiple distinct repositories.

Key components of this pattern include:

• Initialization: A trusted repository provides the map.json and the root files for all participating repositories.
• Target Distribution: The actual metadata, target files, and the scripts used to generate them are distributed across the various individual repositories.
• Consensus: The client uses the mapping provided by the trusted repository to coordinate trust across multiple sources.

To build a software update client, use the metadata/updater/updater.go package. This package allows you to initialize a client and securely download target files.

Key capabilities demonstrated in the client implementation include:

• Client Initialization: Setting up the client to point to a TUF repository.
• Target Downloads: Securely fetching specific target files.
• Interoperability: The implementation is compatible with other TUF implementations (such as python-tuf).

Refer to client/client_example.go for a complete implementation example using a live repository.

Use the init command to set up the client with trusted metadata. You can initialize either by providing a local root.json file or by pointing to a remote URL.

Initialize with a local root.json: Use the -f flag to specify the path to your root.json file.

Initialize from a remote URL: Provide the metadata URL using the --url flag. If no local file is provided, the client will fetch the necessary metadata from the specified URL.

# Initialize by providing a root.json
tuf-client init --url https://jku.github.io/tuf-demo/metadata -f root.json

# Initialize without providing a root.json
tuf-client init --url https://jku.github.io/tuf-demo/metadata

For scenarios requiring consensus across multiple repositories, use the metadata/multirepo/multirepo.go package. This package implements TAP 4 - Multiple repository consensus on entrusted targets.

Workflow for bootstrapping a multi-repository client:

1. Distribution: Distribute a map.json file along with the root files for each individual repository via a trusted repository used for initialization.
2. Bootstrapping: Use these distributed files to bootstrap the multi-repository TUF client.

Refer to multirepo/client/client_example.go for an example of the multirepo package API and the bootstrapping process.

To regenerate the helper TUF repository used for bootstrapping a multi-repository TUF client (TAP 4), run the generator from within the examples/multirepo/repository directory. This process generates the required metadata files in the metadata/ directory, creates the map.json file (which holds repository mappings), and copies the new root.json files to the client/ directory.

# Run from inside the examples/multirepo/repository directory
go run .

You can manually create and maintain TUF repository metadata by using the low-level Metadata API. This is useful for building custom repository management tools. The API supports:

• Metadata Lifecycle: Creation of top-level metadata and root key rotation.
• Target Management: Handling target files and target delegation.
• Security Features: Consistent snapshots, top-level delegation, and signing thresholds.
• Cryptographic Support: A mixture of key types including ED25519, RSA, and ECDSA.
• Signing & Verification: Metadata verification, as well as both in-band and out-of-band metadata signing.
• Persistence: Writing and reading metadata files.

Refer to repository/basic_repository.go for a concrete implementation example.

The following commands are available in the tuf-client CLI:

• init: Initialize the client with trusted root.json metadata.
• get: Download a target file.
• reset: Resets the local environment (deletes metadata and download folders).

Common Flags:

• --url, -u: The URL of the TUF repository metadata.
• -f: Path to a local root.json file (used with init).
• --turl: The URL where target files are located (used with get).
• --nonprefixed: Used with get for non-prefixed target files.