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