The highest tagged major version is
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
- Variables
- func DischargeAll(m *macaroon.Macaroon, ...) (macaroon.Slice, error)
- type FirstPartyChecker
- type FirstPartyCheckerFunc
- type Key
- type KeyPair
- type NewServiceParams
- type PrivateKey
- type PublicKey
- type PublicKeyLocator
- type PublicKeyLocatorMap
- type PublicKeyRing
- type Service
- func (svc *Service) AddCaveat(m *macaroon.Macaroon, cav checkers.Caveat) error
- func (svc *Service) Check(ms macaroon.Slice, checker FirstPartyChecker) error
- func (svc *Service) CheckAny(mss []macaroon.Slice, assert map[string]string, checker checkers.Checker) (map[string]string, error)
- func (svc *Service) Discharge(checker ThirdPartyChecker, id string) (*macaroon.Macaroon, error)
- func (svc *Service) Location() string
- func (svc *Service) NewMacaroon(id string, rootKey []byte, caveats []checkers.Caveat) (*macaroon.Macaroon, error)
- func (svc *Service) PublicKey() *PublicKey
- func (svc *Service) Store() Storage
- type Storage
- type ThirdPartyChecker
- type ThirdPartyCheckerFunc
- type VerificationError
Constants ¶
const KeyLen = 32
KeyLen is the byte length of the Ed25519 public and private keys used for caveat id encryption.
const NonceLen = 24
NonceLen is the byte length of the nonce values used for caveat id encryption.
Variables ¶
var ErrNotFound = errors.New("item not found")
Functions ¶
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.
Types ¶
type FirstPartyChecker ¶
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 ¶
func (FirstPartyCheckerFunc) CheckFirstPartyCaveat ¶
func (c FirstPartyCheckerFunc) CheckFirstPartyCaveat(caveat string) error
type Key ¶
Key is a 256-bit Ed25519 key.
func (Key) MarshalBinary ¶
MarshalBinary implements encoding.BinaryMarshaler.MarshalBinary.
func (Key) MarshalText ¶
MarshalText implements encoding.TextMarshaler.MarshalText.
func (*Key) UnmarshalBinary ¶
UnmarshalBinary implements encoding.BinaryUnmarshaler.UnmarshalBinary.
func (*Key) UnmarshalText ¶
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.
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
// 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 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 ¶
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 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 ¶
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) 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) Discharge ¶
func (svc *Service) Discharge(checker ThirdPartyChecker, 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 by a Service. The condition implicit in the id is checked for validity using 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.
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.
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(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 ¶
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
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. |
|
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. |