doc/misc/sasl.texi

   1 \input texinfo                  @c -*-texinfo-*-
   2
   3 @include gnus-overrides.texi
   4
   5 @setfilename ../../info/sasl
   6
   7 @set VERSION 0.2
   8 @settitle Emacs SASL Library @value{VERSION}
   9
  10 @documentencoding UTF-8
  11
  12 @copying
  13 This file describes the Emacs SASL library, version @value{VERSION}.
  14
  15 Copyright @copyright{} 2000, 2004--2014 Free Software Foundation, Inc.
  16
  17 @quotation
  18 Permission is granted to copy, distribute and/or modify this document
  19 under the terms of the GNU Free Documentation License, Version 1.3 or
  20 any later version published by the Free Software Foundation; with no
  21 Invariant Sections, with the Front-Cover Texts being ``A GNU Manual,''
  22 and with the Back-Cover Texts as in (a) below.  A copy of the license
  23 is included in the section entitled ``GNU Free Documentation License''.
  24
  25 (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
  26 modify this GNU manual.''
  27 @end quotation
  28 @end copying
  29
  30 @dircategory Emacs network features
  31 @direntry
  32 * SASL: (sasl).                 The Emacs SASL library.
  33 @end direntry
  34
  35
  36 @titlepage
  37 @ifset WEBHACKDEVEL
  38 @title Emacs SASL Library @value{VERSION} (DEVELOPMENT VERSION)
  39 @end ifset
  40 @ifclear WEBHACKDEVEL
  41 @title Emacs SASL Library @value{VERSION}
  42 @end ifclear
  43
  44 @author by Daiki Ueno
  45 @page
  46
  47 @vskip 0pt plus 1filll
  48 @insertcopying
  49 @end titlepage
  50
  51
  52 @node Top
  53 @top Emacs SASL
  54
  55 SASL is a common interface to share several authentication mechanisms between
  56 applications using different protocols.
  57
  58 @ifnottex
  59 @insertcopying
  60 @end ifnottex
  61
  62 @menu
  63 * Overview::                    What Emacs SASL library is.
  64 * How to use::                  Adding authentication support to your applications.
  65 * Data types::
  66 * Back end drivers::             Writing your own drivers.
  67 * GNU Free Documentation License::  The license for this documentation.
  68 * Index::
  69 * Function Index::
  70 * Variable Index::
  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
 111 * Mechanisms::
 112 * Clients::
 113 * Steps::
 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
 128 Retrieve an appropriate mechanism.
 129 This function compares @var{mechanisms} and @code{sasl-mechanisms} then
 130 returns appropriate @code{sasl-mechanism} object.
 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
 154   '(identity                            ;no initial response
 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
 238  (if (sasl-step-data step)              ;initial response
 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
 256 @node GNU Free Documentation License
 257 @appendix GNU Free Documentation License
 258 @include doclicense.texi
 259
 260 @node Index
 261 @unnumbered Index
 262 @printindex cp
 263
 264 @node Function Index
 265 @unnumbered Function Index
 266 @printindex fn
 267
 268 @node Variable Index
 269 @unnumbered Variable Index
 270 @printindex vr
 271
 272 @summarycontents
 273 @contents
 274 @bye
 275
 276 @c End: