doc/misc/sasl.texi

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