slp

package
v0.3.14 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Mar 2, 2026 License: Apache-2.0 Imports: 18 Imported by: 0

Documentation

Index

Constants

View Source
const (
	// All package errors are wrapping Error
	Error           = errorFlag("slp: error")
	ErrValidation   = errorFlag("slp: Failed Validation")
	ErrInvalidMsg   = errorFlag("slp: Invalid message")
	ErrInvalidSlp   = errorFlag("slp: Invalid Slp protocol")
	ErrUnsafeMethod = errorFlag("slp: Unsafe AuthMethod")
	ErrNotSupported = errorFlag("slp: Unsupported AuthMethod")
	ErrHttpStatus   = errorFlag("slp: failed Http submission")
)
View Source
const (

	// Slp{Name} enumerates supported OTP/OTK authentication protocols
	// Slp is a short for Simple Login Protocol
	SlpDirect = uint16(0) // one way authentication through direct disclosure of OTP/OTK
	SlpCpace  = uint16(1) // mutual authentication proving OTP/OTK knowledge using CPACE PAKE
	SlpNXpsk2 = uint16(2) // mutual authentication proving OTK knowledge using Noise NXpsk2

)

Variables

This section is empty.

Functions

func DirectCheckOtp added in v0.3.14

func DirectCheckOtp(ctx context.Context, client HttpClient, directLoginUrl string, dlr *DirectLoginRequest) (status bool, err error)

DirectCheckOtp submits a DirectLoginRequest to the given directLoginUrl and returns whether the server validated the client OTP. It uses the provided HttpClient to execute the request, allowing callers to control transport, timeouts, and testability. The caller is responsible for enforcing deadlines via the context. Returns an error if the request cannot be sent, the response is non-2xx, or the response body cannot be decoded.

func EphemSecContextHash

func EphemSecContextHash(realmId []byte, agentCtx []byte, dst []byte) ([]byte, error)

EphemSecContextHash returns the sha256 of TLV encoding of realmId & agentCtx. EphemSecContextHash errors if realmId or agentCtx have length not in 32..255 range.

func GetCardChallenge added in v0.3.14

func GetCardChallenge(ctx context.Context, client HttpClient, getChalUrl string, chr *CardChallengeRequest, dst *CardChallenge) error

GetCardChallenge submits a CardChallengeRequest to the given getChalUrl and returns server generated CardChallenge into dst. It uses the provided HttpClient to execute the request, allowing callers to control transport, timeouts, and testability. The caller is responsible for enforcing deadlines via the context. Returns an error if the request cannot be sent, the response is non-2xx, or the response body cannot be decoded.

Types

type AgentAuthContext

type AgentAuthContext struct {
	SelectedProtocol     uint16 `cbor:"1,keyasint"`
	SessionId            []byte `cbor:"2,keyasint"`
	StaticKeyCert        []byte `cbor:"3,keyasint,omitempty"`
	AppContextUrl        string `cbor:"4,keyasint"`
	AuthServerGetChalUrl string `cbor:"5,keyasint"`
	AuthServerLoginUrl   string `cbor:"6,keyasint"`
	AppStartUrl          string `cbor:"7,keyasint"`
}

AgentAuthContext simplifies canonical hashing (through CBOR encoding) for EPHEMSEC context preparation AgentAuthContext is the 1st component of the KerPass EPHEMSEC context It is derived independently by CardAgent & AuthServer CardApp & AuthServer independently append RealmId to this context prior to use it as EPHEMSEC input

func (*AgentAuthContext) Sum

func (self *AgentAuthContext) Sum(dst []byte) ([]byte, error)

Sum returns the sha256 digest of CTAP2 serialization of the AgentAuthContext. Sum errors if the AgentAuthContext is nil or CTAP2 serialization failed.

type AppAuthRequest

type AppAuthRequest struct {
	// Application Realm Identifier
	// RealmId encodes a "PKI context" that allows validating Application public key certificates
	RealmId []byte `json:"rId" cbor:"1,keyasint"`

	// Url where to submit CardChallengeRequest request
	AuthServerGetChalUrl string `json:"getChalUrl" cbor:"2,keyasint"`

	// Enumerates Application supported Authentication methods
	AllowedMethods []AuthMethod `json:"methods" cbor:"3,keyasint"`
}

AppAuthRequest details relying Application authentication requirements. It is forwarded by a relying Application to a KerPass CardAgent.

func (AppAuthRequest) Check

func (self AppAuthRequest) Check() error

Check validates the AppAuthRequest and returns an error if invalid.

type AuthContext

