capability

Documentation

Overview

Package capability implements narrow, expiring, optionally signed authorization tokens. Delegation may only reduce scope. Deny by default.

Index

• Variables
• type Authority
  • func New(opts ...Option) *Authority
  • func (a *Authority) AdvanceEpoch() (antireplay.SecurityEpoch, error)
  • func (a *Authority) Delegate(parent Token, req Request) (Token, error)
  • func (a *Authority) Epoch() antireplay.SecurityEpoch
  • func (a *Authority) Issue(req Request) (Token, error)
  • func (a *Authority) Revoke(id ID) error
  • func (a *Authority) Verify(tok Token) error
• type Constraints
• type ID
• type Option
  • func WithClock(now func() time.Time) Option
  • func WithKeyRing(ring *signing.KeyRing) Option
  • func WithReplayCache(c *antireplay.Cache) Option
  • func WithSigner(key signing.PrivateKey, ring *signing.KeyRing) Option
• type Permission
• type Request
• type Token

Variables

var (
	ErrDenied         = errors.New("capability: denied")
	ErrExpired        = errors.New("capability: expired")
	ErrRevoked        = errors.New("capability: revoked")
	ErrEpochMismatch  = errors.New("capability: security epoch mismatch")
	ErrInvalidSig     = errors.New("capability: invalid signature")
	ErrWidenDelegate  = errors.New("capability: delegation cannot widen scope")
	ErrSingleUseSpent = errors.New("capability: single-use already spent")
	ErrNotFound       = errors.New("capability: not found")
)

Types

type Authority

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

Authority issues and verifies capabilities.

func New

func New(opts ...Option) *Authority

New creates an authority at epoch 0.

func (*Authority) AdvanceEpoch

func (a *Authority) AdvanceEpoch() (antireplay.SecurityEpoch, error)

AdvanceEpoch invalidates prior capabilities by epoch mismatch.

func (*Authority) Delegate

func (a *Authority) Delegate(parent Token, req Request) (Token, error)

Delegate creates a child capability with equal or reduced scope.

func (*Authority) Epoch

func (a *Authority) Epoch() antireplay.SecurityEpoch

Epoch returns the current security epoch.

func (*Authority) Issue

func (a *Authority) Issue(req Request) (Token, error)

Issue creates a new capability. Empty permission is denied.

func (*Authority) Revoke

func (a *Authority) Revoke(id ID) error

Revoke marks a capability invalid.

func (*Authority) Verify

func (a *Authority) Verify(tok Token) error

Verify checks signature, expiry, revocation, epoch, and optional single-use.

type Constraints

type Constraints struct {
	SingleUse        bool     `json:"single_use,omitempty"`
	Environment      string   `json:"environment,omitempty"`
	MaxUses          int      `json:"max_uses,omitempty"`
	AllowedResources []string `json:"allowed_resources,omitempty"`
}

Constraints narrow how a capability may be used.

type ID

type ID string

ID uniquely identifies a capability token.

type Option

type Option func(*Authority)

Option configures Authority.

func WithClock

func WithClock(now func() time.Time) Option

WithClock overrides time (tests).

func WithKeyRing

func WithKeyRing(ring *signing.KeyRing) Option

WithKeyRing sets verification keys.

func WithReplayCache

func WithReplayCache(c *antireplay.Cache) Option

WithReplayCache binds nonce checks to an anti-replay cache.

func WithSigner

func WithSigner(key signing.PrivateKey, ring *signing.KeyRing) Option

WithSigner enables Ed25519 signing of issued tokens.

type Permission

type Permission string

Permission is a stable permission string (e.g. claim.revoke).

type Request

type Request struct {
	Subject     string
	Permission  Permission
	Resource    string
	TTL         time.Duration
	Constraints Constraints
}

Request describes a capability to issue.

type Token

type Token struct {
	ID          ID                       `json:"id"`
	Subject     string                   `json:"subject"`
	Permission  Permission               `json:"permission"`
	Resource    string                   `json:"resource,omitempty"`
	IssuedAt    time.Time                `json:"issued_at"`
	ExpiresAt   time.Time                `json:"expires_at"`
	Constraints Constraints              `json:"constraints"`
	Nonce       string                   `json:"nonce"`
	Epoch       antireplay.SecurityEpoch `json:"epoch"`
	ParentID    ID                       `json:"parent_id,omitempty"`
	Signature   []byte                   `json:"signature,omitempty"`
	KeyID       string                   `json:"key_id,omitempty"`
}

Token is a capability grant. Contents must not include secrets.