sasl.texi

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