summaryrefslogtreecommitdiff
path: root/doc/misc/sasl.texi
blob: dcb25ec805afca6380fdf700787b0f8a9d9c9526 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
\input texinfo                  @c -*-texinfo-*-

@include gnus-overrides.texi

@setfilename ../../info/sasl

@set VERSION 0.2
@settitle Emacs SASL Library @value{VERSION}

@copying
This file describes the Emacs SASL library, version @value{VERSION}.

Copyright @copyright{} 2000, 2004--2013 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 or
any later version published by the Free Software Foundation; with no
Invariant Sections, with the Front-Cover texts being ``A GNU Manual,''
and with the Back-Cover Texts as in (a) below.  A copy of the license
is included in the section entitled ``GNU Free Documentation License''.

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.''
@end quotation
@end copying

@dircategory Emacs network features
@direntry
* SASL: (sasl).                 The Emacs SASL library.
@end direntry


@titlepage
@ifset WEBHACKDEVEL
@title Emacs SASL Library @value{VERSION} (DEVELOPMENT VERSION)
@end ifset
@ifclear WEBHACKDEVEL
@title Emacs SASL Library @value{VERSION}
@end ifclear

@author by Daiki Ueno
@page

@vskip 0pt plus 1filll
@insertcopying
@end titlepage


@node Top
@top Emacs SASL

SASL is a common interface to share several authentication mechanisms between
applications using different protocols.

@ifnottex
@insertcopying
@end ifnottex

@menu
* Overview::                    What Emacs SASL library is.
* How to use::                  Adding authentication support to your applications.
* Data types::
* Back end drivers::             Writing your own drivers.
* GNU Free Documentation License::  The license for this documentation.
* Index::
* Function Index::
* Variable Index::
@end menu

@node Overview
@chapter Overview

@sc{sasl} is short for @dfn{Simple Authentication and Security Layer}.
This standard is documented in RFC2222.  It provides a simple method for
adding authentication support to various application protocols.

The toplevel interface of this library is inspired by Java @sc{sasl}
Application Program Interface.  It defines an abstraction over a series
of authentication mechanism drivers (@ref{Back end drivers}).

Back end drivers are designed to be close as possible to the
authentication mechanism.  You can access the additional configuration
information anywhere from the implementation.

@node How to use
@chapter How to use

(Not yet written).

To use Emacs SASL library, please evaluate following expression at the
beginning of your application program.

@lisp
(require 'sasl)
@end lisp

If you want to check existence of sasl.el at runtime, instead you
can list autoload settings for functions you want.

@node Data types
@chapter Data types

There are three data types to be used for carrying a negotiated
security layer---a mechanism, a client parameter and an authentication
step.

@menu
* Mechanisms::
* Clients::
* Steps::
@end menu

@node Mechanisms
@section Mechanisms

A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl}
authentication mechanism driver.

@defvar sasl-mechanisms
A list of mechanism names.
@end defvar

@defun sasl-find-mechanism mechanisms

Retrieve an appropriate mechanism.
This function compares @var{mechanisms} and @code{sasl-mechanisms} then
returns appropriate @code{sasl-mechanism} object.

@example
(let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5")))
  (setq mechanism (sasl-find-mechanism server-supported-mechanisms)))
@end example

@end defun

@defun sasl-mechanism-name mechanism
Return name of mechanism, a string.
@end defun

If you want to write an authentication mechanism driver (@ref{Back end
drivers}), use @code{sasl-make-mechanism} and modify
@code{sasl-mechanisms} and @code{sasl-mechanism-alist} correctly.

@defun sasl-make-mechanism name steps
Allocate a @code{sasl-mechanism} object.
This function takes two parameters---name of the mechanism, and a list
of authentication functions.

@example
(defconst sasl-anonymous-steps
  '(identity                            ;no initial response
    sasl-anonymous-response))

(put 'sasl-anonymous 'sasl-mechanism
     (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps))
@end example

@end defun

@node Clients
@section Clients

A client (@code{sasl-client} object) initialized with four
parameters---a mechanism, a user name, name of the service and name of
the server.

@defun sasl-make-client mechanism name service server
Prepare a @code{sasl-client} object.
@end defun

@defun sasl-client-mechanism client
Return the mechanism (@code{sasl-mechanism} object) of client.
@end defun

@defun sasl-client-name client
Return the authorization name of client, a string.
@end defun

@defun sasl-client-service client
Return the service name of client, a string.
@end defun

@defun sasl-client-server client
Return the server name of client, a string.
@end defun

If you want to specify additional configuration properties, please use
@code{sasl-client-set-property}.

@defun sasl-client-set-property client property value
Add the given property/value to client.
@end defun

@defun sasl-client-property client property
Return the value of the property of client.
@end defun

@defun sasl-client-set-properties client plist
Destructively set the properties of client.
The second argument is the new property list.
@end defun

@defun sasl-client-properties client
Return the whole property list of client configuration.
@end defun

@node Steps
@section Steps

A step (@code{sasl-step} object) is an abstraction of authentication
``step'' which holds the response value and the next entry point for the
authentication process (the latter is not accessible).

@defun sasl-step-data step
Return the data which @var{step} holds, a string.
@end defun

@defun sasl-step-set-data step data
Store @var{data} string to @var{step}.
@end defun

To get the initial response, you should call the function
@code{sasl-next-step} with the second argument @code{nil}.

@example
(setq name (sasl-mechanism-name mechanism))
@end example

At this point we could send the command which starts a SASL
authentication protocol exchange.  For example,

@example
(process-send-string
 process
 (if (sasl-step-data step)              ;initial response
     (format "AUTH %s %s\r\n" name (base64-encode-string (sasl-step-data step) t))
   (format "AUTH %s\r\n" name)))
@end example

To go on with the authentication process, all you have to do is call
@code{sasl-next-step} consecutively.

@defun sasl-next-step client step
Perform the authentication step.
At the first time @var{step} should be set to @code{nil}.
@end defun

@node Back end drivers
@chapter Back end drivers

(Not yet written).

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi

@node Index
@unnumbered Index
@printindex cp

@node Function Index
@unnumbered Function Index
@printindex fn

@node Variable Index
@unnumbered Variable Index
@printindex vr

@summarycontents
@contents
@bye

@c End: