auth

Documentation

Overview

Code used to support authentication tokens for arbitrary purposes.

Index

• Constants
• Variables
• func GenerateChallenge() (string, error)
• func IsValidChallenge(challenge string) bool
• type BadKeyError
  • func (e BadKeyError) Error() string
• type BadUsernameError
  • func (e BadUsernameError) Error() string
• type CredentialAuthority
  • func NewCredentialAuthority(log logger.Logger, api UserKeyAPIer) *CredentialAuthority
  • func (v *CredentialAuthority) CheckUserKey(ctx context.Context, uid keybase1.UID, username *libkb.NormalizedUsername, ...) (err error)
  • func (v *CredentialAuthority) CheckUsers(ctx context.Context, users []keybase1.UID) (err error)
  • func (v *CredentialAuthority) CompareUserKeys(ctx context.Context, uid keybase1.UID, sibkeys, subkeys []keybase1.KID) (err error)
  • func (v *CredentialAuthority) Shutdown()
• type InvalidTokenChallengeError
  • func (e InvalidTokenChallengeError) Error() string
• type InvalidTokenKeyError
  • func (e InvalidTokenKeyError) Error() string
• type InvalidTokenServerError
  • func (e InvalidTokenServerError) Error() string
• type InvalidTokenTypeError
  • func (e InvalidTokenTypeError) Error() string
• type MaxTokenExpiresError
  • func (e MaxTokenExpiresError) Error() string
• type Token
  • func NewToken(uid keybase1.UID, username libkb.NormalizedUsername, kid keybase1.KID, ...) *Token
  • func VerifyToken(signature, server, challenge string, maxExpireIn int) (*Token, error)
  • func (t Token) Bytes() []byte
  • func (t Token) Challenge() string
  • func (t Token) ClientName() string
  • func (t Token) ClientVersion() string
  • func (t Token) KID() keybase1.KID
  • func (t Token) Server() string
  • func (t Token) String() string
  • func (t Token) TimeRemaining() int
  • func (t Token) Type() string
  • func (t Token) UID() keybase1.UID
  • func (t Token) Username() libkb.NormalizedUsername
  • func (t Token) Version() int
• type TokenAuth
• type TokenBody
• type TokenClient
• type TokenExpiredError
  • func (e TokenExpiredError) Error() string
• type TokenKey
• type UserKeyAPIer
  • func NewUserKeyAPIer(log logger.Logger, api libkb.API) UserKeyAPIer

Constants

const (
	TokenType             = "auth"
	CurrentTokenVersion   = 2
	ChallengeLengthBytes  = 32
	ChallengeLengthString = ChallengeLengthBytes * 2 // we use hex encoding
)

Variables

var ErrKeysNotEqual = errors.New("keys not equal")

ErrKeysNotEqual is raised when compared keys sets aren't equal.

var ErrShutdown = errors.New("shutting down")

ErrShutdown is raised when an operation is pending but the CA is shutting down

var ErrUserDeleted = errors.New("user was deleted")

ErrUserDeleted is raised when a user is deleted, but was loaded without the loadDeleted flag

Functions

func GenerateChallenge

func GenerateChallenge() (string, error)

GenerateChallenge returns a cryptographically secure random challenge string.

func IsValidChallenge

func IsValidChallenge(challenge string) bool

IsValidChallenge returns true if the passed challenge is validly formed.

Types

type BadKeyError

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

BadKeyError is raised when the given KID is not valid for the given UID.

func (BadKeyError) Error

func (e BadKeyError) Error() string

type BadUsernameError

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

BadUsernameError is raised when the given username disagrees with the expected username

func (BadUsernameError) Error

func (e BadUsernameError) Error() string

type CredentialAuthority

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

CredentialAuthority should be allocated as a singleton object. It validates UID<->Username<->ActiveKey triples for all users across a service. It keeps a cache and subscribes for updates, so you can call into it as much as you'd like without fear of spamming the network.

func NewCredentialAuthority

func NewCredentialAuthority(log logger.Logger, api UserKeyAPIer) *CredentialAuthority

NewCredentialAuthority makes a new signleton CredentialAuthority an start it running. It takes as input a logger and an API for making keybase API calls

func (*CredentialAuthority) CheckUserKey

func (v *CredentialAuthority) CheckUserKey(ctx context.Context, uid keybase1.UID,
	username *libkb.NormalizedUsername, kid *keybase1.KID, loadDeleted bool) (err error)

CheckUserKey is the main point of entry to this library. It takes as input a UID, a username and a kid that should refer to a current valid triple, perhaps extracted from a signed authentication statement. It returns an error if the check fails, and nil otherwise. If username or kid are nil they aren't checked.

func (*CredentialAuthority) CheckUsers

func (v *CredentialAuthority) CheckUsers(ctx context.Context, users []keybase1.UID) (err error)

CheckUsers is used to validate all provided UIDs are known.

func (*CredentialAuthority) CompareUserKeys

func (v *CredentialAuthority) CompareUserKeys(ctx context.Context, uid keybase1.UID, sibkeys, subkeys []keybase1.KID) (
	err error)

CompareUserKeys compares the passed sets to the sets known by the API server. It returns true if the sets are equal.

func (*CredentialAuthority) Shutdown

func (v *CredentialAuthority) Shutdown()

Shutdown the credentialAuthority and delete all internal state.

type InvalidTokenChallengeError

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

InvalidTokenChallengeError is raised when the challenge presented in the token does not correspond to the challenge of the verifier.

func (InvalidTokenChallengeError) Error

func (e InvalidTokenChallengeError) Error() string

type InvalidTokenKeyError

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

InvalidTokenKeyError is raised when the public key presented in the token does not correspond to the private key used to sign the token.

func (InvalidTokenKeyError) Error

func (e InvalidTokenKeyError) Error() string

type InvalidTokenServerError

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

InvalidTokenServerError is raised when the server presented in the token does not correspond to the server being asked to verify the token.

func (InvalidTokenServerError) Error

func (e InvalidTokenServerError) Error() string

type InvalidTokenTypeError

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

InvalidTokenTypeError is raised when the given token is not of the expected type.

func (InvalidTokenTypeError) Error

func (e InvalidTokenTypeError) Error() string

type MaxTokenExpiresError

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

MaxTokenExpiresError is raised when the given token expires too far in the future.

func (MaxTokenExpiresError) Error

func (e MaxTokenExpiresError) Error() string

type Token

type Token struct {
	Body         TokenBody   `json:"body"`
	Client       TokenClient `json:"client"`
	CreationTime int64       `json:"ctime"`
	ExpireIn     int         `json:"expire_in"`
	Tag          string      `json:"tag"`
}

func NewToken

func NewToken(uid keybase1.UID, username libkb.NormalizedUsername, kid keybase1.KID,
	server, challenge string, now int64, expireIn int,
	clientName, clientVersion string) *Token

func VerifyToken

func VerifyToken(signature, server, challenge string, maxExpireIn int) (*Token, error)

func (Token) Bytes

func (t Token) Bytes() []byte

func (Token) Challenge

func (t Token) Challenge() string

func (Token) ClientName

func (t Token) ClientName() string

func (Token) ClientVersion

func (t Token) ClientVersion() string

func (Token) KID

func (t Token) KID() keybase1.KID

func (Token) Server

func (t Token) Server() string

func (Token) String

func (t Token) String() string

func (Token) TimeRemaining

func (t Token) TimeRemaining() int

func (Token) Type

func (t Token) Type() string

func (Token) UID

func (t Token) UID() keybase1.UID

func (Token) Username

func (t Token) Username() libkb.NormalizedUsername

func (Token) Version

func (t Token) Version() int

type TokenAuth

type TokenAuth struct {
	Server    string `json:"server"`
	Challenge string `json:"session"`
}

type TokenBody

type TokenBody struct {
	Auth    TokenAuth `json:"auth"`
	Key     TokenKey  `json:"key"`
	Type    string    `json:"type"`
	Version int       `json:"version"`
}

type TokenClient

type TokenClient struct {
	Name    string `json:"name"`
	Version string `json:"version"`
}

type TokenExpiredError

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

TokenExpiredError is raised when the given token is expired.

func (TokenExpiredError) Error

func (e TokenExpiredError) Error() string

type TokenKey

type TokenKey struct {
	UID      keybase1.UID             `json:"uid"`
	Username libkb.NormalizedUsername `json:"username"`
	KID      keybase1.KID             `json:"kid"`
}

type UserKeyAPIer

type UserKeyAPIer interface {
	// GetUser looks up the username and KIDS active for the given user.
	// Deleted users are loaded by default.
	GetUser(context.Context, keybase1.UID) (
		un libkb.NormalizedUsername, sibkeys, subkeys []keybase1.KID, deleted bool, err error)
	// PollForChanges returns the UIDs that have recently changed on the server
	// side. It will be called in a poll loop. This call should function as
	// a *long poll*, meaning, it should not return unless there is a change
	// to report, or a sufficient amount of time has passed. If an error occurred,
	// then PollForChanges should delay before return, so we don't wind up
	// busy-waiting.
	PollForChanges(context.Context) ([]keybase1.UID, error)
}

UserKeyAPIer is an interface that specifies the UserKeyAPI that will eventually be used to get information about the users from the trusted server authority.

func NewUserKeyAPIer

func NewUserKeyAPIer(log logger.Logger, api libkb.API) UserKeyAPIer

NewUserKeyAPIer returns a UserKeyAPIer implementation.