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