enroll

Documentation

Overview

Package enroll provides client & server implementation of KerPass Enrollment protocol. This protocol allows registering EPHEMSEC credentials (aka "Card") that allows generating and validating ephemeral mutual secrets in OTP/OTK format.

Prior to execution of this protocol, a relying server Application has generated a client authorization and forwarded to the client a secret identifier for this authorization plus the Realm identifier to which this application belongs. KerPass Realm Identifier determines a PKI context that allows validating Application service keys...

The Enrollment protocol is built on top of a Noise XX key exchange. Prior to execution of the protocol, the client generates a fresh X25519 Keypair which is used as client static Keypair for the Noise XX exchange. The server will accept client public key if client transmits a valid authorization identifier. If the Noise XX key exchange succeeds, client and server uses the exchange hash state to derive a PSK, and server generates a new Card identifier that it forwards to client...

If the protocol succeeds: - Client stores RealmId, CardId, client Keypair, PSK as Card record. - Server stores RealmId, CardId, client PubKey, PSK as ServerCard record.

Index

• Constants
• func ClientExit(self *ClientState, rs error) error
• func EnrollOverHTTP(ctx context.Context, cli httpClient, serverUrl string, cfg ClientCfg) error
• func ServerExit(self *ServerState, rs error) error
• type ClientCfg
  • func (self ClientCfg) Check() error
• type ClientExitFunc
• type ClientState
  • func NewClientState(cfg ClientCfg) (*ClientState, error)
  • func (self *ClientState) ExitHandler() ClientExitFunc
  • func (self *ClientState) Initiator() bool
  • func (self *ClientState) SetExitHandler(_ ClientExitFunc)
  • func (self *ClientState) SetState(sf ClientStateFunc)
  • func (self *ClientState) State() (*ClientState, ClientStateFunc)
• type ClientStateFunc
  • func ClientCardCreate(ctx context.Context, self *ClientState, msg []byte) (sf ClientStateFunc, rmsg []byte, err error)
  • func ClientInit(ctx context.Context, self *ClientState, _ []byte) (sf ClientStateFunc, rmsg []byte, err error)
  • func ClientReceiveServerKey(ctx context.Context, self *ClientState, msg []byte) (sf ClientStateFunc, rmsg []byte, err error)
• type EnrollAuthorization
  • func (self EnrollAuthorization) Check() error
• type EnrollCardCreateResp
  • func (self EnrollCardCreateResp) Check() error
• type EnrollReq
  • func (self EnrollReq) Check() error
• type HttpHandler
  • func (self HttpHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)
• type HttpSession
• type ServerCfg
  • func (self ServerCfg) Check() error
• type ServerExitFunc
• type ServerState
  • func NewServerState(cfg ServerCfg) (*ServerState, error)
  • func (self *ServerState) ExitHandler() ServerExitFunc
  • func (self *ServerState) Initiator() bool
  • func (self *ServerState) SetExitHandler(_ ServerExitFunc)
  • func (self *ServerState) SetState(sf ServerStateFunc)
  • func (self *ServerState) State() (*ServerState, ServerStateFunc)
• type ServerStateFunc
  • func ServerCardSave(ctx context.Context, self *ServerState, msg []byte) (sf ServerStateFunc, rmsg []byte, err error)
  • func ServerCheckEnrollAuthorization(ctx context.Context, self *ServerState, msg []byte) (sf ServerStateFunc, rmsg []byte, err error)
  • func ServerInit(ctx context.Context, self *ServerState, msg []byte) (sf ServerStateFunc, rmsg []byte, err error)

Constants

const (
	// All package errors are wrapping Error
	Error                   = errorFlag("enroll: error")
	ErrInvalidAuthorization = errorFlag("enroll: invalid authorization")
)

Functions

func ClientExit

func ClientExit(self *ClientState, rs error) error

func EnrollOverHTTP

func EnrollOverHTTP(ctx context.Context, cli httpClient, serverUrl string, cfg ClientCfg) error

EnrollOverHTTP runs the enroll client protocol over HTTP transport.

func ServerExit

func ServerExit(self *ServerState, rs error) error

Types

type ClientCfg

type ClientCfg struct {
	RealmId         []byte
	AuthorizationId []byte
	Repo            credentials.ClientCredStore
}

func (ClientCfg) Check

func (self ClientCfg) Check() error

type ClientExitFunc

type ClientExitFunc = protocols.ExitFunc[*ClientState]

type ClientState

type ClientState struct {
	RealmId         []byte
	AuthorizationId []byte
	Repo            credentials.ClientCredStore
	// contains filtered or unexported fields
}

