SASL(3tcl)

📦
version 2.0 · 2 versions
, in debian trixie, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 SASL — the SASL(3tcl) glow-up 💖

okay bestie, sit down, hydrate, because we're about to make your Tcl app do authentication and it's gonna be iconic. This is the manual page for SASL, section 3tcl. 🫶

✨ NAME ✨

SASL — the implementation of SASL mechanisms for Tcl. periodt. 💅

🌈 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?

like… that's the whole vibe check right there. every single one of those gets its own moment below. 🎀

🦋 DESCRIPTION 🦋

The Simple Authentication and Security Layer (SASL) is a framework for handing out authentication and authorization to communication protocols. Think of it as the group chat where all the different auth methods get to negotiate who's coming to the party — the framework is literally structured to permit negotiation among a bunch of authentication mechanisms. 🎉

SASL can show up in SMTP, IMAP and HTTP authentication, and it's also in use in XMPP, LDAP and BEEP. So yeah, it gets around. If you wanna see the set of SASL mechanisms that ship with tcllib, hop down to MECHANISMS. 👀

The way it works: the SASL framework operates using a simple multi-step challenge response mechanism. Every mechanism works the same way, even though the number of steps may vary — no two are built the same, but they all follow the same choreography. 💃

In this implementation a callback procedure must be provided, and that's where the SASL framework will get the user's details from. The deets on that live in CALLBACK PROCEDURE. don't skip it, it's giving essential.

👑 COMMANDS 👑

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

Constructs a brand new SASL context. ✨ Check out OPTIONS for everything you can pass in here. A context token comes out of this, and you're gonna need it for basically every other SASL procedure — it's your little backstage pass. 🎟️

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

Modifies and inspects the SASL context option. Want more? OPTIONS. it's all there. 🔧

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

This is THE core procedure for using the SASL framework, no cap. 🫡

  • Keep calling step until it returns 0. that's the signal you're done, bestie.
  • Each step takes a server challenge string, and the response gets calculated and stored in the context.
  • Each mechanism may require one or more steps.
  • For some steps there may be no server challenge required, and in that case you pass an empty string for this parameter.
  • All mechanisms should accept an initial empty challenge. so don't be shy with that first call.

::SASL::response context

Hands you back the next response string that should be sent to the server. 📤 literally just ship it over.

::SASL::reset context

Re-initialize the SASL context. It discards any internal state and lets the token be reused — like a factory reset but for one little context. 🔄

::SASL::cleanup context

Releases all resources associated with the SASL context.

The context token may not be used again after this procedure has been called. it's gone, babe. say your goodbyes. 💀

::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 with a preference value less than the minimum (which defaults to 0) gets removed from the returned list. That's how you set a security threshold, slay.
  • Mechanisms with a preference less than 25 transmit authentication and are particularly susceptible to eavesdropping — so don't provide them unless a secure channel is in use (eg: tls). seriously. 🔒

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. no fake support in this house. 🙅

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

New mechanisms can be added to the package by registering the mechanism name and the implementing procedures. 🧚

  • The serverproc 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.

💅 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. Peep 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 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 is used to set 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. 🔁
A new context must be created for each incoming client connection when in server mode. no sharing, no recycling, one context per connection, that's the rule. 🚨

🎀 CALLBACK PROCEDURE 🎀

When the SASL framework requires any user details, it will call the procedure you provided when the context was created — with 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 to be different to 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. (yes, same reference, it's that important.)
  • 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 is 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. it is NOT subtle, bestie. 😭
  • 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. 🚫
  • 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 to 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]. 🔐
  • OTP — OTP is the One-Time Password system described in RFC 2289 [6]. This mechanism is secure against replay attacks and also avoids storing password or password equivalents on the server. Only a digest of a seed and a passphrase is ever transmitted across the network. Requires the otp package from tcllib and 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 is 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 is 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 and so this mechanism 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 tea so far, but we are not done — part 2 is coming, so don't go anywhere. 💖

💖 EXAMPLES 💖

Ok bestie, lowkey the best way to get this is to see it. There's a whole examples subdirectory with fuller samples of SASL doing its thing with actual network protocols — go peek at that for the real deal. But here's the vibe, the lil taste test. ✨

Heads up fr fr: in real life this should be event driven. Every time you call step, you hand it the last server response as the command argument, so the SASL mechanism can do the right thing. Don't just spin in a loop like the demo does, that's just for showing off the shape of it. 💅
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 🌈

The receipts, the lore, the source material. All of it. 🫶

  1. Myers, J. "Simple Authentication and Security Layer (SASL)", RFC 2222, October 1997. (http://www.ietf.org/rfc/rfc2222.txt)
  2. Newman, C. "Anonymous SASL Mechanism", RFC 2245, November 1997. (http://www.ietf.org/rfc/rfc2245.txt)
  3. Leach, P., Newman, C. "Using Digest Authentication as a SASL Mechanism", RFC 2831, May 2000, (http://www.ietf.org/rfc/rfc2831.txt)
  4. Klensin, J., Catoe, R. and Krumviede, P., "IMAP/POP AUTHorize Extension for Simple Challenge/Response" RFC 2195, September 1997. (http://www.ietf.org/rfc/rfc2195.txt)
  5. No official specification is available. However, http://davenport.sourceforge.net/ntlm.html provides a good description.
  6. Haller, N. et al., "A One-Time Password System", RFC 2289, February 1998, (http://www.ieft.org/rfc/rfc2289.txt)
  7. Newman, C. et al., "Salted Challenge Response Authentication Mechanism (SCRAM) SASL and GSS-API Mechanisms", RFC 5802, July 2010, (http://www.ieft.org/rfc/rfc5802.txt)

👑 AUTHORS 👑

Pat Thoyts

That's the whole list. One icon. Main character energy only. 💅

🙈 BUGS, IDEAS, FEEDBACK 🙈

Not me having to say this, but okay bestie: this document, and the package it describes, will undoubtedly contain bugs and other problems. It's giving humble, but also it's giving honest. 😭

Please report such in the category sasl of the Tcllib Trackers [http://core.tcl.tk/tcllib/reportlist]. And if you've got ideas for enhancements — for the package, for the docs, either one, both — report those too, we want them. 🫶

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

Also, and this is important: attachments are strongly preferred over inlined patches. How do you attach? Go to the Edit form of the ticket right after you create it, then use the left-most button in the secondary navigation bar. Boom. Slay. ✨

💜 KEYWORDS 💜

SASL, authentication

🌸 CATEGORY 🌸

Networking

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

and that's the whole page bestie, you ate it 💖

This lil beauty ships as part of tcllib, version 1.3.4, living at SASL(3tcl). Go authenticate something iconic. mwah 🫶✨👑

📦 where this page comes from