client

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...)
}

Index

• Constants
• func DeleteTrustData(baseDir string, gun data.GUN, URL string, rt http.RoundTripper, ...) error
• type ErrInvalidLocalRole
  • func (err ErrInvalidLocalRole) Error() string
• type ErrInvalidRemoteRole
  • func (err ErrInvalidRemoteRole) Error() string
• type ErrNoSuchTarget
  • func (f ErrNoSuchTarget) Error() string
• type ErrRepoNotInitialized
  • func (err ErrRepoNotInitialized) Error() string
• type ErrRepositoryNotExist
  • func (err ErrRepositoryNotExist) Error() string
• type Repository
  • func NewFileCachedRepository(baseDir string, gun data.GUN, baseURL string, rt http.RoundTripper, ...) (Repository, error)
  • func NewRepository(baseDir string, gun data.GUN, baseURL string, remoteStore store.RemoteStore, ...) (Repository, error)
• type RoleWithSignatures
• type Target
  • func NewTarget(targetName, targetPath string, targetCustom *canonicaljson.RawMessage) (*Target, error)
• type TargetSignedStruct
• type TargetWithRole

Examples

• Package

Constants

const (

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

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

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 Repository

type Repository interface {
	// General management operations
	Initialize(rootKeyIDs []string, serverManagedRoles ...data.RoleName) error
	InitializeWithCertificate(rootKeyIDs []string, rootCerts []data.PublicKey, serverManagedRoles ...data.RoleName) error
	Publish() error

	// Target Operations
	AddTarget(target *Target, roles ...data.RoleName) error
	RemoveTarget(targetName string, roles ...data.RoleName) error
	ListTargets(roles ...data.RoleName) ([]*TargetWithRole, error)
	GetTargetByName(name string, roles ...data.RoleName) (*TargetWithRole, error)
	GetAllTargetMetadataByName(name string) ([]TargetSignedStruct, error)

	// Changelist operations
	GetChangelist() (changelist.Changelist, error)

	// Role operations
	ListRoles() ([]RoleWithSignatures, error)
	GetDelegationRoles() ([]data.Role, error)
	AddDelegation(name data.RoleName, delegationKeys []data.PublicKey, paths []string) error
	AddDelegationRoleAndKeys(name data.RoleName, delegationKeys []data.PublicKey) error
	AddDelegationPaths(name data.RoleName, paths []string) error
	RemoveDelegationKeysAndPaths(name data.RoleName, keyIDs, paths []string) error
	RemoveDelegationRole(name data.RoleName) error
	RemoveDelegationPaths(name data.RoleName, paths []string) error
	RemoveDelegationKeys(name data.RoleName, keyIDs []string) error
	ClearDelegationPaths(name data.RoleName) error

	// Witness and other re-signing operations
	Witness(roles ...data.RoleName) ([]data.RoleName, error)

	// Key Operations
	RotateKey(role data.RoleName, serverManagesKey bool, keyList []string) error

	GetCryptoService() signed.CryptoService
	SetLegacyVersions(int)
	GetGUN() data.GUN
}

Repository represents the set of options that must be supported over a TUF repo.

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 and the specified GUN.

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

func NewRepository

func NewRepository(baseDir string, 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 takes 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). 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 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