client

package
v0.0.0-...-350d6b1 Latest Latest
Warning

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

 Go to latest Published: Apr 22, 2021 License: Apache-2.0 Imports: 21 Imported by: 0

Documentation

Overview

Package client implements everything required for interacting with a Notary repository.

Example 
package main

import (
	"encoding/hex"
	"fmt"
	"net/http"
	"os"
	"time"

	"github.com/docker/distribution/registry/client/auth"
	"github.com/docker/distribution/registry/client/auth/challenge"
	"github.com/docker/distribution/registry/client/transport"
	"github.com/theupdateframework/notary/trustpinning"
	"github.com/theupdateframework/notary/tuf/data"
)

func main() {
	rootDir := ".trust"
	if err := os.MkdirAll(rootDir, 0700); err != nil {
		panic(err)
	}

	server := "https://notary.docker.io"
	image := "docker.io/library/alpine"
	repo, err := NewFileCachedRepository(
		rootDir,
		data.GUN(image),
		server,
		makeHubTransport(server, image),
		nil,
		trustpinning.TrustPinConfig{},
	)
	if err != nil {
		panic(err)
	}

	targets, err := repo.ListTargets()
	if err != nil {
		panic(err)
	}

	for _, tgt := range targets {
		fmt.Printf("%s\t%s\n", tgt.Name, hex.EncodeToString(tgt.Hashes["sha256"]))
	}
}

func makeHubTransport(server, image string) http.RoundTripper {
	base := http.DefaultTransport
	modifiers := []transport.RequestModifier{
		transport.NewHeaderRequestModifier(http.Header{
			"User-Agent": []string{"my-client"},
		}),
	}

	authTransport := transport.NewTransport(base, modifiers...)
	pingClient := &http.Client{
		Transport: authTransport,
		Timeout:   5 * time.Second,
	}
	req, err := http.NewRequest("GET", server+"/v2/", nil)
	if err != nil {
		panic(err)
	}

	challengeManager := challenge.NewSimpleManager()
	resp, err := pingClient.Do(req)
	if err != nil {
		panic(err)
	}
	defer resp.Body.Close()
	if err := challengeManager.AddResponse(resp); err != nil {
		panic(err)
	}
	tokenHandler := auth.NewTokenHandler(base, nil, image, "pull")
	modifiers = append(modifiers, auth.NewAuthorizer(challengeManager, tokenHandler, auth.NewBasicHandler(nil)))

	return transport.NewTransport(base, modifiers...)
}

Output:

Index

Examples

Constants

View Source 
const (

	// SignWithAllOldVersions is a sentinel constant for LegacyVersions flag
	SignWithAllOldVersions = -1
)

Variables

This section is empty.

Functions

func DeleteTrustData 

func DeleteTrustData(baseDir string, gun data.GUN, URL string, rt http.RoundTripper, deleteRemote bool) error

DeleteTrustData removes the trust data stored for this repo in the TUF cache on the client side Note that we will not delete any private key material from local storage

func LoadTUFRepo 

func LoadTUFRepo(options TUFLoadOptions) (*tuf.Repo, *tuf.Repo, error)

LoadTUFRepo bootstraps a trust anchor (root.json) from cache (if provided) before updating all the metadata for the repo from the remote (if provided). It loads a TUF repo from cache, from a remote store, or both.

Types

type ErrInvalidLocalRole 

type ErrInvalidLocalRole struct {
	Role data.RoleName
}

ErrInvalidLocalRole is returned when the client wants to manage a key type that is not permitted

func (ErrInvalidLocalRole) Error 

func (err ErrInvalidLocalRole) Error() string

type ErrInvalidRemoteRole 

type ErrInvalidRemoteRole struct {
	Role data.RoleName
}

ErrInvalidRemoteRole is returned when the server is requested to manage a key type that is not permitted

func (ErrInvalidRemoteRole) Error 

func (err ErrInvalidRemoteRole) Error() string

type ErrNoSuchTarget 

type ErrNoSuchTarget string

ErrNoSuchTarget is returned when no valid trust data is found.

func (ErrNoSuchTarget) Error 

func (f ErrNoSuchTarget) Error() string

type ErrRepoNotInitialized 

type ErrRepoNotInitialized struct{}

ErrRepoNotInitialized is returned when trying to publish an uninitialized notary repository

func (ErrRepoNotInitialized) Error 

func (err ErrRepoNotInitialized) Error() string

type ErrRepositoryNotExist 

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

ErrRepositoryNotExist is returned when an action is taken on a remote repository that doesn't exist

func (ErrRepositoryNotExist) Error 

