macaroon

package
v0.0.0-...-eb3fb91 Latest Latest
Warning

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

 Go to latest Published: Dec 17, 2024 License: MIT Imports: 18 Imported by: 22

Documentation

Overview

Package macaroon implements contextual caveats and authorization.

Index

Constants

This section is empty.

Variables

View Source 
var (
	// Error is a general API Key error.
	Error = errs.Class("api key")
	// ErrFormat means that the structural formatting of the API Key is invalid.
	ErrFormat = errs.Class("api key format")
	// ErrInvalid means that the API Key is improperly signed.
	ErrInvalid = errs.Class("api key invalid")
	// ErrUnauthorized means that the API key does not grant the requested permission.
	ErrUnauthorized = errs.Class("api key unauthorized")
	// ErrRevoked means the API key has been revoked.
	ErrRevoked = errs.Class("api key revocation")
)

Functions

func NewSecret 

func NewSecret() (secret []byte, err error)

NewSecret generates cryptographically random 32 bytes.

Types

type APIKey 

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

APIKey implements a Macaroon-backed Storj-v3 API key.

func FromParts 

func FromParts(head, secret []byte, caveats ...Caveat) (_ *APIKey, err error)

FromParts generates an api key from the provided parts.

func NewAPIKey 

func NewAPIKey(secret []byte) (*APIKey, error)

NewAPIKey generates a brand new unrestricted API key given the provided. server project secret.

func ParseAPIKey 

func ParseAPIKey(key string) (*APIKey, error)

ParseAPIKey parses a given api key string and returns an APIKey if the APIKey was correctly formatted. It does not validate the key.

func ParseRawAPIKey 

func ParseRawAPIKey(data []byte) (*APIKey, error)

ParseRawAPIKey parses raw api key data and returns an APIKey if the APIKey was correctly formatted. It does not validate the key.

func (*APIKey) Check 

func (a *APIKey) Check(ctx context.Context, secret []byte, version APIKeyVersion, action Action, revoker revoker) (err error)

Check makes sure that the key authorizes the provided action given the root project secret, the API key's version, and any possible revocations, returning an error if the action is not authorized. 'revoked' is a list of revoked heads.

func (*APIKey) GetAllowedBuckets 

func (a *APIKey) GetAllowedBuckets(ctx context.Context, action Action) (allowed AllowedBuckets, err error)

GetAllowedBuckets returns a list of all the allowed bucket paths that match the Action operation.

func (*APIKey) GetMaxObjectTTL 

func (a *APIKey) GetMaxObjectTTL(ctx context.Context) (ttl *time.Duration, err error)

GetMaxObjectTTL returns the shortest MaxObjectTTL period conifgured in the APIKey's caveats.

func (*APIKey) Head 

func (a *APIKey) Head() []byte

Head returns the identifier for this macaroon's root ancestor.

func (*APIKey) Restrict 

func (a *APIKey) Restrict(caveat Caveat) (*APIKey, error)

Restrict generates a new APIKey with the provided Caveat attached.

func (*APIKey) Serialize 

func (a *APIKey) Serialize() string

Serialize serializes the API Key to a string.

func (*APIKey) SerializeRaw 

func (a *APIKey) SerializeRaw() []byte

SerializeRaw serialize the API Key to raw bytes.

func (*APIKey) Tail 

func (a *APIKey) Tail() []byte

Tail returns the identifier for this macaroon only.

type APIKeyVersion 

type APIKeyVersion uint

APIKeyVersion specifies the version of an API key. 

const (
	// APIKeyVersionMin is the minimum API key version.
	// It is for API keys that only support read, write, list, delete,
	// and project info retrieval actions.
	APIKeyVersionMin APIKeyVersion = 0

	// APIKeyVersionObjectLock is the API key version that introduces support
	// for Object Lock actions.
	APIKeyVersionObjectLock APIKeyVersion = 1

	// APIKeyVersionLatest is the latest API key version.
	APIKeyVersionLatest APIKeyVersion = APIKeyVersionObjectLock
)

type Action 

type Action struct {
	Op            ActionType
	Bucket        []byte
	EncryptedPath []byte
	Time          time.Time
}

Action specifies the specific operation being performed that the Macaroon will validate.

type ActionType 

type ActionType int

ActionType specifies the operation type being performed that the Macaroon will validate. 

const (

	// ActionRead specifies a read operation.
	ActionRead ActionType = 1
	// ActionWrite specifies a write operation.
	ActionWrite ActionType = 2
	// ActionList specifies a list operation.
	ActionList ActionType = 3
	// ActionDelete specifies a delete operation.
	ActionDelete ActionType = 4
	// ActionProjectInfo requests project-level information.
	ActionProjectInfo ActionType = 5
	// ActionLock represents the following actions:
	//
	//   - Placement or retrieval of retention periods for an object
	//   - Placement or retrieval of Object Lock configurations for a bucket
	//
	// Deprecated: ActionLock exists for historical compatibility
	// and should not be used. Prefer using the granular Object Lock actions
	// ActionPutObjectRetention and ActionGetObjectRetention.
	ActionLock ActionType = 6
	// ActionPutObjectRetention specifies an action related to updating
	// Object Retention configuration.
	ActionPutObjectRetention ActionType = 7
	// ActionGetObjectRetention specifies an action related to retrieving
	// Object Retention configuration.
	ActionGetObjectRetention ActionType = 8
	// ActionPutObjectLegalHold specifies an action related to updating
	// Object Legal Hold configuration.
	ActionPutObjectLegalHold ActionType = 9
	// ActionGetObjectLegalHold specifies an action related to retrieving
	// Object Legal Hold configuration.
	ActionGetObjectLegalHold ActionType = 10
	// ActionBypassGovernanceRetention specifies an action related to bypassing
	// Object Governance Retention.
	ActionBypassGovernanceRetention ActionType = 11
	// ActionPutBucketObjectLockConfiguration specifies an action related to updating
	// Bucket Object Lock configuration.
	ActionPutBucketObjectLockConfiguration ActionType = 12
	// ActionGetBucketObjectLockConfiguration specifies an action related to retrieving
	// Bucket Object Lock configuration.
	ActionGetBucketObjectLockConfiguration ActionType = 13
)

type AllowedBuckets 

type AllowedBuckets struct {
	All     bool
	Buckets map[string]struct{}
}

AllowedBuckets stores information about which buckets are allowed to be accessed, where `Buckets` stores names of buckets that are allowed and `All` is a bool that indicates if all buckets are allowed or not.

type Caveat 

type Caveat struct {
	DisallowReads                            bool           `json:"disallow_reads,omitempty"`
	DisallowWrites                           bool           `json:"disallow_writes,omitempty"`
	DisallowLists                            bool           `json:"disallow_lists,omitempty"`
	DisallowDeletes                          bool           `json:"disallow_deletes,omitempty"`
	DisallowLocks                            bool           `json:"disallow_locks,omitempty"`
	DisallowPutRetention                     bool           `json:"disallow_put_retention,omitempty"`
	DisallowGetRetention                     bool           `json:"disallow_get_retention,omitempty"`
	DisallowPutLegalHold                     bool           `json:"disallow_put_legal_hold,omitempty"`
	DisallowGetLegalHold                     bool           `json:"disallow_get_legal_hold,omitempty"`
	DisallowBypassGovernanceRetention        bool           `json:"disallow_bypass_governance_retention,omitempty"`
	DisallowPutBucketObjectLockConfiguration bool           `json:"disallow_put_bucket_object_lock_configuration,omitempty"`
	DisallowGetBucketObjectLockConfiguration bool           `json:"disallow_get_bucket_object_lock_configuration,omitempty"`
	AllowedPaths                             []*Caveat_Path `json:"allowed_paths,omitempty"`
	NotAfter                                 *time.Time     `json:"not_after,omitempty"`
	NotBefore                                *time.Time     `json:"not_before,omitempty"`
	MaxObjectTtl                             *time.Duration `json:"max_object_ttl,omitempty"`
	Nonce                                    []byte         `json:"nonce,omitempty"`
}

