doc/misc/sasl.texi

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