1 \input texinfo @c -*-texinfo-*-
8 * SASL: (sasl). The Emacs SASL library.
11 @settitle Emacs SASL Library @value{VERSION}
14 This file describes the Emacs SASL library.
16 Copyright (C) 2000 Daiki Ueno.
18 Permission is granted to copy, distribute and/or modify this document
19 under the terms of the GNU Free Documentation License, Version 1.1 or
20 any later version published by the Free Software Foundation; with no
21 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
22 Texts. A copy of the license is included in the section entitled "GNU
23 Free Documentation License".
29 @title Emacs SASL Library
34 @vskip 0pt plus 1filll
35 Copyright @copyright{} 2000 Daiki Ueno.
37 Permission is granted to copy, distribute and/or modify this document
38 under the terms of the GNU Free Documentation License, Version 1.1 or
39 any later version published by the Free Software Foundation; with no
40 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
41 Texts. A copy of the license is included in the section entitled "GNU
42 Free Documentation License".
50 This manual describes the Emacs SASL library.
52 A common interface to share several authentication mechanisms between
53 applications using different protocols.
56 * Overview:: What Emacs SASL library is.
57 * How to use:: Adding authentication support to your applications.
59 * Backend drivers:: Writing your own drivers.
68 @sc{sasl} is short for @dfn{Simple Authentication and Security Layer}.
69 This standard is documented in RFC2222. It provides a simple method for
70 adding authentication support to various application protocols.
72 The toplevel interface of this library is inspired by Java @sc{sasl}
73 Application Program Interface. It defines an abstraction over a series
74 of authentication mechanism drivers (@ref{Backend drivers}).
76 Backend drivers are designed to be close as possible to the
77 authentication mechanism. You can access the additional configuration
78 information anywhere from the implementation.
85 To use Emacs SASL library, please evaluate following expression at the
86 beginning of your application program.
92 If you want to check existence of sasl.el at runtime, instead you
93 can list autoload settings for functions you want.
98 There are three data types to be used for carrying a negotiated
99 security layer---a mechanism, a client parameter and an authentication
111 A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl}
112 authentication mechanism driver.
114 @defvar sasl-mechanisms
115 A list of mechanism names.
118 @defun sasl-find-mechanism mechanisms
120 Retrieve an apropriate mechanism.
121 This function compares MECHANISMS and @code{sasl-mechanisms} then
122 returns apropriate @code{sasl-mechanism} object.
125 (let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5")))
126 (setq mechanism (sasl-find-mechanism server-supported-mechanisms)))
131 @defun sasl-mechanism-name mechanism
132 Return name of mechanism, a string.
135 If you want to write an authentication mechanism driver (@ref{Backend
136 drivers}), use @code{sasl-make-mechanism} and modify
137 @code{sasl-mechanisms} and @code{sasl-mechanism-alist} correctly.
139 @defun sasl-make-mechanism name steps
140 Allocate a @code{sasl-mechanism} object.
141 This function takes two parameters---name of the mechanism, and a list
142 of authentication functions.
145 (defconst sasl-anonymous-steps
146 '(identity ;no initial response
147 sasl-anonymous-response))
149 (put 'sasl-anonymous 'sasl-mechanism
150 (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps))
158 A client (@code{sasl-client} object) initialized with four
159 parameters---a mechanism, a user name, name of the service and name of
162 @defun sasl-make-client mechanism name service server
163 Prepare a @code{sasl-client} object.
166 @defun sasl-client-mechanism client
167 Return the mechanism (@code{sasl-mechanism} object) of client.
170 @defun sasl-client-name client
171 Return the authorization name of client, a string.
174 @defun sasl-client-service client
175 Return the service name of client, a string.
178 @defun sasl-client-server client
179 Return the server name of client, a string.
182 If you want to specify additional configuration properties, please use
183 @code{sasl-client-set-property}.
185 @defun sasl-client-set-property client property value
186 Add the given property/value to client.
189 @defun sasl-client-property client property
190 Return the value of the property of client.
193 @defun sasl-client-set-properties client plist
194 Destructively set the properties of client.
195 The second argument is the new property list.
198 @defun sasl-client-properties client
199 Return the whole property list of client configuration.
205 A step (@code{sasl-step} object) is an abstraction of authentication
206 "step" which holds the response value and the next entry point for the
207 authentication process (the latter is not accessible).
209 @defun sasl-step-data step
210 Return the data which STEP holds, a string.
213 @defun sasl-step-set-data step data
214 Store DATA string to STEP.
217 To get the initial response, you should call the function
218 @code{sasl-next-step} with the second argument nil.
221 (setq name (sasl-mechanism-name mechanism))
224 At this point we could send the command which starts a SASL
225 authentication protocol exchange. For example,
230 (if (sasl-step-data step) ;initial response
231 (format "AUTH %s %s\r\n" name (base64-encode-string (sasl-step-data step) t))
232 (format "AUTH %s\r\n" name)))
235 To go on with the authentication process, all you have to do is call
236 @code{sasl-next-step} consecutively.
238 @defun sasl-next-step client step
239 Perform the authentication step.
240 At the first time STEP should be set to nil.
243 @node Backend drivers
244 @chapter Backend drivers
253 @chapter Function Index
257 @chapter Variable Index