macaroon-bakery.v2-unstable: gopkg.in/macaroon-bakery.v2-unstable/bakery/checkers Index | Files

package checkers

import "gopkg.in/macaroon-bakery.v2-unstable/bakery/checkers"

The checkers package provides some standard first-party caveat checkers and some primitives for combining them.

Index

Package Files

checkers.go declared.go namespace.go time.go

Constants

const (
    CondDeclared   = "declared"
    CondTimeBefore = "time-before"
    CondError      = "error"
)

Constants for all the standard caveat conditions. First and third party caveat conditions are both defined here, even though notionally they exist in separate name spaces.

const (
    CondNeedDeclared = "need-declared"
)
const StdNamespace = "std"

StdNamespace holds the URI of the standard checkers schema.

Variables

var ErrCaveatNotRecognized = errgo.New("caveat not recognized")

ErrCaveatNotRecognized is the cause of errors returned from caveat checkers when the caveat was not recognized.

func Condition Uses

func Condition(name, arg string) string

Condition builds a caveat condition from the given name and argument.

func ConditionWithPrefix Uses

func ConditionWithPrefix(prefix, condition string) string

ConditionWithPrefix returns the given string prefixed by the given prefix. If the prefix is non-empty, a colon is used to separate them.

func ContextWithClock Uses

func ContextWithClock(ctx context.Context, clock Clock) context.Context

func ContextWithMacaroons Uses

func ContextWithMacaroons(ctx context.Context, ns *Namespace, ms macaroon.Slice) context.Context

ContextWithMacaroons returns the given context associated with a macaroon slice and the name space to use to interpret caveats in the macaroons.

func ExpiryTime Uses

func ExpiryTime(ns *Namespace, cavs []macaroon.Caveat) (time.Time, bool)

ExpiryTime returns the minimum time of any time-before caveats found in the given slice and whether there were any such caveats found.

The ns parameter is used to determine the standard namespace prefix - if the standard namespace is not found, the empty prefix is assumed.

func InferDeclared Uses

func InferDeclared(ns *Namespace, ms macaroon.Slice) map[string]string

InferDeclared retrieves any declared information from the given macaroons and returns it as a key-value map.

Information is declared with a first party caveat as created by DeclaredCaveat.

If there are two caveats that declare the same key with different values, the information is omitted from the map. When the caveats are later checked, this will cause the check to fail.

func InferDeclaredFromConditions Uses

func InferDeclaredFromConditions(ns *Namespace, conds []string) map[string]string

InferDeclaredFromConditions is like InferDeclared except that it is passed a set of first party caveat conditions rather than a set of macaroons.

func IsValidPrefix Uses

func IsValidPrefix(prefix string) bool

func IsValidSchemaURI Uses

func IsValidSchemaURI(uri string) bool

IsValidSchemaURI reports whether the given argument is suitable for use as a namespace schema URI. It must be non-empty, a valid UTF-8 string and it must not contain white space.

func MacaroonsExpiryTime Uses

func MacaroonsExpiryTime(ns *Namespace, ms macaroon.Slice) (time.Time, bool)

MacaroonsExpiryTime returns the minimum time of any time-before caveats found in the given macaroons and whether there were any such caveats found.

func ParseCaveat Uses

func ParseCaveat(cav string) (cond, arg string, err error)

ParseCaveat parses a caveat into an identifier, identifying the checker that should be used, and the argument to the checker (the rest of the string).

The identifier is taken from all the characters before the first space character.

func RegisterStd Uses

func RegisterStd(c *Checker)

RegisterStd registers all the standard checkers in the given checker. If not present already, the standard checkers schema (StdNamespace) is added to the checker's namespace with an empty prefix.

type Caveat Uses

type Caveat struct {
    Condition string
    Namespace string
    Location  string
}

Caveat represents a condition that must be true for a check to complete successfully. If Location is non-empty, the caveat must be discharged by a third party at the given location. The Namespace field holds the namespace URI of the condition - if it is non-empty, it will be converted to a namespace prefix before adding to the macaroon.

func DeclaredCaveat Uses

func DeclaredCaveat(key string, value string) Caveat

DeclaredCaveat returns a "declared" caveat asserting that the given key is set to the given value. If a macaroon has exactly one first party caveat asserting the value of a particular key, then InferDeclared will be able to infer the value, and then DeclaredChecker will allow the declared value if it has the value specified here.

If the key is empty or contains a space, DeclaredCaveat will return an error caveat.

func ErrorCaveatf Uses

func ErrorCaveatf(f string, a ...interface{}) Caveat

ErrorCaveatf returns a caveat that will never be satisfied, holding the given fmt.Sprintf formatted text as the text of the caveat.

This should only be used for highly unusual conditions that are never expected to happen in practice, such as a malformed key that is conventionally passed as a constant. It's not a panic but you should only use it in cases where a panic might possibly be appropriate.

This mechanism means that caveats can be created without error checking and a later systematic check at a higher level (in the bakery package) can produce an error instead.

func NeedDeclaredCaveat Uses

func NeedDeclaredCaveat(cav Caveat, keys ...string) Caveat

