Commit | Line | Data |
---|---|---|
01c52d31 MB |
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 | ||
9c6b35b2 GM |
17 | Copyright @copyright{} 2000, 2004, 2005, 2006, 2007, 2008 |
18 | Free Software Foundation, Inc. | |
01c52d31 MB |
19 | |
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". | |
26 | @end ifinfo | |
27 | ||
28 | @tex | |
29 | ||
30 | @titlepage | |
31 | @title Emacs SASL Library | |
32 | ||
33 | @author by Daiki Ueno | |
34 | @page | |
35 | ||
36 | @vskip 0pt plus 1filll | |
37 | Copyright @copyright{} 2000 Daiki Ueno. | |
38 | ||
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". | |
45 | @end titlepage | |
46 | @page | |
47 | ||
48 | @end tex | |
49 | ||
50 | @node Top | |
51 | @top Emacs SASL | |
52 | This manual describes the Emacs SASL library. | |
53 | ||
54 | A common interface to share several authentication mechanisms between | |
55 | applications using different protocols. | |
56 | ||
57 | @menu | |
58 | * Overview:: What Emacs SASL library is. | |
59 | * How to use:: Adding authentication support to your applications. | |
60 | * Data types:: | |
61 | * Back end drivers:: Writing your own drivers. | |
62 | * Index:: | |
63 | * Function Index:: | |
64 | * Variable Index:: | |
65 | @end menu | |
66 | ||
67 | @node Overview | |
68 | @chapter Overview | |
69 | ||
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. | |
73 | ||
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}). | |
77 | ||
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. | |
81 | ||
82 | @node How to use | |
83 | @chapter How to use | |
84 | ||
85 | (Not yet written). | |
86 | ||
87 | To use Emacs SASL library, please evaluate following expression at the | |
88 | beginning of your application program. | |
89 | ||
90 | @lisp | |
91 | (require 'sasl) | |
92 | @end lisp | |
93 | ||
94 | If you want to check existence of sasl.el at runtime, instead you | |
95 | can list autoload settings for functions you want. | |
96 | ||
97 | @node Data types | |
98 | @chapter Data types | |
99 | ||
100 | There are three data types to be used for carrying a negotiated | |
101 | security layer---a mechanism, a client parameter and an authentication | |
102 | step. | |
103 | ||
104 | @menu | |
105 | * Mechanisms:: | |
106 | * Clients:: | |
107 | * Steps:: | |
108 | @end menu | |
109 | ||
110 | @node Mechanisms | |
111 | @section Mechanisms | |
112 | ||
113 | A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl} | |
114 | authentication mechanism driver. | |
115 | ||
116 | @defvar sasl-mechanisms | |
117 | A list of mechanism names. | |
118 | @end defvar | |
119 | ||
120 | @defun sasl-find-mechanism mechanisms | |
121 | ||
122 | Retrieve an apropriate mechanism. | |
123 | This function compares @var{mechanisms} and @code{sasl-mechanisms} then | |
124 | returns apropriate @code{sasl-mechanism} object. | |
125 | ||
126 | @example | |
127 | (let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5"))) | |
128 | (setq mechanism (sasl-find-mechanism server-supported-mechanisms))) | |
129 | @end example | |
130 | ||
131 | @end defun | |
132 | ||
133 | @defun sasl-mechanism-name mechanism | |
134 | Return name of mechanism, a string. | |
135 | @end defun | |
136 | ||
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. | |
140 | ||
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. | |
145 | ||
146 | @example | |
147 | (defconst sasl-anonymous-steps | |
148 | '(identity ;no initial response | |
149 | sasl-anonymous-response)) | |
150 | ||
151 | (put 'sasl-anonymous 'sasl-mechanism | |
152 | (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps)) | |
153 | @end example | |
154 | ||
155 | @end defun | |
156 | ||
157 | @node Clients | |
158 | @section Clients | |
159 | ||
160 | A client (@code{sasl-client} object) initialized with four | |
161 | parameters---a mechanism, a user name, name of the service and name of | |
162 | the server. | |
163 | ||
164 | @defun sasl-make-client mechanism name service server | |
165 | Prepare a @code{sasl-client} object. | |
166 | @end defun | |
167 | ||
168 | @defun sasl-client-mechanism client | |
169 | Return the mechanism (@code{sasl-mechanism} object) of client. | |
170 | @end defun | |
171 | ||
172 | @defun sasl-client-name client | |
173 | Return the authorization name of client, a string. | |
174 | @end defun | |
175 | ||
176 | @defun sasl-client-service client | |
177 | Return the service name of client, a string. | |
178 | @end defun | |
179 | ||
180 | @defun sasl-client-server client | |
181 | Return the server name of client, a string. | |
182 | @end defun | |
183 | ||
184 | If you want to specify additional configuration properties, please use | |
185 | @code{sasl-client-set-property}. | |
186 | ||
187 | @defun sasl-client-set-property client property value | |
188 | Add the given property/value to client. | |
189 | @end defun | |
190 | ||
191 | @defun sasl-client-property client property | |
192 | Return the value of the property of client. | |
193 | @end defun | |
194 | ||
195 | @defun sasl-client-set-properties client plist | |
196 | Destructively set the properties of client. | |
197 | The second argument is the new property list. | |
198 | @end defun | |
199 | ||
200 | @defun sasl-client-properties client | |
201 | Return the whole property list of client configuration. | |
202 | @end defun | |
203 | ||
204 | @node Steps | |
205 | @section Steps | |
206 | ||
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). | |
210 | ||
211 | @defun sasl-step-data step | |
212 | Return the data which @var{step} holds, a string. | |
213 | @end defun | |
214 | ||
215 | @defun sasl-step-set-data step data | |
216 | Store @var{data} string to @var{step}. | |
217 | @end defun | |
218 | ||
219 | To get the initial response, you should call the function | |
220 | @code{sasl-next-step} with the second argument @code{nil}. | |
221 | ||
222 | @example | |
223 | (setq name (sasl-mechanism-name mechanism)) | |
224 | @end example | |
225 | ||
226 | At this point we could send the command which starts a SASL | |
227 | authentication protocol exchange. For example, | |
228 | ||
229 | @example | |
230 | (process-send-string | |
231 | process | |
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))) | |
235 | @end example | |
236 | ||
237 | To go on with the authentication process, all you have to do is call | |
238 | @code{sasl-next-step} consecutively. | |
239 | ||
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}. | |
243 | @end defun | |
244 | ||
245 | @node Back end drivers | |
246 | @chapter Back end drivers | |
247 | ||
248 | (Not yet written). | |
249 | ||
250 | @node Index | |
251 | @chapter Index | |
252 | @printindex cp | |
253 | ||
254 | @node Function Index | |
255 | @chapter Function Index | |
256 | @printindex fn | |
257 | ||
258 | @node Variable Index | |
259 | @chapter Variable Index | |
260 | @printindex vr | |
261 | ||
262 | @summarycontents | |
263 | @contents | |
264 | @bye | |
265 | ||
266 | @c End: | |
267 | ||
268 | @ignore | |
269 | arch-tag: dc9650be-a953-40bf-bc55-24fe5f19d875 | |
270 | @end ignore |