checkers

Documentation

Overview

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

Index

• Constants
• Variables
• func Condition(name, arg string) string
• func ConditionWithPrefix(prefix, condition string) string
• func ContextWithClock(ctx context.Context, clock Clock) context.Context
• func ContextWithDeclared(ctx context.Context, declared map[string]string) context.Context
• func ContextWithOperations(ctx context.Context, ops ...string) context.Context
• func ExpiryTime(ns *Namespace, cavs []macaroon.Caveat) (time.Time, bool)
• func InferDeclared(ns *Namespace, ms macaroon.Slice) map[string]string
• func InferDeclaredFromConditions(ns *Namespace, conds []string) map[string]string
• func IsValidPrefix(prefix string) bool
• func IsValidSchemaURI(uri string) bool
• func MacaroonsExpiryTime(ns *Namespace, ms macaroon.Slice) (time.Time, bool)
• func ParseCaveat(cav string) (cond, arg string, err error)
• func RegisterStd(c *Checker)
• type Caveat
  • func AllowCaveat(op ...string) Caveat
  • func DeclaredCaveat(key string, value string) Caveat
  • func DenyCaveat(op ...string) Caveat
  • func ErrorCaveatf(f string, a ...interface{}) Caveat
  • func NeedDeclaredCaveat(cav Caveat, keys ...string) Caveat
  • func TimeBeforeCaveat(t time.Time) Caveat
• type Checker
  • func New(ns *Namespace) *Checker
  • func NewEmpty(ns *Namespace) *Checker
  • func (c *Checker) CheckFirstPartyCaveat(ctx context.Context, cav string) error
  • func (c *Checker) Info() []CheckerInfo
  • func (c *Checker) Namespace() *Namespace
  • func (c *Checker) Register(cond, uri string, check Func)
• type CheckerInfo
• type Clock
• type Func
• type Namespace
  • func NewNamespace(uriToPrefix map[string]string) *Namespace
  • func (ns *Namespace) EnsureResolved(uri string) (string, bool)
  • func (ns *Namespace) MarshalText() ([]byte, error)
  • func (ns *Namespace) Register(uri, prefix string)
  • func (ns *Namespace) Resolve(uri string) (string, bool)
  • func (ns *Namespace) ResolveCaveat(cav Caveat) Caveat
  • func (ns *Namespace) String() string
  • func (ns *Namespace) UnmarshalText(data []byte) error

Constants

const (
	CondDeclared   = "declared"
	CondTimeBefore = "time-before"
	CondError      = "error"
	CondAllow      = "allow"
	CondDeny       = "deny"
)

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.

Functions

func Condition

func Condition(name, arg string) string

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

func ConditionWithPrefix

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

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

func ContextWithDeclared

func ContextWithDeclared(ctx context.Context, declared map[string]string) context.Context

ContextWithDeclared returns a context with attached declared information, as returned from InferDeclared.

func ContextWithOperations

func ContextWithOperations(ctx context.Context, ops ...string) context.Context

ContextWithOperations returns a context which is associated with all the given operations. An allow caveat will succeed only if one of the allowed operations is in ops; a deny caveat will succeed only if none of the denied operations are in ops.

func ExpiryTime

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

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

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

func IsValidPrefix(prefix string) bool

func IsValidSchemaURI

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

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

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

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.

Types

type Caveat

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 AllowCaveat

func AllowCaveat(op ...string) Caveat

AllowCaveat returns a caveat that will deny attempts to use the macaroon to perform any operation other than those listed. Operations must not contain a space.

func DeclaredCaveat

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 DenyCaveat

func DenyCaveat(op ...string) Caveat

DenyCaveat returns a caveat that will deny attempts to use the macaroon to perform any of the listed operations. Operations must not contain a space.

func ErrorCaveatf

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

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

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

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

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

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

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

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

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

func (*Checker) Namespace

func (c *Checker) Namespace() *Namespace

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

func (*Checker) Register

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

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

type Clock interface {
	Now() time.Time
}

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

type Func

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

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 NewNamespace

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

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

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

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

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

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

func (ns *Namespace) String() string

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

func (*Namespace) UnmarshalText

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