1[comment {-*- tcl -*- doctools manpage}] 2[manpage_begin SASL n 1.3.0] 3[copyright {2005-2006, Pat Thoyts <patthoyts@users.sourceforge.net>}] 4[moddesc {Simple Authentication and Security Layer (SASL)}] 5[titledesc {Implementation of SASL mechanisms for Tcl}] 6[category Networking] 7[require Tcl 8.2] 8[require SASL [opt 1.3]] 9[description] 10[para] 11 12The Simple Authentication and Security Layer (SASL) is a framework 13for providing authentication and authorization to comunications 14protocols. The SASL framework is structured to permit negotiation 15among a number of authentication mechanisms. SASL may be used in 16SMTP, IMAP and HTTP authentication. It is also in use in XMPP, LDAP 17and BEEP. See [sectref MECHANISMS] for the set of available SASL 18mechanisms provided with tcllib. 19 20[para] 21 22The SASL framework operates using a simple multi-step challenge 23response mechanism. All the mechanisms work the same way although the 24number of steps may vary. In this implementation a callback procedure 25must be provided from which the SASL framework will obtain users 26details. See [sectref "CALLBACK PROCEDURE"] for details of this 27procedure. 28 29[section {COMMANDS}] 30 31[list_begin definitions] 32 33[call [cmd "::SASL::new"] [arg "option value [opt ...]"]] 34 35Contruct a new SASL context. See [sectref OPTIONS] for details of the 36possible options to this command. A context token is required for most 37of the SASL procedures. 38 39[call [cmd "::SASL::configure"] [arg "option value"] [opt [arg "..."]]] 40 41Modify and inspect the SASL context option. See [sectref OPTIONS] for 42further details. 43 44[call [cmd "::SASL::step"] [arg "context"] [arg "challenge"] [opt [arg "..."]]] 45 46This is the core procedure for using the SASL framework. The 47[cmd step] procedure should be called until it returns 0. Each step takes a 48server challenge string and the response is calculated and stored in 49the context. Each mechanism may require one or more steps. For some 50steps there may be no server challenge required in which case an empty 51string should be provided for this parameter. All mechanisms should accept 52an initial empty challenge. 53 54[call [cmd "::SASL::response"] [arg "context"]] 55 56Returns the next response string that should be sent to the server. 57 58[call [cmd "::SASL::reset"] [arg "context"]] 59 60Re-initialize the SASL context. Discards any internal state and 61permits the token to be reused. 62 63[call [cmd "::SASL::cleanup"] [arg "context"]] 64 65Release all resources associated with the SASL context. The context 66token may not be used again after this procedure has been called. 67 68[call [cmd "::SASL::mechanisms"] [opt [arg "type"]] [opt [arg "minimum"]]] 69 70Returns a list of all the available SASL mechanisms. The list is 71sorted by the mechanism preference value (see [cmd register]) with the 72preferred mechanisms and the head of the list. Any mechanism with a 73preference value less than the[arg minimum] (which defaults to 0) is removed 74from the returned list. This permits a security threshold to be set. Mechanisms 75with a preference less that 25 transmit authentication are particularly 76susceptible to eavesdropping and should not be provided unless a secure 77channel is in use (eg: tls). 78[para] 79The [arg type] parameter 80may be one of [arg client] or [arg server] and defaults to [arg client]. 81Only mechanisms that have an implementation matching the [arg type] are 82returned (this permits servers to correctly declare support only for 83mechanisms that actually provide a server implementation). 84 85[call [cmd "::SASL::register"] [arg "mechanism"] [arg "preference"] \ 86 [arg "clientproc"] [opt [arg "serverproc"]]] 87 88New mechanisms can be added to the package by registering the 89mechanism name and the implementing procedures. The server procedure 90is optional. The preference value is an integer that is used to order 91the list returned by the [cmd mechanisms] command. Higher values 92indicate a preferred mechanism. If the mechanism is already registered 93then the recorded values are updated. 94 95[list_end] 96 97 98 99[section "OPTIONS"] 100 101[list_begin definitions] 102 103[def [option "-callback"]] 104 105Specify a command to be evaluated when the SASL mechanism requires 106information about the user. The command is called with the current 107SASL context and a name specifying the information desired. See 108[sectref EXAMPLES]. 109 110[def [option "-mechanism"]] 111 112Set the SASL mechanism to be used. See [cmd mechanisms] for a list of 113supported authentication mechanisms. 114 115[def [option "-service"]] 116 117Set the service type for this context. Some mechanisms may make use of 118this parameter (eg DIGEST-MD5, GSSAPI and Kerberos). If not set it 119defaults to an empty string. If the [option -type] is set to 'server' 120then this option should be set to a valid service identity. Some 121examples of valid service names are smtp, ldap, beep and xmpp. 122 123[def [option "-server"]] 124 125This option is used to set the server name used in SASL challenges 126when operating as a SASL server. 127 128[def [option "-type"]] 129 130The context type may be one of 'client' or 'server'. The default is to 131operate as a client application and respond to server 132challenges. Mechanisms may be written to support server-side SASL and 133setting this option will cause each [cmd step] to issue the next 134challenge. A new context must be created for each incoming client 135connection when in server mode. 136 137[list_end] 138 139 140 141[section "CALLBACK PROCEDURE"] 142 143When the SASL framework requires any user details it will call the 144procedure provided when the context was created with an argument that 145specfies the item of information required. 146[para] 147In all cases a single response string should be returned. 148 149[list_begin definitions] 150 151[def "login"] 152 153The callback procedure should return the users authorization identity. 154Return an empty string unless this is to be different to the authentication 155identity. Read [lb]1[rb] for a discussion about the specific meaning of 156authorization and authentication identities within SASL. 157 158[def "username"] 159 160The callback procedure should return the users authentication identity. 161Read [lb]1[rb] for a discussion about the specific meaning of 162authorization and authentication identities within SASL. 163 164[def "password"] 165 166The callback procedure should return the password that matches the 167authentication identity as used within the current realm. 168[para] 169For server mechanisms the password callback should always be called with 170the authentication identity and the realm as the first two parameters. 171 172[def "realm"] 173 174Some SASL mechanisms use realms to partition authentication identities. 175The realm string is protocol dependent and is often the current DNS 176domain or in the case of the NTLM mechanism it is the Windows NT domain name. 177 178[def "hostname"] 179 180Returns the client host name - typically [lb]info host[rb]. 181 182[list_end] 183 184 185 186[section "MECHANISMS"] 187 188[list_begin definitions] 189 190[def "ANONYMOUS"] 191 192As used in FTP this mechanism only passes an email address for 193authentication. The ANONYMOUS mechanism is specified in [lb]2[rb]. 194 195[def "PLAIN"] 196 197This is the simplest mechanism. The users authentication details are 198transmitted in plain text. This mechanism should not be provided 199unless an encrypted link is in use - typically after SSL or TLS has 200been negotiated. 201 202[def "LOGIN"] 203 204The LOGIN [lb]1[rb] mechanism transmits the users details with base64 205encoding. This is no more secure than PLAIN and likewise should not be 206used without a secure link. 207 208[def "CRAM-MD5"] 209 210This mechanism avoids sending the users password over the network in 211plain text by hashing the password with a server provided random value 212(known as a nonce). A disadvantage of this mechanism is that the 213server must maintain a database of plaintext passwords for 214comparison. CRAM-MD5 was defined in [lb]4[rb]. 215 216[def "DIGEST-MD5"] 217 218This mechanism improves upon the CRAM-MD5 mechanism by avoiding the 219need for the server to store plaintext passwords. With digest 220authentication the server needs to store the MD5 digest of the users 221password which helps to make the system more secure. As in CRAM-MD5 222the password is hashed with a server nonce and other data before being 223transmitted across the network. Specified in [lb]3[rb]. 224 225[def "OTP"] 226 227OTP is the One-Time Password system described in RFC 2289 [lb]6[rb]. 228This mechanism is secure against replay attacks and also avoids storing 229password or password equivalents on the server. Only a digest of a seed 230and a passphrase is ever transmitted across the network. Requires the 231[package otp] package from tcllib and one or more of the cryptographic 232digest packages (md5 or sha-1 are the most commonly used). 233 234[def "NTLM"] 235 236This is a proprietary protocol developed by Microsoft [lb]5[rb] and is 237in common use for authenticating users in a Windows network 238environment. NTLM uses DES encryption and MD4 digests of the users 239password to authenticate a connection. Certain weaknesses have been 240found in NTLM and thus there are a number of versions of the protocol. 241As this mechanism has additional dependencies it is made available as 242a separate sub-package. To enable this mechanism your application must 243load the SASL::NTLM package. 244 245[def "X-GOOGLE-TOKEN"] 246 247This is a proprietary protocol developed by Google and used for 248authenticating users for the Google Talk service. This mechanism makes 249a pair of HTTP requests over an SSL channel and so this mechanism 250depends upon the availability of the tls and http packages. To enable 251this mechanism your application must load the SASL::XGoogleToken package. 252In addition you are recommended to make use of the autoproxy package to 253handle HTTP proxies reasonably transparently. 254 255[list_end] 256 257 258 259[section "EXAMPLES"] 260 261See the examples subdirectory for more complete samples using SASL 262with network protocols. The following should give an idea how the SASL 263commands are to be used. In reality this should be event 264driven. Each time the [cmd step] command is called, the last server 265response should be provided as the command argument so that the SASL 266mechanism can take appropriate action. 267 268[example { 269proc ClientCallback {context command args} { 270 switch -exact -- $command { 271 login { return "" } 272 username { return $::tcl_platform(user) } 273 password { return "SecRet" } 274 realm { return "" } 275 hostname { return [info host] } 276 default { return -code error unxpected } 277 } 278} 279 280proc Demo {{mech PLAIN}} { 281 set ctx [SASL::new -mechanism $mech -callback ClientCallback] 282 set challenge "" 283 while {1} { 284 set more_steps [SASL::step $ctx challenge] 285 puts "Send '[SASL::response $ctx]'" 286 puts "Read server response into challenge var" 287 if {!$more_steps} {break} 288 } 289 SASL::cleanup $ctx 290} 291}] 292 293[section "REFERENCES"] 294 295[list_begin enumerated] 296 297[enum] 298 Myers, J. "Simple Authentication and Security Layer (SASL)", 299 RFC 2222, October 1997. 300 ([uri http://www.ietf.org/rfc/rfc2222.txt]) 301 302[enum] 303 Newman, C. "Anonymous SASL Mechanism", 304 RFC 2245, November 1997. 305 ([uri http://www.ietf.org/rfc/rfc2245.txt]) 306 307[enum] 308 Leach, P., Newman, C. "Using Digest Authentication as a SASL 309 Mechanism", RFC 2831, May 2000, 310 ([uri http://www.ietf.org/rfc/rfc2831.txt]) 311 312[enum] 313 Klensin, J., Catoe, R. and Krumviede, P., 314 "IMAP/POP AUTHorize Extension for Simple Challenge/Response" 315 RFC 2195, September 1997. 316 ([uri http://www.ietf.org/rfc/rfc2195.txt]) 317 318[enum] 319 No official specification is available. However, 320 [uri http://davenport.sourceforge.net/ntlm.html] provides a good 321 description. 322 323[enum] 324 Haller, N. et al., "A One-Time Password System", 325 RFC 2289, February 1998, 326 ([uri http://www.ieft.org/rfc/rfc2289.txt]) 327 328[list_end] 329 330[section AUTHORS] 331Pat Thoyts 332 333[section {BUGS, IDEAS, FEEDBACK}] 334 335This document, and the package it describes, will undoubtedly contain 336bugs and other problems. 337 338Please report such in the category [emph sasl] of the 339[uri {http://sourceforge.net/tracker/?group_id=12883} {Tcllib SF Trackers}]. 340 341Please also report any ideas for enhancements you may have for either 342package and/or documentation. 343 344 345[keywords SASL authentication] 346[manpage_end] 347