sasl-ja.texi

   1 \input texinfo                  @c -*-texinfo-*-
   2
   3 @setfilename sasl-ja
   4
   5 @set VERSION 0.2
   6
   7 @dircategory Emacs
   8 @direntry
   9 * SASL: (sasl-ja).              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 (C) 2000 Daiki Ueno.
  18
  19 Permission is granted to copy, distribute and/or modify this document
  20 under the terms of the GNU Free Documentation License, Version 1.1 or
  21 any later version published by the Free Software Foundation; with no
  22 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  23 Texts.  A copy of the license is included in the section entitled "GNU
  24 Free Documentation License".
  25
  26 \e$B$3$NJ8=q$r!"%U%j!<%=%U%H%&%'%":bCDH/9T$N\e(B GNU \e$B%U%j!<J8=qMxMQ5vBz7@Ls=q\e(B
  27 \e$BBh\e(B 1.1 \e$BHG$^$?$O$=$l0J9_$NHG$,Dj$a$k>r7o$N2<$GJ#@=!"G[I[!"$"$k$$$OJQ99$9\e(B
  28 \e$B$k$3$H$r5v2D$7$^$9!#JQ99IT2DItJ,!"I=I=;f%F%-%9%H$*$h$SN"I=;f%F%-%9%H$O;X\e(B
  29 \e$BDj$7$^$;$s!#$3$NMxMQ5vBz7@Ls=q$NJ#<L$O!V\e(BGNU \e$B%U%j!<J8=qMxMQ5vBz7@Ls=q!W$H\e(B
  30 \e$B$$$&>O$K4^$^$l$F$$$^$9!#\e(B
  31 @end ifinfo
  32
  33 @tex
  34
  35 @titlepage
  36 @title Emacs SASL Library
  37
  38 @author by Daiki Ueno
  39 @page
  40
  41 @vskip 0pt plus 1filll
  42 Copyright @copyright{} 2000 Daiki Ueno.
  43
  44 Permission is granted to copy, distribute and/or modify this document
  45 under the terms of the GNU Free Documentation License, Version 1.1 or
  46 any later version published by the Free Software Foundation; with no
  47 Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
  48 Texts.  A copy of the license is included in the section entitled "GNU
  49 Free Documentation License".
  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 apropriate mechanism.
 128 This function compares @var{mechanisms} and @code{sasl-mechanisms} then
 129 returns apropriate @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 Local Variables:
 272 @c coding: iso-2022-7bit
 273 @c fill-column: 72
 274 @c mode: texinfo
 275 @c use-kuten-for-period: t
 276 @c use-touten-for-comma: t
 277 @c End: