Skip to main content

TUF (The Update Framework) Management

go-tuf is an implementation of The Update Framework (TUF), a security-focused standard for securing software update systems. It helps prevent compromise of the update process by ensuring that clients can verify the authenticity and integrity of updates before installing them. This section describes how to use TUF with FaynoSync: enabling it on your instance, managing keys and metadata, and how it fits into your update workflow.

In FaynoSync, TUF metadata and related files on S3 are organized separately per administrator and per application name. Each app has its own TUF repository, so keys and metadata are isolated by account and app.

Key storage principles​

  • Private keys must be kept secret and must never be published or exposed.
  • Root keys should be stored on an offline system. They are used to establish trust and sign other keys; keeping them offline reduces the risk of compromise.
  • Keys for the targets, snapshot, and timestamp roles must be stored in the directory specified by the ONLINE_KEY_DIR environment variable, for example:
    • ONLINE_KEY_DIR=~/tuf_keys/private_keys

Enabling go-tuf on FaynoSync​

To enable TUF support on your FaynoSync instance, set:

  • TUF_ENABLED=true
  • ONLINE_KEY_DIR=~/tuf_keys/private_keys (or your chosen path for online signing keys)

Public metadata files are stored on S3 and are publicly accessible. They are signed with the private keys above; clients use these signed metadata files to verify that an update is trusted and that the build they download is the one intended by the publisher.

Metadata caching​

timestamp.json is the only metadata file that faynoSync overwrites under a fixed name, and it is the first file a TUF client fetches. faynoSync writes it with Cache-Control: public, max-age=60, must-revalidate, so clients and any CDN in front of the bucket see a new publish within about a minute. Versioned files (N.root.json, N.snapshot.json, N.targets.json and delegated roles) never change once written and keep the storage default, which lets them be cached for as long as the provider allows.

Caching cannot weaken verification: a client never accepts a timestamp older than the one it already trusts, and signatures and expiration are checked on every file. A cached timestamp.json only delays when clients notice a new release. If you put a CDN in front of the metadata, do not cache timestamp.json longer than its Cache-Control allows.

Client-side configuration​

TUF verification happens on the client application. Your app must be configured to consume TUF metadata and verify updates before applying them. Refer to the TUF documentation and the go-tuf client usage to learn how to configure your application for secure update verification.

The following API endpoints allow you to manage TUF bootstrap, metadata, configuration, and publishing within FaynoSync.

TUF endpoints​