macaroons

package
v1.0.0 Latest Latest
Warning

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

 Go to latest Published: Oct 13, 2022 License: BSD-3-Clause Imports: 18 Imported by: 0

Documentation

Overview

Author: Paul Côté Last Change Author: Paul Côté Last Date Changed: 2022/06/10

Copyright (C) 2015-2018 Lightning Labs and The Lightning Network Developers

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Author: Paul Côté Last Change Author: Paul Côté Last Date Changed: 2022/06/10

Copyright (C) 2015-2018 Lightning Labs and The Lightning Network Developers

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Author: Paul Côté Last Change Author: Paul Côté Last Date Changed: 2022/09/20

Copyright (C) 2015-2018 Lightning Labs and The Lightning Network Developers

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Author: Paul Côté Last Change Author: Paul Côté Last Date Changed: 2022/06/10

Copyright (C) 2015-2018 Lightning Labs and The Lightning Network Developers

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

Index

Constants

View Source 
const (
	ErrCantGetPeerFromContext   = bg.Error("unable to get peer info from context")
	ErrInvalidListOfPlugins     = bg.Error("invalid list of plugins")
	ErrUnauthorizedPluginAction = bg.Error("unauthorized plugin action")
	ErrNoMacaroonsFromContext   = bg.Error("no macaroons received from context")
)
View Source 
const (
	PermissionEntityCustomURI           = "uri"
	ErrMissingRootKeyID                 = bg.Error("missing root key ID")
	ErrValidatorNil                     = bg.Error("validator cannot be nil")
	ErrValidatorMethodAlreadyRegistered = bg.Error("external validator for method already registered")
	ErrMetadataFromContext              = bg.Error("unable to get metadata from context")
	ErrUnexpectedMacNumber              = bg.Error("unexpected number of macaroons")
	ErrKeyNotInContext                  = bg.Error("key is not in the context")
	PluginContextKey                    = "plugin"
)
View Source 
const (
	ErrAlreadyUnlocked       = bg.Error("macaroon store already unlocked")
	ErrContextRootKeyID      = bg.Error("failed to read root key ID from context")
	ErrKeyValueForbidden     = bg.Error("root key ID value is not allowed")
	ErrPasswordRequired      = bg.Error("a non-nil password is required")
	ErrStoreLocked           = bg.Error("macaroon store is locked")
	ErrRootKeyBucketNotFound = bg.Error("root key bucket not found")
	ErrEncKeyNotFound        = bg.Error("macaroon encryption key not found")
	ErrDeletionForbidden     = bg.Error("the specified ID cannot be deleted")
	ErrRootKeyIDNotFound     = bg.Error("root key with id doesn't exist")
)

Variables

View Source 
var (
	RootKeyIDContextKey = contextKey{"rootkeyid"}
	RootKeyLen          = 32
	DefaultRootKeyID    = []byte("0")
)

Functions

func AddConstraints 

func AddConstraints(mac *macaroon.Macaroon, cs ...Constraint) (*macaroon.Macaroon, error)

AddConstraints returns new derived macaroon by applying every passed constraint and tightening its restrictions.

func ContextWithRootKeyId 

func ContextWithRootKeyId(ctx context.Context, value interface{}) context.Context

ContextWithRootKeyId passes the root key ID value to context

func PluginCaveat 

func PluginCaveat(pluginNames []string) checkers.Caveat

PluginCaveat is a wrapper function which returns a checkers.Caveat struct

func PluginConstraint 

func PluginConstraint(pluginNames []string) func(*macaroon.Macaroon) error

PluginConstraint locks a macaroon to a given set of plugins. The plugin names are validated but not checked against currently registered list of plugins

func RootKeyIDFromContext 

func RootKeyIDFromContext(ctx context.Context) ([]byte, error)

RootKeyIDFromContext retrieves the root key ID from context using the key RootKeyIDContextKey.

func SafeCopyMacaroon 

func SafeCopyMacaroon(mac *macaroon.Macaroon) (*macaroon.Macaroon, error)

SafeCopyMacaroon creates a copy of a macaroon that is safe to be used and modified. This is necessary because the macaroon library's own Clone() method is unsafe for certain edge cases, resulting in both the cloned and the original macaroons to be modified.

func TimeoutCaveat 

