bakery

Documentation

Overview

The bakery package layers on top of the macaroon package, providing a transport and storage-agnostic way of using macaroons to assert client capabilities.

Index

• Variables
• type Caveat
• type CaveatIdDecoder
• type CaveatIdEncoder
• type CaveatNotRecognizedError
  • func (e *CaveatNotRecognizedError) Error() string
• type Discharger
  • func (d *Discharger) Discharge(id string) (*macaroon.Macaroon, error)
• type FirstPartyChecker
• type FirstPartyCheckerFunc
  • func (c FirstPartyCheckerFunc) CheckFirstPartyCaveat(caveat string) error
• type NewMacarooner
• type NewServiceParams
• type Request
  • func (req *Request) AddClientMacaroon(m *macaroon.Macaroon)
  • func (req *Request) Check() error
• type Service
  • func NewService(p NewServiceParams) *Service
  • func (svc *Service) AddCaveat(m *macaroon.Macaroon, cav Caveat) error
  • func (svc *Service) NewMacaroon(id string, rootKey []byte, caveats []Caveat) (*macaroon.Macaroon, error)
  • func (svc *Service) NewRequest(checker FirstPartyChecker) *Request
  • func (svc *Service) Store() Storage
• type Storage
  • func NewMemStorage() Storage
• type ThirdPartyChecker
• type ThirdPartyCheckerFunc
  • func (c ThirdPartyCheckerFunc) CheckThirdPartyCaveat(caveat string) ([]Caveat, error)
• type VerificationError
  • func (e *VerificationError) Error() string

Variables

var ErrNotFound = errors.New("item not found")

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.

type CaveatIdDecoder

type CaveatIdDecoder interface {
	DecodeCaveatId(id string) (rootKey []byte, condition string, err error)
}

CaveatIdDecoder decodes caveat ids created by a CaveatIdEncoder.

type CaveatIdEncoder

type CaveatIdEncoder interface {
	EncodeCaveatId(caveat Caveat, rootKey []byte) (string, error)
}

CaveatIdEncoder can create caveat ids for third parties. It is left abstract to allow location-dependent caveat id creation.

type CaveatNotRecognizedError

type CaveatNotRecognizedError struct {
	Caveat string
}

func (*CaveatNotRecognizedError) Error

func (e *CaveatNotRecognizedError) Error() string

type Discharger

type Discharger struct {
	// Checker is used to check the caveat's condition.
	Checker ThirdPartyChecker

	// Decoder is used to decode the caveat id.
	Decoder CaveatIdDecoder

	// Factory is used to create the macaroon.
	// Note that *Service implements NewMacarooner.
	Factory NewMacarooner
}

A Discharger can be used to discharge third party caveats.

func (*Discharger) Discharge

func (d *Discharger) Discharge(id string) (*macaroon.Macaroon, error)

Discharge creates a macaroon that discharges the third party caveat with the given id. The id should have been created earlier with a matching CaveatIdEncoder. The condition implicit in the id is checked for validity using d.Checker, and then if valid, a new macaroon is minted which discharges the caveat, and can eventually be associated with a client request using AddClientMacaroon.

type FirstPartyChecker

type FirstPartyChecker interface {
	CheckFirstPartyCaveat(caveat string) error
}

FirstPartyChecker holds a function that checks first party caveats for validity.

If the caveat kind was not recognised, the checker should return ErrCaveatNotRecognised.

type FirstPartyCheckerFunc

type FirstPartyCheckerFunc func(caveat string) error

func (FirstPartyCheckerFunc) CheckFirstPartyCaveat

func (c FirstPartyCheckerFunc) CheckFirstPartyCaveat(caveat string) error

type NewMacarooner

type NewMacarooner interface {
	NewMacaroon(id string, rootKey []byte, caveats []Caveat) (*macaroon.Macaroon, error)
}

NewMacaroon mints a new macaroon with the given id and caveats. If the id is empty, a random id will be used. If rootKey is nil, a random root key will be used.

type NewServiceParams

type NewServiceParams struct {
	// Location will be set as the location of any macaroons
	// minted by the service.
	Location string

	// Store will be used to store macaroon
	// information locally. If it is nil,
	// an in-memory storage will be used.
	Store Storage

	// CaveatIdEncoder is used to create third-party caveats.
	CaveatIdEncoder CaveatIdEncoder
}

NewServiceParams holds the parameters for a NewService call.

type Request

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

Request represents a request made to a service by a client. The request may be long-lived. It holds a set of macaroons that the client wishes to be taken into account.

Methods on a Request may be called concurrently with each other.

func (*Request) AddClientMacaroon

func (req *Request) AddClientMacaroon(m *macaroon.Macaroon)

AddClientMacaroon associates the given macaroon with the request. The macaroon will be taken into account when req.Check is called.

TODO(rog) provide a way of deleting client macaroons?

func (*Request) Check

func (req *Request) Check() error

Check checks that the macaroons presented by the client verify correctly. If the verification fails in a way which might be remediable (for example by the addition of additional dicharge macaroons), it returns a VerificationError that describes the error.

type Service

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

Service represents a service which can use macaroons to check authorization.

func NewService

func NewService(p NewServiceParams) *Service

NewService returns a new service that can mint new macaroons and store their associated root keys.

func (*Service) AddCaveat

func (svc *Service) AddCaveat(m *macaroon.Macaroon, cav Caveat) error

AddCaveat adds a caveat to the given macaroon.

If it's a third-party caveat, it uses the service's caveat-id encoder to create the id of the new caveat.

func (*Service) NewMacaroon

func (svc *Service) NewMacaroon(id string, rootKey []byte, caveats []Caveat) (*macaroon.Macaroon, error)

NewMacaroon implements NewMacarooner.NewMacaroon.

func (*Service) NewRequest

func (svc *Service) NewRequest(checker FirstPartyChecker) *Request

NewRequest returns a new client request object that uses checker to verify caveats.

func (*Service) Store

func (svc *Service) Store() Storage

Store returns the store used by the service.

type Storage

type Storage interface {
	// Put stores the item at the given location, overwriting
	// any item that might already be there.
	// TODO(rog) would it be better to lose the overwrite
	// semantics?
	Put(location string, item string) error

	// Get retrieves an item from the given location.
	// If the item is not there, it returns ErrNotFound.
	Get(location string) (item string, err error)

	// Del deletes the item from the given location.
	Del(location string) error
}

Storage defines storage for macaroons. Calling its methods concurrently is allowed.

func NewMemStorage

func NewMemStorage() Storage

NewMemStorage returns an implementation of Storage that stores all items in memory.

type ThirdPartyChecker

type ThirdPartyChecker interface {
	CheckThirdPartyCaveat(caveat string) ([]Caveat, error)
}

ThirdPartyChecker holds a function that checks third party caveats for validity. It the caveat is valid, it returns a nil error and optionally a slice of extra caveats that will be added to the discharge macaroon.

If the caveat kind was not recognised, the checker should return ErrCaveatNotRecognised.

type ThirdPartyCheckerFunc

type ThirdPartyCheckerFunc func(caveat string) ([]Caveat, error)

func (ThirdPartyCheckerFunc) CheckThirdPartyCaveat

func (c ThirdPartyCheckerFunc) CheckThirdPartyCaveat(caveat string) ([]Caveat, error)

type VerificationError

type VerificationError struct {
	Reason error
}

func (*VerificationError) Error

func (e *VerificationError) Error() string