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