themis

README

Themis

In the name of the ancient Greek goddess of justice, we present Themis, the User Authentication Module by Tunnel.Work.

✔ Themis is a Golang library providing definitions and implementations for Authentication primitives.

❌ Themis isn't a User Management System nor a Authentication Server implementation.

Interfaces

TBA

Structs

TBA

Examples

TBA

License

MIT

Documentation

Index

• Constants
• Variables
• type AuthBody
  • func AuthBodyFromBase64(b64token string) (AuthBody, error)
  • func NewAuthBody(authedIdentity uint64, authedIP net.IP, revID uint64, validFor time.Duration) AuthBody
  • func (ab *AuthBody) Base64() string
  • func (ab *AuthBody) HasRevocation() bool
  • func (ab *AuthBody) Initialized() bool
• type AuthSignature
  • func (as AuthSignature) Initialized() bool
• type AuthToken
• type AuthTokenRenewable
• type AuthTokenRevocable
• type BearerToken
  • func GetNewBearerToken(uid uint64, uip net.IP, validFor time.Duration, rv Revoker) (*BearerToken, error)
  • func ImportBearerToken(fulltoken string, rv Revoker) (*BearerToken, error)
  • func (b *BearerToken) Body() AuthBody
  • func (b *BearerToken) ExpireNow()
  • func (b *BearerToken) GetFullToken() string
  • func (b *BearerToken) Renew(validFor time.Duration) error
  • func (b *BearerToken) Revoke() error
  • func (b *BearerToken) SetFullToken()
  • func (b *BearerToken) Sign(factor interface{}) error
  • func (b *BearerToken) Verify(factor interface{}) error
• type ConcurrentRRMap
• type OfflineRevocationRecord
• type OfflineRevoker
  • func NewOfflineRevoker() *OfflineRevoker
  • func (orev *OfflineRevoker) Register(uid uint64, params ...interface{}) (uint64, error)
  • func (orev *OfflineRevoker) Revoke(uid, id uint64) error
  • func (orev *OfflineRevoker) Validate(uid, id uint64) error
• type RevocationRecordMap
• type Revoker

Constants

const (
	BearerTokenSeparator string = "."
)

Variables

var (
	ErrBadBase64Token error = errors.New("themis: bad base64 token")
	ErrIllformedBody  error = errors.New("themis: auth body is illformed")
	ErrBadIpAddr      error = errors.New("themis: cannot parse ip address")
)

var (
	ErrIllformedBearerToken error = errors.New("themis: token is illformed")
	ErrBearerAuthBodyUninit error = errors.New("themis: bearer token auth body is not initialized")
	ErrBearerAuthSigUninit  error = errors.New("themis: bearer token auth signature is not initialized")
	ErrBearerTokenExpired   error = errors.New("themis: bearer token expired")

	ErrBearerBadSigningKey   error = errors.New("themis: BearerToken.Sign() expects a seed string or an ed25519.PrivateKey as input")
	ErrBearerBadVerifyingKey error = errors.New("themis: BearerToken.Verify() expects a seed string or an ed25519.PublicKey as input")
)

var (
	ErrOfflineRevokerNotEnoughParams error = errors.New("themis: not enough parameters for offline revoker")
	ErrBadRevocationID               error = errors.New("themis: invalid revocation id or token has been revoked")
)

Types

type AuthBody

type AuthBody struct {
	Identity     uint64
	IpAddr       net.IP
	Expiry       time.Time
	RevocationID uint64
}

func AuthBodyFromBase64

func AuthBodyFromBase64(b64token string) (AuthBody, error)

func NewAuthBody

func NewAuthBody(authedIdentity uint64, authedIP net.IP, revID uint64, validFor time.Duration) AuthBody

func (*AuthBody) Base64

func (ab *AuthBody) Base64() string

func (*AuthBody) HasRevocation

func (ab *AuthBody) HasRevocation() bool

func (*AuthBody) Initialized

func (ab *AuthBody) Initialized() bool

type AuthSignature

type AuthSignature string

func (AuthSignature) Initialized

func (as AuthSignature) Initialized() bool

Initialized() checks only if a AuthSignature is set. It doesn't Verify() the signature.

