mirror

README

mirror

This package contains components to mirror TUF metadata and targets to OCI.

Documentation

Index

• Constants
• Variables
• type DelegatedTargetMetadata
• type Image
• type Index
• type TUFMetadata
• type TUFMirror
  • func NewTUFMirror(root []byte, tufPath, metadataURL, targetsURL string, ...) (*TUFMirror, error)
  • func (m *TUFMirror) GetDelegatedMetadataMirrors() ([]*Image, error)
  • func (m *TUFMirror) GetDelegatedTargetMirrors() ([]*Index, error)
  • func (m *TUFMirror) GetMetadataManifest(metadataURL string) (*oci.EmptyConfigImage, error)
  • func (m *TUFMirror) GetTUFTargetMirrors() ([]*Image, error)
• type TUFRole

Examples

• NewTUFMirror

Constants

const (
	DefaultMetadataURL = "https://docker.github.io/tuf/metadata"
	DefaultTargetsURL  = "https://docker.github.io/tuf/targets"
)

Variables

var TUFRoles = []TUFRole{metadata.ROOT, metadata.SNAPSHOT, metadata.TARGETS, metadata.TIMESTAMP}

Types

type DelegatedTargetMetadata

type DelegatedTargetMetadata struct {
	Name    string
	Version string
	Data    []byte
}

type Image

type Image struct {
	Image *oci.EmptyConfigImage
	Tag   string
}

type Index

type Index struct {
	Index v1.ImageIndex
	Tag   string
}

type TUFMetadata

type TUFMetadata struct {
	Root      map[string][]byte
	Snapshot  map[string][]byte
	Targets   map[string][]byte
	Timestamp []byte
}

type TUFMirror

type TUFMirror struct {
	TUFClient *tuf.Client
	// contains filtered or unexported fields
}

func NewTUFMirror

func NewTUFMirror(root []byte, tufPath, metadataURL, targetsURL string, versionChecker tuf.VersionChecker) (*TUFMirror, error)

Example

package main

import (
	"fmt"
	"os"
	"path/filepath"
	"strings"

	"github.com/docker/attest/pkg/mirror"
	"github.com/docker/attest/pkg/oci"
	"github.com/docker/attest/pkg/tuf"
	v1 "github.com/google/go-containerregistry/pkg/v1"
)

type TufMirrorOutput struct {
	metadata          v1.Image
	delegatedMetadata []*mirror.Image
	targets           []*mirror.Image
	delegatedTargets  []*mirror.Index
}

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

	// configure TUF mirror
	metadataURI := "https://docker.github.io/tuf-staging/metadata"
	targetsURI := "https://docker.github.io/tuf-staging/targets"
	m, err := mirror.NewTUFMirror(tuf.DockerTUFRootStaging.Data, tufOutputPath, metadataURI, targetsURI, tuf.NewMockVersionChecker())
	if err != nil {
		panic(err)
	}

	// create metadata manifest
	metadataManifest, err := m.GetMetadataManifest(metadataURI)
	if err != nil {
		panic(err)
	}
	// create delegated targets metadata manifests
	delegatedMetadata, err := m.GetDelegatedMetadataMirrors()
	if err != nil {
		panic(err)
	}

	// create targets manifest
	targets, err := m.GetTUFTargetMirrors()
	if err != nil {
		panic(err)
	}
	// create delegated targets manifests
	delegatedTargets, err := m.GetDelegatedTargetMirrors()
	if err != nil {
		panic(err)
	}

	mirrorOutput := &TufMirrorOutput{
		metadata:          metadataManifest,
		delegatedMetadata: delegatedMetadata,
		targets:           targets,
		delegatedTargets:  delegatedTargets,
	}

	// push metadata and targets to registry (optional)
	err = mirrorToRegistry(mirrorOutput)
	if err != nil {
		panic(err)
	}

	// save metadata and targets to local directory (optional)
	mirrorOutputPath := filepath.Join(home, ".docker", "tuf", "mirror")
	err = mirrorToLocal(mirrorOutput, mirrorOutputPath)
	if err != nil {
		panic(err)
	}
}

func mirrorToRegistry(o *TufMirrorOutput) error {
	// push metadata to registry
	metadataRepo := "registry-1.docker.io/docker/tuf-metadata:latest"
	err := oci.PushImageToRegistry(o.metadata, metadataRepo)
	if err != nil {
		return err
	}
	// push delegated metadata to registry
	for _, metadata := range o.delegatedMetadata {
		repo, _, ok := strings.Cut(metadataRepo, ":")
		if !ok {
			return fmt.Errorf("failed to get repo without tag: %s", metadataRepo)
		}
		imageName := fmt.Sprintf("%s:%s", repo, metadata.Tag)
		err = oci.PushImageToRegistry(metadata.Image, imageName)
		if err != nil {
			return err
		}
	}

	// push top-level targets to registry
	targetsRepo := "registry-1.docker.io/docker/tuf-targets"
	for _, target := range o.targets {
		imageName := fmt.Sprintf("%s:%s", targetsRepo, target.Tag)
		err = oci.PushImageToRegistry(target.Image, imageName)
		if err != nil {
			return err
		}
	}
	// push delegated targets to registry
	for _, target := range o.delegatedTargets {
		imageName := fmt.Sprintf("%s:%s", targetsRepo, target.Tag)
		err = oci.PushIndexToRegistry(target.Index, imageName)
		if err != nil {
			return err
		}
	}
	return nil
}

func mirrorToLocal(o *TufMirrorOutput, outputPath string) error {
	// output metadata to local directory
	err := oci.SaveImageAsOCILayout(o.metadata, outputPath)
	if err != nil {
		return err
	}
	// output delegated metadata to local directory
	for _, metadata := range o.delegatedMetadata {
		path := filepath.Join(outputPath, metadata.Tag)
		err = oci.SaveImageAsOCILayout(metadata.Image, path)
		if err != nil {
			return err
		}
	}

	// output top-level targets to local directory
	for _, target := range o.targets {
		path := filepath.Join(outputPath, target.Tag)
		err = oci.SaveImageAsOCILayout(target.Image, path)
		if err != nil {
			return err
		}
	}
	// output delegated targets to local directory
	for _, target := range o.delegatedTargets {
		path := filepath.Join(outputPath, target.Tag)
		err = oci.SaveIndexAsOCILayout(target.Index, path)
		if err != nil {
			return err
		}
	}
	return nil
}

func (*TUFMirror) GetDelegatedMetadataMirrors

func (m *TUFMirror) GetDelegatedMetadataMirrors() ([]*Image, error)

GetDelegatedMetadataMirrors returns a list of mirrors (image/tag pairs) for each delegated targets role metadata.

func (*TUFMirror) GetDelegatedTargetMirrors

func (m *TUFMirror) GetDelegatedTargetMirrors() ([]*Index, error)

GetDelegatedTargetMirrors returns a list of delegated target files as MirrorIndexes (image index with tag) each image in the index contains a delegated target file.

func (*TUFMirror) GetMetadataManifest

func (m *TUFMirror) GetMetadataManifest(metadataURL string) (*oci.EmptyConfigImage, error)

GetMetadataManifest returns an image with TUF root metadata as layers.

func (*TUFMirror) GetTUFTargetMirrors

func (m *TUFMirror) GetTUFTargetMirrors() ([]*Image, error)

GetTUFTargetMirrors returns a list of top-level target files as MirrorImages (image with tag).

type TUFRole

type TUFRole string