1SASL(n)         Simple Authentication and Security Layer (SASL)        SASL(n)
2
3
4
5______________________________________________________________________________
6

NAME

8       SASL - Implementation of SASL mechanisms for Tcl
9

SYNOPSIS

11       package require Tcl  8.2
12
13       package require SASL  ?1.3.3?
14
15       ::SASL::new option value ?...?
16
17       ::SASL::configure option value ?...?
18
19       ::SASL::step context challenge ?...?
20
21       ::SASL::response context
22
23       ::SASL::reset context
24
25       ::SASL::cleanup context
26
27       ::SASL::mechanisms ?type? ?minimum?
28
29       ::SASL::register mechanism preference clientproc ?serverproc?
30
31______________________________________________________________________________
32

DESCRIPTION

34       The  Simple Authentication and Security Layer (SASL) is a framework for
35       providing authentication and authorization to comunications  protocols.
36       The  SASL  framework is structured to permit negotiation among a number
37       of authentication mechanisms. SASL may be used in SMTP, IMAP  and  HTTP
38       authentication.  It  is  also in use in XMPP, LDAP and BEEP. See MECHA‐
39       NISMS for the set of available SASL mechanisms provided with tcllib.
40
41       The  SASL  framework  operates  using  a  simple  multi-step  challenge
42       response  mechanism.  All the mechanisms work the same way although the
43       number of steps may vary. In this implementation a  callback  procedure
44       must  be  provided  from  which  the  SASL  framework will obtain users
45       details. See CALLBACK PROCEDURE for details of this procedure.
46

COMMANDS

48       ::SASL::new option value ?...?
49              Contruct a new SASL context. See OPTIONS for details of the pos‐
50              sible  options  to this command. A context token is required for
51              most of the SASL procedures.
52
53       ::SASL::configure option value ?...?
54              Modify and inspect the SASL context option. See OPTIONS for fur‐
55              ther details.
56
57       ::SASL::step context challenge ?...?
58              This  is  the  core  procedure for using the SASL framework. The
59              step procedure should be called until it returns  0.  Each  step
60              takes  a  server challenge string and the response is calculated
61              and stored in the context. Each mechanism  may  require  one  or
62              more  steps.  For  some  steps  there may be no server challenge
63              required in which case an empty string should  be  provided  for
64              this  parameter.  All  mechanisms should accept an initial empty
65              challenge.
66
67       ::SASL::response context
68              Returns the next response string that  should  be  sent  to  the
69              server.
70
71       ::SASL::reset context
72              Re-initialize  the SASL context. Discards any internal state and
73              permits the token to be reused.
74
75       ::SASL::cleanup context
76              Release all resources associated with the SASL context. The con‐
77              text  token  may not be used again after this procedure has been
78              called.
79
80       ::SASL::mechanisms ?type? ?minimum?
81              Returns a list of all the available SASL mechanisms. The list is
82              sorted by the mechanism preference value (see register) with the
83              preferred mechanisms and the head of  the  list.  Any  mechanism
84              with  a preference value less than theminimum (which defaults to
85              0) is removed from the returned list. This  permits  a  security
86              threshold  to  be set. Mechanisms with a preference less that 25
87              transmit authentication are particularly susceptible  to  eaves‐
88              dropping  and  should not be provided unless a secure channel is
89              in use (eg: tls).
90
91              The type parameter may be one of client or server  and  defaults
92              to client.  Only mechanisms that have an implementation matching
93              the type are returned (this permits servers to correctly declare
94              support  only  for  mechanisms  that  actually  provide a server
95              implementation).
96
97       ::SASL::register mechanism preference clientproc ?serverproc?
98              New mechanisms can be added to the package  by  registering  the
99              mechanism  name and the implementing procedures. The server pro‐
100              cedure is optional. The preference value is an integer  that  is
101              used  to  order  the  list  returned  by the mechanisms command.
102              Higher values indicate a preferred mechanism. If  the  mechanism
103              is already registered then the recorded values are updated.
104

OPTIONS

106       -callback
107              Specify  a  command  to  be  evaluated  when  the SASL mechanism
108              requires information about the user. The command is called  with
109              the  current  SASL context and a name specifying the information
110              desired. See EXAMPLES.
111
112       -mechanism
113              Set the SASL mechanism to be used. See mechanisms for a list  of
114              supported authentication mechanisms.
115
116       -service
117              Set  the service type for this context. Some mechanisms may make
118              use of this parameter (eg DIGEST-MD5, GSSAPI and  Kerberos).  If
119              not  set  it defaults to an empty string. If the -type is set to
120              'server' then this option should be set to a valid service iden‐
121              tity.  Some examples of valid service names are smtp, ldap, beep
122              and xmpp.
123
124       -server
125              This option is used to set the server name used  in  SASL  chal‐
126              lenges when operating as a SASL server.
127
128       -type  The context type may be one of 'client' or 'server'. The default
129              is to operate as a client  application  and  respond  to  server
130              challenges.  Mechanisms  may  be  written to support server-side
131              SASL and setting this option will cause each step to  issue  the
132              next  challenge. A new context must be created for each incoming
133              client connection when in server mode.
134

CALLBACK PROCEDURE

136       When the SASL framework requires any user details it will call the pro‐
137       cedure  provided  when  the  context  was created with an argument that
138       specfies the item of information required.
139
140       In all cases a single response string should be returned.
141
142       login  The callback procedure should  return  the  users  authorization
143              identity.  Return an empty string unless this is to be different
144              to the authentication identity. Read [1] for a discussion  about
145              the specific meaning of authorization and authentication identi‐
146              ties within SASL.
147
148       username
149              The callback procedure should return  the  users  authentication
150              identity.   Read [1] for a discussion about the specific meaning
151              of authorization and authentication identities within SASL.
152
153       password
154              The callback procedure should return the password  that  matches
155              the authentication identity as used within the current realm.
156
157              For  server  mechanisms  the  password callback should always be
158              called with the authentication identity and  the  realm  as  the
159              first two parameters.
160
161       realm  Some  SASL  mechanisms  use  realms  to partition authentication
162              identities.  The realm string is protocol dependent and is often
163              the  current  DNS domain or in the case of the NTLM mechanism it
164              is the Windows NT domain name.
165
166       hostname
167              Returns the client host name - typically [info host].
168

MECHANISMS

170       ANONYMOUS
171              As used in FTP this mechanism only passes an email  address  for
172              authentication. The ANONYMOUS mechanism is specified in [2].
173
174       PLAIN  This is the simplest mechanism. The users authentication details
175              are transmitted in plain text. This mechanism should not be pro‐
176              vided  unless  an encrypted link is in use - typically after SSL
177              or TLS has been negotiated.
178
179       LOGIN  The LOGIN [1] mechanism transmits the users details with  base64
180              encoding.  This is no more secure than PLAIN and likewise should
181              not be used without a secure link.
182
183       CRAM-MD5
184              This mechanism avoids sending the users password over  the  net‐
185              work  in  plain  text by hashing the password with a server pro‐
186              vided random value (known as a nonce). A  disadvantage  of  this
187              mechanism  is that the server must maintain a database of plain‐
188              text passwords for comparison. CRAM-MD5 was defined in [4].
189
190       DIGEST-MD5
191              This mechanism improves upon the CRAM-MD5 mechanism by  avoiding
192              the  need  for  the  server  to  store plaintext passwords. With
193              digest authentication the server needs to store the  MD5  digest
194              of  the  users  password  which  helps  to  make the system more
195              secure. As in CRAM-MD5 the password  is  hashed  with  a  server
196              nonce  and  other  data before being transmitted across the net‐
197              work. Specified in [3].
198
199       OTP    OTP is the One-Time Password system described in RFC  2289  [6].
200              This  mechanism is secure against replay attacks and also avoids
201              storing password or password equivalents on the server.  Only  a
202              digest of a seed and a passphrase is ever transmitted across the
203              network. Requires the otp package from tcllib and one or more of
204              the  cryptographic  digest  packages  (md5 or sha-1 are the most
205              commonly used).
206
207       NTLM   This is a proprietary protocol developed by Microsoft [5] and is
208              in  common  use  for  authenticating  users in a Windows network
209              environment. NTLM uses DES encryption and  MD4  digests  of  the
210              users  password to authenticate a connection. Certain weaknesses
211              have been found in NTLM and thus there are a number of  versions
212              of  the protocol.  As this mechanism has additional dependencies
213              it is made available as a separate sub-package. To  enable  this
214              mechanism your application must load the SASL::NTLM package.
215
216       X-GOOGLE-TOKEN
217              This  is a proprietary protocol developed by Google and used for
218              authenticating users for the Google Talk service. This mechanism
219              makes  a  pair  of HTTP requests over an SSL channel and so this
220              mechanism depends upon the availability  of  the  tls  and  http
221              packages.  To  enable  this mechanism your application must load
222              the SASL::XGoogleToken package.  In addition you are recommended
223              to make use of the autoproxy package to handle HTTP proxies rea‐
224              sonably transparently.
225
226       SCRAM  This is a protocol specified in RFC 5802  [7].  To  enable  this
227              mechanism your application must load the SASL::SCRAM package.
228