NeedDeclaredCaveat returns a third party caveat that wraps the provided third party caveat and requires that the third party must add "declared" caveats for all the named keys. TODO(rog) namespaces in third party caveats?

func TimeBeforeCaveat Uses

func TimeBeforeCaveat(t time.Time) Caveat

TimeBeforeCaveat returns a caveat that specifies that the time that it is checked should be before t.

type Checker Uses

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

Checker holds a set of checkers for first party caveats. It implements bakery.CheckFirstParty caveat.

func New Uses

func New(ns *Namespace) *Checker

New returns a checker with all the standard caveats checkers registered. If ns is nil, a new one will be created. The standard namespace is also added to ns if not present.

func NewEmpty Uses

func NewEmpty(ns *Namespace) *Checker

NewEmpty returns a checker using the given namespace that has no registered checkers. If ns is nil, a new one will be created.

func (*Checker) CheckFirstPartyCaveat Uses

func (c *Checker) CheckFirstPartyCaveat(ctx context.Context, cav string) error

CheckFirstPartyCaveat implements bakery.FirstPartyCaveatChecker by checking the caveat against all registered caveats conditions.

func (*Checker) Info Uses

func (c *Checker) Info() []CheckerInfo

Info returns information on all the registered checkers, sorted by namespace and then name.

func (*Checker) Namespace Uses

func (c *Checker) Namespace() *Namespace

Namespace returns the namespace associated with the checker. It implements bakery.FirstPartyCaveatChecker.Namespace.

func (*Checker) Register Uses

func (c *Checker) Register(cond, uri string, check Func)

Register registers the given condition in the given namespace URI to be checked with the given check function. It will panic if the namespace is not registered or if the condition has already been registered.

type CheckerInfo Uses

type CheckerInfo struct {
    // Check holds the actual checker function.
    Check Func
    // Prefix holds the prefix for the checker condition.
    Prefix string
    // Name holds the name of the checker condition.
    Name string
    // Namespace holds the namespace URI for the checker's
    // schema.
    Namespace string
}

CheckerInfo holds information on a registered checker.

type Clock Uses

type Clock interface {
    Now() time.Time
}

Clock represents a clock that can be faked for testing purposes.

type Func Uses

type Func func(ctx context.Context, cond, arg string) error

Func is the type of a function used by Checker to check a caveat. The cond parameter will hold the caveat condition including any namespace prefix; the arg parameter will hold any additional caveat argument text.

type Namespace Uses

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

Namespace holds maps from schema URIs to the prefixes that are used to encode them in first party caveats. Several different URIs may map to the same prefix - this is usual when several different backwardly compatible schema versions are registered.

func MacaroonsFromContext Uses

func MacaroonsFromContext(ctx context.Context) (*Namespace, macaroon.Slice)

MacaroonsFromContext returns the namespace and macaroons associated with the context by ContextWithMacaroons. This can be used to implement "structural" first-party caveats that are predicated on the macaroons being validated.

func NewNamespace Uses

func NewNamespace(uriToPrefix map[string]string) *Namespace

NewNamespace returns a new namespace with the given initial contents. It will panic if any of the URI keys or their associated prefix are invalid (see IsValidSchemaURI and IsValidPrefix).

func (*Namespace) EnsureResolved Uses

func (ns *Namespace) EnsureResolved(uri string) (string, bool)

EnsureResolved tries to resolve the given schema URI to a prefix and returns the prefix and whether the resolution was successful. If the URI hasn't been registered but a compatible version has, the given URI is registered with the same prefix.

func (*Namespace) MarshalText Uses

func (ns *Namespace) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler by returning all the elements in the namespace sorted by URI, joined to the associated prefix with a colon and separated with spaces.

func (*Namespace) Register Uses

func (ns *Namespace) Register(uri, prefix string)

Register registers the given URI and associates it with the given prefix. If the URI has already been registered, this is a no-op.

func (*Namespace) Resolve Uses

func (ns *Namespace) Resolve(uri string) (string, bool)

Resolve resolves the given schema URI to its registered prefix and returns the prefix and whether the resolution was successful.

If ns is nil, it is treated as if it were empty.

Resolve does not mutate ns and may be called concurrently with other non-mutating Namespace methods.

func (*Namespace) ResolveCaveat Uses

func (ns *Namespace) ResolveCaveat(cav Caveat) Caveat

ResolveCaveat resolves the given caveat by using Resolve to map from its schema namespace to the appropriate prefix using Resolve. If there is no registered prefix for the namespace, it returns an error caveat.

If ns.Namespace is empty or ns.Location is non-empty, it returns cav unchanged.

If ns is nil, it is treated as if it were empty.

ResolveCaveat does not mutate ns and may be called concurrently with other non-mutating Namespace methods.

func (*Namespace) String Uses

func (ns *Namespace) String() string

String returns the namespace representation as returned by ns.MarshalText.

func (*Namespace) UnmarshalText Uses

func (ns *Namespace) UnmarshalText(data []byte) error

Package checkers imports 9 packages (graph) and is imported by 32 packages. Updated 2018-01-07. Refresh now. Tools for package owners.