client

Documentation

Overview

Package client implements a serviceguard client with wallet backend. It offers methods to fetch tokens from the walletserver, reissue tokens for use with services and receive tokens as a service. It furthermore implements functions for wallet housekeeping. Wallet methods will return ErrRetry if the error is recoverable at a later time, ErrFatal if an internal (client-side) error exists - such as unavailable processing or storage. ErrFinal will be returned if an error is not recoverable but not due to a system/service error. ErrOffline is returned if a function can only be run if it has internet access. Details on what exactly caused an error is available in client.LastError.

Index

• Variables
• type Client
  • func New(keyBackends []types.Backend, walletstore WalletStore, ...) (*Client, error)
  • func (c *Client) DelToken(tokenHash []byte)
  • func (c *Client) GetBalance(usage string, owner *[ed25519.PublicKeySize]byte) int64
  • func (c *Client) GetBalanceOwn(usage string) int64
  • func (c *Client) GetToken(usage string, owner *[ed25519.PublicKeySize]byte) (*TokenEntry, error)
  • func (c *Client) GetVerifyKeys() error
  • func (c *Client) GoOffline()
  • func (c *Client) GoOnline()
  • func (c *Client) IsOnline() bool
  • func (c *Client) LockToken(tokenHash []byte) int64
  • func (c *Client) ReceiveToken(usage string, inputToken []byte) error
  • func (c *Client) ReissueToken(tokenHash []byte, ownerPubkey *[ed25519.PublicKeySize]byte) (newTokenHash []byte, err error)
  • func (c *Client) Runner()
  • func (c *Client) SetTarget(target map[[ed25519.PublicKeySize]byte]Target)
  • func (c *Client) StopRunner()
  • func (c *Client) UnlockToken(tokenHash []byte)
  • func (c *Client) Verify(inputToken []byte) (outputToken *TokenEntry, err error)
  • func (c *Client) WalletToken(usage string, owner *[ed25519.PublicKeySize]byte) (tokenHash []byte, err error)
• type Target
• type TokenEntry
• type WalletStore

Variables

var (

	// ErrRetry is returned on recoverable errors
	ErrRetry = errors.New("client: retry")
	// ErrOffline is returned if the client is offline
	ErrOffline = errors.New("client: offline")
	// ErrFinal is returned on final errors that cannot continue
	ErrFinal = errors.New("client: final serviceguard error")
	// ErrFatal is returned on fatal errors produced by the client implementation itself
	ErrFatal = errors.New("client: fatal client error")
	// ErrNeedReissue is returned if a non-renewable token was issued by the walletserver but not owner was specified
	ErrNeedReissue = errors.New("client: token needs reissue to owner")
	// ErrNotMine is returned if a token is not under our control
	ErrNotMine = errors.New("client: not my token")
	// ErrLocked is returned if a token has been locked
	ErrLocked = errors.New("client: token in use")
	// ErrExpireToken is returned if a token has expired
	ErrExpireToken = errors.New("client: token expired")
	// ErrSignatureToken is returned if the token has a bad signature
	ErrSignatureToken = errors.New("client: bad signature")
	// ErrOwnerToken is returned if a token has an unexpected owner
	ErrOwnerToken = errors.New("client: unexpected owner")
	// ErrUsageToken is returned if a token has an unexpected usage
	ErrUsageToken = errors.New("client: unexpected usage")
	// ErrTokenKnown is returned if a received token is already known
	ErrTokenKnown = errors.New("client: token is already known")
	// ErrNoToken is returned if no token could be fetched from wallet storage
	ErrNoToken = errors.New("client: no token in wallet")
)

