Documentation
¶
Index ¶
- Constants
- func DirectCheckOtp(ctx context.Context, client HttpClient, directLoginUrl string, ...) (status bool, err error)
- func EphemSecContextHash(realmId []byte, agentCtx []byte, dst []byte) ([]byte, error)
- func GetCardChallenge(ctx context.Context, client HttpClient, getChalUrl string, ...) error
- type AgentAuthContext
- type AppAuthRequest
- type AuthContext
- type AuthMethod
- type CardChalResponse
- type CardChallenge
- type CardChallengeEndpoint
- type CardChallengeRequest
- type ChalSetter
- type ChallengeFactory
- type ChallengeFactoryImpl
- func (self *ChallengeFactoryImpl) Check() error
- func (self *ChallengeFactoryImpl) GetAgentAuthContext(sid []byte, dst *AgentAuthContext) error
- func (self *ChallengeFactoryImpl) GetCardChallenge(req *CardChallengeRequest, dst *CardChallenge) error
- func (self *ChallengeFactoryImpl) GetServerOtp(cc *CardChalResponse, dst []byte) ([]byte, error)
- type DirectEndpoint
- type DirectLoginRequest
- type DirectValidationResult
- type HkdfChalSetter
- type HttpClient
- type SessionChal
Constants ¶
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") )
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 ¶
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
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
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.