SASL(n)

📦
version 2.0 · 2 versions
, in fedora 43, fedora 44, nixos 26.05, nixpkgs unstable

SASL 💖

okay bestie, welcome to the Simple Authentication and Security Layer page for Tcl. this is the manual for the SASL package (part 1 of 2, so don't go anywhere, we're not done yet 💅).

✨ NAME ✨

SASL — an implementation of SASL mechanisms for Tcl 🦋

🌸 SYNOPSIS 🌸

package require Tcl 8.5 9

package require SASL ?1.3.4?

::SASL::new option value ?...?

::SASL::configure option value ?...?

::SASL::step context challenge ?...?

::SASL::response context

::SASL::reset context

::SASL::cleanup context

::SASL::mechanisms ?type? ?minimum?

::SASL::register mechanism preference clientproc ?serverproc?

💜 DESCRIPTION 💜

so, the Simple Authentication and Security Layer (SASL, for the girlies who shorten things) is a framework for handing out authentication and authorization to communication protocols. and like, the whole point of a framework is that it lets a bunch of different authentication mechanisms negotiate with each other. it's giving diplomacy. it's giving "let's talk about it."

SASL may be used in SMTP, IMAP and HTTP authentication. it's also in use in XMPP, LDAP and BEEP. if you want the actual list of SASL mechanisms that ship with tcllib, scroll down to MECHANISMS, bestie, I got you.

The framework operates using a simple multi-step challenge response mechanism. every single mechanism works the same way, no cap — the only thing that varies is how many steps it takes. and in this implementation, you have to provide a callback procedure, because that's how the SASL framework gets the user's details. the full tea on that procedure is in CALLBACK PROCEDURE. 🫶

