tuf

package module
v0.3.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: May 5, 2022 License: BSD-3-Clause Imports: 24 Imported by: 20

README

go-tuf

build Coverage Status PkgGoDev Go Report Card

This is a Go implementation of The Update Framework (TUF), a framework for securing software update systems.

Directory layout

A TUF repository has the following directory layout:

.
├── keys
├── repository
│   └── targets
└── staged
    └── targets

The directories contain the following files:

  • keys/ - signing keys (optionally encrypted) with filename pattern ROLE.json
  • repository/ - signed metadata files
  • repository/targets/ - hashed target files
  • staged/ - either signed, unsigned or partially signed metadata files
  • staged/targets/ - unhashed target files

CLI

go-tuf provides a CLI for managing a local TUF repository.

Install

go-tuf is tested on Go versions 1.16 and 1.17.

go get github.com/theupdateframework/go-tuf/cmd/tuf
Commands
tuf init [--consistent-snapshot=false]

Initializes a new repository.

This is only required if the repository should not generate consistent snapshots (i.e. by passing --consistent-snapshot=false). If consistent snapshots should be generated, the repository will be implicitly initialized to do so when generating keys.

tuf gen-key [--expires=<days>] <role>

Prompts the user for an encryption passphrase (unless the --insecure-plaintext flag is set), then generates a new signing key and writes it to the relevant key file in the keys directory. It also stages the addition of the new key to the root metadata file. Alternatively, passphrases can be set via environment variables in the form of TUF_{{ROLE}}_PASSPHRASE

tuf revoke-key [--expires=<days>] <role> <id>

Revoke a signing key

The key will be removed from the root metadata file, but the key will remain in the "keys" directory if present.

tuf add [<path>...]

Hashes files in the staged/targets directory at the given path(s), then updates and stages the targets metadata file. Specifying no paths hashes all files in the staged/targets directory.

tuf remove [<path>...]

Stages the removal of files with the given path(s) from the targets metadata file (they get removed from the filesystem when the change is committed). Specifying no paths removes all files from the targets metadata file.

tuf snapshot [--expires=<days>]

Expects a staged, fully signed targets metadata file and stages an appropriate snapshot metadata file. Optionally one can set number of days after which the snapshot metadata will expire.

tuf timestamp [--expires=<days>]

Stages an appropriate timestamp metadata file. If a snapshot metadata file is staged, it must be fully signed. Optionally one can set number of days after which the timestamp metadata will expire.

tuf sign <metadata>

Signs the given role's staged metadata file with all keys present in the keys directory for that role.

tuf commit

Verifies that all staged changes contain the correct information and are signed to the correct threshold, then moves the staged files into the repository directory. It also removes any target files which are not in the targets metadata file.

tuf regenerate [--consistent-snapshot=false]

Note: Not supported yet

Recreates the targets metadata file based on the files in repository/targets.

tuf clean

Removes all staged metadata files and targets.

tuf root-keys

Outputs a JSON serialized array of root keys to STDOUT. The resulting JSON should be distributed to clients for performing initial updates.

tuf set-threshold <role> <threshold>

Sets role's threshold (required number of keys for signing) to threshold.

tuf get-threshold <role>

Outputs role's threshold (required number of keys for signing).

tuf change-passphrase <role>

Changes the passphrase for given role keys file. The CLI supports reading both the existing and the new passphrase via the following environment variables - TUF_{{ROLE}}_PASSPHRASE and respectively TUF_NEW_{{ROLE}}_PASSPHRASE

Usage of environment variables

The tuf CLI supports receiving passphrases via environment variables in the form of TUF_{{ROLE}}_PASSPHRASE for existing ones and TUF_NEW_{{ROLE}}_PASSPHRASE for setting new ones.

For a list of supported commands, run tuf help from the command line.

Examples

The following are example workflows for managing a TUF repository with the CLI.

The tree commands do not need to be run, but their output serve as an illustration of what files should exist after performing certain commands.

