bakery

package
v1.0.0-...-f3518ac Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Aug 22, 2018 License: LGPL-3.0 Imports: 16 Imported by: 26

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

Constants

View Source 
const KeyLen = 32

KeyLen is the byte length of the Ed25519 public and private keys used for caveat id encryption.

View Source 
const NonceLen = 24

NonceLen is the byte length of the nonce values used for caveat id encryption.

Variables

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

ErrNotFound is returned by Storage.Get implementations to signal that an id has not been found.

Functions

func Discharge 

func Discharge(key *KeyPair, checker ThirdPartyChecker, id string) (*macaroon.Macaroon, []checkers.Caveat, error)

Discharge creates a macaroon that discharges the third party caveat with the given id that should have been created earlier using key.Public. The condition implicit in the id is checked for validity using checker. If it is valid, a new macaroon is returned which discharges the caveat along with any caveats returned from the checker.

func DischargeAll 

func DischargeAll(
	m *macaroon.Macaroon,
	getDischarge func(firstPartyLocation string, cav macaroon.Caveat) (*macaroon.Macaroon, error),
) (macaroon.Slice, error)

DischargeAll gathers discharge macaroons for all the third party caveats in m (and any subsequent caveats required by those) using getDischarge to acquire each discharge macaroon. It returns a slice with m as the first element, followed by all the discharge macaroons. All the discharge macaroons will be bound to the primary macaroon.

func DischargeAllWithKey 

func DischargeAllWithKey(
	m *macaroon.Macaroon,
	getDischarge func(firstPartyLocation string, cav macaroon.Caveat) (*macaroon.Macaroon, error),
	localKey *KeyPair,
) (macaroon.Slice, error)

DischargeAllWithKey is like DischargeAll except that the localKey parameter may optionally hold the key of the client, in which case it will be used to discharge any third party caveats with the special location "local". In this case, the caveat itself must be "true". This can be used be a server to ask a client to prove ownership of the private key.

When localKey is nil, DischargeAllWithKey is exactly the same as DischargeAll.

func LocalThirdPartyCaveat 

func LocalThirdPartyCaveat(key *PublicKey) checkers.Caveat

LocalThirdPartyCaveat returns a third-party caveat that, when added to a macaroon with AddCaveat, results in a caveat with the location "local", encrypted with the given public key. This can be automatically discharged by DischargeAllWithKey.

Types

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 ErrCaveatNotRecognized.

type FirstPartyCheckerFunc 

type FirstPartyCheckerFunc func(caveat string) error

func (FirstPartyCheckerFunc) CheckFirstPartyCaveat 

func (c FirstPartyCheckerFunc) CheckFirstPartyCaveat(caveat string) error

type Key 

type Key [KeyLen]byte

Key is a 256-bit Ed25519 key.

func (Key) MarshalBinary 

func (k Key) MarshalBinary() ([]byte, error)

MarshalBinary implements encoding.BinaryMarshaler.MarshalBinary.

func (Key) MarshalText 

func (k Key) MarshalText() ([]byte, error)

MarshalText implements encoding.TextMarshaler.MarshalText.

func (Key) String 

func (k Key) String() string

String returns the base64 representation of the key.

func (*Key) UnmarshalBinary 

func (k *Key) UnmarshalBinary(data []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler.UnmarshalBinary.

func (*Key) UnmarshalText 

func (k *Key) UnmarshalText(text []byte) error

UnmarshalText implements encoding.TextUnmarshaler.UnmarshalText.

type KeyPair 

type KeyPair struct {
	Public  PublicKey  `json:"public"`
	Private PrivateKey `json:"private"`
}

KeyPair holds a public/private pair of keys.

func GenerateKey 

func GenerateKey() (*KeyPair, error)

GenerateKey generates a new key pair.

func (*KeyPair) String 

func (key *KeyPair) String() string

String implements the fmt.Stringer interface by returning the base64 representation of the public key part of key.

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

	// RootKeyStore is used to store macaroon root keys. If this
	// is non-nil, it will be used in preference to Store and it
	// will not be possible to specify non-empty macaroon ids and
	// root keys when calling NewMacaroon.
	RootKeyStore RootKeyStorage

	// Key is the public key pair used by the service for
	// third-party caveat encryption.
	// It may be nil, in which case a new key pair
	// will be generated.
	Key *KeyPair

	// Locator provides public keys for third-party services by location when
	// adding a third-party caveat.
	// It may be nil, in which case, no third-party caveats can be created.
	Locator PublicKeyLocator
}

NewServiceParams holds the parameters for a NewService call.

type PrivateKey 

type PrivateKey struct {
	Key
}

PrivateKey is a 256-bit Ed25519 private key.

type PublicKey 

type PublicKey struct {
	Key
}

PublicKey is a 256-bit Ed25519 public key.

type PublicKeyLocator 

type PublicKeyLocator interface {
	// PublicKeyForLocation returns the public key matching the caveat or
	// macaroon location. It returns ErrNotFound if no match is found.
	PublicKeyForLocation(loc string) (*PublicKey, error)
}

PublicKeyLocator is used to find the public key for a given caveat or macaroon location.

type PublicKeyLocatorMap 

type PublicKeyLocatorMap map[string]*PublicKey

PublicKeyLocatorMap implements PublicKeyLocator for a map. Each entry in the map holds a public key value for a location named by the map key.

func (PublicKeyLocatorMap) PublicKeyForLocation 

func (m PublicKeyLocatorMap) PublicKeyForLocation(loc string) (*PublicKey, error)

PublicKeyForLocation implements the PublicKeyLocator interface.

type PublicKeyRing 

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

PublicKeyRing stores public keys for third-party services, accessible by location string.

func NewPublicKeyRing 

func NewPublicKeyRing() *PublicKeyRing

NewPublicKeyRing returns a new PublicKeyRing instance.

func (*PublicKeyRing) AddPublicKeyForLocation 

func (kr *PublicKeyRing) AddPublicKeyForLocation(loc string, prefix bool, key *PublicKey) error

AddPublicKeyForLocation adds a public key to the keyring for the given location. If prefix is true, then inexact locations will be allowed (see PublicKeyForLocation). The matching is similar to that of http.ServeMux, For example, http://foo.com/x/ matches http://foo.com/x/y but http://foo.com/x does not.

As a special case, http://foo.com is always treated the same as http://foo.com/.

The scheme is not significant.

It is safe to call methods concurrently on this type. The loc argument should be a valid URL.

func (*PublicKeyRing) PublicKeyForLocation 

func (kr *PublicKeyRing) PublicKeyForLocation(loc string) (*PublicKey, error)

PublicKeyForLocation implements the PublicKeyLocator interface, by returning the public key most closely associated with loc. If loc is not a valid URL, it returns ErrNotFound; otherwise the host part of the URL must match a registered location.

Of those registered locations with matching host parts, longer paths take precedence over short ones. The matching is similar to that of http.ServeMux, except there must be a host part.

type RootKeyStorage 

type RootKeyStorage interface {
	// Get returns the root key for the given id.
	// If the item is not there, it returns ErrNotFound.
	Get(id string) ([]byte, error)

	// RootKey returns the root key to be used for making a new
	// macaroon, and an id that can be used to look it up later with
	// the Get method.
	//
	// Note that the root keys should remain available for as long
	// as the macaroons using them are valid.
	//
	// Note that there is no need for it to return a new root key
	// for every call - keys may be reused, although some key
	// cycling is over time is advisable.
	RootKey() (rootKey []byte, id string, err error)
}

RootKeyStorage defines defines storage for macaroon root keys.

func NewMemRootKeyStorage 

func NewMemRootKeyStorage() RootKeyStorage

NewMemRootKeyStorage returns an implementation of RootKeyStorage that generates a single key and always returns that from RootKey. The same id ("0") is always used.

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, error)

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 checkers.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.

As a special case, if the caveat's Location field has the prefix "local " the caveat is added as a client self-discharge caveat using the public key base64-encoded in the rest of the location. In this case, the Condition field must be empty. The resulting third-party caveat will encode the condition "true" encrypted with that public key. See LocalThirdPartyCaveat for a way of creating such caveats.

