authorization

Documentation

Overview

Package authorization is used for managing one-time-use certificate-signing- authorizations and claims.

Index

• Constants
• Variables
• type Authorization
  • func NewAuthorization(userID string) (*Authorization, error)
  • func (a Authorization) String() string
• type Claim
• type ClaimOpts
• type DB
  • func OpenDB(ctx context.Context, dbURL string, overwrite bool) (*DB, error)
  • func OpenDBFromCfg(ctx context.Context, config DBConfig) (*DB, error)
  • func (authDB *DB) Claim(ctx context.Context, opts *ClaimOpts) (err error)
  • func (authDB *DB) Close() error
  • func (authDB *DB) Create(ctx context.Context, userID string, count int) (_ Group, err error)
  • func (authDB *DB) Get(ctx context.Context, userID string) (_ Group, err error)
  • func (authDB *DB) List(ctx context.Context) (auths Group, err error)
  • func (authDB *DB) Unclaim(ctx context.Context, authToken string) (err error)
  • func (authDB *DB) UserIDs(ctx context.Context) (userIDs []string, err error)
• type DBConfig
• type Endpoint
  • func NewEndpoint(log *zap.Logger, service *Service, listener net.Listener) *Endpoint
  • func (endpoint *Endpoint) Close() error
  • func (endpoint *Endpoint) Run(ctx context.Context) (err error)
• type Group
  • func (group Group) GroupByClaimed() (claimed, open Group)
  • func (group Group) Marshal() ([]byte, error)
  • func (group *Group) Unmarshal(data []byte) error
• type Service
  • func NewService(log *zap.Logger, db *DB) *Service
  • func (service *Service) GetOrCreate(ctx context.Context, userID string) (_ *Token, err error)
• type Token
  • func ParseToken(tokenString string) (*Token, error)
  • func (t *Token) Equal(cmpToken *Token) bool
  • func (t *Token) String() string

Constants

const (
	// Bucket is the bucket used with a bolt-backed authorizations DB.
	Bucket = "authorizations"
	// MaxClockSkew is the max duration in the past or future that a claim
	// timestamp is allowed to have and still be valid.
	MaxClockSkew = 5 * time.Minute
)

Variables

var (

	// Error is used when an error occurs involving an authorization.
	Error = errs.Class("authorization")
	// ErrInvalidToken is used when a token is invalid.
	ErrInvalidToken = errs.Class("authorization token")
)

var (
	// ErrDB is used when an error occurs involving the authorization database.
	ErrDB = errs.Class("authorizationdb")
	// ErrEmptyUserID is used when a user ID is required but not provided.
	ErrEmptyUserID = ErrDB.New("userID cannot be empty")
	// ErrCount is used when attempting to create an invalid number of authorizations.
	ErrCount = ErrDB.New("cannot add less than one authorization")
	// ErrInvalidClaim is used when a claim is invalid due to some user input.
	ErrInvalidClaim = errs.Class("invalid authorization claim")
	// ErrAlreadyClaimed is used when a valid claim is attempted with a token that's been used already.
	ErrAlreadyClaimed = errs.Class("authorization already claimed")
	// ErrNotFound is used when there is no matching authorization in the DB for a given userID and token.
	ErrNotFound = errs.Class("authorization not found")
	// ErrDBInternal is used when an internal error occurs involving the authorization database.
	ErrDBInternal = errs.Class("internal authorization db")
)

var ErrEndpoint = errs.Class("authorization endpoint")

ErrEndpoint is the default error class for the authorization endpoint.

var ErrService = errs.Class("authorization service")

ErrService is the default error class for the authorization service.

Types

type Authorization

type Authorization struct {
	Token Token
	Claim *Claim
}

Authorization represents a single-use authorization token and its status.

func NewAuthorization

func NewAuthorization(userID string) (*Authorization, error)

NewAuthorization creates a new, unclaimed authorization with a random token value.

func (Authorization) String

func (a Authorization) String() string

String implements the stringer interface and prevents authorization data from completely leaking into logs and errors.

type Claim

type Claim struct {
	Addr             string
	Timestamp        int64
	Identity         *identity.PeerIdentity
	SignedChainBytes [][]byte
}