Although only two machines are referenced (i.e. the "root" and "repo" boxes), the workflows can be trivially extended to many signing machines by copying staged changes and signing on each machine in turn before finally committing.

Some key IDs are truncated for illustrative purposes.

Create signed root metadata file

Generate a root key on the root box:

$ tuf gen-key root
Enter root keys passphrase:
Repeat root keys passphrase:
Generated root key with ID 184b133f

$ tree .
.
├── keys
│   └── root.json
├── repository
└── staged
    ├── root.json
    └── targets

Copy staged/root.json from the root box to the repo box and generate targets, snapshot and timestamp keys:

$ tree .
.
├── keys
├── repository
└── staged
    ├── root.json
    └── targets

$ tuf gen-key targets
Enter targets keys passphrase:
Repeat targets keys passphrase:
Generated targets key with ID 8cf4810c

$ tuf gen-key snapshot
Enter snapshot keys passphrase:
Repeat snapshot keys passphrase:
Generated snapshot key with ID 3e070e53

$ tuf gen-key timestamp
Enter timestamp keys passphrase:
Repeat timestamp keys passphrase:
Generated timestamp key with ID a3768063

$ tree .
.
├── keys
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
├── repository
└── staged
    ├── root.json
    └── targets

Copy staged/root.json from the repo box back to the root box and sign it:

$ tree .
.
├── keys
│   ├── root.json
├── repository
└── staged
    ├── root.json
    └── targets

$ tuf sign root.json
Enter root keys passphrase:

The staged root.json can now be copied back to the repo box ready to be committed alongside other metadata files.

Add a target file

Assuming a staged, signed root metadata file and the file to add exists at staged/targets/foo/bar/baz.txt:

$ tree .
.
├── keys
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
├── repository
└── staged
    ├── root.json
    └── targets
        └── foo
            └── bar
                └── baz.txt

$ tuf add foo/bar/baz.txt
Enter targets keys passphrase:

$ tree .
.
├── keys
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
├── repository
└── staged
    ├── root.json
    ├── targets
    │   └── foo
    │       └── bar
    │           └── baz.txt
    └── targets.json

$ tuf snapshot
Enter snapshot keys passphrase:

$ tuf timestamp
Enter timestamp keys passphrase:

$ tree .
.
├── keys
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
├── repository
└── staged
    ├── root.json
    ├── snapshot.json
    ├── targets
    │   └── foo
    │       └── bar
    │           └── baz.txt
    ├── targets.json
    └── timestamp.json

$ tuf commit

$ tree .
.
├── keys
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
├── repository
│   ├── root.json
│   ├── snapshot.json
│   ├── targets
│   │   └── foo
│   │       └── bar
│   │           └── baz.txt
│   ├── targets.json
│   └── timestamp.json
└── staged
Remove a target file

Assuming the file to remove is at repository/targets/foo/bar/baz.txt:

$ tree .
.
├── keys
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
├── repository
│   ├── root.json
│   ├── snapshot.json
│   ├── targets
│   │   └── foo
│   │       └── bar
│   │           └── baz.txt
│   ├── targets.json
│   └── timestamp.json
└── staged

$ tuf remove foo/bar/baz.txt
Enter targets keys passphrase:

$ tree .
.
├── keys
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
├── repository
│   ├── root.json
│   ├── snapshot.json
│   ├── targets
│   │   └── foo
│   │       └── bar
│   │           └── baz.txt
│   ├── targets.json
│   └── timestamp.json
└── staged
    └── targets.json

$ tuf snapshot
Enter snapshot keys passphrase:

$ tuf timestamp
Enter timestamp keys passphrase:

$ tree .
.
├── keys
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
├── repository
│   ├── root.json
│   ├── snapshot.json
│   ├── targets
│   │   └── foo
│   │       └── bar
│   │           └── baz.txt
│   ├── targets.json
│   └── timestamp.json
└── staged
    ├── snapshot.json
    ├── targets.json
    └── timestamp.json

$ tuf commit

