Documentation
¶
Overview ¶
Package sql implements SQL passdb/userdb for yarilo-auth. Supports SQLite, MySQL, PostgreSQL via a unified interface, with Dovecot-style customizable queries (password_query / user_query / iterate_query) and %u/%n/%d parameter substitution.
Index ¶
- func ParseSCRAMSha1Credentials(stored string) (*sasl.ScramCredentials, bool)
- func ParseSCRAMSha256Credentials(stored string) (*sasl.ScramCredentials, bool)
- type Config
- type Passdb
- func (p *Passdb) Authenticate(req *protocol.Request) (protocol.Result, error)
- func (p *Passdb) Close() error
- func (p *Passdb) Iterate() ([]string, error)
- func (p *Passdb) LookupSCRAMSha1(username string) (*sasl.ScramCredentials, error)
- func (p *Passdb) LookupSCRAMSha256(username string) (*sasl.ScramCredentials, error)
- func (p *Passdb) LookupUser(username string) (home, mailLoc string, err error)
- type Userdb
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func ParseSCRAMSha1Credentials ¶ added in v1.39.0
func ParseSCRAMSha1Credentials(stored string) (*sasl.ScramCredentials, bool)
ParseSCRAMSha1Credentials is the SHA-1 counterpart used by the passdb to satisfy LookupSCRAMSha1.
func ParseSCRAMSha256Credentials ¶ added in v1.39.0
func ParseSCRAMSha256Credentials(stored string) (*sasl.ScramCredentials, bool)
ParseSCRAMSha256Credentials extracts the SCRAM verifier from a stored password column carrying the `{SCRAM-SHA-256}` scheme. Returns (nil, false) when the value does not carry that scheme or the blob is malformed — callers use the falsy outcome to mean "this user does not have a SCRAM verifier".
Types ¶
type Config ¶ added in v0.3.5
type Config struct {
Driver string // sqlite | mysql | postgres
DSN string
PasswordQuery string // optional; defaults to built-in yarilo_users schema
UserQuery string // optional; if set, userdb lookup uses this query
IterateQuery string // optional; for admin tooling (list users)
DefaultPassScheme string // assumed scheme when stored password has no {SCHEME} prefix (default PLAIN)
SkipSchema bool // do not auto-create yarilo_users
}
Config is the open-time configuration for a SQL passdb.
type Passdb ¶
type Passdb struct {
// contains filtered or unexported fields
}
Passdb is an SQL-backed passdb (and optional userdb) entry.
func (*Passdb) Authenticate ¶
Authenticate verifies req.Username / req.Password against the SQL store and writes user fields directly into req.Fields when the lookup succeeds. Phase AUTH-2 PR 2 wire — drivers no longer allocate their own AuthResponse; the Chain owns the bag and the Result enum drives chain control flow.
Outcomes:
ResultNext — row not found in this database; chain falls through
ResultTempFail — backend / query error (the error return carries
the underlying cause for the server-side log)
ResultFail — user found but disabled OR password mismatch
ResultOK — verified; req.Fields populated with user / home / mail
Columns are matched by name, not position. Only "password" is required; "home", "mail", and "enabled" are optional. When "enabled" is absent the row is treated as active — callers may use a WHERE active=1 guard instead. The optional UserQuery runs after the password check to enrich home/mail.
func (*Passdb) Iterate ¶ added in v0.3.5
Iterate runs the iterate_query and returns the list of usernames. Returns an error if iterate_query is not configured.
func (*Passdb) LookupSCRAMSha1 ¶ added in v1.39.0
func (p *Passdb) LookupSCRAMSha1(username string) (*sasl.ScramCredentials, error)
LookupSCRAMSha1 satisfies protocol.SCRAMSha1Lookup. SHA-1 counterpart of LookupSCRAMSha256 — uses the same password_query path; only the verifier-blob scheme prefix differs.
func (*Passdb) LookupSCRAMSha256 ¶ added in v1.39.0
func (p *Passdb) LookupSCRAMSha256(username string) (*sasl.ScramCredentials, error)
LookupSCRAMSha256 satisfies protocol.SCRAMSha256Lookup. The SQL passdb runs its configured password_query, recognises the `{SCRAM-SHA-256}` scheme prefix on the password column, and returns the parsed ScramCredentials so the SCRAM-SHA-256 SASL mechanism can drive challenge-response without ever seeing a plain password.
Returns (nil, nil) for any of: user unknown / user disabled / stored password not a SCRAM-SHA-256 verifier. The session-side SCRAM server treats nil as "fabricate a fake verifier" so the exchange completes with a uniform auth-failed outcome and an attacker cannot enumerate users.
type Userdb ¶ added in v1.39.0
type Userdb struct {
// contains filtered or unexported fields
}
Userdb is the SQL-backed implementation of protocol.Userdb. It shares Config + DSN with the existing Passdb (operators typically have one DB serving both roles) but is exposed as a separate type so a deployment can chain heterogeneous backends — e.g. SQL passdb + LDAP userdb.
The default lookup query selects the columns shipped in the built-in yarilo_users schema (home, mail). Operators with richer schemas point Config.UserQuery at their own SELECT that returns the column names listed in [defaultUserdbColumns] — see the rowScanner below for the exact mapping from column name → UserInfo field. Any column the row carries that does not match a known typed field lands in UserInfo.Extra so forward-compatibility is preserved without requiring driver changes for every new field.
func NewUserdb ¶ added in v1.39.0
NewUserdb opens an SQL userdb. The Config is shared with Passdb's New so callers can construct both from one block; the userdb honours Config.UserQuery and Config.IterateQuery, defaulting to the same yarilo_users columns the Passdb assumes when the operator has not overridden them.
func (*Userdb) Iterate ¶ added in v1.39.0
Iterate implements protocol.UserdbIterator when an iterate_query is configured. Returns an error if no query was set so callers can distinguish "no enumeration support" from "empty result".
Source Files