* sasl.texi: Texinfo markup fixes. From Jesper Harder
[elisp/flim.git] / sasl.texi
1 \input texinfo                  @c -*-texinfo-*-
2
3 @setfilename sasl.info
4
5 @set VERSION 0.2
6
7 @dircategory Emacs
8 @direntry
9 * SASL: (sasl).   The Emacs SASL library.
10 @end direntry
11
12 @settitle Emacs SASL Library @value{VERSION}
13
14 @ifinfo
15 This file describes the Emacs SASL library.
16
17 Copyright (C) 2000 Daiki Ueno.
18
19 Permission is granted to copy, distribute and/or modify this document
20 under the terms of the GNU Free Documentation License, Version 1.1 or
21 any later version published by the Free Software Foundation; with no
22 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
23 Texts.  A copy of the license is included in the section entitled "GNU
24 Free Documentation License".
25 @end ifinfo
26
27 @tex
28
29 @titlepage
30 @title Emacs SASL Library
31
32 @author by Daiki Ueno
33 @page
34
35 @vskip 0pt plus 1filll
36 Copyright @copyright{} 2000 Daiki Ueno.
37
38 Permission is granted to copy, distribute and/or modify this document
39 under the terms of the GNU Free Documentation License, Version 1.1 or
40 any later version published by the Free Software Foundation; with no
41 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
42 Texts.  A copy of the license is included in the section entitled "GNU
43 Free Documentation License".
44 @end titlepage
45 @page
46
47 @end tex
48
49 @node Top
50 @top Emacs SASL
51 This manual describes the Emacs SASL library.
52
53 A common interface to share several authentication mechanisms between
54 applications using different protocols.
55
56 @menu
57 * Overview::                    What Emacs SASL library is.
58 * How to use::                  Adding authentication support to your applications.
59 * Data types::                  
60 * Backend drivers::             Writing your own drivers.
61 * Index::                       
62 * Function Index::              
63 * Variable Index::              
64 @end menu
65
66 @node Overview
67 @chapter Overview
68
69 @sc{sasl} is short for @dfn{Simple Authentication and Security Layer}.
70 This standard is documented in RFC2222.  It provides a simple method for
71 adding authentication support to various application protocols.
72
73 The toplevel interface of this library is inspired by Java @sc{sasl}
74 Application Program Interface.  It defines an abstraction over a series
75 of authentication mechanism drivers (@ref{Backend drivers}).
76
77 Backend drivers are designed to be close as possible to the
78 authentication mechanism.  You can access the additional configuration
79 information anywhere from the implementation.
80
81 @node How to use
82 @chapter How to use
83
84 (Not yet written).
85
86 To use Emacs SASL library, please evaluate following expression at the
87 beginning of your application program.
88
89 @lisp
90 (require 'sasl)
91 @end lisp
92
93 If you want to check existence of sasl.el at runtime, instead you
94 can list autoload settings for functions you want.
95
96 @node Data types
97 @chapter Data types
98
99 There are three data types to be used for carrying a negotiated
100 security layer---a mechanism, a client parameter and an authentication
101 step.
102
103 @menu
104 * Mechanisms::                  
105 * Clients::                     
106 * Steps::                       
107 @end menu
108
109 @node Mechanisms
110 @section Mechanisms
111
112 A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl}
113 authentication mechanism driver.
114
115 @defvar sasl-mechanisms
116 A list of mechanism names.
117 @end defvar
118
119 @defun sasl-find-mechanism mechanisms
120
121 Retrieve an apropriate mechanism.
122 This function compares @var{mechanisms} and @code{sasl-mechanisms} then
123 returns apropriate @code{sasl-mechanism} object.
124
125 @example
126 (let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5")))
127   (setq mechanism (sasl-find-mechanism server-supported-mechanisms)))
128 @end example
129
130 @end defun
131
132 @defun sasl-mechanism-name mechanism
133 Return name of mechanism, a string.
134 @end defun
135
136 If you want to write an authentication mechanism driver (@ref{Backend
137 drivers}), use @code{sasl-make-mechanism} and modify
138 @code{sasl-mechanisms} and @code{sasl-mechanism-alist} correctly.
139
140 @defun sasl-make-mechanism name steps
141 Allocate a @code{sasl-mechanism} object.
142 This function takes two parameters---name of the mechanism, and a list
143 of authentication functions.
144
145 @example
146 (defconst sasl-anonymous-steps
147   '(identity                            ;no initial response
148     sasl-anonymous-response))
149
150 (put 'sasl-anonymous 'sasl-mechanism
151      (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps))
152 @end example
153
154 @end defun
155
156 @node Clients
157 @section Clients
158
159 A client (@code{sasl-client} object) initialized with four
160 parameters---a mechanism, a user name, name of the service and name of
161 the server.
162
163 @defun sasl-make-client mechanism name service server
164 Prepare a @code{sasl-client} object.
165 @end defun
166
167 @defun sasl-client-mechanism client
168 Return the mechanism (@code{sasl-mechanism} object) of client.
169 @end defun
170
171 @defun sasl-client-name client
172 Return the authorization name of client, a string.
173 @end defun
174
175 @defun sasl-client-service client
176 Return the service name of client, a string.
177 @end defun
178
179 @defun sasl-client-server client
180 Return the server name of client, a string.
181 @end defun
182
183 If you want to specify additional configuration properties, please use
184 @code{sasl-client-set-property}.
185
186 @defun sasl-client-set-property client property value
187 Add the given property/value to client.
188 @end defun
189
190 @defun sasl-client-property client property
191 Return the value of the property of client.
192 @end defun
193
194 @defun sasl-client-set-properties client plist
195 Destructively set the properties of client.
196 The second argument is the new property list.
197 @end defun
198
199 @defun sasl-client-properties client
200 Return the whole property list of client configuration.
201 @end defun
202
203 @node Steps
204 @section Steps
205
206 A step (@code{sasl-step} object) is an abstraction of authentication
207 ``step'' which holds the response value and the next entry point for the
208 authentication process (the latter is not accessible).
209
210 @defun sasl-step-data step
211 Return the data which @var{step} holds, a string.
212 @end defun
213
214 @defun sasl-step-set-data step data
215 Store @var{data} string to @var{step}.
216 @end defun
217
218 To get the initial response, you should call the function
219 @code{sasl-next-step} with the second argument @code{nil}.
220
221 @example
222 (setq name (sasl-mechanism-name mechanism))
223 @end example
224
225 At this point we could send the command which starts a SASL
226 authentication protocol exchange.  For example,
227
228 @example
229 (process-send-string
230  process
231  (if (sasl-step-data step)              ;initial response
232      (format "AUTH %s %s\r\n" name (base64-encode-string (sasl-step-data step) t))
233    (format "AUTH %s\r\n" name)))
234 @end example
235
236 To go on with the authentication process, all you have to do is call
237 @code{sasl-next-step} consecutively.
238
239 @defun sasl-next-step client step
240 Perform the authentication step.
241 At the first time @var{step} should be set to @code{nil}.
242 @end defun
243
244 @node Backend drivers
245 @chapter Backend drivers
246
247 (Not yet written).
248
249 @node Index
250 @chapter Index
251 @printindex cp
252
253 @node Function Index
254 @chapter Function Index
255 @printindex fn
256
257 @node Variable Index
258 @chapter Variable Index
259 @printindex vr
260
261 @summarycontents
262 @contents
263 @bye
264
265 @c End: