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