auth

package
v0.9.1 Latest Latest
Warning

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

Go to latest
Published: Nov 12, 2026 License: Apache-2.0 Imports: 29 Imported by: 0

Documentation

Overview

Package auth provides XMPP authentication mechanisms.

Index

Constants

View Source
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
)
View Source
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.

View Source
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

func IsFastMechanism(mech string) bool

IsFastMechanism reports whether mech is a known FAST (HT-SHA-256-*) mechanism name.

func NewFastToken

func NewFastToken() ([]byte, error)

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

func NewExternal(address string, isSecure bool) *External

NewExternal returns a new external authenticator.

func (*External) Authenticated

func (e *External) Authenticated() bool

Authenticated returns whether or not user has been authenticated.

func (*External) Mechanism

func (e *External) Mechanism() string

Mechanism returns authenticator mechanism name.

func (*External) ProcessElement

func (e *External) ProcessElement(ctx context.Context, elem stravaganza.Element) (stravaganza.Element, *SASLError)

ProcessElement process an incoming authenticator element.

func (*External) Reset

func (e *External) Reset()

Reset resets scram internal state.

func (*External) SetDomain

func (e *External) SetDomain(_ string)

SetDomain is a no-op for External authenticator.

func (*External) Start

func (e *External) Start(ctx context.Context) error

Start dials external authenticator gRPC connection.

func (*External) Stop

func (e *External) Stop(_ context.Context) error

Stop closes underlying gRPC connection.

func (*External) Username

func (e *External) Username() string

Username returns authenticated username in case authentication process has been completed.

func (*External) UsesChannelBinding

func (e *External) UsesChannelBinding() bool

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

func (h *HTScram) AttemptedUsername() string

AttemptedUsername returns the username named by the current attempt, even if the token was rejected.

func (*HTScram) Authenticated

func (h *HTScram) Authenticated() bool

Authenticated reports whether the authentication succeeded.

func (*HTScram) Mechanism

func (h *HTScram) Mechanism() string

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) Reset

func (h *HTScram) Reset()

Reset clears the authenticator state for reuse.

func (*HTScram) SetClientID added in v0.4.0

func (h *HTScram) SetClientID(clientID string)

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) SetDomain

func (h *HTScram) SetDomain(_ string)

SetDomain is a no-op for HTScram authenticator.

func (*HTScram) Username

func (h *HTScram) Username() string

Username returns the authenticated username (empty until Authenticated() is true).

func (*HTScram) UsesChannelBinding

func (h *HTScram) UsesChannelBinding() bool

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

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 NewPlain

func NewPlain(rep repository.User, peppers *pepper.Keys, logger kitlog.Logger) *Plain

NewPlain returns a new PLAIN authenticator instance.

func (*Plain) AttemptedUsername added in v0.6.0

func (p *Plain) AttemptedUsername() string

AttemptedUsername returns the existing account targeted by the current attempt.

func (*Plain) Authenticated

func (p *Plain) Authenticated() bool

Authenticated returns true if the authentication has succeeded.

func (*Plain) Mechanism

func (p *Plain) Mechanism() string

Mechanism returns the SASL mechanism name.

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

func (p *Plain) SetDomain(domain string)

SetDomain sets the XMPP virtual host domain for this authentication attempt.

func (*Plain) Username

func (p *Plain) Username() string

Username returns the authenticated username, or empty string if not yet authenticated.

func (*Plain) UsesChannelBinding

func (p *Plain) UsesChannelBinding() bool

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).

func (*SASLError) Error

func (se *SASLError) Error() string

Error satisfies error interface.

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

func (s *Scram) AttemptedUsername() string

AttemptedUsername returns the existing account targeted by the current attempt, even if authentication has not (yet) succeeded.

func (*Scram) Authenticated

func (s *Scram) Authenticated() bool

Authenticated returns whether or not user has been authenticated.

func (*Scram) Mechanism

func (s *Scram) Mechanism() string

Mechanism returns authenticator mechanism name.

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

func (s *Scram) ProtectionHashFunc() func() hash.Hash

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) Reset

func (s *Scram) Reset()

Reset resets scram internal state.

func (*Scram) ServerProtectionHash added in v0.5.0

func (s *Scram) ServerProtectionHash() []byte

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

func (s *Scram) SetDomain(domain string)

SetDomain sets the XMPP virtual host domain for this authentication attempt.

func (*Scram) SetServerProtectionHash

func (s *Scram) SetServerProtectionHash(hash []byte)

SetServerProtectionHash sets the XEP-0474 server protection hash to be embedded in the SCRAM server-first-message as the h= attribute.

func (*Scram) StoreUpgradedHash

func (s *Scram) StoreUpgradedHash(ctx context.Context, task string, saltedPassword []byte) error

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

func (s *Scram) Username() string

Username returns authenticated username in case authentication process has been completed.

func (*Scram) UsesChannelBinding

func (s *Scram) UsesChannelBinding() bool

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.

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.

Jump to

Keyboard shortcuts

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