SASL(n)                                           Simple Authentication and Security Layer (SASL)                                          SASL(n)

__________________________________________________________________________________________________________________________________________________

NAME

       SASL - Implementation of SASL mechanisms for Tcl

SYNOPSIS

       package require Tcl  8.2

       package require SASL  ?1.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 proto-
       cols. 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  num-
       ber  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 mecha-
              nisms 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 implementa-
              tion).

       ::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  cur-
              rent 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 chal-
              lenges. Mechanisms may be written to support server-side SASL and setting this option will cause each step to issue the  next  chal-
              lenge. 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 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 network in plain text by hashing the password with a server provided ran-
              dom 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 net-
              work.  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  envi-
              ronment.  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.

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)

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 SF Trackers [http://sourceforge.net/tracker/?group_id=12883].  Please also report any ideas for enhancements you  may  have  for
       either package and/or documentation.

KEYWORDS

       SASL, authentication

COPYRIGHT

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

sasl                                                                   1.3.0                                                               SASL(n)