texi/sasl.texi

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