


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



sasl                          1.3.0                             1





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


              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 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
              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 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
              requires information about the user. The command is called  with
              the  current  SASL context and a name specifying the information
              desired. See EXAMPLES.




sasl                          1.3.0                             2





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


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



sasl                          1.3.0                             3





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


       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
              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 net-
              work. 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



sasl                          1.3.0                             4





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


              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.


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)



sasl                          1.3.0                             5





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


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

KEYWORDS
       SASL, authentication

CATEGORY
       Networking

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
































sasl                          1.3.0                             6