👑 COMMANDS 👑

  • ::SASL::new option value ?...? — construct a brand new SASL context ✨. the possible options are all listed down in OPTIONS. you need a context token for basically most of the SASL procedures, so this is your main character origin story.
  • ::SASL::configure option value ?...? — modify and inspect the SASL context option. more details in OPTIONS, obviously.
  • ::SASL::step context challenge ?...? — THE core procedure, the moment, the icon 🔥. you keep calling step until it returns 0. each step takes a server challenge string, and the response gets calculated and stored in the context. some mechanisms need one step, some need a whole situationship of steps. for some steps there may be no server challenge required at all, and in that case you pass an empty string for this parameter. all mechanisms should accept an initial empty challenge. (yes, all of them. they're polite like that.)
  • ::SASL::response context — returns the next response string that should be sent to the server. 📤
  • ::SASL::reset context — re-initialize the SASL context. this discards any internal state and lets the token be reused. it's the "we're starting over, fresh slate, no baggage" button 🧚
  • ::SASL::cleanup context — release ALL resources associated with the SASL context. and listen: the context token may not be used again after this procedure has been called. it's gone. periodt. 💀
  • ::SASL::mechanisms ?type? ?minimum? — returns a list of all the available SASL mechanisms. the list is sorted by the mechanism preference value (see register), with the preferred mechanisms at the head of the list. any mechanism whose preference value is less than the minimum (which defaults to 0) gets removed from the returned list. this lets you set a security threshold, which is lowkey important.
bestie, real talk: mechanisms with a preference less than 25 transmit authentication in a way that is particularly susceptible to eavesdropping. do not provide them unless a secure channel is in use (eg: tls). I'm not being dramatic, I'm being accurate. 😭

the type parameter may be one of client or server, and it defaults to client. only mechanisms that have an implementation matching the type are returned — this lets servers correctly declare support only for mechanisms that actually provide a server implementation. honest king behavior.

  • ::SASL::register mechanism preference clientproc ?serverproc? — new mechanisms can be added to the package by registering the mechanism name and the implementing procedures. the server procedure is optional. the preference value is an integer used to order the list returned by the mechanisms command — higher values indicate a preferred mechanism. if the mechanism is already registered, then the recorded values are updated. glow-up, not duplicate. ✨

💅 OPTIONS 💅

  • -callback — specify a command to be evaluated when the SASL mechanism requires information about the user. the command is called with the current SASL context and a name specifying the information desired. see EXAMPLES. 🎀
  • -mechanism — set the SASL mechanism to be used. see mechanisms for a list of supported authentication mechanisms.
  • -service — set the service type for this context. some mechanisms may make use of this parameter (eg DIGEST-MD5, GSSAPI and Kerberos). if it's not set, it defaults to an empty string. if the -type is set to server, then this option should be set to a valid service identity. some examples of valid service names are smtp, ldap, beep and xmpp. 📬
  • -server — this option sets the server name used in SASL challenges when operating as a SASL server.
  • -type — the context type may be one of client or server. the default is to operate as a client application and respond to server challenges. mechanisms may be written to support server-side SASL, and setting this option will cause each step to issue the next challenge.
🚨 heads up: a new context must be created for each incoming client connection when in server mode. no sharing, no reusing, we don't do that here.

🌈 CALLBACK PROCEDURE 🌈

when the SASL framework needs any user details, it will call the procedure you provided when the context was created, passing an argument that specifies the item of information required.

in all cases, a single response string should be returned. one string. that's it. 🫶

  • login — the callback procedure should return the user's authorization identity. return an empty string unless this is meant to be different from the authentication identity. read [1] for a discussion about the specific meaning of authorization and authentication identities within SASL.
  • username — the callback procedure should return the user's authentication identity. read [1] for a discussion about the specific meaning of authorization and authentication identities within SASL.
  • password — the callback procedure should return the password that matches the authentication identity as used within the current realm.

for server mechanisms, the password callback should always be called with the authentication identity and the realm as the first two parameters. 🔐

  • realm — some SASL mechanisms use realms to partition authentication identities. the realm string is protocol dependent and is often the current DNS domain, or in the case of the NTLM mechanism it's the Windows NT domain name.
  • hostname — returns the client host name — typically [info host]. 🖥️

🦋 MECHANISMS 🦋

  • ANONYMOUS — as used in FTP, this mechanism only passes an email address for authentication. the ANONYMOUS mechanism is specified in [2].
  • PLAIN — this is the simplest mechanism. the user's authentication details are transmitted in plain text. this mechanism should not be provided unless an encrypted link is in use — typically after SSL or TLS has been negotiated. bestie. please. 😭
  • LOGIN — the LOGIN [1] mechanism transmits the user's details with base64 encoding. this is no more secure than PLAIN, and likewise should not be used without a secure link. it's giving "I put a sticker on it and called it encryption."
  • CRAM-MD5 — this mechanism avoids sending the user's password over the network in plain text by hashing the password with a server provided random value (known as a nonce). a disadvantage of this mechanism is that the server must maintain a database of plaintext passwords for comparison. CRAM-MD5 was defined in [4].
  • DIGEST-MD5 — this mechanism improves upon the CRAM-MD5 mechanism by avoiding the need for the server to store plaintext passwords. with digest authentication, the server needs to store the MD5 digest of the user's password, which helps make the system more secure. as in CRAM-MD5, the password is hashed with a server nonce and other data before being transmitted across the network. specified in [3]. we love an upgrade arc ✨
  • OTP — OTP is the One-Time Password system described in RFC 2289 [6]. this mechanism is secure against replay attacks and also avoids storing passwords or password equivalents on the server. only a digest of a seed and a passphrase is ever transmitted across the network. it requires the otp package from tcllib, plus one or more of the cryptographic digest packages (md5 or sha-1 are the most commonly used).
  • NTLM — this is a proprietary protocol developed by Microsoft [5] and it's in common use for authenticating users in a Windows network environment. NTLM uses DES encryption and MD4 digests of the user's password to authenticate a connection. certain weaknesses have been found in NTLM, and thus there are a number of versions of the protocol. as this mechanism has additional dependencies, it's made available as a separate sub-package. to enable this mechanism, your application must load the SASL::NTLM package. 📦
  • X-GOOGLE-TOKEN — this is a proprietary protocol developed by Google and used for authenticating users for the Google Talk service. this mechanism makes a pair of HTTP requests over an SSL channel, so it depends upon the availability of the tls and http packages. to enable this mechanism, your application must load the SASL::XGoogleToken package. in addition, you are recommended to make use of the autoproxy package to handle HTTP proxies reasonably transparently.
  • SCRAM — this is a protocol specified in RFC 5802 [7]. to enable this mechanism, your application must load the SASL::SCRAM package. 🔥

okay that's the whole first half, bestie — more parts follow so don't close the tab, we're literally not done 👑💖

✨ EXAMPLES ✨

okay bestie, the examples subdirectory has way more complete samples using SASL with network protocols. The snippet below is just the vibe of how the SASL commands are supposed to be used. Real talk: in reality this should be event driven. Every single time the step command is called, you pass the last server response as the command argument so the SASL mechanism can take appropriate action. 💅

proc ClientCallback {context command args} {
    switch -exact -- $command {
        login    { return "" }
        username { return $::tcl_platform(user) }
        password { return "SecRet" }
        realm    { return "" }
        hostname { return [info host] }
        default  { return -code error unxpected }
    }
}

proc Demo {{mech PLAIN}} {
    set ctx [SASL::new -mechanism $mech -callback ClientCallback]
    set challenge ""
    while {1} {
        set more_steps [SASL::step $ctx challenge]
        puts "Send '[SASL::response $ctx]'"
        puts "Read server response into challenge var"
        if {!$more_steps} {break}
    }
    SASL::cleanup $ctx
}

🌈 REFERENCES 🌈

👑 AUTHORS 👑

Pat Thoyts

💅 BUGS, IDEAS, FEEDBACK 💅

This document, and the package it describes, will undoubtedly contain bugs and other problems. 😭 Please report such in the category sasl of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. Please also report any ideas for enhancements you may have for either package and/or documentation.

When proposing code changes, please provide unified diffs, i.e the output of diff -u.

Note further that attachments are strongly preferred over inlined patches. Attachments can be made by going to the Edit form of the ticket immediately after its creation, and then using the left-most button in the secondary navigation bar.

⭐ KEYWORDS ⭐

SASL, authentication

🎀 CATEGORY 🎀

Networking

Copyright (c) 2005-2006, Pat Thoyts <patthoyts@users.sourceforge.net>

This whole thing is from tcllib 1.3.4, SASL(n). That's the source/version at the bottom, bestie. 💋

📦 where this page comes from