type AuthContext struct {
	RealmId              [32]byte
	AuthMethod           AuthMethod
	AppContextUrl        string
	AuthServerGetChalUrl string
	AuthServerLoginUrl   string
	AppStartUrl          string
}

AuthContext holds ChallengeFactoryImpl configuration for a specific authentication realm. It contains all the URLs and authentication method information needed to process authentication requests for a particular application realm.

func (*AuthContext) Check

func (self *AuthContext) Check() error

Check validates the AuthContext configuration and returns an error if invalid. It verifies the authentication method and all configured URLs are valid.

type AuthMethod

type AuthMethod struct {
	// One of the enumerated Slp authentication protocol
	Protocol uint16 `json:"proto" cbor:"1,keyasint"`

	// One of the registered EPHEMSEC scheme
	Scheme uint16 `json:"scheme" cbor:"2,keyasint"`
}

AuthMethod binds a Slp authentication protocol to an EPHEMSEC OTP/OTK generation scheme.

func (AuthMethod) Check

func (self AuthMethod) Check() error

Check validates the AuthMethod and returns an error if invalid.

func (AuthMethod) EncodeToInt added in v0.3.10

func (self AuthMethod) EncodeToInt() int

EncodeToInt encodes the AuthMethod into an integer with Protocol in bits 16-17 and Scheme in bits 0-15.

func (*AuthMethod) ReadInt added in v0.3.10

func (self *AuthMethod) ReadInt(v int) error

ReadInt decodes an integer into an AuthMethod by extracting Protocol from bits 16-17 and Scheme from bits 0-15. It validates the decoded AuthMethod and returns an error if invalid.

type CardChalResponse added in v0.3.14

type CardChalResponse struct {
	// references a Server generated CardChallenge
	SessionId []byte `json:"sid" cbor:"1,keyasint"`

	// identifier allowing ServerCard access
	CardId []byte `json:"cid" cbor:"2,keyasint"`

	// synchronization hint allowing Server to determine Client OTP time
	SyncHint byte `json:"sync" cbor:"3,keyasint"`

	// Client generated ephemeral key
	// transmitted if authentication scheme uses E2S2 key exchange
	E credentials.PublicKeyHandle `json:"e,omitzero" cbor:"4,keyasint,omitzero"`
}

CardChalResponse holds client-side authentication commitment data transmitted to the Server during an SLP authentication session. It allows the Server to independently derive the same OTP/OTK as the Client — without the Client ever transmitting the secret itself.

type CardChallenge

type CardChallenge struct {
	// AuthServer generated SessionId
	SessionId []byte `json:"sId" cbor:"1,keyasint"`

	// AuthServer generated ephemeral key
	// E is compatible with the EPHEMSEC scheme selected in related CardChallengeRequest.
	E credentials.PublicKeyHandle `json:"E" cbor:"2,keyasint"`

	// AuthServer generated nonce
	INonce []byte `json:"nonce" cbor:"3,keyasint"`

	// AuthServer EPHEMSEC static key
	// It is set if the selected EPHEMSEC scheme uses E1S2 or E2S2 key exchange pattern
	S credentials.PublicKeyHandle `json:"S" cbor:"4,keyasint,omitzero"`

	// Static key certificate
	// It is set if the selected EPHEMSEC scheme uses E1S2 or E2S2 key exchange pattern
	StaticKeyCert []byte `json:"cert" cbor:"5,keyasint,omitempty"`

	// Url where to start the selected authentication protocol
	// CardAgent & AuthServer independently append this Url to their EPHEMSEC OTP/OTK generation context
	AuthServerLoginUrl string `json:"loginUrl" cbor:"6,keyasint"`

	// Url where to go following successful Slp authentication
	// CardAgent & AuthServer independently append this Url to their EPHEMSEC OTP/OTK generation context
	AppStartUrl string `json:"appStartUrl" cbor:"7,keyasint"`
}

CardChallenge contains AuthServer generated EPHEMSEC ephemeral key & nonce. It is returned by relying Application AuthServer in response to CardChallengeRequest.

func (CardChallenge) Check

func (self CardChallenge) Check() error

Check validates the CardChallenge and returns an error if invalid.

type CardChallengeEndpoint

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

CardChallengeEndpoint implements http.Handler to process authentication challenge requests. It decodes the CBOR-encoded CardChallengeRequest, delegates challenge generation to the configured ChallengeFactory, and returns the CBOR-encoded CardChallenge.

func NewCardChallengeEndpoint

func NewCardChallengeEndpoint(factory ChallengeFactory) (*CardChallengeEndpoint, error)