var (

	// ErrWalletServer is returned if the server experienced a problem that cannot be exposed to the client
	ErrWalletServer = registerTranslateError("walletserver: server error", false)
	// ErrNoUser is returned if the user could not be found
	ErrNoUser = registerTranslateError("walletserver: no such user", true)
	// ErrBadToken is returned if the user's authtoken could not be verified
	ErrBadToken = registerTranslateError("walletserver: bad token", true)
	// ErrInsufficientFunds is returned if the user's funds are exhausted
	ErrInsufficientFunds = registerTranslateError("walletserver: insufficient funds", true)

	// ErrKeyLookupServer is returned if there was an error in the lookup server
	ErrKeyLookupServer = registerTranslateError("keylookup: server error", false)
	// ErrNotFound is returned if the key could not be found
	ErrNotFound = registerTranslateError("keylookup: key not found", true)

	// ErrUsageMismatch is returned if the usage of the parameter publickey and the token publickey do not match
	ErrUsageMismatch = registerTranslateError("issuer: parameter and Token usage mismatch", true)
	// ErrParamsExpired is returned if the parameters given are not in line with any available private key
	ErrParamsExpired = registerTranslateError("issuer: parameters have expired", true)
	// ErrBadCallType is returned if a wrong calltype is present in a packet
	ErrBadCallType = registerTranslateError("issuer: wrong calltype", true)
	// ErrIssuerServer is returned on server error
	ErrIssuerServer = registerTranslateError("issuer: server errror", false)
	// ErrTokenDoubleSpend is returned if the token has already been spent
	ErrTokenDoubleSpend = registerTranslateError("issuer: token double spend", true)
	// ErrParamDoubleSpend is returned if a parameter has already been spent
	ErrParamDoubleSpend = registerTranslateError("issuer: parameter double spend", true)
	// ErrBadPacket is returned if packet contents cannot be unmarshalled
	ErrBadPacket = registerTranslateError("issuer: bad package", true)
	// ErrOwnerSignature is returned if an owner signature could not be verified
	ErrOwnerSignature = registerTranslateError("issuer: owner signature verification failed", true)
	// ErrWrongIssuer is returned if a token is presented to the wrong issuer
	ErrWrongIssuer = registerTranslateError("issuer: wrong issuer", true)
	// ErrExpire is returned if a token has already expired
	ErrExpire = registerTranslateError("issuer: token expired", true)
	// ErrBadUsage is returned if a key is presented with the wrong usage setting
	ErrBadUsage = registerTranslateError("issuer: bad usage", true)
	// ErrBadIssuer is returned if a key is presented with the wrong issuer
	ErrBadIssuer = registerTranslateError("issuer: bad issuer", true)
	// ErrBadSignature is returned if a signature could not be verified
	ErrBadSignature = registerTranslateError("issuer: bad signature in token", true)
	// ErrParameterMixed is returned if the parameter set contains mixed keys
	ErrParameterMixed = registerTranslateError("issuer: parameters were mixed", true)
)

var AuthTokenRetry = constants.AuthTokenRetry

AuthTokenRetry defines how often an AuthToken should be retried on connection/server errors.

var TrustRoot *[ed25519.PublicKeySize]byte

TrustRoot is the signature key of the key lookup service. It should be globally the same, always.

Types

type Client

type Client struct {
	LastError error
	// contains filtered or unexported fields
}

Client encapsulates a client API.

func New

func New(keyBackends []types.Backend, walletstore WalletStore, walletKey *[ed25519.PrivateKeySize]byte, cacert []byte) (*Client, error)

New returns a new client. In most cases, use mute/serviceguard/client/trivial instead

func (*Client) DelToken

func (c *Client) DelToken(tokenHash []byte)

DelToken deletes a token.

func (*Client) GetBalance

func (c *Client) GetBalance(usage string, owner *[ed25519.PublicKeySize]byte) int64

GetBalance returns the number of usable tokens available for usage owned by owner or not self (if owner==nil).

func (*Client) GetBalanceOwn

func (c *Client) GetBalanceOwn(usage string) int64

GetBalanceOwn returns the number of renewable tokens for usage.

func (*Client) GetToken

func (c *Client) GetToken(usage string, owner *[ed25519.PublicKeySize]byte) (*TokenEntry, error)

GetToken returns a token from the database matching usage and optional owner. The token will be locked and must be deleted with DelToken when used (or unlocked). It should be used like this:

func DoWithToken() (retErr error){
	token, err := client.GetToken(usage, owner)
	defer func(){
		if retErr == nil{
			client.DelToken(token.Hash)
		} else {
			client.UnlockToken(token.Hash)
		}
	}
	... do something here that could fail
}

func (*Client) GetVerifyKeys

func (c *Client) GetVerifyKeys() error

GetVerifyKeys loads the verification keys from the keylookup server and adds them to the keypool and wallet.

func (*Client) GoOffline

func (c *Client) GoOffline()

GoOffline sets the client offline. The method will block until all routines using the internet connection have returned.

func (*Client) GoOnline

func (c *Client) GoOnline()

GoOnline sets the client online.

func (*Client) IsOnline

func (c *Client) IsOnline() bool

IsOnline tests if the client is online.

func (*Client) LockToken

func (c *Client) LockToken(tokenHash []byte) int64

LockToken locks a token against use by others.

func (*Client) ReceiveToken

func (c *Client) ReceiveToken(usage string, inputToken []byte) error

ReceiveToken receives a token, verifies it, checks for ownership and usage, and adds it to the wallet if not known.

