1 \input texinfo @c -*-texinfo-*-
9 * SASL: (sasl). The Emacs SASL library.
12 @settitle Emacs SASL Library @value{VERSION}
15 This file describes the Emacs SASL library.
17 Copyright @copyright{} 2000, 2004, 2005, 2006, 2007, 2008
18 Free Software Foundation, Inc.
20 Permission is granted to copy, distribute and/or modify this document
21 under the terms of the GNU Free Documentation License, Version 1.2 or
22 any later version published by the Free Software Foundation; with no
23 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
24 Texts. A copy of the license is included in the section entitled "GNU
25 Free Documentation License".
31 @title Emacs SASL Library
36 @vskip 0pt plus 1filll
37 Copyright @copyright{} 2000 Daiki Ueno.
39 Permission is granted to copy, distribute and/or modify this document
40 under the terms of the GNU Free Documentation License, Version 1.2 or
41 any later version published by the Free Software Foundation; with no
42 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
43 Texts. A copy of the license is included in the section entitled "GNU
44 Free Documentation License".
52 This manual describes the Emacs SASL library.
54 A common interface to share several authentication mechanisms between
55 applications using different protocols.
58 * Overview:: What Emacs SASL library is.
59 * How to use:: Adding authentication support to your applications.
61 * Back end drivers:: Writing your own drivers.
70 @sc{sasl} is short for @dfn{Simple Authentication and Security Layer}.
71 This standard is documented in RFC2222. It provides a simple method for
72 adding authentication support to various application protocols.
74 The toplevel interface of this library is inspired by Java @sc{sasl}
75 Application Program Interface. It defines an abstraction over a series
76 of authentication mechanism drivers (@ref{Back end drivers}).
78 Back end drivers are designed to be close as possible to the
79 authentication mechanism. You can access the additional configuration
80 information anywhere from the implementation.
87 To use Emacs SASL library, please evaluate following expression at the
88 beginning of your application program.
94 If you want to check existence of sasl.el at runtime, instead you
95 can list autoload settings for functions you want.
100 There are three data types to be used for carrying a negotiated
101 security layer---a mechanism, a client parameter and an authentication
113 A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl}
114 authentication mechanism driver.
116 @defvar sasl-mechanisms
117 A list of mechanism names.
120 @defun sasl-find-mechanism mechanisms
122 Retrieve an apropriate mechanism.
123 This function compares @var{mechanisms} and @code{sasl-mechanisms} then
124 returns apropriate @code{sasl-mechanism} object.
127 (let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5")))
128 (setq mechanism (sasl-find-mechanism server-supported-mechanisms)))
133 @defun sasl-mechanism-name mechanism
134 Return name of mechanism, a string.
137 If you want to write an authentication mechanism driver (@ref{Back end
138 drivers}), use @code{sasl-make-mechanism} and modify
139 @code{sasl-mechanisms} and @code{sasl-mechanism-alist} correctly.
141 @defun sasl-make-mechanism name steps
142 Allocate a @code{sasl-mechanism} object.
143 This function takes two parameters---name of the mechanism, and a list
144 of authentication functions.
147 (defconst sasl-anonymous-steps
148 '(identity ;no initial response
149 sasl-anonymous-response))
151 (put 'sasl-anonymous 'sasl-mechanism
152 (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps))
160 A client (@code{sasl-client} object) initialized with four
161 parameters---a mechanism, a user name, name of the service and name of
164 @defun sasl-make-client mechanism name service server
165 Prepare a @code{sasl-client} object.
168 @defun sasl-client-mechanism client
169 Return the mechanism (@code{sasl-mechanism} object) of client.
172 @defun sasl-client-name client
173 Return the authorization name of client, a string.
176 @defun sasl-client-service client
177 Return the service name of client, a string.
180 @defun sasl-client-server client
181 Return the server name of client, a string.
184 If you want to specify additional configuration properties, please use
185 @code{sasl-client-set-property}.
187 @defun sasl-client-set-property client property value
188 Add the given property/value to client.
191 @defun sasl-client-property client property
192 Return the value of the property of client.
195 @defun sasl-client-set-properties client plist
196 Destructively set the properties of client.
197 The second argument is the new property list.
200 @defun sasl-client-properties client
201 Return the whole property list of client configuration.
207 A step (@code{sasl-step} object) is an abstraction of authentication
208 ``step'' which holds the response value and the next entry point for the
209 authentication process (the latter is not accessible).
211 @defun sasl-step-data step
212 Return the data which @var{step} holds, a string.
215 @defun sasl-step-set-data step data
216 Store @var{data} string to @var{step}.
219 To get the initial response, you should call the function
220 @code{sasl-next-step} with the second argument @code{nil}.
223 (setq name (sasl-mechanism-name mechanism))
226 At this point we could send the command which starts a SASL
227 authentication protocol exchange. For example,
232 (if (sasl-step-data step) ;initial response
233 (format "AUTH %s %s\r\n" name (base64-encode-string (sasl-step-data step) t))
234 (format "AUTH %s\r\n" name)))
237 To go on with the authentication process, all you have to do is call
238 @code{sasl-next-step} consecutively.
240 @defun sasl-next-step client step
241 Perform the authentication step.
242 At the first time @var{step} should be set to @code{nil}.
245 @node Back end drivers
246 @chapter Back end drivers
255 @chapter Function Index
259 @chapter Variable Index
269 arch-tag: dc9650be-a953-40bf-bc55-24fe5f19d875