notary: github.com/theupdateframework/notary/client Index | Examples | Files | Directories

package client

import "github.com/theupdateframework/notary/client"

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

Code:

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

Examples

Package Files

client.go delegations.go errors.go helpers.go interface.go reader.go repo.go tufclient.go witness.go

Constants

const (

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

func DeleteTrustData Uses

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 Uses

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.

type ErrInvalidLocalRole Uses

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 Uses

func (err ErrInvalidLocalRole) Error() string

type ErrInvalidRemoteRole Uses

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 Uses

func (err ErrInvalidRemoteRole) Error() string

type ErrNoSuchTarget Uses

type ErrNoSuchTarget string

ErrNoSuchTarget is returned when no valid trust data is found.

func (ErrNoSuchTarget) Error Uses

func (f ErrNoSuchTarget) Error() string

type ErrRepoNotInitialized Uses

type ErrRepoNotInitialized struct{}

ErrRepoNotInitialized is returned when trying to publish an uninitialized notary repository

func (ErrRepoNotInitialized) Error Uses

func (err ErrRepoNotInitialized) Error() string

type ErrRepositoryNotExist Uses

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 Uses

func (err ErrRepositoryNotExist) Error() string

type ReadOnly Uses

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 Uses

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 Uses

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 Uses

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 Uses

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 Uses

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

RoleWithSignatures is a Role with its associated signatures

type TUFLoadOptions Uses

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 Uses

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 Uses

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

NewTarget is a helper method that returns a Target

type TargetSignedStruct Uses

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 Uses

type TargetWithRole struct {
    Target
    Role data.RoleName
}

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

Directories

PathSynopsis
changelist

Package client imports 21 packages (graph) and is imported by 17 packages. Updated 2019-03-13. Refresh now. Tools for package owners.