git.chise.org Git - elisp/gnus.git-/blob - texi/sasl.texi

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