NewCardChallengeEndpoint constructs a new CardChallengeEndpoint with the given factory. Returns an error if factory is nil or fails its optional Check() validation.

func (*CardChallengeEndpoint) ServeHTTP

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

ServeHTTP handles incoming POST requests carrying a CBOR-encoded CardChallengeRequest. It enforces the POST method, reads and decodes the request body, generates a CardChallenge, and writes back a CBOR-encoded CardChallenge response.

type CardChallengeRequest

type CardChallengeRequest struct {
	// Application Realm Identifier
	// RealmId encodes a "PKI context" that allows validating Application public key certificates
	RealmId []byte `json:"rId" cbor:"1,keyasint"`

	// CardAgent selected AuthMethod Id
	// It is the index of the selected AuthMethod in related AppAuthRequest.AllowedMethods
	SelectedMethod AuthMethod `json:"mtd" cbor:"2,keyasint"`

	// CardAgent acquired Url that corresponds to where the AppAuthRequest was obtained.
	// AuthServer may refuse CardChallengeRequest request if this url is not legit.
	// CardAgent & AuthServer independently append this Url to their EPHEMSEC OTP/OTK generation context.
	AppContextUrl string `json:"appUrl" cbor:"3,keyasint"`
}

CardChallengeRequest allows obtaining EPHEMSEC ephemeral key & nonce. It is submitted by a KerPass CardAgent to a relying application AuthServer.

func (CardChallengeRequest) Check

func (self CardChallengeRequest) Check() error

Check validates the CardChallengeRequest and returns an error if invalid.

type ChalSetter

type ChalSetter interface {
	// SetChal set ecdh ephemeral key & nonce in dst.
	SetChal(crv algos.Curve, sid []byte, dst *SessionChal) error
}

ChalSetter generates EPHEMSEC authentication challenge (ECDH ephemeral key & nonce). Implementations of this interface are responsible for producing cryptographic material used in authentication sessions.

type ChallengeFactory

type ChallengeFactory interface {
	// GetCardChallenge generates a CardChallenge in response to a CardChallengeRequest.
	// Returns an error if the request does not match any configured AuthContext or challenge generation fails.
	GetCardChallenge(req *CardChallengeRequest, dst *CardChallenge) error

	// GetAgentAuthContext retrieves the AgentAuthContext bound to the given session ID.
	// Returns an error if the session ID is invalid or expired, or the AuthContext cannot be reconstructed.
	GetAgentAuthContext(sid []byte, dst *AgentAuthContext) error

	// GetServerOtp derives the server-side OTP/OTK matching the one independently derived
	// by the Client for the authentication session referenced in cc.
	// Returns an error if the session is invalid, the card cannot be loaded, or OTP derivation fails.
	GetServerOtp(cc *CardChalResponse, dst []byte) ([]byte, error)
}

ChallengeFactory provides methods for creating authentication challenges and contexts. It is the main interface for generating authentication protocol data structures.

type ChallengeFactoryImpl

type ChallengeFactoryImpl struct {
	Skf  session.KeyFactory[session.Sid]
	Kst  credentials.KeyStore
	Scs  credentials.ServerCredStore
	Cst  ChalSetter
	Cfgs []AuthContext
}

ChallengeFactoryImpl implements the ChallengeFactory interface. It uses a session key factory, key store, and challenge setter to generate authentication challenges and contexts based on configuration.

func NewChallengeFactoryImpl added in v0.3.9

func NewChallengeFactoryImpl(sl time.Duration, kst credentials.KeyStore, scs credentials.ServerCredStore, acts []AuthContext) (*ChallengeFactoryImpl, error)

NewChallengeFactoryImpl creates and initializes a new ChallengeFactoryImpl. It configures a session key factory with the given lifetime sl, initializes an HKDF/SHA-512 based challenge setter, and validates all provided AuthContexts and their required static keys against the key store kst. Returns an error if any component fails initialization or validation.

func (*ChallengeFactoryImpl) Check

func (self *ChallengeFactoryImpl) Check() error

Check validates the ChallengeFactoryImpl and returns an error if invalid.

func (*ChallengeFactoryImpl) GetAgentAuthContext

func (self *ChallengeFactoryImpl) GetAgentAuthContext(sid []byte, dst *AgentAuthContext) error

GetAgentAuthContext retrieves the authentication context for a given session ID. It validates the session ID, looks up the corresponding AuthContext configuration, loads the appropriate static key certificate if needed, and populates the AgentAuthContext with all necessary authentication protocol information.

func (*ChallengeFactoryImpl) GetCardChallenge

func (self *ChallengeFactoryImpl) GetCardChallenge(req *CardChallengeRequest, dst *CardChallenge) error