func ParseCaveat 

func ParseCaveat(data []byte) (*Caveat, error)

ParseCaveat parses binary encoded caveat.

func WithNonce 

func WithNonce(in Caveat) Caveat

WithNonce returns a Caveat with the nonce set to a random value. Note: This does a shallow copy the provided Caveat.

func (*Caveat) Allows 

func (c *Caveat) Allows(action Action) bool

Allows returns true if the provided action is allowed by the caveat.

func (*Caveat) Decode 

func (m *Caveat) Decode(c *picobuf.Decoder)

func (*Caveat) Encode 

func (m *Caveat) Encode(c *picobuf.Encoder) bool

func (*Caveat) UnmarshalBinary 

func (caveat *Caveat) UnmarshalBinary(data []byte) error

UnmarshalBinary implements encoding.BinaryUnmarshaler.

type Caveat_Path 

type Caveat_Path struct {
	Bucket              []byte `json:"bucket,omitempty"`
	EncryptedPathPrefix []byte `json:"encrypted_path_prefix,omitempty"`
}

func (*Caveat_Path) Decode 

func (m *Caveat_Path) Decode(c *picobuf.Decoder)

func (*Caveat_Path) Encode 

func (m *Caveat_Path) Encode(c *picobuf.Encoder) bool

func (*Caveat_Path) MarshalJSON 

func (cp *Caveat_Path) MarshalJSON() ([]byte, error)

MarshalJSON implements the json.Marshaler interface.

type Macaroon 

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

Macaroon is a struct that determine contextual caveats and authorization.

func NewUnrestricted 

func NewUnrestricted(secret []byte) (*Macaroon, error)

NewUnrestricted creates Macaroon with random Head and generated Tail.

func NewUnrestrictedFromParts 

func NewUnrestrictedFromParts(head, secret []byte) *Macaroon

NewUnrestrictedFromParts constructs an unrestricted Macaroon from the provided head and secret.

func ParseMacaroon 

func ParseMacaroon(data []byte) (_ *Macaroon, err error)

ParseMacaroon converts binary to macaroon.

func (*Macaroon) AddFirstPartyCaveat 

func (m *Macaroon) AddFirstPartyCaveat(c []byte) (macaroon *Macaroon, err error)

AddFirstPartyCaveat creates signed macaroon with appended caveat.

func (*Macaroon) CaveatLen 

func (m *Macaroon) CaveatLen() int

CaveatLen returns the number of caveats this macaroon has.

func (*Macaroon) Caveats 

func (m *Macaroon) Caveats() (caveats [][]byte)

Caveats returns copy of macaroon caveats.

func (*Macaroon) Copy 

func (m *Macaroon) Copy() *Macaroon

Copy return copy of macaroon.

func (*Macaroon) Head 

func (m *Macaroon) Head() (head []byte)

Head returns copy of macaroon head.

func (*Macaroon) Serialize 

func (m *Macaroon) Serialize() (data []byte)

Serialize converts macaroon to binary format.

func (*Macaroon) Tail 

func (m *Macaroon) Tail() (tail []byte)

Tail returns copy of macaroon tail.

func (*Macaroon) Tails 

func (m *Macaroon) Tails(secret []byte) [][]byte

Tails returns all ancestor tails up to and including the current tail.

func (*Macaroon) Validate 

func (m *Macaroon) Validate(secret []byte) (ok bool)

Validate reconstructs with all caveats from the secret and compares tails, returning true if the tails match.

func (*Macaroon) ValidateAndTails 

func (m *Macaroon) ValidateAndTails(secret []byte) (bool, [][]byte)

ValidateAndTails combines Validate and Tails to a single method.

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.