tuf

README

go-tuf

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 manifests
• repository/targets/ - hashed target files
• staged/ - either signed, unsigned or partially signed manifests
• staged/targets/ - unhashed target files

CLI

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

Install

go get github.com/flynn/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 <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 manifest.

tuf add [<path>...]

Hashes files in the staged/targets directory at the given path(s), then updates and stages the targets manifest. 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 manifest (they get removed from the filesystem when the change is committed). Specifying no paths removes all files from the targets manifest.

tuf snapshot [--compression=<format>]

Expects a staged, fully signed targets manifest and stages an appropriate snapshot manifest. It optionally compresses the staged targets manifest.

tuf timestamp

Stages an appropriate timestamp manifest. If a snapshot manifest is staged, it must be fully signed.

tuf sign ROLE

Signs the given role's staged manifest 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 manifest.

tuf regenerate [--consistent-snapshot=false]

Recreates the targets manifest based on the files in repository/targets.

tuf clean

Removes all staged manifests 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.

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 manifest

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 manifests.

Add a target file

Assuming a staged, signed root manifest 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 manifests based on targets tree

$ 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

Modify key thresholds

TODO

Client

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

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

Documentation

Index

• type CompressionType
• type Repo
  • func NewRepo(trust signed.CryptoService, local store.LocalStore, hashAlgorithms ...string) (*Repo, error)
  • func (r *Repo) AddTargets(custom json.RawMessage, paths ...string) error
  • func (r *Repo) AddTargetsWithExpires(custom json.RawMessage, expires time.Time, paths ...string) error
  • func (r *Repo) Clean() error
  • func (r *Repo) Commit() error
  • func (r *Repo) GenKey(role string) (string, error)
  • func (r *Repo) GenKeyWithExpires(keyRole string, expires time.Time) (string, error)
  • func (r *Repo) GetKeyIDs(name string) ([]string, error)
  • func (r *Repo) GetKeys(name string) ([]*keys.PublicKey, error)
  • func (r *Repo) Init(consistentSnapshot bool) error
  • func (r *Repo) RemoveTargets(paths ...string) error
  • func (r *Repo) RemoveTargetsWithExpires(expires time.Time, paths ...string) error
  • func (r *Repo) RevokeKey(role, id string) error
  • func (r *Repo) RevokeKeyWithExpires(keyRole, id string, expires time.Time) error
  • func (r *Repo) RootKeys() ([]*data.Key, error)
  • func (r *Repo) Sign(name string) error
  • func (r *Repo) Snapshot(t CompressionType) error
  • func (r *Repo) SnapshotWithExpires(t CompressionType, expires time.Time) error
  • func (r *Repo) Timestamp() error
  • func (r *Repo) TimestampWithExpires(expires time.Time) error

Types

type CompressionType

type CompressionType uint8

const (
	CompressionTypeNone CompressionType = iota
	CompressionTypeGzip
)

type Repo

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

Repo represents an instance of a TUF repo

func NewRepo

func NewRepo(trust signed.CryptoService, local store.LocalStore, hashAlgorithms ...string) (*Repo, error)

NewRepo is a factory function for instantiating new TUF repos objects. If the local store is already populated, local.GetMeta() will initialise the Repo with the appropriate state.

func (*Repo) AddTargets

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

func (*Repo) AddTargetsWithExpires

func (r *Repo) AddTargetsWithExpires(custom json.RawMessage, expires time.Time, paths ...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) (string, error)

func (*Repo) GetKeyIDs

func (r *Repo) GetKeyIDs(name string) ([]string, error)

func (*Repo) GetKeys

func (r *Repo) GetKeys(name string) ([]*keys.PublicKey, error)

func (*Repo) Init

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

Init attempts to initialize a brand new TUF repo. It will fail if an existing targets file is detected.

func (*Repo) RemoveTargets

func (r *Repo) RemoveTargets(paths ...string) error

RemoveTargets calls through to RemoveTargetsWithExpires, setting the default expiry time for the targets file.

func (*Repo) RemoveTargetsWithExpires

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

RemoveTargetsWithExpires removes targets from the current set of targets. If no paths are provided, all targets will be removed.

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.Key, error)

func (*Repo) Sign

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

func (*Repo) Snapshot

func (r *Repo) Snapshot(t CompressionType) error

Snapshot calls through to SnapshotWithExpires, setting the default expiry time for the snapshot file

func (*Repo) SnapshotWithExpires

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

SnapshotWithExpires creates a TUF snapshot with the given expiry time.

func (*Repo) Timestamp

func (r *Repo) Timestamp() error

Timestamp calls through the TimestampWithExpires, setting the default expiry for the timestamp file

func (*Repo) TimestampWithExpires

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

TimestampWithExpires creates a timestamp file with the given expiry time