EXAMPLES

230       See the examples subdirectory for more complete samples using SASL with
231       network protocols. The following should give an idea how the SASL  com‐
232       mands are to be used. In reality this should be event driven. Each time
233       the step command is called, the last server response should be provided
234       as the command argument so that the SASL mechanism can take appropriate
235       action.
236
237
238              proc ClientCallback {context command args} {
239                  switch -exact -- $command {
240                      login    { return "" }
241                      username { return $::tcl_platform(user) }
242                      password { return "SecRet" }
243                      realm    { return "" }
244                      hostname { return [info host] }
245                      default  { return -code error unxpected }
246                  }
247              }
248
249              proc Demo {{mech PLAIN}} {
250                  set ctx [SASL::new -mechanism $mech -callback ClientCallback]
251                  set challenge ""
252                  while {1} {
253                      set more_steps [SASL::step $ctx challenge]
254                      puts "Send '[SASL::response $ctx]'"
255                      puts "Read server response into challenge var"
256                      if {!$more_steps} {break}
257                  }
258                  SASL::cleanup $ctx
259              }
260
261

REFERENCES

263       [1]    Myers, J. "Simple Authentication and Security Layer (SASL)", RFC
264              2222, October 1997.  (http://www.ietf.org/rfc/rfc2222.txt)
265
266       [2]    Newman,  C. "Anonymous SASL Mechanism", RFC 2245, November 1997.
267              (http://www.ietf.org/rfc/rfc2245.txt)
268
269       [3]    Leach, P., Newman, C. "Using Digest  Authentication  as  a  SASL
270              Mechanism",          RFC         2831,         May         2000,
271              (http://www.ietf.org/rfc/rfc2831.txt)
272
273       [4]    Klensin, J., Catoe, R. and Krumviede,  P.,  "IMAP/POP  AUTHorize
274              Extension  for  Simple  Challenge/Response"  RFC 2195, September
275              1997.  (http://www.ietf.org/rfc/rfc2195.txt)
276
277       [5]    No official specification is available.  However,  http://daven
278              port.sourceforge.net/ntlm.html provides a good description.
279
280       [6]    Haller,  N. et al., "A One-Time Password System", RFC 2289, Feb‐
281              ruary 1998, (http://www.ieft.org/rfc/rfc2289.txt)
282
283       [7]    Newman, C. et al.,  "Salted  Challenge  Response  Authentication
284              Mechanism  (SCRAM)  SASL and GSS-API Mechanisms", RFC 5802, July
285              2010, (http://www.ieft.org/rfc/rfc5802.txt)
286

AUTHORS

288       Pat Thoyts
289

BUGS, IDEAS, FEEDBACK

291       This document, and the package it describes, will  undoubtedly  contain
292       bugs  and  other  problems.  Please report such in the category sasl of
293       the  Tcllib  Trackers  [http://core.tcl.tk/tcllib/reportlist].   Please
294       also  report any ideas for enhancements you may have for either package
295       and/or documentation.
296
297       When proposing code changes, please provide unified diffs, i.e the out‐
298       put of diff -u.
299
300       Note  further  that  attachments  are  strongly  preferred over inlined
301       patches. Attachments can be made by going  to  the  Edit  form  of  the
302       ticket  immediately  after  its  creation, and then using the left-most
303       button in the secondary navigation bar.
304

KEYWORDS

306       SASL, authentication
307

CATEGORY

309       Networking
310
312       Copyright (c) 2005-2006, Pat Thoyts <patthoyts@users.sourceforge.net>
313
314
315
316
317tcllib                               1.3.3                             SASL(n)
Impressum