README
¶
Macaroons
This package makes the lnd/macaroons package a standalone go module.
Commit: 42099ef5.
CHANGELOG
- Filename is provided as argument to
NewService()instead of being hardcoded into a string variable.
Documentation
¶
Index ¶
- Constants
- Variables
- func AddConstraints(mac *macaroon.Macaroon, cs ...Constraint) (*macaroon.Macaroon, error)
- func ContextWithRootKeyID(ctx context.Context, value interface{}) context.Context
- func IPLockChecker() (string, checkers.Func)
- func IPLockConstraint(ipAddr string) func(*macaroon.Macaroon) error
- func RootKeyIDFromContext(ctx context.Context) ([]byte, error)
- func TimeoutConstraint(seconds int64) func(*macaroon.Macaroon) error
- type Checker
- type Constraint
- type MacaroonCredential
- type MacaroonValidator
- type RootKeyStorage
- func (r *RootKeyStorage) ChangePassword(oldPw, newPw []byte) error
- func (r *RootKeyStorage) Close() error
- func (r *RootKeyStorage) CreateUnlock(password *[]byte) error
- func (r *RootKeyStorage) DeleteMacaroonID(_ context.Context, rootKeyID []byte) ([]byte, error)
- func (r *RootKeyStorage) GenerateNewRootKey() error
- func (r *RootKeyStorage) Get(_ context.Context, id []byte) ([]byte, error)
- func (r *RootKeyStorage) ListMacaroonIDs(_ context.Context) ([][]byte, error)
- func (r *RootKeyStorage) RootKey(ctx context.Context) ([]byte, []byte, error)
- type Service
- func (svc *Service) ChangePassword(oldPw, newPw []byte) error
- func (svc *Service) Close() error
- func (svc *Service) CreateUnlock(password *[]byte) error
- func (svc *Service) DeleteMacaroonID(ctxt context.Context, rootKeyID []byte) ([]byte, error)
- func (svc *Service) GenerateNewRootKey() error
- func (svc *Service) ListMacaroonIDs(ctxt context.Context) ([][]byte, error)
- func (svc *Service) NewMacaroon(ctx context.Context, rootKeyID []byte, ops ...bakery.Op) (*bakery.Macaroon, error)
- func (svc *Service) RegisterExternalValidator(fullMethod string, validator MacaroonValidator) error
- func (svc *Service) ValidateMacaroon(ctx context.Context, requiredPermissions []bakery.Op, fullMethod string) error
Constants ¶
const (
// RootKeyLen is the length of a root key.
RootKeyLen = 32
)
Variables ¶
var ( // RootKeyIDContextKey is the key to get rootKeyID from context. RootKeyIDContextKey = contextKey{"rootkeyid"} // ErrContextRootKeyID is used when the supplied context doesn't have // a root key ID. ErrContextRootKeyID = fmt.Errorf( "failed to read root key ID from context", ) )
var ( // ErrMissingRootKeyID specifies the root key ID is missing. ErrMissingRootKeyID = fmt.Errorf("missing root key ID") // ErrDeletionForbidden is used when attempting to delete the // DefaultRootKeyID or the encryptedKeyID. ErrDeletionForbidden = fmt.Errorf("the specified ID cannot be deleted") // PermissionEntityCustomURI is a special entity name for a permission // that does not describe an entity:action pair but instead specifies a // specific URI that needs to be granted access to. This can be used for // more fine-grained permissions where a macaroon only grants access to // certain methods instead of a whole list of methods that define the // same entity:action pairs. PermissionEntityCustomURI = "uri" )
var ( // DefaultRootKeyID is the ID of the default root key. The first is // just 0, to emulate the memory storage that comes with bakery. DefaultRootKeyID = []byte("0") // ErrAlreadyUnlocked specifies that the store has already been // unlocked. ErrAlreadyUnlocked = fmt.Errorf("macaroon store already unlocked") // ErrStoreLocked specifies that the store needs to be unlocked with // a password. ErrStoreLocked = fmt.Errorf("macaroon store is locked") // ErrPasswordRequired specifies that a nil password has been passed. ErrPasswordRequired = fmt.Errorf("a non-nil password is required") // ErrKeyValueForbidden is used when the root key ID uses encryptedKeyID as // its value. ErrKeyValueForbidden = fmt.Errorf("root key ID value is not allowed") // ErrRootKeyBucketNotFound specifies that there is no macaroon root key // bucket yet which can/should only happen if the store has been // corrupted or was initialized incorrectly. ErrRootKeyBucketNotFound = fmt.Errorf("root key bucket not found") // ErrEncKeyNotFound specifies that there was no encryption key found // even if one was expected to be generated. ErrEncKeyNotFound = fmt.Errorf("macaroon encryption key not found") )
Functions ¶
func AddConstraints ¶
AddConstraints returns new derived macaroon by applying every passed constraint and tightening its restrictions.
func ContextWithRootKeyID ¶
ContextWithRootKeyID passes the root key ID value to context.
func IPLockChecker ¶
IPLockChecker accepts client IP from the validation context and compares it with IP locked in the macaroon. It is of the `Checker` type.
func IPLockConstraint ¶
IPLockConstraint locks macaroon to a specific IP address. If address is an empty string, this constraint does nothing to accommodate default value's desired behavior.
func RootKeyIDFromContext ¶
RootKeyIDFromContext retrieves the root key ID from context using the key RootKeyIDContextKey.
Types ¶
type Checker ¶
Checker type adds a layer of indirection over macaroon checkers. A Checker returns the name of the checker and the checker function; these are used to register the function with the bakery service's compound checker.
type Constraint ¶
Constraint type adds a layer of indirection over macaroon caveats.
type MacaroonCredential ¶
MacaroonCredential wraps a macaroon to implement the credentials.PerRPCCredentials interface.
func NewMacaroonCredential ¶
func NewMacaroonCredential(m *macaroon.Macaroon, withTLS bool) MacaroonCredential
NewMacaroonCredential returns a copy of the passed macaroon wrapped in a MacaroonCredential struct which implements PerRPCCredentials.
func (MacaroonCredential) GetRequestMetadata ¶
func (m MacaroonCredential) GetRequestMetadata( ctx context.Context, uri ...string, ) (map[string]string, error)
GetRequestMetadata implements the PerRPCCredentials interface. This method is required in order to pass the wrapped macaroon into the gRPC context. With this, the macaroon will be available within the request handling scope of the ultimate gRPC server implementation.
func (MacaroonCredential) RequireTransportSecurity ¶
func (m MacaroonCredential) RequireTransportSecurity() bool
RequireTransportSecurity implements the PerRPCCredentials interface.
type MacaroonValidator ¶
type MacaroonValidator interface {
// ValidateMacaroon extracts the macaroon from the context's gRPC
// metadata, checks its signature, makes sure all specified permissions
// for the called method are contained within and finally ensures all
// caveat conditions are met. A non-nil error is returned if any of the
// checks fail.
ValidateMacaroon(ctx context.Context,
requiredPermissions []bakery.Op, fullMethod string) error
}
MacaroonValidator is an interface type that can check if macaroons are valid.
type RootKeyStorage ¶
RootKeyStorage implements the bakery.RootKeyStorage interface.
func NewRootKeyStorage ¶
func NewRootKeyStorage(db kvdb.Backend) (*RootKeyStorage, error)
NewRootKeyStorage creates a RootKeyStorage instance. TODO(aakselrod): Add support for encryption of data with passphrase.
func (*RootKeyStorage) ChangePassword ¶
func (r *RootKeyStorage) ChangePassword(oldPw, newPw []byte) error
ChangePassword decrypts the macaroon root key with the old password and then encrypts it again with the new password.
func (*RootKeyStorage) Close ¶
func (r *RootKeyStorage) Close() error
Close closes the underlying database and zeroes the encryption key stored in memory.
func (*RootKeyStorage) CreateUnlock ¶
func (r *RootKeyStorage) CreateUnlock(password *[]byte) error
CreateUnlock sets an encryption key if one is not already set, otherwise it checks if the password is correct for the stored encryption key.
func (*RootKeyStorage) DeleteMacaroonID ¶
DeleteMacaroonID removes one specific root key ID. If the root key ID is found and deleted, it will be returned.
func (*RootKeyStorage) GenerateNewRootKey ¶
func (r *RootKeyStorage) GenerateNewRootKey() error
GenerateNewRootKey generates a new macaroon root key, replacing the previous root key if it existed.
func (*RootKeyStorage) ListMacaroonIDs ¶
func (r *RootKeyStorage) ListMacaroonIDs(_ context.Context) ([][]byte, error)
ListMacaroonIDs returns all the root key ID values except the value of encryptedKeyID.
type Service ¶
type Service struct {
bakery.Bakery
// ExternalValidators is a map between an absolute gRPC URIs and the
// corresponding external macaroon validator to be used for that URI.
// If no external validator for an URI is specified, the service will
// use the internal validator.
ExternalValidators map[string]MacaroonValidator
// StatelessInit denotes if the service was initialized in the stateless
// mode where no macaroon files should be created on disk.
StatelessInit bool
// contains filtered or unexported fields
}
Service encapsulates bakery.Bakery and adds a Close() method that zeroes the root key service encryption keys, as well as utility methods to validate a macaroon against the bakery and gRPC middleware for macaroon-based auth.
func NewService ¶
func NewService( datadir, location, filename string, statelessInit bool, checks ...Checker, ) (*Service, error)
NewService returns a service backed by the macaroon Bolt DB stored in the passed directory. The `checks` argument can be any of the `Checker` type functions defined in this package, or a custom checker if desired. This constructor prevents double-registration of checkers to prevent panics, so listing the same checker more than once is not harmful. Default checkers, such as those for `allow`, `time-before`, `declared`, and `error` caveats are registered automatically and don't need to be added.
func (*Service) ChangePassword ¶
ChangePassword calls the underlying root key store's ChangePassword and returns the result.
func (*Service) Close ¶
Close closes the database that underlies the RootKeyStore and zeroes the encryption keys.
func (*Service) CreateUnlock ¶
CreateUnlock calls the underlying root key store's CreateUnlock and returns the result.
func (*Service) DeleteMacaroonID ¶
DeleteMacaroonID removes one specific root key ID. If the root key ID is found and deleted, it will be returned.
func (*Service) GenerateNewRootKey ¶
GenerateNewRootKey calls the underlying root key store's GenerateNewRootKey and returns the result.
func (*Service) ListMacaroonIDs ¶
ListMacaroonIDs returns all the root key ID values except the value of encryptedKeyID.
func (*Service) NewMacaroon ¶
func (svc *Service) NewMacaroon( ctx context.Context, rootKeyID []byte, ops ...bakery.Op) (*bakery.Macaroon, error)
NewMacaroon wraps around the function Oven.NewMacaroon with the defaults,
- version is always bakery.LatestVersion;
- caveats is always nil.
In addition, it takes a rootKeyID parameter, and puts it into the context. The context is passed through Oven.NewMacaroon(), in which calls the function RootKey(), that reads the context for rootKeyID.
func (*Service) RegisterExternalValidator ¶
func (svc *Service) RegisterExternalValidator(fullMethod string, validator MacaroonValidator) error
RegisterExternalValidator registers a custom, external macaroon validator for the specified absolute gRPC URI. That validator is then fully responsible to make sure any macaroon passed for a request to that URI is valid and satisfies all conditions.
func (*Service) ValidateMacaroon ¶
func (svc *Service) ValidateMacaroon(ctx context.Context, requiredPermissions []bakery.Op, fullMethod string) error
ValidateMacaroon validates the capabilities of a given request given a bakery service, context, and uri. Within the passed context.Context, we expect a macaroon to be encoded as request metadata using the key "macaroon".
Source Files