GetCardChallenge generates a CardChallenge response for a given CardChallengeRequest. It validates the request against configured AuthContexts, generates a session ID, creates an authentication challenge using the configured ChalSetter, and loads appropriate static keys for the selected EPHEMSEC scheme.

func (*ChallengeFactoryImpl) GetServerOtp added in v0.3.14

func (self *ChallengeFactoryImpl) GetServerOtp(cc *CardChalResponse, dst []byte) ([]byte, error)

GetServerOtp derives the server-side OTP/OTK for a given CardChalResponse. It validates the session ID, retrieves the corresponding AuthContext and EPHEMSEC scheme, loads the Client Card identified by cc.CardId, reloads the deterministic session challenge, reconstructs the EPHEMSEC context hash, and runs EPHEMSEC as Initiator to produce the OTP/OTK. The result matches what the Client independently derived, enabling mutual authentication without transmission of the shared secret. Returns an error if the session is invalid, the card cannot be loaded, or OTP derivation fails.

type DirectEndpoint added in v0.3.14

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

DirectEndpoint implements http.Handler for the SlpDirect authentication protocol. It receives a CBOR-encoded DirectLoginRequest, derives the expected OTP server-side using the configured ChallengeFactory, and returns a CBOR-encoded DirectValidationResult indicating whether the client-provided OTP is valid.

func NewDirectEndpoint added in v0.3.14

func NewDirectEndpoint(factory ChallengeFactory) (*DirectEndpoint, error)

NewDirectEndpoint constructs a new DirectEndpoint with the given factory. Returns an error if factory is nil or fails its optional Check() validation.

func (*DirectEndpoint) ServeHTTP added in v0.3.14

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

ServeHTTP handles incoming POST requests carrying a CBOR-encoded DirectLoginRequest. It enforces the POST method, decodes the request, derives the expected OTP server-side, compares it against the client-provided OTP using constant-time comparison, and returns a CBOR-encoded DirectValidationResult.

type DirectLoginRequest added in v0.3.14

type DirectLoginRequest struct {
	SessionId []byte                      `json:"sid" cbor:"1,keyasint"`
	CardId    []byte                      `json:"cid" cbor:"2,keyasint"`
	Otp       []byte                      `json:"otp" cbor:"3,keyasint"`
	E         credentials.PublicKeyHandle `json:"e,omitzero" cbor:"4,keyasint,omitzero"`
}

DirectLoginRequest is the client-to-server payload for the SlpDirect authentication protocol. It carries the session reference, card identity, client-generated OTP, and optionally a client ephemeral key for schemes using E2S2 key exchange. The last byte of Otp encodes the synchronization hint used by the server to align OTP time windows.

func (*DirectLoginRequest) Check added in v0.3.14

func (self *DirectLoginRequest) Check() error

Check validates the DirectLoginRequest and returns an error if any required field is missing.

type DirectValidationResult added in v0.3.14

type DirectValidationResult struct {
	Valid bool `json:"valid" cbor:"1,keyasint"`
}

DirectValidationResult holds the outcome of an SlpDirect OTP validation.

type HkdfChalSetter

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

HkdfChalSetter is a ChalSetter that uses HKDF to derive EPHEMSEC authentication challenge from a session identifier. It provides deterministic yet unpredictable generation of ephemeral keys and nonces for authentication sessions.

func NewHkdfChalSetter

func NewHkdfChalSetter(hash crypto.Hash) (*HkdfChalSetter, error)

NewHkdfChalSetter creates a new HkdfChalSetter with the specified hash function. It generates random salt and input key material (IKM) for HKDF extraction. Returns an error if the hash function is not available.

func (*HkdfChalSetter) Check

func (self *HkdfChalSetter) Check() error

Check validates the HkdfChalSetter and returns an error if invalid.

func (*HkdfChalSetter) SetChal

func (self *HkdfChalSetter) SetChal(crv algos.Curve, sid []byte, dst *SessionChal) error

SetChal initializes dst SessionChal by generating ECDH ephemeral key and nonce using HKDF. It uses the provided curve, session ID, and the HKDF state to deterministically generate cryptographic material. Returns an error if key generation fails.

type HttpClient added in v0.3.14

type HttpClient interface {
	Do(req *http.Request) (*http.Response, error)
}

HttpClient is a minimal interface for executing HTTP requests. It is satisfied by *http.Client, allowing callers to inject a custom or mock implementation for testing.

type SessionChal

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

SessionChal holds ECDH ephemeral key and nonce used for generating EPHEMSEC OTP/OTK. It is used internally during authentication challenge generation.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL