SASL(3tcl) Simple Authentication and Security Layer (SASL) SASL(3tcl)
______________________________________________________________________________
NAME
SASL - Implementation of SASL mechanisms for Tcl
SYNOPSIS
package require Tcl 8.2
package require SASL ?1.3.3?
::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
The Simple Authentication and Security Layer (SASL) is a framework for
providing authentication and authorization to comunications protocols.
The SASL framework is structured to permit negotiation among a number
of authentication mechanisms. SASL may be used in SMTP, IMAP and HTTP
authentication. It is also in use in XMPP, LDAP and BEEP. See MECHA-
NISMS for the set of available SASL mechanisms provided with tcllib.
The SASL framework operates using a simple multi-step challenge re-
sponse mechanism. All the mechanisms work the same way although the
number of steps may vary. In this implementation a callback procedure
must be provided from which the SASL framework will obtain users de-
tails. See CALLBACK PROCEDURE for details of this procedure.
COMMANDS
::SASL::new option value ?...?
Contruct a new SASL context. See OPTIONS for details of the pos-
sible options to this command. A context token is required for
most of the SASL procedures.
::SASL::configure option value ?...?
Modify and inspect the SASL context option. See OPTIONS for fur-
ther details.
::SASL::step context challenge ?...?
This is the core procedure for using the SASL framework. The
step procedure should be called until it returns 0. Each step
takes a server challenge string and the response is calculated
and stored in the context. Each mechanism may require one or
more steps. For some steps there may be no server challenge re-
quired in which case an empty string should be provided for this
parameter. All mechanisms should accept an initial empty chal-
lenge.
::SASL::response context
Returns the next response string that should be sent to the
server.
::SASL::reset context
Re-initialize the SASL context. Discards any internal state and
permits the token to be reused.
::SASL::cleanup context
Release all resources associated with the SASL context. The con-
text token may not be used again after this procedure has been
called.
::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 and the head of the list. Any mechanism
with a preference value less than theminimum (which defaults to
0) is removed from the returned list. This permits a security
threshold to be set. Mechanisms with a preference less that 25
transmit authentication are particularly susceptible to eaves-
dropping and should not be provided unless a secure channel is
in use (eg: tls).
The type parameter may be one of client or server and defaults
to client. Only mechanisms that have an implementation matching
the type are returned (this permits servers to correctly declare
support only for mechanisms that actually provide a server im-
plementation).
::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 pro-
cedure is optional. The preference value is an integer that is
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 re-
quires 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
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 iden-
tity. 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 chal-
lenges 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.
CALLBACK PROCEDURE
When the SASL framework requires any user details it will call the pro-
cedure provided when the context was created with an argument that
specfies the item of information required.
In all cases a single response string should be returned.
login The callback procedure should return the users 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 identi-
ties within SASL.
username
The callback procedure should return the users 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
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 users authentication details
are transmitted in plain text. This mechanism should not be pro-
vided unless an encrypted link is in use - typically after SSL
or TLS has been negotiated.
LOGIN The LOGIN [1] mechanism transmits the users 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 users password over the net-
work in plain text by hashing the password with a server pro-
vided random value (known as a nonce). A disadvantage of this
mechanism is that the server must maintain a database of plain-
text 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 di-
gest authentication the server needs to store the MD5 digest of
the users 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. Speci-
fied 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 en-
vironment. NTLM uses DES encryption and MD4 digests of the users
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 rea-
sonably transparently.
SCRAM This is a protocol specified in RFC 5802 [7]. To enable this
mechanism your application must load the SASL::SCRAM package.
EXAMPLES
See the examples subdirectory for more complete samples using SASL with
network protocols. The following should give an idea how the SASL com-
mands are to be used. In reality this should be event driven. Each time
the step command is called, the last server response should be provided
as the command argument so that 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
[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://daven-
port.sourceforge.net/ntlm.html provides a good description.
[6] Haller, N. et al., "A One-Time Password System", RFC 2289, Feb-
ruary 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
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 out-
put 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
Copyright (c) 2005-2006, Pat Thoyts <patthoyts@users.sourceforge.net>
tcllib 1.3.3 SASL(3tcl)