Provided by: tcllib_1.21+dfsg-1_all bug

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
       MECHANISMS for the set of available SASL mechanisms provided with tcllib.

       The  SASL  framework  operates using a simple multi-step challenge response 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 details. See CALLBACK PROCEDURE for details of this procedure.

COMMANDS

       ::SASL::new option value ?...?
              Contruct a new SASL context. See OPTIONS for details of  the  possible  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 further 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 required in which  case
              an empty string should be provided for this parameter. All mechanisms should accept
              an initial empty challenge.

       ::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 context 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  eavesdropping  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 implementation).

       ::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  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 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 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.

CALLBACK PROCEDURE

       When the SASL framework requires any user details it will call the procedure 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
              identities 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 provided 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 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 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. 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 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 reasonably 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 commands 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://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

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

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