tuf

README

tuf

This package implements TUF clients for http and oci data sources.

Documentation

Index

• Constants
• Variables
• func GetEmbeddedRoot(root string) (*embed.EmbeddedRoot, error)
• type Client
  • func NewClient(ctx context.Context, opts *ClientOptions) (*Client, error)
  • func (t *Client) DownloadTarget(target string, filePath string) (file *TargetFile, err error)
  • func (t *Client) GetMetadata() trustedmetadata.TrustedMetadata
  • func (t *Client) GetPriorRoots(metadataURL string) (map[string][]byte, error)
  • func (t *Client) LoadDelegatedTargets(roleName, parentName string) (*metadata.Metadata[metadata.TargetsType], error)
  • func (t *Client) MaxRootLength() int64
  • func (t *Client) SetRemoteTargetsURL(url string)
• type ClientOptions
  • func NewDockerDefaultClientOptions(tufPath string) *ClientOptions
• type DefaultVersionChecker
  • func NewDefaultVersionChecker() *DefaultVersionChecker
  • func (vc *DefaultVersionChecker) CheckVersion(client Downloader) error
• type Downloader
• type ImageCache
  • func NewImageCache() *ImageCache
  • func (c *ImageCache) Get(imgRef string) ([]byte, bool)
  • func (c *ImageCache) Put(imgRef string, img []byte)
• type InvalidVersionError
  • func (e *InvalidVersionError) Error() string
• type Layer
• type Layers
• type MockTufClient
  • func NewMockTufClient(srcPath string) *MockTufClient
  • func (dc *MockTufClient) DownloadTarget(target string, _ string) (file *TargetFile, err error)
• type MockVersionChecker
  • func NewMockVersionChecker() *MockVersionChecker
  • func (vc *MockVersionChecker) CheckVersion(_ Downloader) error
• type RegistryFetcher
  • func NewRegistryFetcher(ctx context.Context, cfg *config.UpdaterConfig) (*RegistryFetcher, error)
  • func (d *RegistryFetcher) DownloadFile(urlPath string, maxLength int64, timeout time.Duration) ([]byte, error)
• type Role
• type Source
• type TargetFile
• type VersionChecker

Examples

• NewClient (Registry)

Constants

const (
	HTTPSource Source = "http"
	OCISource  Source = "oci"
	LatestTag  string = "latest"
)

const (
	TUFFileNameAnnotation = "tuf.io/filename"
)

const ThisModulePath = "github.com/docker/attest"

Variables

var (
	DockerTUFRootProd    = embed.RootProd
	DockerTUFRootStaging = embed.RootStaging
	DockerTUFRootDev     = embed.RootDev
	DockerTUFRootDefault = embed.RootDefault
)

var Roles = []Role{metadata.ROOT, metadata.SNAPSHOT, metadata.TARGETS, metadata.TIMESTAMP}

Functions

func GetEmbeddedRoot

func GetEmbeddedRoot(root string) (*embed.EmbeddedRoot, error)

GetEmbeddedRoot returns the embedded TUF root based on the given root name.

Types

type Client

type Client struct {
	// contains filtered or unexported fields
}

func NewClient

func NewClient(ctx context.Context, opts *ClientOptions) (*Client, error)

NewClient creates a new TUF client.

Example (Registry)

package main

import (
	"context"
	"os"
	"path/filepath"

	"github.com/docker/attest/tuf"
	"github.com/theupdateframework/go-tuf/v2/metadata"
)

func main() {
	// create a tuf client
	home, err := os.UserHomeDir()
	if err != nil {
		panic(err)
	}
	tufOutputPath := filepath.Join(home, ".docker", "tuf")

	opts := tuf.NewDockerDefaultClientOptions(tufOutputPath)
	registryClient, err := tuf.NewClient(context.Background(), opts)
	if err != nil {
		panic(err)
	}

	// get trusted tuf metadata
	trustedMetadata := registryClient.GetMetadata()

	// top-level target files
	targets := trustedMetadata.Targets[metadata.TARGETS].Signed.Targets

	for _, t := range targets {
		// download target files
		_, err := registryClient.DownloadTarget(t.Path, filepath.Join(tufOutputPath, "download"))
		if err != nil {
			panic(err)
		}
	}
}

func (*Client) DownloadTarget

func (t *Client) DownloadTarget(target string, filePath string) (file *TargetFile, err error)

DownloadTarget downloads the target file using Updater. The Updater gets the target information, verifies if the target is already cached, and if it is not cached, downloads the target file.

func (*Client) GetMetadata

func (t *Client) GetMetadata() trustedmetadata.TrustedMetadata

func (*Client) GetPriorRoots

func (t *Client) GetPriorRoots(metadataURL string) (map[string][]byte, error)

func (*Client) LoadDelegatedTargets

func (t *Client) LoadDelegatedTargets(roleName, parentName string) (*metadata.Metadata[metadata.TargetsType], error)

Derived from updater.loadTargets() in theupdateframework/go-tuf.

func (*Client) MaxRootLength

func (t *Client) MaxRootLength() int64

func (*Client) SetRemoteTargetsURL

func (t *Client) SetRemoteTargetsURL(url string)

type ClientOptions

type ClientOptions struct {
	// InitialRoot is the initial root.json file to use for the TUF client.
	InitialRoot []byte
	// LocalStorageDir is the directory where the TUF client will cache any downloaded metadata and target files.
	LocalStorageDir string
	// MetadataSource is the source of the metadata files.
	MetadataSource string
	// TargetsSource is the source of the target files.
	TargetsSource string
	// VersionChecker checks if the current version of this library meets the constraints from the TUF repo.
	VersionChecker VersionChecker
	// PathPrefix is the prefix to prepend to all target paths before downloading.
	PathPrefix string
}

ClientOptions contains the options for creating a new TUF client.

func NewDockerDefaultClientOptions

func NewDockerDefaultClientOptions(tufPath string) *ClientOptions

type DefaultVersionChecker

type DefaultVersionChecker struct {
	VersionFetcher version.Fetcher
}

func NewDefaultVersionChecker

func NewDefaultVersionChecker() *DefaultVersionChecker

func (*DefaultVersionChecker) CheckVersion

func (vc *DefaultVersionChecker) CheckVersion(client Downloader) error

type Downloader

type Downloader interface {
	DownloadTarget(target, filePath string) (file *TargetFile, err error)
}

type ImageCache

type ImageCache struct {
	// contains filtered or unexported fields
}

func NewImageCache

func NewImageCache() *ImageCache

func (*ImageCache) Get

func (c *ImageCache) Get(imgRef string) ([]byte, bool)

Get image from cache.

func (*ImageCache) Put

func (c *ImageCache) Put(imgRef string, img []byte)

Add image to cache.

type InvalidVersionError

type InvalidVersionError struct {
	AttestVersion     string
	VersionConstraint string
	Errors            []error
}

func (*InvalidVersionError) Error

func (e *InvalidVersionError) Error() string

type Layer

type Layer struct {
	Annotations map[string]string `json:"annotations"`
	Digest      string            `json:"digest"`
}

type Layers

type Layers struct {
	Layers    []Layer `json:"layers"`
	Manifests []Layer `json:"manifests"`
	MediaType string  `json:"mediaType"`
}

type MockTufClient

type MockTufClient struct {
	// contains filtered or unexported fields
}

func NewMockTufClient

func NewMockTufClient(srcPath string) *MockTufClient

func (*MockTufClient) DownloadTarget

func (dc *MockTufClient) DownloadTarget(target string, _ string) (file *TargetFile, err error)

type MockVersionChecker

type MockVersionChecker struct {
	// contains filtered or unexported fields
}

func NewMockVersionChecker

func NewMockVersionChecker() *MockVersionChecker

func (*MockVersionChecker) CheckVersion

func (vc *MockVersionChecker) CheckVersion(_ Downloader) error

type RegistryFetcher

type RegistryFetcher struct {
	// contains filtered or unexported fields
}

RegistryFetcher implements Fetcher.

func NewRegistryFetcher

func NewRegistryFetcher(ctx context.Context, cfg *config.UpdaterConfig) (*RegistryFetcher, error)

func (*RegistryFetcher) DownloadFile

func (d *RegistryFetcher) DownloadFile(urlPath string, maxLength int64, timeout time.Duration) ([]byte, error)

DownloadFile downloads a file from an OCI registry, errors out if it failed, its length is larger than maxLength or the timeout is reached.

type Role

type Role string

type Source

type Source string

type TargetFile

type TargetFile struct {
	ActualFilePath string
	TargetURI      string
	Digest         string
	Data           []byte
}

type VersionChecker

type VersionChecker interface {
	// CheckVersion checks if the current version of this library meets the constraints from the TUF repo
	CheckVersion(tufClient Downloader) error
}