$ tree .
.
├── keys
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
├── repository
│   ├── root.json
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
└── staged
Regenerate metadata files based on targets tree (Note: Not supported yet)
$ tree .
.
├── keys
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
├── repository
│   ├── root.json
│   ├── snapshot.json
│   ├── targets
│   │   └── foo
│   │       └── bar
│   │           └── baz.txt
│   ├── targets.json
│   └── timestamp.json
└── staged

$ tuf regenerate
Enter targets keys passphrase:

$ tree .
.
├── keys
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
├── repository
│   ├── root.json
│   ├── snapshot.json
│   ├── targets
│   │   └── foo
│   │       └── bar
│   │           └── baz.txt
│   ├── targets.json
│   └── timestamp.json
└── staged
    └── targets.json

$ tuf snapshot
Enter snapshot keys passphrase:

$ tuf timestamp
Enter timestamp keys passphrase:

$ tree .
.
├── keys
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
├── repository
│   ├── root.json
│   ├── snapshot.json
│   ├── targets
│   │   └── foo
│   │       └── bar
│   │           └── baz.txt
│   ├── targets.json
│   └── timestamp.json
└── staged
    ├── snapshot.json
    ├── targets.json
    └── timestamp.json

$ tuf commit

$ tree .
.
├── keys
│   ├── snapshot.json
│   ├── targets.json
│   └── timestamp.json
├── repository
│   ├── root.json
│   ├── snapshot.json
│   ├── targets
│   │   └── foo
│   │       └── bar
│   │           └── baz.txt
│   ├── targets.json
│   └── timestamp.json
└── staged
Update timestamp.json
$ tree .
.
├── keys
│   └── timestamp.json
├── repository
│   ├── root.json
│   ├── snapshot.json
│   ├── targets
│   │   └── foo
│   │       └── bar
│   │           └── baz.txt
│   ├── targets.json
│   └── timestamp.json
└── staged

$ tuf timestamp
Enter timestamp keys passphrase:

$ tree .
.
├── keys
│   └── timestamp.json
├── repository
│   ├── root.json
│   ├── snapshot.json
│   ├── targets
│   │   └── foo
│   │       └── bar
│   │           └── baz.txt
│   ├── targets.json
│   └── timestamp.json
└── staged
    └── timestamp.json

$ tuf commit

$ tree .
.
├── keys
│   └── timestamp.json
├── repository
│   ├── root.json
│   ├── snapshot.json
│   ├── targets
│   │   └── foo
│   │       └── bar
│   │           └── baz.txt
│   ├── targets.json
│   └── timestamp.json
└── staged

Client

For the client package, see https://godoc.org/github.com/theupdateframework/go-tuf/client.

For the client CLI, see https://github.com/theupdateframework/go-tuf/tree/master/cmd/tuf-client.

Development

For local development, go-tuf requires Go version 1.16 or 1.17.

The Python interoperability tests require Python 3 (available as python on the $PATH) and the python-tuf package installed (pip install tuf). To update the data for these tests requires Docker and make (see test data README.md for details).

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrInitNotAllowed               = errors.New("tuf: repository already initialized")
	ErrNewRepository                = errors.New("tuf: repository not yet committed")
	ErrChangePassphraseNotSupported = errors.New("tuf: store does not support changing passphrase")
)

Functions

This section is empty.

Types

type ErrFileNotFound 

type ErrFileNotFound struct {
	Path string
}

func (ErrFileNotFound) Error 

func (e ErrFileNotFound) Error() string

type ErrInsufficientKeys 

type ErrInsufficientKeys struct {
	Name string
}

func (ErrInsufficientKeys) Error 

func (e ErrInsufficientKeys) Error() string

type ErrInsufficientSignatures 

type ErrInsufficientSignatures struct {
	Name string
	Err  error
}

func (ErrInsufficientSignatures) Error 

func (e ErrInsufficientSignatures) Error() string

type ErrInvalidExpires 

type ErrInvalidExpires struct {
	Expires time.Time
}

func (ErrInvalidExpires) Error 

