go-tuf: Open Source ERP & Operations

What is go-tuf?

go-tuf is the Go implementation of The Update Framework (TUF), a library for securing software update systems and other content delivery, and it is aimed at Go developers who need update clients and repositories that remain safe even when a repository or a signing key is compromised.

What it is

go-tuf v2 is a lightweight Go library implementing The Update Framework, a framework for secure content delivery and updates. It provides the machinery a developer would otherwise write by hand: creation, reading and writing of TUF metadata, an object-oriented approach for interacting with that metadata, signing and verifying it, consistent snapshots, and a client-side workflow that decides whether downloaded content is trustworthy. TUF itself is hosted by the Linux Foundation as part of the Cloud Native Computing Foundation, and its design is used in production by various tech companies and open-source organizations.

The problem it solves is supply chain compromise during update. TUF is designed so that a software update system keeps its security even against attackers who compromise the repository or the signing keys, which is the failure mode that ordinary signed-manifest schemes do not survive. go-tuf lives in the Go module ecosystem and replaces custom, project-specific update signing and verification code that teams would otherwise maintain themselves. It also implements the published TUF specification rather than a private variant, so metadata written by one TUF implementation can be consumed by another.

Key capabilities

Creates, reads and writes TUF metadata, exposing a low-level Metadata API and an object-oriented layer for maintaining repository metadata, demonstrated in examples/repository/basic_repository.go.
Signs and verifies TUF metadata using the ED25519, RSA and ECDSA key types referenced by the latest TUF specification.
Supports top-level role delegation together with target delegation through standard and hash bin delegations.
Supports succinct hash bin delegations, the mechanism described in TAP 15 that significantly reduces the size of TUF metadata.
Preserves unrecognized fields inside metadata, reachable as root.Signed.UnrecognizedFields["some-unknown-field"], and includes them when verifying or signing if they appear in the Signed portion.
Ships a TUF client API through the updater package at metadata/updater/updater.go, plus a multi-repository client API at metadata/multirepo/multirepo.go implementing TAP 4, multiple repository consensus on entrusted targets.
Provides tuf-client, a CLI at examples/cli/tuf-client/ that implements the client workflow specified by the TUF specification.

Who uses it and how

Go teams building an update or package distribution path who need metadata creation and maintenance through the low-level Metadata API; the basic_repository.go example shows manual repository metadata handling.
Client implementers who need to fetch and validate updates, using the updater package and the pattern in examples/client/client_example.go.
Organizations that cannot trust a single repository and need consensus across several, using the multi-repository TAP 4 client against the multirepo package.
Operators who want the client workflow without embedding the library, using the tuf-client CLI.
Projects inside the CNCF and Linux Foundation orbit, where TUF adoption is documented across tech companies and open-source organizations.

Getting started

Import the library as the Go module github.com/theupdateframework/go-tuf. Runnable examples come from the repository's Make targets: make example-repository, make example-client, make example-tuf-client-cli, and make example-multirepo, each writing its artifacts under examples/.

How it compares

No competing or paid product is named in the facts for this entry, so on this registry go-tuf stands alone rather than displacing a listed commercial alternative. Its differentiation is conformance to the published TUF specification and to the TAPs it implements, notably TAP 4 for multi-repository consensus and TAP 15 for succinct hash bin delegations, under Linux Foundation and CNCF stewardship.

When to use it — and when not to

Expect to operate key management and metadata publication yourself, because go-tuf is a library with examples and a CLI, not a hosted update service. Do not pick it if you want a turnkey signing server, or if nobody on the team can hold signing keys offline and reason about TUF roles and delegations. Also note the weak spots visible in the facts: the package documentation in the README is thin and trails off mid-description of the metadata package, so the pkg.go.dev reference and the examples are the real guides.

project readme (upstream, from github) — read inline

GitHub Workflow Status (with branch)

go-tuf/v2 - Framework for Securing Software Update Systems

The Update Framework (TUF) is a framework for secure content delivery and updates. It protects against various types of supply chain attacks and provides resilience to compromise.

About The Update Framework

The Update Framework (TUF) design helps developers maintain the security of a software update system, even against attackers that compromise the repository or signing keys. TUF provides a flexible specification defining functionality that developers can use in any software update system or re-implement to fit their needs.