Claim holds information about the circumstances under which an authorization token was claimed.

type ClaimOpts

type ClaimOpts struct {
	Req           *certificatepb.SigningRequest
	Peer          *rpcpeer.Peer
	ChainBytes    [][]byte
	MinDifficulty uint16
}

ClaimOpts hold parameters for claiming an authorization.

type DB

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

DB stores authorizations which may be claimed in exchange for a certificate signature.

func OpenDB

func OpenDB(ctx context.Context, dbURL string, overwrite bool) (*DB, error)

OpenDB creates and/or opens the authorization database.

func OpenDBFromCfg

func OpenDBFromCfg(ctx context.Context, config DBConfig) (*DB, error)

OpenDBFromCfg creates and/or opens the authorization database specified by the config.

func (*DB) Claim

func (authDB *DB) Claim(ctx context.Context, opts *ClaimOpts) (err error)

Claim marks an authorization as claimed and records claim information.

func (*DB) Close

func (authDB *DB) Close() error

Close closes the authorization database's underlying store.

func (*DB) Create

func (authDB *DB) Create(ctx context.Context, userID string, count int) (_ Group, err error)

Create creates a new authorization and adds it to the authorization database.

func (*DB) Get

func (authDB *DB) Get(ctx context.Context, userID string) (_ Group, err error)

Get retrieves authorizations by user ID.

func (*DB) List

func (authDB *DB) List(ctx context.Context) (auths Group, err error)

List returns all authorizations in the database.

func (*DB) Unclaim

func (authDB *DB) Unclaim(ctx context.Context, authToken string) (err error)

Unclaim removes a claim from an authorization.

func (*DB) UserIDs

func (authDB *DB) UserIDs(ctx context.Context) (userIDs []string, err error)

UserIDs returns a list of all userIDs present in the authorization database.

type DBConfig

type DBConfig struct {
	URL       string `default:"bolt://$CONFDIR/authorizations.db" help:"url to the certificate signing authorization database"`
	Overwrite bool   `default:"false" help:"if true, overwrites config AND authorization db is truncated" setup:"true"`
}

DBConfig is the authorization db config.

type Endpoint

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

Endpoint provides a http endpoint for interacting with an authorization service.

func NewEndpoint

func NewEndpoint(log *zap.Logger, service *Service, listener net.Listener) *Endpoint

NewEndpoint creates a authorization endpoint.

func (*Endpoint) Close

func (endpoint *Endpoint) Close() error

Close closes the endpoint HTTP server.

func (*Endpoint) Run

func (endpoint *Endpoint) Run(ctx context.Context) (err error)

Run starts the endpoint HTTP server and waits for the context to be cancelled or for `Close` to be called.

type Group

type Group []*Authorization

Group is a slice of authorizations for convenient de/serialization. and grouping.

func (Group) GroupByClaimed

func (group Group) GroupByClaimed() (claimed, open Group)

GroupByClaimed separates a group of authorizations into a group of claimed and a group of open authorizations.

func (Group) Marshal

func (group Group) Marshal() ([]byte, error)

Marshal serializes a set of authorizations.

func (*Group) Unmarshal

func (group *Group) Unmarshal(data []byte) error

Unmarshal deserializes a set of authorizations.

type Service

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

Service is the authorization service.

func NewService

func NewService(log *zap.Logger, db *DB) *Service

NewService creates a new authorization service.

func (*Service) GetOrCreate

func (service *Service) GetOrCreate(ctx context.Context, userID string) (_ *Token, err error)

GetOrCreate will return an authorization for the given user ID.

type Token

type Token struct {
	// NB: currently email address for convenience
	UserID string
	Data   [tokenDataLength]byte
}

Token is a userID and a random byte array, when serialized, can be used like a pre-shared key for claiming certificate signatures.

func ParseToken

func ParseToken(tokenString string) (*Token, error)

ParseToken splits the token string on the delimiter to get a userID and data for a token and base58 decodes the data.

func (*Token) Equal

func (t *Token) Equal(cmpToken *Token) bool

Equal checks if two tokens have equal user IDs and data.

func (*Token) String

func (t *Token) String() string

String implements the stringer interface. Base68 w/ version and checksum bytes are used for easy and reliable human transport.