Documentation
¶
Overview ¶
Package auth provides XMPP authentication mechanisms.
Index ¶
- Constants
- func AttemptedUsername(a Authenticator) string
- func IsFastMechanism(mech string) bool
- func NewFastToken() ([]byte, error)
- func VerifyUserPassword(ctx context.Context, rep repository.User, peppers *pepper.Keys, ...) (bool, error)
- type Authenticator
- type External
- func (e *External) Authenticated() bool
- func (e *External) Mechanism() string
- func (e *External) ProcessElement(ctx context.Context, elem stravaganza.Element) (stravaganza.Element, *SASLError)
- func (e *External) Reset()
- func (e *External) SetDomain(_ string)
- func (e *External) Start(ctx context.Context) error
- func (e *External) Stop(_ context.Context) error
- func (e *External) Username() string
- func (e *External) UsesChannelBinding() bool
- type FastCBType
- type HTScram
- func (h *HTScram) AttemptedUsername() string
- func (h *HTScram) Authenticated() bool
- func (h *HTScram) Mechanism() string
- func (h *HTScram) ProcessElement(ctx context.Context, elem stravaganza.Element) (stravaganza.Element, *SASLError)
- func (h *HTScram) Reset()
- func (h *HTScram) SetClientID(clientID string)
- func (h *HTScram) SetDomain(_ string)
- func (h *HTScram) Username() string
- func (h *HTScram) UsesChannelBinding() bool
- type OAuthBearer
- func (o *OAuthBearer) Authenticated() bool
- func (o *OAuthBearer) Mechanism() string
- func (o *OAuthBearer) ProcessElement(ctx context.Context, elem stravaganza.Element) (stravaganza.Element, *SASLError)
- func (o *OAuthBearer) Reset()
- func (o *OAuthBearer) SetDomain(_ string)
- func (o *OAuthBearer) Username() string
- func (o *OAuthBearer) UsesChannelBinding() bool
- type OAuthBearerSASL
- func (o *OAuthBearerSASL) AttemptedUsername() string
- func (o *OAuthBearerSASL) Authenticated() bool
- func (o *OAuthBearerSASL) Mechanism() string
- func (o *OAuthBearerSASL) ProcessElement(ctx context.Context, elem stravaganza.Element) (stravaganza.Element, *SASLError)
- func (o *OAuthBearerSASL) Reset()
- func (o *OAuthBearerSASL) SetDomain(domain string)
- func (o *OAuthBearerSASL) Username() string
- func (o *OAuthBearerSASL) UsesChannelBinding() bool
- type Plain
- func (p *Plain) AttemptedUsername() string
- func (p *Plain) Authenticated() bool
- func (p *Plain) Mechanism() string
- func (p *Plain) ProcessElement(ctx context.Context, elem stravaganza.Element) (stravaganza.Element, *SASLError)
- func (p *Plain) Reset()
- func (p *Plain) SetDomain(domain string)
- func (p *Plain) Username() string
- func (p *Plain) UsesChannelBinding() bool
- type SASLError
- type SASLErrorReason
- type Scram
- func (s *Scram) AttemptedUsername() string
- func (s *Scram) Authenticated() bool
- func (s *Scram) Mechanism() string
- func (s *Scram) ProcessElement(ctx context.Context, elem stravaganza.Element) (stravaganza.Element, *SASLError)
- func (s *Scram) ProtectionHashFunc() func() hash.Hash
- func (s *Scram) Reset()
- func (s *Scram) ServerProtectionHash() []byte
- func (s *Scram) SetDomain(domain string)
- func (s *Scram) SetServerProtectionHash(hash []byte)
- func (s *Scram) StoreUpgradedHash(ctx context.Context, task string, saltedPassword []byte) error
- func (s *Scram) UpgradeInfo() *ScramUpgradeInfo
- func (s *Scram) Username() string
- func (s *Scram) UsesChannelBinding() bool
- type ScramType
- type ScramUpgradeInfo
Constants ¶
const ( // HTScramMechanism is the SASL mechanism name for the non-channel-bound // variant, advertised in stream features. HTScramMechanism = "HT-SHA-256-NONE" // HTScramMechanismEndp is the tls-server-end-point channel-bound variant. HTScramMechanismEndp = "HT-SHA-256-ENDP" // HTScramMechanismExpr is the tls-exporter channel-bound variant. HTScramMechanismExpr = "HT-SHA-256-EXPR" // FastTokenTTL is the default lifetime for issued FAST tokens. FastTokenTTL = 7 * 24 * time.Hour )
const OAuthDiscoveryPath = "/.well-known/oauth-authorization-server"
OAuthDiscoveryPath is the RFC 8414 well-known path under which Zerta publishes its authorization-server metadata. Shared by the SASL OAUTHBEARER error challenge and the HTTP discovery document so both advertise the same location.
const ScopeXMPPClientNormal = "xmpp:client:normal"
ScopeXMPPClientNormal is the OAuth scope that grants XMPP client login. Tokens issued by the authorization-code flow carry it, and the SASL OAUTHBEARER mechanism requires it (X-OAUTH2 keeps requiring the narrower xmpp:login).
Variables ¶
This section is empty.
Functions ¶
func AttemptedUsername ¶ added in v0.6.0
func AttemptedUsername(a Authenticator) string
AttemptedUsername returns the username of an existing account that the current (possibly failed) authentication attempt targeted, or "" when the account does not exist or the mechanism cannot tell.
func IsFastMechanism ¶ added in v0.8.0
IsFastMechanism reports whether mech is a known FAST (HT-SHA-256-*) mechanism name.
func NewFastToken ¶
NewFastToken generates 32 random bytes suitable as a FAST HMAC key.
func VerifyUserPassword ¶ added in v0.9.0
func VerifyUserPassword(ctx context.Context, rep repository.User, peppers *pepper.Keys, logger kitlog.Logger, domain, username, password string) (bool, error)
VerifyUserPassword checks a plaintext password against the stored credentials of the given account. It returns (false, nil) for an unknown account or a wrong password and only reports an error when the repository failed, so callers can keep both failure cases indistinguishable towards the client. A successful verification of a legacy SHA-1 import migrates the account to SCRAM.
Types ¶
type Authenticator ¶
type Authenticator interface {
// Mechanism returns authenticator mechanism name.
Mechanism() string
// Username returns authenticated username in case authentication process has been completed.
Username() string
// Authenticated returns whether or not user has been authenticated.
Authenticated() bool
// UsesChannelBinding returns whether or not this authenticator requires channel binding bytes.
UsesChannelBinding() bool
// SetDomain sets the XMPP virtual host domain for this authentication attempt.
SetDomain(domain string)
// ProcessElement process an incoming authenticator element.
ProcessElement(context.Context, stravaganza.Element) (stravaganza.Element, *SASLError)
// Reset resets authenticator internal state.
Reset()
}
Authenticator defines a generic authenticator state machine.
type External ¶
type External struct {
// contains filtered or unexported fields
}
External represents external authentication mechanism (PLAIN).
func NewExternal ¶
NewExternal returns a new external authenticator.
func (*External) Authenticated ¶
Authenticated returns whether or not user has been authenticated.
func (*External) ProcessElement ¶
func (e *External) ProcessElement(ctx context.Context, elem stravaganza.Element) (stravaganza.Element, *SASLError)
ProcessElement process an incoming authenticator element.
func (*External) Username ¶
Username returns authenticated username in case authentication process has been completed.
func (*External) UsesChannelBinding ¶
UsesChannelBinding returns whether or not this authenticator requires channel binding bytes.
type FastCBType ¶ added in v0.8.0
type FastCBType int
FastCBType selects the channel-binding type a HT-SHA-256-* authenticator is pinned to. Each FAST mechanism name is tied to exactly one binding type (draft-ietf-kitten-hash-tokens §2).
const ( // FastNoCB is the HT-SHA-256-NONE variant: no channel binding (cb-data is empty). FastNoCB FastCBType = iota // FastEndp is the HT-SHA-256-ENDP variant: tls-server-end-point (RFC 5929). FastEndp // FastExpr is the HT-SHA-256-EXPR variant: tls-exporter (RFC 9266). FastExpr )
func FastCBTypeForMechanism ¶ added in v0.8.0
func FastCBTypeForMechanism(mech string) (FastCBType, bool)
FastCBTypeForMechanism maps a FAST (HT-SHA-256-*) mechanism name to its channel-binding type. ok is false for unknown mechanism names.
type HTScram ¶
type HTScram struct {
// contains filtered or unexported fields
}
HTScram implements the HT-SHA-256-* family for the Authenticator interface.
func NewHTScram ¶
func NewHTScram(tr transport.Transport, cbType FastCBType, rep repository.Fast, keys *fasttoken.Keys) *HTScram
NewHTScram creates an HT-SHA-256-* authenticator pinned to cbType. keys decrypts stored token bytes at rest; see fasttoken.Keys. The transport supplies the channel-binding bytes for the -ENDP/-EXPR variants.
func (*HTScram) AttemptedUsername ¶ added in v0.7.1
AttemptedUsername returns the username named by the current attempt, even if the token was rejected.
func (*HTScram) Authenticated ¶
Authenticated reports whether the authentication succeeded.
func (*HTScram) Mechanism ¶
Mechanism returns the SASL mechanism name for this authenticator's binding type.
func (*HTScram) ProcessElement ¶
func (h *HTScram) ProcessElement(ctx context.Context, elem stravaganza.Element) (stravaganza.Element, *SASLError)
ProcessElement handles the single <auth> or <initial-response> payload. Expected payload (base64-encoded): authzid NUL HMAC-SHA256(token_key, "Initiator" || cb-data)
func (*HTScram) SetClientID ¶ added in v0.4.0
SetClientID sets the XEP-0388 <user-agent id='...'> value for the device attempting FAST authentication. Called by the SASL2 layer (pkg/c2s) before ProcessElement, since the id lives in the <authenticate> envelope, not in the synthetic SASL1 payload this authenticator otherwise sees. The plain SASL1 path never calls SetClientID, so clientID stays "" there and ProcessElement rejects the attempt below — FAST is SASL2-only by design (XEP-0484 requires user-agent for multi-device slot tracking).
func (*HTScram) Username ¶
Username returns the authenticated username (empty until Authenticated() is true).
func (*HTScram) UsesChannelBinding ¶
UsesChannelBinding reports whether this authenticator requires channel binding bytes (true for -ENDP and -EXPR, false for -NONE).
type OAuthBearer ¶
type OAuthBearer struct {
// contains filtered or unexported fields
}
OAuthBearer implements the X-OAUTH2 SASL mechanism. It accepts base64(\0username\0token) as credentials. The token must exist in the DB, not be revoked, not be expired, and have scope "xmpp:login".
func NewOAuthBearer ¶
func NewOAuthBearer(rep repository.OAuth) *OAuthBearer
NewOAuthBearer returns a new OAuthBearer authenticator instance.
func (*OAuthBearer) Authenticated ¶
func (o *OAuthBearer) Authenticated() bool
Authenticated returns whether the user has been authenticated.
func (*OAuthBearer) Mechanism ¶
func (o *OAuthBearer) Mechanism() string
Mechanism returns the SASL mechanism name.
func (*OAuthBearer) ProcessElement ¶
func (o *OAuthBearer) ProcessElement(ctx context.Context, elem stravaganza.Element) (stravaganza.Element, *SASLError)
ProcessElement processes the SASL auth element. Expected format: base64(\0username\0token)
func (*OAuthBearer) Reset ¶
func (o *OAuthBearer) Reset()
Reset clears the authenticator internal state.
func (*OAuthBearer) SetDomain ¶
func (o *OAuthBearer) SetDomain(_ string)
SetDomain is a no-op for OAuthBearer authenticator.
func (*OAuthBearer) Username ¶
func (o *OAuthBearer) Username() string
Username returns the authenticated username, or empty string if not yet authenticated.
func (*OAuthBearer) UsesChannelBinding ¶
func (o *OAuthBearer) UsesChannelBinding() bool
UsesChannelBinding returns false as X-OAUTH2 does not use channel binding.
type OAuthBearerSASL ¶ added in v0.9.0
type OAuthBearerSASL struct {
// contains filtered or unexported fields
}
OAuthBearerSASL implements the SASL OAUTHBEARER mechanism (RFC 7628).
Client-first-message: base64(gs2-header %x01 *kvpair %x01 %x01) with "auth=Bearer <token>" as the only mandatory kvpair. On an invalid token the server answers with a challenge carrying base64(JSON{"status":"invalid_token", "openid-configuration":...}); the client then sends the dummy %x01 response and the server aborts with <failure> (RFC 7628 §3.2.3).
Tokens are validated the same way as X-OAUTH2 (repository lookup, username match, expiry, revocation), but require scope xmpp:client:normal.
func NewOAuthBearerSASL ¶ added in v0.9.0
func NewOAuthBearerSASL(rep repository.OAuth) *OAuthBearerSASL
NewOAuthBearerSASL returns a new OAUTHBEARER authenticator instance.
func (*OAuthBearerSASL) AttemptedUsername ¶ added in v0.9.0
func (o *OAuthBearerSASL) AttemptedUsername() string
AttemptedUsername returns the account targeted by the current attempt, if the bearer token resolved to one. Used for rate limiting/reporting on failure.
func (*OAuthBearerSASL) Authenticated ¶ added in v0.9.0
func (o *OAuthBearerSASL) Authenticated() bool
Authenticated returns whether the user has been authenticated.
func (*OAuthBearerSASL) Mechanism ¶ added in v0.9.0
func (o *OAuthBearerSASL) Mechanism() string
Mechanism returns the SASL mechanism name.
func (*OAuthBearerSASL) ProcessElement ¶ added in v0.9.0
func (o *OAuthBearerSASL) ProcessElement(ctx context.Context, elem stravaganza.Element) (stravaganza.Element, *SASLError)
ProcessElement processes the SASL auth/response element.
func (*OAuthBearerSASL) Reset ¶ added in v0.9.0
func (o *OAuthBearerSASL) Reset()
Reset clears the authenticator internal state.
func (*OAuthBearerSASL) SetDomain ¶ added in v0.9.0
func (o *OAuthBearerSASL) SetDomain(domain string)
SetDomain sets the XMPP virtual host domain for this authentication attempt. The domain also determines the advertised openid-configuration URL.
func (*OAuthBearerSASL) Username ¶ added in v0.9.0
func (o *OAuthBearerSASL) Username() string
Username returns the authenticated username, or empty string if not yet authenticated.
func (*OAuthBearerSASL) UsesChannelBinding ¶ added in v0.9.0
func (o *OAuthBearerSASL) UsesChannelBinding() bool
UsesChannelBinding returns false as OAUTHBEARER does not use channel binding.
type Plain ¶
type Plain struct {
// contains filtered or unexported fields
}
Plain represents a PLAIN SASL authenticator with legacy password migration. When a user has legacy ejabberd credentials (plain SHA-1 hash), PLAIN auth verifies the password, then transparently migrates to SCRAM. This enables zero-downtime migration from ejabberd without password resets.
func (*Plain) AttemptedUsername ¶ added in v0.6.0
AttemptedUsername returns the existing account targeted by the current attempt.
func (*Plain) Authenticated ¶
Authenticated returns true if the authentication has succeeded.
func (*Plain) ProcessElement ¶
func (p *Plain) ProcessElement(ctx context.Context, elem stravaganza.Element) (stravaganza.Element, *SASLError)
ProcessElement processes a PLAIN auth element. Format: base64(\0username\0password)
func (*Plain) Reset ¶
func (p *Plain) Reset()
Reset clears the authentication state so the mechanism can be reused.
func (*Plain) SetDomain ¶
SetDomain sets the XMPP virtual host domain for this authentication attempt.
func (*Plain) Username ¶
Username returns the authenticated username, or empty string if not yet authenticated.
func (*Plain) UsesChannelBinding ¶
UsesChannelBinding returns false since PLAIN does not use channel binding.
type SASLError ¶
type SASLError struct {
Reason SASLErrorReason
Err error
}
SASLError represents specific SASL error type.
func (*SASLError) Element ¶
func (se *SASLError) Element() stravaganza.Element
Element returs sasl error XML representation. The error condition element uses the urn:ietf:params:xml:ns:xmpp-sasl namespace as required by XEP-0388 §6.2 (SASL2 failure uses SASL1 error conditions).
type SASLErrorReason ¶
type SASLErrorReason uint8
SASLErrorReason defines the SASL error reason.
const ( // IncorrectEncoding represents a 'incorrect-encoding' authentication error. IncorrectEncoding SASLErrorReason = iota // MalformedRequest represents a 'malformed-request' authentication error. MalformedRequest // NotAuthorized represents a 'not-authorized' authentication error. NotAuthorized // TemporaryAuthFailure represents a 'temporary-auth-failure' authentication error. TemporaryAuthFailure )
func (SASLErrorReason) String ¶
func (r SASLErrorReason) String() string
String returns SASLErrorReason string representation.
type Scram ¶
type Scram struct {
// contains filtered or unexported fields
}
Scram represents a SCRAM authenticator.
func NewScram ¶
func NewScram( tr transport.Transport, scramType ScramType, usesChannelBinding bool, rep repository.User, peppers *pepper.Keys, ) *Scram
NewScram returns a new scram authenticator instance.
func (*Scram) AttemptedUsername ¶ added in v0.6.0
AttemptedUsername returns the existing account targeted by the current attempt, even if authentication has not (yet) succeeded.
func (*Scram) Authenticated ¶
Authenticated returns whether or not user has been authenticated.
func (*Scram) ProcessElement ¶
func (s *Scram) ProcessElement(ctx context.Context, elem stravaganza.Element) (stravaganza.Element, *SASLError)
ProcessElement process an incoming authenticator element.
func (*Scram) ProtectionHashFunc ¶ added in v0.7.1
ProtectionHashFunc returns the hash constructor matching this SCRAM mechanism (SHA-1, SHA-256, SHA-512 or SHA3-512). The c2s layer uses it to compute the XEP-0474 downgrade-protection hash with the same algorithm as the SCRAM mechanism currently in use, as required by XEP-0474 §6.1.
func (*Scram) ServerProtectionHash ¶ added in v0.5.0
ServerProtectionHash returns the XEP-0474 server protection hash currently set to be embedded in the SCRAM server-first-message as the h= attribute (nil = disabled).
func (*Scram) SetDomain ¶
SetDomain sets the XMPP virtual host domain for this authentication attempt.
func (*Scram) SetServerProtectionHash ¶
SetServerProtectionHash sets the XEP-0474 server protection hash to be embedded in the SCRAM server-first-message as the h= attribute.
func (*Scram) StoreUpgradedHash ¶
StoreUpgradedHash stores a new SaltedPassword for the given XEP-0480 upgrade task. task must be "UPGR-SCRAM-SHA-256" or "UPGR-SCRAM-SHA-512". The saltedPassword must be the raw PBKDF2 output (not base64-encoded). Returns an error if the user is not known (no successful auth yet).
func (*Scram) UpgradeInfo ¶
func (s *Scram) UpgradeInfo() *ScramUpgradeInfo
UpgradeInfo returns the XEP-0480 upgrade information for the authenticated user. Returns nil if the authenticator has not yet completed a successful authentication.
func (*Scram) Username ¶
Username returns authenticated username in case authentication process has been completed.
func (*Scram) UsesChannelBinding ¶
UsesChannelBinding returns whether or not scram authenticator requires channel binding bytes.
type ScramType ¶
type ScramType int
ScramType represents a scram autheticator class
const ( // ScramSHA1 represents SCRAM-SHA-1 authentication method. ScramSHA1 ScramType = iota // ScramSHA256 represents SCRAM-SHA-256 authentication method. ScramSHA256 // ScramSHA512 represents SCRAM-SHA-512 authentication method. ScramSHA512 // ScramSHA3512 represents SCRAM-SHA3-512 authentication method. ScramSHA3512 )
type ScramUpgradeInfo ¶
type ScramUpgradeInfo struct {
// PepperedSalt is the raw (decoded) salt + pepper that was used for authentication.
PepperedSalt []byte
// Iterations is the PBKDF2 iteration count used.
Iterations int64
// HasSHA256 is true when SHA-256 credentials are already stored.
HasSHA256 bool
// HasSHA512 is true when SHA-512 credentials are already stored.
HasSHA512 bool
// HasSHA3512 is true when SHA3-512 credentials are already stored.
HasSHA3512 bool
}
ScramUpgradeInfo holds the data needed by the server to issue an XEP-0480 SCRAM Upgrade Task after successful authentication.
Source Files
¶
Directories
¶
| Path | Synopsis |
|---|---|
|
Package fasttoken provides at-rest encryption for FAST (XEP-0484) HMAC token keys, mirroring the key-rotation shape of pkg/auth/pepper.
|
Package fasttoken provides at-rest encryption for FAST (XEP-0484) HMAC token keys, mirroring the key-rotation shape of pkg/auth/pepper. |
|
Package pepper provides pepper key management for SCRAM password hashing.
|
Package pepper provides pepper key management for SCRAM password hashing. |