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