tuf

README

GOTUF

This is still a work in progress but will shortly be a fully compliant Go implementation of The Update Framework (TUF).

Where's the CLI

This repository provides a library only. The Notary project from Docker should be considered the official CLI to be used with this implementation of TUF.

TODOs:

• Add Targets to existing repo
• Sign metadata files
• Refactor TufRepo to take care of signing and verification
• Ensure consistent capitalization in naming (TUF___ vs Tuf___)
• Make caching of metadata files smarter - PR #5
• Add configuration for CLI commands. Order of configuration priority from most to least: flags, config file, defaults Notary should be the official CLI
• Reasses organization of data types. Possibly consolidate a few things into the data package but break up package into a few more distinct files
• Comprehensive test cases
• Delete files no longer in use
• Fix up errors. Some have to be instantiated, others don't, the inconsistency is annoying.
• Bump version numbers in meta files (could probably be done better)

Credits

This implementation was originally forked from flynn/go-tuf, however in attempting to add delegations I found I was making such significant changes that I could not maintain backwards compatibility without the code becoming overly convoluted.

Some features such as pluggable verifiers have already been merged upstream to flynn/go-tuf and we are in discussion with titanous about working to merge the 2 implementations.

This implementation retains the same 3 Clause BSD license present on the original flynn implementation.

Documentation

Overview

Package tuf defines the core TUF logic around manipulating a repo.

Index

• type ErrLocalRootExpired
  • func (e ErrLocalRootExpired) Error() string
• type ErrMetaExpired
  • func (e ErrMetaExpired) Error() string
• type ErrNotLoaded
  • func (err ErrNotLoaded) Error() string
• type ErrSigVerifyFail
  • func (e ErrSigVerifyFail) Error() string
• type Repo
  • func NewRepo(cryptoService signed.CryptoService) *Repo
  • func (tr *Repo) AddBaseKeys(role string, keys ...data.PublicKey) error
  • func (tr *Repo) AddTargets(role string, targets data.Files) (data.Files, error)
  • func (tr *Repo) DeleteDelegation(roleName string) error
  • func (tr *Repo) GetAllLoadedRoles() []*data.Role
  • func (tr *Repo) GetBaseRole(name string) (data.BaseRole, error)
  • func (tr *Repo) GetDelegationRole(name string) (data.DelegationRole, error)
  • func (tr *Repo) InitRoot(root, timestamp, snapshot, targets data.BaseRole, consistent bool) error
  • func (tr *Repo) InitSnapshot() error
  • func (tr *Repo) InitTargets(role string) (*data.SignedTargets, error)
  • func (tr *Repo) InitTimestamp() error
  • func (tr *Repo) RemoveBaseKeys(role string, keyIDs ...string) error
  • func (tr *Repo) RemoveTargets(role string, targets ...string) error
  • func (tr *Repo) ReplaceBaseKeys(role string, keys ...data.PublicKey) error
  • func (tr *Repo) SetRoot(s *data.SignedRoot) error
  • func (tr *Repo) SetSnapshot(s *data.SignedSnapshot) error
  • func (tr *Repo) SetTargets(role string, s *data.SignedTargets) error
  • func (tr *Repo) SetTimestamp(s *data.SignedTimestamp) error
  • func (tr *Repo) SignRoot(expires time.Time) (*data.Signed, error)
  • func (tr *Repo) SignSnapshot(expires time.Time) (*data.Signed, error)
  • func (tr *Repo) SignTargets(role string, expires time.Time) (*data.Signed, error)
  • func (tr *Repo) SignTimestamp(expires time.Time) (*data.Signed, error)
  • func (tr Repo) TargetDelegations(role, path string) []*data.Role
  • func (tr Repo) TargetMeta(role, path string) *data.FileMeta
  • func (tr *Repo) UpdateDelegationKeys(roleName string, addKeys data.KeyList, removeKeys []string, newThreshold int) error
  • func (tr *Repo) UpdateDelegationPaths(roleName string, addPaths, removePaths []string, clearPaths bool) error
  • func (tr *Repo) UpdateSnapshot(role string, s *data.Signed) error
  • func (tr *Repo) UpdateTimestamp(s *data.Signed) error
  • func (tr *Repo) VerifyCanSign(roleName string) error
  • func (tr *Repo) WalkTargets(targetPath, rolePath string, visitTargets walkVisitorFunc, skipRoles ...string) error
• type StopWalk

Types

type ErrLocalRootExpired

type ErrLocalRootExpired struct{}

ErrLocalRootExpired - the local root file is out of date

func (ErrLocalRootExpired) Error

func (e ErrLocalRootExpired) Error() string

type ErrMetaExpired

type ErrMetaExpired struct{}

ErrMetaExpired - metadata file has expired

func (ErrMetaExpired) Error

func (e ErrMetaExpired) Error() string

type ErrNotLoaded

type ErrNotLoaded struct {
	Role string
}

ErrNotLoaded - attempted to access data that has not been loaded into the repo. This means specifically that the relevant JSON file has not been loaded.

func (ErrNotLoaded) Error

func (err ErrNotLoaded) Error() string

type ErrSigVerifyFail

type ErrSigVerifyFail struct{}

ErrSigVerifyFail - signature verification failed

func (ErrSigVerifyFail) Error

func (e ErrSigVerifyFail) Error() string

type Repo

type Repo struct {
	Root      *data.SignedRoot
	Targets   map[string]*data.SignedTargets
	Snapshot  *data.SignedSnapshot
	Timestamp *data.SignedTimestamp
	// contains filtered or unexported fields
}

Repo is an in memory representation of the TUF Repo. It operates at the data.Signed level, accepting and producing data.Signed objects. Users of a Repo are responsible for fetching raw JSON and using the Set* functions to populate the Repo instance.

func NewRepo

func NewRepo(cryptoService signed.CryptoService) *Repo

NewRepo initializes a Repo instance with a CryptoService. If the Repo will only be used for reading, the CryptoService can be nil.

func (*Repo) AddBaseKeys

func (tr *Repo) AddBaseKeys(role string, keys ...data.PublicKey) error

AddBaseKeys is used to add keys to the role in root.json

func (*Repo) AddTargets

func (tr *Repo) AddTargets(role string, targets data.Files) (data.Files, error)

AddTargets will attempt to add the given targets specifically to the directed role. If the metadata for the role doesn't exist yet, AddTargets will create one.

func (*Repo) DeleteDelegation

func (tr *Repo) DeleteDelegation(roleName string) error

DeleteDelegation removes a delegated targets role from its parent targets object. It also deletes the delegation from the snapshot. DeleteDelegation will only make use of the role Name field.

func (*Repo) GetAllLoadedRoles

func (tr *Repo) GetAllLoadedRoles() []*data.Role

GetAllLoadedRoles returns a list of all role entries loaded in this TUF repo, could be empty

func (*Repo) GetBaseRole

func (tr *Repo) GetBaseRole(name string) (data.BaseRole, error)

GetBaseRole gets a base role from this repo's metadata

func (*Repo) GetDelegationRole

func (tr *Repo) GetDelegationRole(name string) (data.DelegationRole, error)

GetDelegationRole gets a delegation role from this repo's metadata, walking from the targets role down to the delegation itself

func (*Repo) InitRoot

func (tr *Repo) InitRoot(root, timestamp, snapshot, targets data.BaseRole, consistent bool) error

InitRoot initializes an empty root file with the 4 core roles passed to the method, and the consistent flag.

func (*Repo) InitSnapshot

func (tr *Repo) InitSnapshot() error

InitSnapshot initializes a snapshot based on the current root and targets

func (*Repo) InitTargets

func (tr *Repo) InitTargets(role string) (*data.SignedTargets, error)

InitTargets initializes an empty targets, and returns the new empty target

func (*Repo) InitTimestamp

func (tr *Repo) InitTimestamp() error

InitTimestamp initializes a timestamp based on the current snapshot

func (*Repo) RemoveBaseKeys

func (tr *Repo) RemoveBaseKeys(role string, keyIDs ...string) error

RemoveBaseKeys is used to remove keys from the roles in root.json

func (*Repo) RemoveTargets

func (tr *Repo) RemoveTargets(role string, targets ...string) error

RemoveTargets removes the given target (paths) from the given target role (delegation)

func (*Repo) ReplaceBaseKeys

func (tr *Repo) ReplaceBaseKeys(role string, keys ...data.PublicKey) error

