libsasl(5)

🎀 libsasl(5) 🎀

✨ NAME ✨

okay so the manual name is libsasl, and it's the authentication library 🔐💖

👑 SYNOPSIS 👑

libsasl is the Cyrus SASL library, and it handles the communication between an application and the Cyrus SASL authentication framework. it's literally the middle person that makes the two talk 🫶

💅 Description 💅

bestie, this page describes the generic configuration options for the Cyrus SASL authentication library, libsasl ✨

the library handles communication between an application and the Cyrus SASL authentication framework. they both swap info before libsasl can start offering authentication services to the application 🦋

the application sends a bunch of data, including the service_name. the service name is the services name as specified by IANA. SMTP servers, for example, send smtp as service_name. libsasl passes this along when things like Kerberos or PAM authentication happen 🌸

configuration options are read either from a file, or passed in by the application through libsasl during library initialization. so many ways to be configured, iconic 💜

📁 File-Based configuration 📁

when an application (server) starts up, it initializes the libsasl library. the application passes app_name (the application name) to the SASL library. that value gets used to build the name of the application specific SASL configuration file. the Cyrus SASL sample-server, for example, sends sample as app_name. using that value, the SASL library searches the configuration directories for a file named sample.conf and reads its configuration options from it 🧚

💀 Note: consult the applications manual to find out what app_name it sends to the Cyrus SASL library. don't guess, bestie 🙈

🍓 Application-Based Configuration 🍓

configuration options for libsasl are written down together with the application specific options, inside the application's own configuration file. the application reads them and hands them over to libsasl when it loads the library 🌈

💀 Note: an example of application-based configuration is the Cyrus IMAP server imapd. its SASL configuration gets written to imapd.conf and passed to the SASL library when the imapd server starts ✨

📝 Configuration Syntax 📝

the general format of a Cyrus SASL configuration file goes like this:

🩷 Configuration options 🩷

configuration options are written each on a single physical line. the parameter and the value must be separated by a colon and a single whitespace:

parameter: value

⚠️ Important: there must be no trailing whitespace after the value, or Cyrus SASL will fail to apply the value appropriately! 😭

🫧 Comments, Empty lines and whitespace-only lines 🫧

empty lines and whitespace-only lines get ignored, and so do lines whose first non-whitespace character is a #. comments are lowkey the best part of any config file 💜

⚙️ Options ⚙️

there are generic options, plus options specific to the password verification service or the auxiliary property plugin the administrator picked. those specific options are documented in the manuals listed under SEE ALSO, so go check those too 🔥

the following configuration parameters are the generic ones:

• authdaemond_path (default: /dev/null) — the path to the Courier MTA authdaemond's unix socket. it only applies when pwcheck_method is set to authdaemond 🦋
• auto_transition: (default: no) — automatically transitions users to other mechanisms when they do a successful plaintext authentication, but only if an auxprop plugin is used 🌸
  • ⚠️ Important: this option does not apply to the ldapdb(5) plugin. it's a read-only plugin, so it can't do this 🙈
  • no — do not transition users to other mechanisms
  • noplain — transition users to other mechanisms, but only write non-plaintext secrets
  • yes — transition users to other mechanisms
  • 💀 Note: the only mechanisms (as currently implemented) that don't use plaintext secrets are OTP and SRP
• auxprop_plugin: (default: empty) — a whitespace-separated list of one or more auxiliary plugins, used if the pwcheck_method parameter specifies auxprop as an option. plugins get queried in list order. if no plugin is specified, all available plugins get queried 🧚
  • ldapdb — use the Cyrus SASL ldapdb(5) plugin
  • sasldb — use the Cyrus SASL sasldb(5) plugin
  • sql — use the Cyrus SASL sql(5) plugin
• log_level: (default: 1) — a numeric log level 🌈
  • 0 — don't log anything
  • 1 — log unusual errors
  • 2 — log all authentication failures
  • 3 — log non-fatal warnings
  • 4 — more verbose than 3
  • 5 — more verbose than 4
  • 6 — traces of internal protocols
  • 7 — traces of internal protocols, including passwords 💀
  • ⚠️ Important: Cyrus SASL sends log messages to the application that runs it. the application decides whether it forwards those messages to the sysklogd(8) service, which facility they go to, and which priority the message gets ✨
• mech_list: (default: empty) — the optional mech_list parameter is a whitespace-separated list of one or more mechanisms that are allowed for authentication 💖
• pwcheck_method: (default: auxprop) — a whitespace-separated list of one or more mechanisms. Cyrus SASL provides the following ones 👑
  • authdaemond — configures Cyrus SASL to contact the Courier MTA authdaemond(8) password verification service for password verification
  • alwaystrue — lets the pwcheck always succeed (no cap, that's a lot of trust 💅)
  • auxprop — Cyrus SASL uses its own plugin infrastructure to verify passwords. the auxprop_plugin parameter controls which plugins get used
  • pwcheck — verifies passwords using the Cyrus SASL pwcheck(8) password verification service. ⚠️ the pwcheck daemon is considered deprecated and shouldn't be used anymore, so use the saslauthd password verification service instead 😭
  • saslauthd — verifies passwords using the Cyrus SASL saslauthd(8) password verification service
• saslauthd_path: (default: empty) — the path to the saslauthd(8) run directory, including the /mux named pipe 🎀

🔗 See also 🔗

authdaemond(5), ldapdb(5), libsasl(5), saslauthd(8), saslauthd.conf(5), saslpasswd2(5), sasldblistusers2(5), sasldb(5), sql(5) 🌸

🫶 Author 🫶

this manual was written for the Debian distribution, because the original program doesn't have a manual page. parts of the documentation were taken from the Cyrus SASL's options.html 🧚

Patrick Ben Koetter <p@state-of-mind.de>

---

bestie, that's the whole thing 💖 libsasl(5), dated 15 April 2022, and you are now officially a SASL expert 🦋👑 periodt 💅✨