func (err ErrRepositoryNotExist) Error() string

type ReadOnly 

type ReadOnly interface {
	// ListTargets lists all targets for the current repository. The list of
	// roles should be passed in order from highest to lowest priority.
	//
	// IMPORTANT: if you pass a set of roles such as [ "targets/a", "targets/x"
	// "targets/a/b" ], even though "targets/a/b" is part of the "targets/a" subtree
	// its entries will be strictly shadowed by those in other parts of the "targets/a"
	// subtree and also the "targets/x" subtree, as we will defer parsing it until
	// we explicitly reach it in our iteration of the provided list of roles.
	ListTargets(roles ...data.RoleName) ([]*TargetWithRole, error)

	// GetTargetByName returns a target by the given name. If no roles are passed
	// it uses the targets role and does a search of the entire delegation
	// graph, finding the first entry in a breadth first search of the delegations.
	// If roles are passed, they should be passed in descending priority and
	// the target entry found in the subtree of the highest priority role
	// will be returned.
	// See the IMPORTANT section on ListTargets above. Those roles also apply here.
	GetTargetByName(name string, roles ...data.RoleName) (*TargetWithRole, error)

	// GetAllTargetMetadataByName searches the entire delegation role tree to find
	// the specified target by name for all roles, and returns a list of
	// TargetSignedStructs for each time it finds the specified target.
	// If given an empty string for a target name, it will return back all targets
	// signed into the repository in every role
	GetAllTargetMetadataByName(name string) ([]TargetSignedStruct, error)

	// ListRoles returns a list of RoleWithSignatures objects for this repo
	// This represents the latest metadata for each role in this repo
	ListRoles() ([]RoleWithSignatures, error)

	// GetDelegationRoles returns the keys and roles of the repository's delegations
	// Also converts key IDs to canonical key IDs to keep consistent with signing prompts
	GetDelegationRoles() ([]data.Role, error)
}

ReadOnly represents the set of options that must be supported over a TUF repo for reading

func NewReadOnly 

func NewReadOnly(repo *tuf.Repo) ReadOnly

NewReadOnly is the base method that returns a new notary repository for reading. It expects an initialized cache. In case of a nil remote store, a default offline store is used.

type Repository 

type Repository interface {
	ReadOnly

	// GetGUN returns the GUN associated with the repository
	GetGUN() data.GUN

	// SetLegacyVersion sets the number of versions back to fetch roots to sign with
	SetLegacyVersions(int)

	// Initialize creates a new repository by using rootKey as the root Key for the
	// TUF repository. The remote store/server must be reachable (and is asked to
	// generate a timestamp key and possibly other serverManagedRoles), but the
	// created repository result is only stored on local cache, not published to
	// the remote store. To do that, use r.Publish() eventually.
	Initialize(rootKeyIDs []string, serverManagedRoles ...data.RoleName) error

	// InitializeWithCertificate initializes the repository with root keys and their
	// corresponding certificates
	InitializeWithCertificate(rootKeyIDs []string, rootCerts []data.PublicKey, serverManagedRoles ...data.RoleName) error

	// Publish pushes the local changes in signed material to the remote notary-server
	// Conceptually it performs an operation similar to a `git rebase`
	Publish() error

	// AddTarget creates new changelist entries to add a target to the given roles
	// in the repository when the changelist gets applied at publish time.
	// If roles are unspecified, the default role is "targets"
	AddTarget(target *Target, roles ...data.RoleName) error

	// RemoveTarget creates new changelist entries to remove a target from the given
	// roles in the repository when the changelist gets applied at publish time.
	// If roles are unspecified, the default role is "target".
	RemoveTarget(targetName string, roles ...data.RoleName) error

	// GetChangelist returns the list of the repository's unpublished changes
	GetChangelist() (changelist.Changelist, error)

	// AddDelegation creates changelist entries to add provided delegation public keys and paths.
	// This method composes AddDelegationRoleAndKeys and AddDelegationPaths (each creates one changelist if called).
	AddDelegation(name data.RoleName, delegationKeys []data.PublicKey, paths []string) error

	// AddDelegationRoleAndKeys creates a changelist entry to add provided delegation public keys.
	// This method is the simplest way to create a new delegation, because the delegation must have at least
	// one key upon creation to be valid since we will reject the changelist while validating the threshold.
	AddDelegationRoleAndKeys(name data.RoleName, delegationKeys []data.PublicKey) error

	// AddDelegationPaths creates a changelist entry to add provided paths to an existing delegation.
	// This method cannot create a new delegation itself because the role must meet the key threshold upon
	// creation.
	AddDelegationPaths(name data.RoleName, paths []string) error

	// RemoveDelegationKeysAndPaths creates changelist entries to remove provided delegation key IDs and
	// paths. This method composes RemoveDelegationPaths and RemoveDelegationKeys (each creates one
	// changelist entry if called).
	RemoveDelegationKeysAndPaths(name data.RoleName, keyIDs, paths []string) error

	// RemoveDelegationRole creates a changelist to remove all paths and keys from a role, and delete the
	// role in its entirety.
	RemoveDelegationRole(name data.RoleName) error

	// RemoveDelegationPaths creates a changelist entry to remove provided paths from an existing delegation.
	RemoveDelegationPaths(name data.RoleName, paths []string) error

	// RemoveDelegationKeys creates a changelist entry to remove provided keys from an existing delegation.
	// When this changelist is applied, if the specified keys are the only keys left in the role,
	// the role itself will be deleted in its entirety.
	// It can also delete a key from all delegations under a parent using a name
	// with a wildcard at the end.
	RemoveDelegationKeys(name data.RoleName, keyIDs []string) error

	// ClearDelegationPaths creates a changelist entry to remove all paths from an existing delegation.
	ClearDelegationPaths(name data.RoleName) error

	// Witness creates change objects to witness (i.e. re-sign) the given
	// roles on the next publish. One change is created per role
	Witness(roles ...data.RoleName) ([]data.RoleName, error)

	// RotateKey removes all existing keys associated with the role. If no keys are
	// specified in keyList, then this creates and adds one new key or delegates
	// managing the key to the server. If key(s) are specified by keyList, then they are
	// used for signing the role.
	// These changes are staged in a changelist until publish is called.
	RotateKey(role data.RoleName, serverManagesKey bool, keyList []string) error

	// GetCryptoService is the getter for the repository's CryptoService, which is used
	// to sign all updates.
	GetCryptoService() signed.CryptoService
}

Repository represents the set of options that must be supported over a TUF repo for both reading and writing.

func NewFileCachedRepository 

func NewFileCachedRepository(baseDir string, gun data.GUN, baseURL string, rt http.RoundTripper,
	retriever notary.PassRetriever, trustPinning trustpinning.TrustPinConfig) (Repository, error)

NewFileCachedRepository is a wrapper for NewRepository that initializes a file cache from the provided repository, local config information and a crypto service. It also retrieves the remote store associated to the base directory under where all the trust files will be stored (This is normally defaults to "~/.notary" or "~/.docker/trust" when enabling Docker content trust) and the specified GUN.

In case of a nil RoundTripper, a default offline store is used instead.

func NewRepository 

func NewRepository(gun data.GUN, baseURL string, remoteStore store.RemoteStore, cache store.MetadataStore,
	trustPinning trustpinning.TrustPinConfig, cryptoService signed.CryptoService, cl changelist.Changelist) (Repository, error)

NewRepository is the base method that returns a new notary repository. It expects an initialized cache. In case of a nil remote store, a default offline store is used.

type RoleWithSignatures 

type RoleWithSignatures struct {
	Signatures []data.Signature
	data.Role
}

RoleWithSignatures is a Role with its associated signatures

type TUFLoadOptions 

type TUFLoadOptions struct {
	GUN                    data.GUN
	TrustPinning           trustpinning.TrustPinConfig
	CryptoService          signed.CryptoService
	Cache                  store.MetadataStore
	RemoteStore            store.RemoteStore
	AlwaysCheckInitialized bool
}

TUFLoadOptions are provided to LoadTUFRepo, which loads a TUF repo from cache, from a remote store, or both

type Target 

type Target struct {
	Name   string                    // the name of the target
	Hashes data.Hashes               // the hash of the target
	Length int64                     // the size in bytes of the target
	Custom *canonicaljson.RawMessage // the custom data provided to describe the file at TARGETPATH
}

Target represents a simplified version of the data TUF operates on, so external applications don't have to depend on TUF data types.

func NewTarget 

func NewTarget(targetName, targetPath string, targetCustom *canonicaljson.RawMessage) (*Target, error)

NewTarget is a helper method that returns a Target

type TargetSignedStruct 

type TargetSignedStruct struct {
	Role       data.DelegationRole
	Target     Target
	Signatures []data.Signature
}

TargetSignedStruct is a struct that contains a Target, the role it was found in, and the list of signatures for that role

type TargetWithRole 

type TargetWithRole struct {
	Target
	Role data.RoleName
}

TargetWithRole represents a Target that exists in a particular role - this is produced by ListTargets and GetTargetByName

Source Files

View all Source files

Directories

Path Synopsis

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.