TUF is hosted by the Linux Foundation as part of the Cloud Native Computing Foundation (CNCF) and its design is used in production by various tech companies and open-source organizations.

Please see TUF's website for more information about TUF!

Overview

The go-tuf v2 project provides a lightweight library with the following functionality:

creation, reading, and writing of TUF metadata
an easy object-oriented approach for interacting with TUF metadata
consistent snapshots
signing and verifying TUF metadata
ED25519, RSA, and ECDSA key types referenced by the latest TUF specification
top-level role delegation
target delegation via standard and hash bin delegations
support of succinct hash bin delegations which significantly reduce the size of the TUF metadata
support for unrecognized fields within the metadata (i.e. preserved and accessible through root.Signed.UnrecognizedFields["some-unknown-field"], also used for verifying/signing (if included in the Signed portion of the metadata))
TUF client API
TUF multi-repository client API (implements TAP 4 - Multiple repository consensus on entrusted targets)

Examples

There are several examples that can act as a guideline on how to use the library and its features. Some of which are:

basic_repository.go example which demonstrates how to manually create and maintain repository metadata using the low-level Metadata API.

To try it - run make example-repository (the artifacts will be located at examples/repository/).

client_example.go which demonstrates how to implement a client using the updater package.

To try it - run make example-client (the artifacts will be located at examples/client/)

tuf-client CLI - a CLI tool that implements the client workflow specified by The Update Framework (TUF) specification.

To try it - run make example-tuf-client-cli

multi-repository client example (TAP4) which demonstrates how to implement a multi-repository TUF client using the multirepo package.

To try it - run make example-multirepo

Package details

The `metadata` package

The metadata package provides access to a Metadata file abstraction that closely follows the TUF specification’s document formats. This API handles de/serialization to and from files and bytes. It also covers the process of creating and verifying metadata signatures and makes it easier to access and modify metadata content. It is purely focused on individual pieces of Metadata and provides no concepts like “repository” or “update workflow”.

The `trustedmetadata` package

A TrustedMetadata instance ensures that the collection of metadata in it is valid and trusted through the whole client update workflow. It provides easy ways to update the metadata with the caller making decisions on what is updated.

The `config` package

The config package stores configuration for an Updater instance.

The `fetcher` package

The fetcher package defines an interface for abstract network download.

The `updater` package

The updater package provides an implementation of the TUF client workflow. It provides ways to query and download target files securely while handling the TUF update workflow behind the scenes. It is implemented on top of the Metadata API and can be used to implement various TUF clients with relatively little effort.

The `multirepo` package

The multirepo package provides an implementation of TAP 4 - Multiple repository consensus on entrusted targets. It provides a secure search for particular targets across multiple repositories. It provides the functionality for how multiple repositories with separate roots of trust can be required to sign off on the same targets, effectively creating an AND relation and ensuring any files obtained can be trusted. It offers a way to initialize multiple repositories using a map.json file and also mechanisms to query and download target files securely. It is implemented on top of the Updater API and can be used to implement various multi-repository TUF clients with relatively little effort.

Documentation

History - legacy go-tuf vs go-tuf/v2

The legacy go-tuf (v0.7.0) codebase was difficult to maintain and prone to errors due to its initial design decisions. Now it is considered deprecated in favour of go-tuf v2 (originaly from rdimitrov/go-tuf-metadata) which started from the idea of providing a Go implementation of TUF that is heavily influenced by the design decisions made in python-tuf.

Contact

Questions, feedback, and suggestions are welcomed on the #tuf and/or #go-tuf channels on CNCF Slack.

We strive to make the specification easy to implement, so if you come across any inconsistencies or experience any difficulty, do let us know by sending an email, or by reporting an issue in the GitHub specification repo.

Frequently asked questions

Is go-tuf free to use?

go-tuf is open source under the Apache-2.0 licence. There is no licence fee and no seat count — you can self-host it or, where the project offers one, pay a vendor for a managed version instead.

What does go-tuf do?

Go implementation of The Update Framework (TUF)

What is go-tuf written in?

go-tuf is primarily written in Go. Its source is publicly available at https://github.com/theupdateframework/go-tuf, and it has 717 GitHub stars.