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