func (*Client) ReissueToken

func (c *Client) ReissueToken(tokenHash []byte, ownerPubkey *[ed25519.PublicKeySize]byte) (newTokenHash []byte, err error)

ReissueToken reissues a token identified by tokenHash for owner.

func (*Client) Runner

func (c *Client) Runner()

Runner starts the background runner for token-store management.

func (*Client) SetTarget

func (c *Client) SetTarget(target map[[ed25519.PublicKeySize]byte]Target)

SetTarget sets the fill target of the wallet. The map contains the public key of the receiver and the usage/watermark definition.

func (*Client) StopRunner

func (c *Client) StopRunner()

StopRunner stops the runner. Should be called non-blocking (go StopRunner()).

func (*Client) UnlockToken

func (c *Client) UnlockToken(tokenHash []byte)

UnlockToken unlocks a previously locked token.

func (*Client) Verify

func (c *Client) Verify(inputToken []byte) (outputToken *TokenEntry, err error)

Verify a given inputToken and return it's public key if it verifies.

func (*Client) WalletToken

func (c *Client) WalletToken(usage string, owner *[ed25519.PublicKeySize]byte) (tokenHash []byte, err error)

WalletToken gets a token from wallet that matches usage. The token is reissued for owner if not nil. If the token is a subscription-token and owner is not present, it is stored and a "NeedReissue" error is returned.

type Target

type Target struct {
	Usage         string
	LowWaterMark  int64
	HighWaterMark int64
	// contains filtered or unexported fields
}

Target defines a fill target for the wallet.

type TokenEntry

type TokenEntry struct {
	Hash            []byte                        // The unique token identifier
	Token           []byte                        // The token itself, marshalled
	Params          []byte                        // Params for the token, can be nil
	OwnerPubKey     *[ed25519.PublicKeySize]byte  // The Owner of the token
	OwnerPrivKey    *[ed25519.PrivateKeySize]byte // The private key of the owner, can be nil if specified for somebody else
	Renewable       bool                          // The token can be renewed (at least once)
	CanReissue      bool                          // Can this token be reissued?
	Usage           string                        // Usage of the token
	Expire          int64                         // When the token will expire
	ServerPacket    []byte                        // Packet to be send to server
	BlindingFactors []byte                        // Local blinding factors
	NewOwnerPubKey  *[ed25519.PublicKeySize]byte  // The Owner of the token after reissue
	NewOwnerPrivKey *[ed25519.PrivateKeySize]byte // The private key of the new owner, can be nil if specified for somebody else
}

TokenEntry is an entry in the token database.

type WalletStore

type WalletStore interface {
	SetAuthToken(authToken []byte, tries int) error                                        // Store an authtoken and tries
	GetAuthToken() (authToken []byte, tries int)                                           // Get authtoken from store
	SetToken(tokenEntry TokenEntry) error                                                  // SetToken writes a token to the walletstore. repeated calls update the entry of tokenEntry.Hash is the same
	GetToken(tokenHash []byte, lockID int64) (*TokenEntry, error)                          // GetToken returns the token identified by tokenHash. If lockID>=0, enforce lock (return ErrLocked)
	GetAndLockToken(usage string, owner *[ed25519.PublicKeySize]byte) (*TokenEntry, error) // Return a token matching usage and optional owner. Must return ErrNoToken if no token is in store
	FindToken(usage string) (*TokenEntry, error)                                           // Find a token owner by self that has usage set
	DelToken(tokenHash []byte)                                                             // DelToken deletes the token identified by tokenHash
	LockToken(tokenHash []byte) (LockID int64)                                             // Lock token against other use. Return lockID > 0 on success, <0 on failure
	UnlockToken(tokenHash []byte)                                                          // Unlock a locked token
	SetVerifyKeys([][ed25519.PublicKeySize]byte)                                           // Save verification keys
	GetVerifyKeys() [][ed25519.PublicKeySize]byte                                          // Load verification keys. Offline only
	GetExpire() (tokenHash []byte)                                                         // Return next expiring token that can be reissued, or nil
	GetInReissue() (tokenHash []byte)                                                      // Get next token with interrupted reissue
	GetBalanceOwn(usage string) int64                                                      // Get the number of tokens for usage owned by self
	GetBalance(usage string, owner *[ed25519.PublicKeySize]byte) int64                     // Get the number of tokens for usage owner by owner, or by anybody but myself if owner==nil
	ExpireUnusable() bool                                                                  // Expire unusable tokens, returns true if it should be called again
}

WalletStore interface for storing and fetching wallet state.