type AuthToken

type AuthToken interface {
	// Sign() updates an internl signature variable
	// by signing the authbody wih key
	Sign(factor interface{}) error

	// Verify() checks for te signature's validity
	Verify(factor interface{}) error

	Body() AuthBody
}

AuthToken is a minimal token interface for user verification.

type AuthTokenRenewable

type AuthTokenRenewable interface {
	AuthToken

	// Renew() extends the expiry of a token to now+validFor
	Renew(validFor time.Duration) error
}

AuthTokenRenewable is an AuthToken that automatically expires after a while

type AuthTokenRevocable

type AuthTokenRevocable interface {
	AuthTokenRenewable

	// Revoke() should set the token to a irreversible invalid state.
	Revoke() error
}

AuthTokenRevocable is an AuthTokenRenewable allowing the caller to Revoke() this token.

type BearerToken

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

func GetNewBearerToken

func GetNewBearerToken(uid uint64, uip net.IP, validFor time.Duration, rv Revoker) (*BearerToken, error)

GetNewBearerToken() returns an UNSIGNED *BearerToken rv needs to be not nil.

func ImportBearerToken

func ImportBearerToken(fulltoken string, rv Revoker) (*BearerToken, error)

ImportBearerToken() only imports the token. Caller need to Verify() it.

func (*BearerToken) Body

func (b *BearerToken) Body() AuthBody

func (*BearerToken) ExpireNow

func (b *BearerToken) ExpireNow()

func (*BearerToken) GetFullToken

func (b *BearerToken) GetFullToken() string

GetFullToken() returns the current fullToken of a BearerToken

func (*BearerToken) Renew

func (b *BearerToken) Renew(validFor time.Duration) error

Renew() only updates the body. sig/fullToken must be manually updated by calling corresponding functions.

func (*BearerToken) Revoke

func (b *BearerToken) Revoke() error

Revoke() will use the revoker to cancel the validity of the token for good.

func (*BearerToken) SetFullToken

func (b *BearerToken) SetFullToken()

SetFullToken() automatically sets the fullToken of a SIGNED BearerToken. Caller must make sure it is signed.

func (*BearerToken) Sign

func (b *BearerToken) Sign(factor interface{}) error

Sign() fill the signature after any updates being made to body if returns error, token will be left `unsigned` factor could be either a seed string or an ed25519.PrivateKey

func (*BearerToken) Verify

func (b *BearerToken) Verify(factor interface{}) error

Verify() will verify first body and sig are set, and body is not expired. then verify the signature for the authenticity of the body. if all passed, check with the revoker that the revocation ID from the body isn't revoked. factor could be either a seed string or an ed25519.PublicKey

type ConcurrentRRMap

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

type OfflineRevocationRecord

type OfflineRevocationRecord struct {
	Creator      net.IP    // Registered for
	CreationTime time.Time // Registered at
	LastActive   time.Time // Last time it calls Validate()
}

type OfflineRevoker

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

A *OfflineRevoker shall implement Revoker interface

func NewOfflineRevoker

func NewOfflineRevoker() *OfflineRevoker

func (*OfflineRevoker) Register

func (orev *OfflineRevoker) Register(uid uint64, params ...interface{}) (uint64, error)

func (*OfflineRevoker) Revoke

func (orev *OfflineRevoker) Revoke(uid, id uint64) error

func (*OfflineRevoker) Validate

func (orev *OfflineRevoker) Validate(uid, id uint64) error

type RevocationRecordMap

type RevocationRecordMap map[uint64]OfflineRevocationRecord

type Revoker

type Revoker interface {
	// Register() returns the revocationID for the new entry and nil
	// Otherwise, return 0 and failing error.
	Register(uid uint64, params ...interface{}) (uint64, error)

	// Validate() returns nil when the id is valid for this revoker.
	// Otherwise, return the reason why the validation should fail.
	Validate(uid uint64, id uint64) error

	// Revoke() returns nil when the id is successfully revoked
	// WITHIN THIS function call
	// Otherwise, return the reason why the revoke is unsuccessful.
	//
	// However the consequent Validate() shall fail (i.e. not return nil)
	Revoke(uid uint64, id uint64) error
}