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 ContextWithMacaroons(ctx context.Context, ns *Namespace, ms macaroon.Slice) 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
- type Checker
- type CheckerInfo
- type Clock
- type Func
- type Namespace
- func (ns *Namespace) EnsureResolved(uri string) (string, bool)
- func (ns1 *Namespace) Equal(ns2 *Namespace) 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" )
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 ConditionWithPrefix ¶
ConditionWithPrefix returns the given string prefixed by the given prefix. If the prefix is non-empty, a colon is used to separate them.
func ContextWithMacaroons ¶
ContextWithMacaroons returns the given context associated with a macaroon slice and the name space to use to interpret caveats in the macaroons.
func ExpiryTime ¶
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 ¶
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 ¶
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 IsValidSchemaURI ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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.
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 Func ¶
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 MacaroonsFromContext ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
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 ¶
String returns the namespace representation as returned by ns.MarshalText.
Source Files