func (e ErrInvalidExpires) Error() string

type ErrInvalidRole 

type ErrInvalidRole struct {
	Role   string
	Reason string
}

func (ErrInvalidRole) Error 

func (e ErrInvalidRole) Error() string

type ErrKeyNotFound 

type ErrKeyNotFound struct {
	Role  string
	KeyID string
}

func (ErrKeyNotFound) Error 

func (e ErrKeyNotFound) Error() string

type ErrMissingMetadata 

type ErrMissingMetadata struct {
	Name string
}

func (ErrMissingMetadata) Error 

func (e ErrMissingMetadata) Error() string

type ErrNoDelegatedTarget added in v0.3.0 

type ErrNoDelegatedTarget struct {
	Path string
}

func (ErrNoDelegatedTarget) Error added in v0.3.0 

func (e ErrNoDelegatedTarget) Error() string

type ErrNotEnoughKeys 

type ErrNotEnoughKeys struct {
	Role      string
	Keys      int
	Threshold int
}

func (ErrNotEnoughKeys) Error 

func (e ErrNotEnoughKeys) Error() string

type ErrPassphraseRequired 

type ErrPassphraseRequired struct {
	Role string
}

func (ErrPassphraseRequired) Error 

func (e ErrPassphraseRequired) Error() string

type LocalStore 

type LocalStore interface {
	// GetMeta returns a map from metadata file names (e.g. root.json) to their raw JSON payload or an error.
	GetMeta() (map[string]json.RawMessage, error)

	// SetMeta is used to update a metadata file name with a JSON payload.
	SetMeta(name string, meta json.RawMessage) error

	// WalkStagedTargets calls targetsFn for each staged target file in paths.
	// If paths is empty, all staged target files will be walked.
	WalkStagedTargets(paths []string, targetsFn TargetsWalkFunc) error

	// FileIsStaged determines if a metadata file is currently staged, to avoid incrementing
	// version numbers repeatedly while staged.
	FileIsStaged(filename string) bool

	// Commit is used to publish staged files to the repository
	//
	// This will also reset the staged meta to signal incrementing version numbers.
	// TUF 1.0 requires that the root metadata version numbers in the repository does not
	// gaps. To avoid this, we will only increment the number once until we commit.
	Commit(bool, map[string]int64, map[string]data.Hashes) error

	// GetSigners return a list of signers for a role.
	// This may include revoked keys, so the signers should not
	// be used without filtering.
	GetSigners(role string) ([]keys.Signer, error)

	// SaveSigner adds a signer to a role.
	SaveSigner(role string, signer keys.Signer) error

	// SignersForRole return a list of signing keys for a role.
	SignersForKeyIDs(keyIDs []string) []keys.Signer

	// Clean is used to remove all staged manifests.
	Clean() error
}

func FileSystemStore 

func FileSystemStore(dir string, p util.PassphraseFunc) LocalStore

func MemoryStore 

func MemoryStore(meta map[string]json.RawMessage, files map[string][]byte) LocalStore

type PassphraseChanger 

type PassphraseChanger interface {
	// ChangePassphrase changes the passphrase for a role keys file.
	ChangePassphrase(string) error
}

type Repo 

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

func NewRepo 

func NewRepo(local LocalStore, hashAlgorithms ...string) (*Repo, error)

func NewRepoIndent 

func NewRepoIndent(local LocalStore, prefix string, indent string, hashAlgorithms ...string) (*Repo, error)

func (*Repo) AddDelegatedRole added in v0.3.0 

func (r *Repo) AddDelegatedRole(delegator string, delegatedRole data.DelegatedRole, keys []*data.PublicKey) error

AddDelegatedRole is equivalent to AddDelegatedRoleWithExpires, but with a default expiration time.

func (*Repo) AddDelegatedRoleWithExpires added in v0.3.0 

func (r *Repo) AddDelegatedRoleWithExpires(delegator string, delegatedRole data.DelegatedRole, keys []*data.PublicKey, expires time.Time) error

AddDelegatedRoleWithExpires adds a delegation from the delegator to the role specified in the role argument. Key IDs referenced in role.KeyIDs should have corresponding Key entries in the keys argument. New metadata is written with the given expiration time.

func (*Repo) AddDelegatedRolesForPathHashBins added in v0.3.0 

func (r *Repo) AddDelegatedRolesForPathHashBins(delegator string, bins *targets.HashBins, keys []*data.PublicKey, threshold int) error

AddDelegatedRolesForPathHashBins is equivalent to AddDelegatedRolesForPathHashBinsWithExpires, but with a default expiration time.

func (*Repo) AddDelegatedRolesForPathHashBinsWithExpires added in v0.3.0 

func (r *Repo) AddDelegatedRolesForPathHashBinsWithExpires(delegator string, bins *targets.HashBins, keys []*data.PublicKey, threshold int, expires time.Time) error

AddDelegatedRolesForPathHashBinsWithExpires adds delegations to the delegator role for the given hash bins configuration. New metadata is written with the given expiration time.

func (*Repo) AddOrUpdateSignature 

func (r *Repo) AddOrUpdateSignature(roleFilename string, signature data.Signature) error

AddOrUpdateSignature allows users to add or update a signature generated with an external tool. The name must be a valid metadata file name, like root.json.

func (*Repo) AddPrivateKey 

func (r *Repo) AddPrivateKey(role string, signer keys.Signer) error

func (*Repo) AddPrivateKeyWithExpires 

func (r *Repo) AddPrivateKeyWithExpires(keyRole string, signer keys.Signer, expires time.Time) error

func (*Repo) AddTarget 

func (r *Repo) AddTarget(path string, custom json.RawMessage) error

func (*Repo) AddTargetToPreferredRole added in v0.3.0 

func (r *Repo) AddTargetToPreferredRole(path string, custom json.RawMessage, preferredRole string) error

func (*Repo) AddTargetWithExpires 

func (r *Repo) AddTargetWithExpires(path string, custom json.RawMessage, expires time.Time) error

func (*Repo) AddTargetWithExpiresToPreferredRole added in v0.3.0 

func (r *Repo) AddTargetWithExpiresToPreferredRole(path string, custom json.RawMessage, expires time.Time, preferredRole string) error

func (*Repo) AddTargets 

func (r *Repo) AddTargets(paths []string, custom json.RawMessage) error

func (*Repo) AddTargetsToPreferredRole added in v0.3.0 

func (r *Repo) AddTargetsToPreferredRole(paths []string, custom json.RawMessage, preferredRole string) error

func (*Repo) AddTargetsWithDigest 

func (r *Repo) AddTargetsWithDigest(digest string, digestAlg string, length int64, path string, custom json.RawMessage) error

func (*Repo) AddTargetsWithExpires 

func (r *Repo) AddTargetsWithExpires(paths []string, custom json.RawMessage, expires time.Time) error

func (*Repo) AddTargetsWithExpiresToPreferredRole added in v0.3.0 

func (r *Repo) AddTargetsWithExpiresToPreferredRole(paths []string, custom json.RawMessage, expires time.Time, preferredRole string) error

AddTargetsWithExpiresToPreferredRole signs the staged targets at `paths`.

If preferredRole is not the empty string, the target is added to the given role's manifest if delegations allow it. If delegations do not allow the preferredRole to sign the given path, an error is returned.

func (*Repo) AddVerificationKey 

func (r *Repo) AddVerificationKey(keyRole string, pk *data.PublicKey) error

func (*Repo) AddVerificationKeyWithExpiration 

func (r *Repo) AddVerificationKeyWithExpiration(keyRole string, pk *data.PublicKey, expires time.Time) error

func (*Repo) ChangePassphrase 

func (r *Repo) ChangePassphrase(keyRole string) error

func (*Repo) Clean 

func (r *Repo) Clean() error

func (*Repo) Commit 

func (r *Repo) Commit() error

func (*Repo) GenKey 

