doc/misc/sasl.texi

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