ReplaceBaseKeys is used to replace all keys for the given role with the new keys

func (*Repo) SetRoot

func (tr *Repo) SetRoot(s *data.SignedRoot) error

SetRoot sets the Repo.Root field to the SignedRoot object.

func (*Repo) SetSnapshot

func (tr *Repo) SetSnapshot(s *data.SignedSnapshot) error

SetSnapshot parses the Signed object into a SignedSnapshots object and sets the Repo.Snapshot field.

func (*Repo) SetTargets

func (tr *Repo) SetTargets(role string, s *data.SignedTargets) error

SetTargets sets the SignedTargets object agaist the role in the Repo.Targets map.

func (*Repo) SetTimestamp

func (tr *Repo) SetTimestamp(s *data.SignedTimestamp) error

SetTimestamp parses the Signed object into a SignedTimestamp object and sets the Repo.Timestamp field.

func (*Repo) SignRoot

func (tr *Repo) SignRoot(expires time.Time) (*data.Signed, error)

SignRoot signs the root, using all keys from the "root" role (i.e. currently trusted) as well as available keys used to sign the previous version, if the public part is carried in tr.Root.Keys and the private key is available (i.e. probably previously trusted keys, to allow rollover). If there are any errors, attempt to put root back to the way it was (so version won't be incremented, for instance).

func (*Repo) SignSnapshot

func (tr *Repo) SignSnapshot(expires time.Time) (*data.Signed, error)

SignSnapshot updates the snapshot based on the current targets and root then signs it

func (*Repo) SignTargets

func (tr *Repo) SignTargets(role string, expires time.Time) (*data.Signed, error)

SignTargets signs the targets file for the given top level or delegated targets role

func (*Repo) SignTimestamp

func (tr *Repo) SignTimestamp(expires time.Time) (*data.Signed, error)

SignTimestamp updates the timestamp based on the current snapshot then signs it

func (Repo) TargetDelegations

func (tr Repo) TargetDelegations(role, path string) []*data.Role

TargetDelegations returns a slice of Roles that are valid publishers for the target path provided.

func (Repo) TargetMeta

func (tr Repo) TargetMeta(role, path string) *data.FileMeta

TargetMeta returns the FileMeta entry for the given path in the targets file associated with the given role. This may be nil if the target isn't found in the targets file.

func (*Repo) UpdateDelegationKeys

func (tr *Repo) UpdateDelegationKeys(roleName string, addKeys data.KeyList, removeKeys []string, newThreshold int) error

UpdateDelegationKeys updates the appropriate delegations, either adding a new delegation or updating an existing one. If keys are provided, the IDs will be added to the role (if they do not exist there already), and the keys will be added to the targets file.

func (*Repo) UpdateDelegationPaths

func (tr *Repo) UpdateDelegationPaths(roleName string, addPaths, removePaths []string, clearPaths bool) error

UpdateDelegationPaths updates the appropriate delegation's paths. It is not allowed to create a new delegation.

func (*Repo) UpdateSnapshot

func (tr *Repo) UpdateSnapshot(role string, s *data.Signed) error

UpdateSnapshot updates the FileMeta for the given role based on the Signed object

func (*Repo) UpdateTimestamp

func (tr *Repo) UpdateTimestamp(s *data.Signed) error

UpdateTimestamp updates the snapshot meta in the timestamp based on the Signed object

func (*Repo) VerifyCanSign

func (tr *Repo) VerifyCanSign(roleName string) error

VerifyCanSign returns nil if the role exists and we have at least one signing key for the role, false otherwise. This does not check that we have enough signing keys to meet the threshold, since we want to support the use case of multiple signers for a role. It returns an error if the role doesn't exist or if there are no signing keys.

func (*Repo) WalkTargets

func (tr *Repo) WalkTargets(targetPath, rolePath string, visitTargets walkVisitorFunc, skipRoles ...string) error

WalkTargets will apply the specified visitor function to iteratively walk the targets/delegation metadata tree, until receiving a StopWalk. The walk starts from the base "targets" role, and searches for the correct targetPath and/or rolePath to call the visitor function on. Any roles passed into skipRoles will be excluded from the walk, as well as roles in those subtrees

type StopWalk

type StopWalk struct{}

StopWalk - used by visitor functions to signal WalkTargets to stop walking