Mercurial > emacs
comparison doc/misc/sasl.texi @ 85712:a3c27999decb
Update Gnus to No Gnus 0.7 from the Gnus CVS trunk
Revision: emacs@sv.gnu.org/emacs--devo--0--patch-911
author | Miles Bader <miles@gnu.org> |
---|---|
date | Sun, 28 Oct 2007 09:18:39 +0000 |
parents | |
children | bec74d38ca1e |
comparison
equal
deleted
inserted
replaced
85711:b6f5dc84b2e1 | 85712:a3c27999decb |
---|---|
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 @copyright{} 2004, 2005, 2006 Free Software Foundation, Inc. | |
18 Copyright @copyright{} 2000 Daiki Ueno. | |
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 |