func TimeoutCaveat(seconds int64) checkers.Caveat

TimeoutCaveat is a wrapper function which returns a checkers.Caveat struct

func TimeoutConstraint 

func TimeoutConstraint(seconds int64) func(*macaroon.Macaroon) error

TimeoutConstraint restricts the lifetime of the macaroon to the amount of seconds given.

Types

type Checker 

type Checker func() (string, checkers.Func)

type Constraint 

type Constraint func(*macaroon.Macaroon) error

type MacLogger 

type MacLogger struct {
	zerolog.Logger
}

func (*MacLogger) Debugf 

func (m *MacLogger) Debugf(ctx context.Context, f string, args ...interface{})

Debugf is part of the macaroon-bakery Logger interface

func (*MacLogger) Infof 

func (m *MacLogger) Infof(ctx context.Context, f string, args ...interface{})

Infof is part of the macaroon-bakery Logger interface

type MacaroonCredential 

type MacaroonCredential struct {
	*macaroon.Macaroon
}

func NewMacaroonCredential 

func NewMacaroonCredential(m *macaroon.Macaroon) (MacaroonCredential, error)

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(ctx context.Context, requiredPermissions []bakery.Op, fullMethod string) error
}

type RootKeyStorage 

type RootKeyStorage struct {
	kvdb.DB
	// contains filtered or unexported fields
}

func InitRootKeyStorage 

func InitRootKeyStorage(db kvdb.DB) (*RootKeyStorage, error)

InitRootKeyStorage initializes the top level bucket within the bbolt db for macaroons

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 resets the encryption key in memory

func (*RootKeyStorage) CreateUnlock 

func (r *RootKeyStorage) CreateUnlock(password *[]byte) error

CreateUnlock sets an encryption key if one isn't already set or checks if the password is correct for the existing encryption key.

func (*RootKeyStorage) DeleteMacaroonID 

func (r *RootKeyStorage) DeleteMacaroonID(
	_ context.Context, rootKeyID []byte) ([]byte, error)

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) Get 

func (r *RootKeyStorage) Get(_ context.Context, id []byte) ([]byte, error)

Get returns the root key for the given id. If the item is not there, it returns an error

func (*RootKeyStorage) ListMacaroonIDs 

func (r *RootKeyStorage) ListMacaroonIDs(_ context.Context) ([][]byte, error)

ListMacaroonIDs returns all the root key ID values except the value of encryptedKeyID.

func (*RootKeyStorage) RootKey 

func (r *RootKeyStorage) RootKey(ctx context.Context) ([]byte, []byte, error)

Implements RootKey from the bakery.RootKeyStorage interface

type Service 

type Service struct {
	bakery.Bakery

	ExternalValidators map[string]MacaroonValidator
	// contains filtered or unexported fields
}

func InitService 

func InitService(db kvdb.DB, location string, logger zerolog.Logger, pluginNames []string, checks ...Checker) (*Service, error)

InitService returns initializes the rootkeystorage for the Macaroon service and returns the initialized service

func (*Service) ChangePassword 

func (svc *Service) ChangePassword(oldPw, newPw []byte) error

ChangePassword calls the underlying root key store's ChangePassword and returns the result.

func (*Service) Close 

func (s *Service) Close() error

Close closes the rootkeystorage of the macaroon service

func (*Service) CreateUnlock 

func (s *Service) CreateUnlock(password *[]byte) error

Thin-wrapper for the CreateUnlock function of the RootKeyStorage attribute of the Service

func (*Service) DeleteMacaroonID 

func (svc *Service) DeleteMacaroonID(ctxt context.Context,
	rootKeyID []byte) ([]byte, error)

DeleteMacaroonID removes one specific root key ID. If the root key ID is found and deleted, it will be returned.

func (*Service) ListMacaroonIDs 

func (svc *Service) ListMacaroonIDs(ctxt context.Context) ([][]byte, error)

ListMacaroonIDs returns all the root key ID values except the value of encryptedKeyID.

func (*Service) NewMacaroon 

func (s *Service) NewMacaroon(ctx context.Context, rootKeyId []byte, cav []checkers.Caveat, ops ...bakery.Op) (*bakery.Macaroon, error)

NewMacaroon is a wrapper around the Oven.NewMacaroon method and returns a freshly baked macaroon

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

View all Source files

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.