func (*Service) Check 

func (svc *Service) Check(ms macaroon.Slice, checker FirstPartyChecker) error

Check checks that the given macaroons verify correctly using the provided checker to check first party caveats. The primary macaroon is in ms[0]; the discharges fill the rest of the slice.

If there is a verification error, it returns a VerificationError that describes the error (other errors might be returned in other circumstances).

func (*Service) CheckAny 

func (svc *Service) CheckAny(mss []macaroon.Slice, assert map[string]string, checker checkers.Checker) (map[string]string, error)

CheckAny checks that the given slice of slices contains at least one macaroon minted by the given service, using checker to check any first party caveats. It returns an error with a *bakery.VerificationError cause if the macaroon verification failed.

The assert map holds any required attributes of "declared" attributes, overriding any inferences made from the macaroons themselves. It has a similar effect to adding a checkers.DeclaredCaveat for each key and value, but the error message will be more useful.

It adds all the standard caveat checkers to the given checker.

It returns any attributes declared in the successfully validated request.

func (*Service) CheckAnyM 

func (svc *Service) CheckAnyM(mss []macaroon.Slice, assert map[string]string, checker checkers.Checker) (map[string]string, macaroon.Slice, error)

CheckAnyM is like CheckAny except that on success it also returns the set of macaroons that was successfully checked. The "M" suffix is for backward compatibility reasons - in a later bakery version, the signature of CheckAny will be changed to return the macaroon slice and CheckAnyM will be removed.

func (*Service) Discharge 

func (svc *Service) Discharge(checker ThirdPartyChecker, id string) (*macaroon.Macaroon, error)

Discharge calls Discharge with the service's key and uses the service to add any returned caveats to the discharge macaroon.

func (*Service) Location 

func (svc *Service) Location() string

Location returns the service's configured macaroon location.

func (*Service) NewMacaroon 

func (svc *Service) NewMacaroon(id string, rootKey []byte, caveats []checkers.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. The macaroon will be stored in the service's storage. TODO swap the first two arguments so that they're in the same order as macaroon.New.

func (*Service) PublicKey 

func (svc *Service) PublicKey() *PublicKey

PublicKey returns the service's public key.

func (*Service) Store 

func (svc *Service) Store() Storage

Store returns the store used by the service. If the service has a RootKeyStorage (there was one specified in the parameters or the service was created with WithRootKeyStorage), it returns nil.

func (*Service) WithRootKeyStore 

func (svc *Service) WithRootKeyStore(store RootKeyStorage) *Service

WithRootKeyStore returns a copy of service where macaroon creation and lookup uses the given root key store to look up and create macaroon root keys.

When NewMacaroon is called on the returned Service, it must always be called with an empty id and rootKey.

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.

This type is the original storage interface supported by the bakery and will eventually be deprecated in favour of RootKeyStorage.

func NewMemStorage 

func NewMemStorage() Storage

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

type ThirdPartyChecker 

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

ThirdPartyChecker holds a function that checks third party caveats for validity. If the caveat is valid, it returns a nil error and optionally a slice of extra caveats that will be added to the discharge macaroon. The caveatId parameter holds the still-encoded id of the caveat.

If the caveat kind was not recognised, the checker should return an error with a ErrCaveatNotRecognized cause.

type ThirdPartyCheckerFunc 

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

func (ThirdPartyCheckerFunc) CheckThirdPartyCaveat 

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

type VerificationError 

type VerificationError struct {
	Reason error
}

func (*VerificationError) Error 

func (e *VerificationError) Error() string

Source Files

View all Source files

Directories

Path Synopsis
The checkers package provides some standard first-party caveat checkers and some primitives for combining them.
 The checkers package provides some standard first-party caveat checkers and some primitives for combining them.
This example demonstrates three components: - A target service, representing a web server that wishes to use macaroons for authorization.
 This example demonstrates three components: - A target service, representing a web server that wishes to use macaroons for authorization.
idservice
meeting
Package mgostorage provides an implementation of the bakery Storage interface that uses MongoDB to store items.
 Package mgostorage provides an implementation of the bakery Storage interface that uses MongoDB to store items.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.