sasl.texi

   1 \input texinfo                  @c -*-texinfo-*-
   2
   3 @setfilename sasl.info
   4
   5 @set VERSION 0.2
   6
   7 @direntry
   8 * SASL: (sasl).   The Emacs SASL library.
   9 @end direntry
  10
  11 @settitle Emacs SASL Library @value{VERSION}
  12
  13 @node Top
  14 @top Emacs SASL
  15 This manual describes the Emacs SASL library.
  16
  17 A common interface to share several authentication mechanisms between
  18 applications using different protocols.
  19
  20 @menu
  21 * Overview::                    What Emacs SASL library is.
  22 * How to use::                  Adding authentication support to your applications.
  23 * Data types::
  24 * Backend drivers::             Writing your own drivers.
  25 * Index::
  26 * Function Index::
  27 * Variable Index::
  28 @end menu
  29
  30 @node Overview
  31 @chapter Overview
  32
  33 @sc{sasl} is short for @dfn{Simple Authentication and Security Layer}.
  34 This standard is documented in RFC2222.  It provides a simple method for
  35 adding authentication support to various application protocols.
  36
  37 The toplevel interface of this library is inspired by Java @sc{sasl}
  38 Application Program Interface.  It defines an abstraction over a series
  39 of authentication mechanism drivers (@ref{Backend drivers}).
  40
  41 Backend drivers are designed to be close as possible to the
  42 authentication mechanism.  You can access the additional configuration
  43 information anywhere from the implementation.
  44
  45 @node How to use
  46 @chapter How to use
  47
  48 (Not yet written).
  49
  50 To use Emacs SASL library, please evaluate following expression at the
  51 beginning of your application program.
  52
  53 @lisp
  54 (require 'sasl)
  55 @end lisp
  56
  57 If you want to check existence of sasl.el at runtime, instead you
  58 can list autoload settings for functions you want.
  59
  60 @node Data types
  61 @chapter Data types
  62
  63 There are three data types to be used for carrying a negotiated
  64 security layer---a mechanism, a client parameter and an authentication
  65 step.
  66
  67 @menu
  68 * Mechanisms::
  69 * Clients::
  70 * Steps::
  71 @end menu
  72
  73 @node Mechanisms
  74 @section Mechanisms
  75
  76 A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl}
  77 authentication mechanism driver.
  78
  79 @defvar sasl-mechanisms
  80 A list of mechanism names.
  81 @end defvar
  82
  83 @defun sasl-find-mechanism mechanisms
  84
  85 Retrieve an apropriate mechanism.
  86 This function compares MECHANISMS and @code{sasl-mechanisms} then
  87 returns apropriate @code{sasl-mechanism} object.
  88
  89 @example
  90 (let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5")))
  91   (setq mechanism (sasl-find-mechanism server-supported-mechanisms)))
  92 @end example
  93
  94 @end defun
  95
  96 @defun sasl-mechanism-name mechanism
  97 Return name of mechanism, a string.
  98 @end defun
  99
 100 If you want to write an authentication mechanism driver (@ref{Backend
 101 drivers}), use @code{sasl-make-mechanism} and modify
 102 @code{sasl-mechanisms} and @code{sasl-mechanism-alist} correctly.
 103
 104 @defun sasl-make-mechanism name steps
 105 Allocate a @code{sasl-mechanism} object.
 106 This function takes two parameters---name of the mechanism, and a list
 107 of authentication functions.
 108
 109 @example
 110 (defconst sasl-anonymous-steps
 111   '(identity                            ;no initial response
 112     sasl-anonymous-response))
 113
 114 (put 'sasl-anonymous 'sasl-mechanism
 115      (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps))
 116 @end example
 117
 118 @end defun
 119
 120 @node Clients
 121 @section Clients
 122
 123 A client (@code{sasl-client} object) initialized with four
 124 parameters---a mechanism, a user name, name of the service and name of
 125 the server.
 126
 127 @defun sasl-make-client mechanism name service server
 128 Prepare a @code{sasl-client} object.
 129 @end defun
 130
 131 @defun sasl-client-mechanism client
 132 Return the mechanism (@code{sasl-mechanism} object) of client.
 133 @end defun
 134
 135 @defun sasl-client-name client
 136 Return the authorization name of client, a string.
 137 @end defun
 138
 139 @defun sasl-client-service client
 140 Return the service name of client, a string.
 141 @end defun
 142
 143 @defun sasl-client-server client
 144 Return the server name of client, a string.
 145 @end defun
 146
 147 If you want to specify additional configuration properties, please use
 148 @code{sasl-client-set-property}.
 149
 150 @defun sasl-client-set-property client property value
 151 Add the given property/value to client.
 152 @end defun
 153
 154 @defun sasl-client-property client property
 155 Return the value of the property of client.
 156 @end defun
 157
 158 @defun sasl-client-set-properties client plist
 159 Destructively set the properties of client.
 160 The second argument is the new property list.
 161 @end defun
 162
 163 @defun sasl-client-properties client
 164 Return the whole property list of client configuration.
 165 @end defun
 166
 167 @node Steps
 168 @section Steps
 169
 170 A step (@code{sasl-step} object) is an abstraction of authentication
 171 "step" which holds the response value and the next entry point for the
 172 authentication process (the latter is not accessible).
 173
 174 @defun sasl-step-data step
 175 Return the data which STEP holds, a string.
 176 @end defun
 177
 178 @defun sasl-step-set-data step data
 179 Store DATA string to STEP.
 180 @end defun
 181
 182 To get the initial response, you should call the function
 183 @code{sasl-next-step} with the second argument nil.
 184
 185 @example
 186 (setq name (sasl-mechanism-name mechanism))
 187 @end example
 188
 189 At this point we could send the command which starts a SASL
 190 authentication protocol exchange.  For example,
 191
 192 @example
 193 (process-send-string
 194  process
 195  (if (sasl-step-data step)              ;initial response
 196      (format "AUTH %s %s\r\n" name (base64-encode-string (sasl-step-data step) t))
 197    (format "AUTH %s\r\n" name)))
 198 @end example
 199
 200 To go on with the authentication process, all you have to do is call
 201 @code{sasl-next-step} consecutively.
 202
 203 @defun sasl-next-step client step
 204 Perform the authentication step.
 205 At the first time STEP should be set to nil.
 206 @end defun
 207
 208 @node Backend drivers
 209 @chapter Backend drivers
 210
 211 (Not yet written).
 212
 213 @node Index
 214 @chapter Index
 215 @printindex cp
 216
 217 @node Function Index
 218 @chapter Function Index
 219 @printindex fn
 220
 221 @node Variable Index
 222 @chapter Variable Index
 223 @printindex vr
 224
 225 @summarycontents
 226 @contents
 227 @bye
 228
 229 @c End: