tuf

Documentation

Index

• type Client
  • func NewClient(settings *Settings, opts ...Option) (*Client, error)
  • func (c *Client) Download(targetName string, destination io.Writer) error
  • func (c *Client) Stop()
  • func (c *Client) Update() (files FimMap, latest bool, err error)
• type DelegationRole
• type Delegations
• type FileIntegrityMeta
  • func (fim FileIntegrityMeta) Equal(fimTarget FileIntegrityMeta) bool
• type FimMap
• type Key
• type KeyVal
• type NotificationHandler
• type Option
  • func WithAutoUpdate(targetName, stagingPath string, onUpdate NotificationHandler) Option
  • func WithBackupAge(age time.Duration) Option
  • func WithFrequency(duration time.Duration) Option
  • func WithHTTPClient(httpClient *http.Client) Option
  • func WithLogger(logger log.Logger) Option
• type Role
• type Root
• type RootTarget
• type Settings
• type Signature
• type SignedRoot
• type SignedSnapshot
• type SignedTarget
• type SignedTimestamp
• type Snapshot
• type Targets
• type Timestamp

Types

type Client

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

Client is a TUF client.

func NewClient

func NewClient(settings *Settings, opts ...Option) (*Client, error)

NewClient creates a TUF Client which can securely download packages from a remote mirror. The Client downloads payloads(also called targets) from a remote mirror, validating each payload according to the TUF spec. The Client uses a Docker Notary service to fetch TUF metadata files stored in the local repository.

You can use one of the provided Options to customize the client configuration.

func (*Client) Download

func (c *Client) Download(targetName string, destination io.Writer) error

Download downloads a local resource from a remote URL. Download will use local TUF metadata, so it's important to call Update before dowloading a new file.

func (*Client) Stop

func (c *Client) Stop()

Stop must be called when done with the updater.

func (*Client) Update

func (c *Client) Update() (files FimMap, latest bool, err error)

Update updates the local TUF metadata from a remote repository. If the update is successful, a list of files that have changed will be returned.

Update gets the current metadata from the notary repository and performs requisite checks and validations as specified in the TUF spec section 5.1 'The Client Application'. Note that we expect that we do not use consistent snapshots and delegations are not supported because for our purposes, both are unnecessary. See https://github.com/theupdateframework/tuf/blob/904fa9b8df8ab8c632a210a2b05fd741e366788a/docs/tuf-spec.txt

type DelegationRole

type DelegationRole struct {
	Role
	Name  string   `json:"name"`
	Paths []string `json:"paths"`
}

DelegationRole contains information about targets delegated to other mirrors.

type Delegations

type Delegations struct {
	Keys  map[keyID]Key    `json:"keys"`
	Roles []DelegationRole `json:"roles"`
}

Delegations contain signing information for targets hosted by external principals. Delegations are children of targets.

type FileIntegrityMeta

type FileIntegrityMeta struct {
	Hashes map[hashingMethod]string `json:"hashes"`
	Length int64                    `json:"length"`
}

FileIntegrityMeta hashes and length of a file based resource to help ensure the binary footprint of the file hasn't been tampered with

func (FileIntegrityMeta) Equal

func (fim FileIntegrityMeta) Equal(fimTarget FileIntegrityMeta) bool

Equal is deep comparison of two FileIntegrityMeta

type FimMap

type FimMap map[string]FileIntegrityMeta

FimMap is used to map paths to hashes and length information about that file which is used for verification purposes when the file is downloaded.

type Key

type Key struct {
	KeyType string `json:"keytype"`
	KeyVal  KeyVal `json:"keyval"`
}

Key signing key with key type

type KeyVal

type KeyVal struct {
	Private *string `json:"private"`
	Public  string  `json:"public"`
}

KeyVal the contents of the private and/or public keys

type NotificationHandler

type NotificationHandler func(stagingPath string, err error)

NotificationHandler gets called when the hosting application has a new version of a target that it needs to deal with. The hosting application will need to check the err object, if err is nil the stagingPath will point to a validated target which is the hosting application's responsibility to deal with.

type Option

type Option func(*Client)

Option allows customization of the Client.

func WithAutoUpdate

func WithAutoUpdate(targetName, stagingPath string, onUpdate NotificationHandler) Option

WithAutoUpdate specifies a target which will be auto-downloaded into a staging path by the client. WithAutoUpdate requires a NotificationHandler which will be called whenever there is a new upate. Use WithFrequency to configure how often the autoupdate goroutine runs. There can only be one NotificationHandler per Client.

func WithBackupAge

func WithBackupAge(age time.Duration) Option

WithBackupAge changes the amount of time that repository backup files are kept before being removed. Current default is one day.

func WithFrequency

func WithFrequency(duration time.Duration) Option

WithFrequency allows changing the frequency of autoupdate checks.

func WithHTTPClient

func WithHTTPClient(httpClient *http.Client) Option

WithHTTPClient configures a custom HTTP Client to be used by the Client.

func WithLogger

func WithLogger(logger log.Logger) Option

WithLogger configures a logger.

type Role

type Role struct {
	KeyIDs    []string `json:"keyids"`
	Threshold int      `json:"threshold"`
}

Role maps keys in role that are needed to check signatures.

type Root

type Root struct {
	Signed     SignedRoot  `json:"signed"`
	Signatures []Signature `json:"signatures"`
}

Root is the root role. It indicates which keys are authorized for all top-level roles, including the root role itself.

type RootTarget

type RootTarget struct {
	*Targets
	// contains filtered or unexported fields
}

RootTarget is the top level target it contains some bookeeping information about targets

type Settings

type Settings struct {
	// LocalRepoPath is the directory where we will cache TUF roles. This
	// directory should be seeded with TUF role files with 0600 permissions.
	LocalRepoPath string
	// NotaryURL is the base URL of the notary server where we get new
	// keys and update information.  i.e. https://notary.kolide.co. Must use
	// https scheme.
	NotaryURL string
	// MirrorURL is the base URL where distribution packages are found and
	// downloaded. Must use https scheme.
	MirrorURL string
	// GUN Globally Unique Identifier, an ID used by Notary to identify
	// a repository. Typically in the form organization/reponame/platform
	GUN string
}

Settings various parameters needed to find updates

type Signature

type Signature struct {
	KeyID         keyID         `json:"keyid"`
	SigningMethod signingMethod `json:"method"`
	Value         string        `json:"sig"`
}

Signature information to validate digital signatures

type SignedRoot

type SignedRoot struct {
	Type               string        `json:"_type"`
	ConsistentSnapshot bool          `json:"consistent_snapshot"`
	Expires            time.Time     `json:"expires"`
	Keys               map[keyID]Key `json:"keys"`
	Roles              map[role]Role `json:"roles"`
	Version            int           `json:"version"`
}

SignedRoot signed contents of the root role

type SignedSnapshot

type SignedSnapshot struct {
	Type    string                     `json:"_type"`
	Expires time.Time                  `json:"expires"`
	Version int                        `json:"version"`
	Meta    map[role]FileIntegrityMeta `json:"meta"`
}

SignedSnapshot is the signed portion of the snapshot

type SignedTarget

type SignedTarget struct {
	Type        string      `json:"_type"`
	Delegations Delegations `json:"delegations"`
	Expires     time.Time   `json:"expires"`
	Targets     FimMap      `json:"targets"`
	Version     int         `json:"version"`
}

SignedTarget specifics of the Targets

type SignedTimestamp

type SignedTimestamp struct {
	Type    string                     `json:"_type"`
	Expires time.Time                  `json:"expires"`
	Version int                        `json:"version"`
	Meta    map[role]FileIntegrityMeta `json:"meta"`
}

SignedTimestamp signed portion of timestamp role.

type Snapshot

type Snapshot struct {
	Signed     SignedSnapshot `json:"signed"`
	Signatures []Signature    `json:"signatures"`
}

Snapshot is the snapshot role. It lists the version numbers of all metadata on the repository, excluding timestamp.json and mirrors.json.

type Targets

type Targets struct {
	Signed     SignedTarget `json:"signed"`
	Signatures []Signature  `json:"signatures"`
	// contains filtered or unexported fields
}

Targets represents TUF role of the same name. See https://github.com/theupdateframework/tuf/blob/develop/docs/tuf-spec.txt

type Timestamp

type Timestamp struct {
	Signed     SignedTimestamp `json:"signed"`
	Signatures []Signature     `json:"signatures"`
}

Timestamp role indicates the latest versions of other files and is frequently resigned to limit the amount of time a client can be kept unaware of interference with obtaining updates.