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