1SASL(n) Simple Authentication and Security Layer (SASL) SASL(n)
2______________________________________________________________________________
6
8 SASL - Implementation of SASL mechanisms for Tcl
9
11 package require Tcl 8.2
12 package require SASL ?1.3.3?
14 ::SASL::new option value ?...?
16 ::SASL::configure option value ?...?
18 ::SASL::step context challenge ?...?
20 ::SASL::response context
22 ::SASL::reset context
24 ::SASL::cleanup context
26 ::SASL::mechanisms ?type? ?minimum?
28 ::SASL::register mechanism preference clientproc ?serverproc?
30______________________________________________________________________________
32
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 The SASL framework operates using a simple multi-step challenge re‐
42 sponse 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 de‐
45 tails. See CALLBACK PROCEDURE for details of this procedure.
46
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 ::SASL::configure option value ?...?
54 Modify and inspect the SASL context option. See OPTIONS for fur‐
55 ther details.
56 ::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 re‐
63 quired in which case an empty string should be provided for this
64 parameter. All mechanisms should accept an initial empty chal‐
65 lenge.
66 ::SASL::response context
68 Returns the next response string that should be sent to the
69 server.
70 ::SASL::reset context
72 Re-initialize the SASL context. Discards any internal state and
73 permits the token to be reused.
74 ::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 ::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 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 im‐
95 plementation).
96 ::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
106 -callback
107 Specify a command to be evaluated when the SASL mechanism re‐
108 quires 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 -mechanism
113 Set the SASL mechanism to be used. See mechanisms for a list of
114 supported authentication mechanisms.
115 -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 -server
125 This option is used to set the server name used in SASL chal‐
126 lenges when operating as a SASL server.
127 -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
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 In all cases a single response string should be returned.
141 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 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 password
154 The callback procedure should return the password that matches
155 the authentication identity as used within the current realm.
156 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 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 hostname
167 Returns the client host name - typically [info host].
168
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 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 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 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 DIGEST-MD5
191 This mechanism improves upon the CRAM-MD5 mechanism by avoiding
192 the need for the server to store plaintext passwords. With di‐
193 gest authentication the server needs to store the MD5 digest of
194 the users password which helps to make the system more secure.
195 As in CRAM-MD5 the password is hashed with a server nonce and
196 other data before being transmitted across the network. Speci‐
197 fied in [3].
198 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 NTLM This is a proprietary protocol developed by Microsoft [5] and is
208 in common use for authenticating users in a Windows network en‐
209 vironment. NTLM uses DES encryption and MD4 digests of the users
210 password to authenticate a connection. Certain weaknesses have
211 been found in NTLM and thus there are a number of versions of
212 the protocol. As this mechanism has additional dependencies it
213 is made available as a separate sub-package. To enable this
214 mechanism your application must load the SASL::NTLM package.
215 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 SCRAM This is a protocol specified in RFC 5802 [7]. To enable this
227 mechanism your application must load the SASL::SCRAM package.
228
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 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 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
263 [1] Myers, J. "Simple Authentication and Security Layer (SASL)", RFC
264 2222, October 1997. (http://www.ietf.org/rfc/rfc2222.txt)
265 [2] Newman, C. "Anonymous SASL Mechanism", RFC 2245, November 1997.
267 (http://www.ietf.org/rfc/rfc2245.txt)
268 [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 [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 [5] No official specification is available. However, http://daven‐
278 port.sourceforge.net/ntlm.html provides a good description.
279 [6] Haller, N. et al., "A One-Time Password System", RFC 2289, Feb‐
281 ruary 1998, (http://www.ieft.org/rfc/rfc2289.txt)
282 [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
288 Pat Thoyts
289
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 When proposing code changes, please provide unified diffs, i.e the out‐
298 put of diff -u.
299 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
306 SASL, authentication
307
309 Networking
310
312 Copyright (c) 2005-2006, Pat Thoyts <patthoyts@users.sourceforge.net>
313tcllib 1.3.3 SASL(n)