func (r *Repo) GenKey(role string) ([]string, error)

func (*Repo) GenKeyWithExpires 

func (r *Repo) GenKeyWithExpires(keyRole string, expires time.Time) (keyids []string, err error)

func (*Repo) GetThreshold 

func (r *Repo) GetThreshold(keyRole string) (int, error)

func (*Repo) Init 

func (r *Repo) Init(consistentSnapshot bool) error

func (*Repo) RemoveTarget 

func (r *Repo) RemoveTarget(path string) error

func (*Repo) RemoveTargetWithExpires 

func (r *Repo) RemoveTargetWithExpires(path string, expires time.Time) error

func (*Repo) RemoveTargets 

func (r *Repo) RemoveTargets(paths []string) error

func (*Repo) RemoveTargetsWithExpires 

func (r *Repo) RemoveTargetsWithExpires(paths []string, expires time.Time) error

If paths is empty, all targets will be removed.

func (*Repo) ResetTargetsDelegations added in v0.3.0 

func (r *Repo) ResetTargetsDelegations(delegator string) error

ResetTargetsDelegation is equivalent to ResetTargetsDelegationsWithExpires with a default expiry time.

func (*Repo) ResetTargetsDelegationsWithExpires added in v0.3.0 

func (r *Repo) ResetTargetsDelegationsWithExpires(delegator string, expires time.Time) error

ResetTargetsDelegationsWithExpires removes all targets delegations from the given delegator role. New metadata is written with the given expiration time.

func (*Repo) RevokeKey 

func (r *Repo) RevokeKey(role, id string) error

func (*Repo) RevokeKeyWithExpires 

func (r *Repo) RevokeKeyWithExpires(keyRole, id string, expires time.Time) error

func (*Repo) RootKeys 

func (r *Repo) RootKeys() ([]*data.PublicKey, error)

func (*Repo) RootVersion 

func (r *Repo) RootVersion() (int64, error)

func (*Repo) SetSnapshotVersion 

func (r *Repo) SetSnapshotVersion(v int64) error

func (*Repo) SetTargetsVersion 

func (r *Repo) SetTargetsVersion(v int64) error

func (*Repo) SetThreshold 

func (r *Repo) SetThreshold(keyRole string, t int) error

func (*Repo) SetTimestampVersion 

func (r *Repo) SetTimestampVersion(v int64) error

func (*Repo) Sign 

func (r *Repo) Sign(roleFilename string) error

func (*Repo) SignedMeta 

func (r *Repo) SignedMeta(roleFilename string) (*data.Signed, error)

Used to retrieve the signable portion of the metadata when using an external signing tool.

func (*Repo) Snapshot 

func (r *Repo) Snapshot() error

func (*Repo) SnapshotVersion 

func (r *Repo) SnapshotVersion() (int64, error)

func (*Repo) SnapshotWithExpires 

func (r *Repo) SnapshotWithExpires(expires time.Time) error

func (*Repo) Targets 

func (r *Repo) Targets() (data.TargetFiles, error)

func (*Repo) TargetsVersion 

func (r *Repo) TargetsVersion() (int64, error)

func (*Repo) Timestamp 

func (r *Repo) Timestamp() error

func (*Repo) TimestampVersion 

func (r *Repo) TimestampVersion() (int64, error)

func (*Repo) TimestampWithExpires 

func (r *Repo) TimestampWithExpires(expires time.Time) error

type TargetsWalkFunc 

type TargetsWalkFunc func(path string, target io.Reader) error

TargetsWalkFunc is a function of a target path name and a target payload used to execute some function on each staged target file. For example, it may normalize path names and generate target file metadata with additional custom metadata.

Source Files

View all Source files

Directories

Path Synopsis
leveldbstore
cmd
tuf
tuf-client
Package encrypted provides a simple, secure system for encrypting data symmetrically with a passphrase.
 Package encrypted provides a simple, secure system for encrypting data symmetrically with a passphrase.
internal
roles
sets
signer
pkg
keys
targets

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.