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