func NewClientState

func NewClientState(cfg ClientCfg) (*ClientState, error)

func (*ClientState) ExitHandler

func (self *ClientState) ExitHandler() ClientExitFunc

func (*ClientState) Initiator

func (self *ClientState) Initiator() bool

func (*ClientState) SetExitHandler

func (self *ClientState) SetExitHandler(_ ClientExitFunc)

func (*ClientState) SetState

func (self *ClientState) SetState(sf ClientStateFunc)

func (*ClientState) State

func (self *ClientState) State() (*ClientState, ClientStateFunc)

type ClientStateFunc

type ClientStateFunc = protocols.StateFunc[*ClientState]

func ClientCardCreate

func ClientCardCreate(ctx context.Context, self *ClientState, msg []byte) (sf ClientStateFunc, rmsg []byte, err error)

func ClientInit

func ClientInit(ctx context.Context, self *ClientState, _ []byte) (sf ClientStateFunc, rmsg []byte, err error)

func ClientReceiveServerKey

func ClientReceiveServerKey(ctx context.Context, self *ClientState, msg []byte) (sf ClientStateFunc, rmsg []byte, err error)

type EnrollAuthorization

type EnrollAuthorization struct {
	AuthorizationId []byte `json:"authorization_id" cbor:"1,keyasint"`
}

EnrollAuthorization is sent by the CardAgent client to the KerPass server.

func (EnrollAuthorization) Check

func (self EnrollAuthorization) Check() error

type EnrollCardCreateResp

type EnrollCardCreateResp struct {
	CardId  []byte `json:"card_id" cbor:"1,keyasint"`
	AppName string `json:"app_name" cbor:"3,keyasint"`
	AppLogo []byte `json:"app_logo" cbor:"4,keyasint"`
}

EnrollCardCreateResp is sent by the KerPass server to the CardAgent client. It contains information that are necessary for creating the Card.

func (EnrollCardCreateResp) Check

func (self EnrollCardCreateResp) Check() error

type EnrollReq

type EnrollReq struct {
	RealmId []byte `json:"realm_id" cbor:"1,keyasint"` // Determine the Static Key used by the Server
	Msg     []byte `json:"noise_msg" cbor:"2,keyasint"`
}

EnrollReq is sent by the CardAgent client to the KerPass server. It is a plaintext that starts the EnrollProtocol.

func (EnrollReq) Check

func (self EnrollReq) Check() error

type HttpHandler

type HttpHandler struct {
	Cfg          ServerCfg
	SessionStore *session.MemStore[session.Sid, HttpSession]
}

HttpHandler holds configuration & state necessary for executing the enroll server protocol.

func (HttpHandler) ServeHTTP

func (self HttpHandler) ServeHTTP(w http.ResponseWriter, r *http.Request)

ServeHTTP update enroll ServerState using message in incoming request. ServeHTTP restore session ServerState in case of error.

type HttpSession

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

HttpSession allows synchronized access to enroll ServerState.

type ServerCfg

type ServerCfg struct {
	KeyStore credentials.KeyStore
	Repo     credentials.ServerCredStore
}

func (ServerCfg) Check

func (self ServerCfg) Check() error

type ServerExitFunc

type ServerExitFunc = protocols.ExitFunc[*ServerState]

type ServerState

type ServerState struct {
	KeyStore credentials.KeyStore
	Repo     credentials.ServerCredStore
	// contains filtered or unexported fields
}

func NewServerState

func NewServerState(cfg ServerCfg) (*ServerState, error)

func (*ServerState) ExitHandler

func (self *ServerState) ExitHandler() ServerExitFunc

func (*ServerState) Initiator

func (self *ServerState) Initiator() bool

func (*ServerState) SetExitHandler

func (self *ServerState) SetExitHandler(_ ServerExitFunc)

func (*ServerState) SetState

func (self *ServerState) SetState(sf ServerStateFunc)

func (*ServerState) State

func (self *ServerState) State() (*ServerState, ServerStateFunc)

type ServerStateFunc

type ServerStateFunc = protocols.StateFunc[*ServerState]

func ServerCardSave

func ServerCardSave(ctx context.Context, self *ServerState, msg []byte) (sf ServerStateFunc, rmsg []byte, err error)

func ServerCheckEnrollAuthorization

func ServerCheckEnrollAuthorization(ctx context.Context, self *ServerState, msg []byte) (sf ServerStateFunc, rmsg []byte, err error)

func ServerInit

func ServerInit(ctx context.Context, self *ServerState, msg []byte) (sf ServerStateFunc, rmsg []byte, err error)