checkers

Documentation

Overview

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

Index

• Constants
• Variables
• func ExpiryTime(cavs []macaroon.Caveat) (time.Time, bool)
• func MacaroonsExpiryTime(ms macaroon.Slice) (time.Time, bool)
• func ParseCaveat(cav string) (cond, arg string, err error)
• type Caveat
  • func AllowCaveat(op ...string) Caveat
  • func ClientIPAddrCaveat(addr net.IP) Caveat
  • func ClientOriginCaveat(origin 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
• type CheckerFunc
  • func (f CheckerFunc) Check(cond, arg string) error
  • func (f CheckerFunc) Condition() string
• type Declared
  • func InferDeclared(ms macaroon.Slice) Declared
  • func (c Declared) Check(_, arg string) error
  • func (c Declared) Condition() string
• type Map
  • func (m Map) Check(cond, arg string) error
  • func (m Map) Condition() string
• type MultiChecker
  • func New(checkers ...Checker) *MultiChecker
  • func (c *MultiChecker) Check(cond, arg string) error
  • func (c *MultiChecker) CheckFirstPartyCaveat(cav string) error
  • func (c *MultiChecker) Condition() string
• type OperationChecker
  • func (o OperationChecker) Check(cond, arg string) error
  • func (OperationChecker) Condition() string
• type OperationsChecker
  • func (os OperationsChecker) Check(cond, arg string) error
  • func (OperationsChecker) Condition() string

Constants

const (
	CondDeclared     = "declared"
	CondTimeBefore   = "time-before"
	CondClientIPAddr = "client-ip-addr"
	CondClientOrigin = "origin"
	CondError        = "error"
	CondNeedDeclared = "need-declared"
	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.

Variables

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

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

var TimeBefore = CheckerFunc{
	Condition_: CondTimeBefore,
	Check_: func(_, cav string) error {
		t, err := time.Parse(time.RFC3339Nano, cav)
		if err != nil {
			return errgo.Mask(err)
		}
		if !timeNow().Before(t) {
			return fmt.Errorf("macaroon has expired")
		}
		return nil
	},
}

TimeBefore is a checker that checks caveats as created by TimeBeforeCaveat.

Functions

func ExpiryTime

func ExpiryTime(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.

func MacaroonsExpiryTime

func MacaroonsExpiryTime(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.

Types

type Caveat

type Caveat struct {
	Location  string
	Condition 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. This differs from macaroon.Caveat in that the condition is not encrypted.

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 ClientIPAddrCaveat

func ClientIPAddrCaveat(addr net.IP) Caveat

ClientIPAddrCaveat returns a caveat that will check whether the client's IP address is as provided. Note that the checkers package provides no specific implementation of the checker for this - that is left to external transport-specific packages.

func ClientOriginCaveat

func ClientOriginCaveat(origin string) Caveat

ClientOriginCaveat returns a caveat that will check whether the client's Origin header in its HTTP request is as provided.

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.

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 interface {
	// Condition returns the identifier of the condition
	// to be checked - the Check method will be used
	// to check caveats with this identifier.
	//
	// It may return an empty string, in which case
	// it will be used to check any condition
	Condition() string

	// Check checks that the given caveat holds true.
	// The condition and arg are as returned
	// from ParseCaveat.
	//
	// For a checker with an empty condition, a
	// return of bakery.ErrCaveatNotRecognised from
	// this method indicates that the condition was
	// not recognized.
	Check(cond, arg string) error
}

Checker is implemented by types that can check caveats.

type CheckerFunc

type CheckerFunc struct {
	// Condition_ holds the condition that the checker
	// implements.
	Condition_ string

	// Check_ holds the function to call to make the check.
	Check_ func(cond, arg string) error
}

CheckerFunc implements Checker for a function.

func (CheckerFunc) Check

func (f CheckerFunc) Check(cond, arg string) error

Check implements Checker.Check

func (CheckerFunc) Condition

func (f CheckerFunc) Condition() string

Condition implements Checker.Condition.

type Declared

type Declared map[string]string

Declared implements a checker that will check that any "declared" caveats have a matching key for their value in the map.

func InferDeclared

func InferDeclared(ms macaroon.Slice) Declared

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 (Declared) Check

func (c Declared) Check(_, arg string) error

Check implements Checker.Check by checking that the given argument holds a key in the map with a matching value.

func (Declared) Condition

func (c Declared) Condition() string

Condition implements Checker.Condition.

type Map

type Map map[string]func(cond string, arg string) error

Map is a checker where the various checkers are specified as entries in a map, one for each condition. The cond argument passed to the function is always the same as its corresponding key in the map.

func (Map) Check

func (m Map) Check(cond, arg string) error

Check implements Checker.Check

func (Map) Condition

func (m Map) Condition() string

Condition implements Checker.Condition.

type MultiChecker

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

MultiChecker implements bakery.FirstPartyChecker and Checker for a collection of checkers.

func New

func New(checkers ...Checker) *MultiChecker

New returns a new MultiChecker that uses all the provided Checkers to check caveats. If several checkers return the same condition identifier, all of them will be used.

The cause of any error returned by a checker will be preserved.

Note that because the returned checker implements Checker as well as bakery.FirstPartyChecker, calls to New can be nested. For example, a checker can be easily added to an existing MultiChecker, by doing:

checker := checkers.New(old, another)

func (*MultiChecker) Check

func (c *MultiChecker) Check(cond, arg string) error

Check implements Checker.Check.

func (*MultiChecker) CheckFirstPartyCaveat

func (c *MultiChecker) CheckFirstPartyCaveat(cav string) error

CheckFirstPartyCaveat implements bakery.FirstPartyChecker.CheckFirstPartyCaveat.

func (*MultiChecker) Condition

func (c *MultiChecker) Condition() string

Condition implements Checker.Condition.

type OperationChecker

type OperationChecker string

OperationChecker checks any allow or deny caveats, ensuring they do not prohibit the named operation.

func (OperationChecker) Check

func (o OperationChecker) Check(cond, arg string) error

Check implements Checker.Check.

func (OperationChecker) Condition

func (OperationChecker) Condition() string

Condition implements Checker.Condition.

type OperationsChecker

type OperationsChecker []string

OperationsChecker checks any allow or deny caveats with respect to all the named operations in the slice. An allow caveat must allow all the operations in the slice; a deny caveat will fail if it denies any operation in the slice.

func (OperationsChecker) Check

func (os OperationsChecker) Check(cond, arg string) error

Check implements Checker.Check.

func (OperationsChecker) Condition

func (OperationsChecker) Condition() string

Condition implements Checker.Condition.