[Emacs-diffs] Changes to doc/misc/sasl.texi

[Miles Bader]

CVSROOT:        /cvsroot/emacs
Module name:    emacs
Changes by:     Miles Bader <miles>     07/10/28 09:18:40

Index: doc/misc/sasl.texi
===================================================================
RCS file: doc/misc/sasl.texi
diff -N doc/misc/sasl.texi
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ doc/misc/sasl.texi  28 Oct 2007 09:18:37 -0000      1.1
@@ -0,0 +1,270 @@
+\input texinfo                  @c -*-texinfo-*-
+
address@hidden sasl.info
+
address@hidden VERSION 0.2
+
address@hidden Emacs
address@hidden
+* SASL: (sasl).   The Emacs SASL library.
address@hidden direntry
+
address@hidden Emacs SASL Library @value{VERSION}
+
address@hidden
+This file describes the Emacs SASL library.
+
+Copyright @copyright{} 2004, 2005, 2006 Free Software Foundation, Inc.
+Copyright @copyright{} 2000 Daiki Ueno.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the section entitled "GNU
+Free Documentation License".
address@hidden ifinfo
+
address@hidden
+
address@hidden
address@hidden Emacs SASL Library
+
address@hidden by Daiki Ueno
address@hidden
+
address@hidden 0pt plus 1filll
+Copyright @copyright{} 2000 Daiki Ueno.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with no Front-Cover Texts, and with no Back-Cover
+Texts.  A copy of the license is included in the section entitled "GNU
+Free Documentation License".
address@hidden titlepage
address@hidden
+
address@hidden tex
+
address@hidden Top
address@hidden Emacs SASL
+This manual describes the Emacs SASL library.
+
+A common interface to share several authentication mechanisms between
+applications using different protocols.
+
address@hidden
+* Overview::                    What Emacs SASL library is.
+* How to use::                  Adding authentication support to your 
applications.
+* Data types::                  
+* Back end drivers::             Writing your own drivers.
+* Index::                       
+* Function Index::              
+* Variable Index::              
address@hidden menu
+
address@hidden Overview
address@hidden Overview
+
address@hidden is short for @dfn{Simple Authentication and Security Layer}.
+This standard is documented in RFC2222.  It provides a simple method for
+adding authentication support to various application protocols.
+
+The toplevel interface of this library is inspired by Java @sc{sasl}
+Application Program Interface.  It defines an abstraction over a series
+of authentication mechanism drivers (@ref{Back end drivers}).
+
+Back end drivers are designed to be close as possible to the
+authentication mechanism.  You can access the additional configuration
+information anywhere from the implementation.
+
address@hidden How to use
address@hidden How to use
+
+(Not yet written).
+
+To use Emacs SASL library, please evaluate following expression at the
+beginning of your application program.
+
address@hidden
+(require 'sasl)
address@hidden lisp
+
+If you want to check existence of sasl.el at runtime, instead you
+can list autoload settings for functions you want.
+
address@hidden Data types
address@hidden Data types
+
+There are three data types to be used for carrying a negotiated
+security layer---a mechanism, a client parameter and an authentication
+step.
+
address@hidden
+* Mechanisms::                  
+* Clients::                     
+* Steps::                       
address@hidden menu
+
address@hidden Mechanisms
address@hidden Mechanisms
+
+A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl}
+authentication mechanism driver.
+
address@hidden sasl-mechanisms
+A list of mechanism names.
address@hidden defvar
+
address@hidden sasl-find-mechanism mechanisms
+
+Retrieve an apropriate mechanism.
+This function compares @var{mechanisms} and @code{sasl-mechanisms} then
+returns apropriate @code{sasl-mechanism} object.
+
address@hidden
+(let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5")))
+  (setq mechanism (sasl-find-mechanism server-supported-mechanisms)))
address@hidden example
+
address@hidden defun
+
address@hidden sasl-mechanism-name mechanism
+Return name of mechanism, a string.
address@hidden defun
+
+If you want to write an authentication mechanism driver (@ref{Back end
+drivers}), use @code{sasl-make-mechanism} and modify
address@hidden and @code{sasl-mechanism-alist} correctly.
+
address@hidden sasl-make-mechanism name steps
+Allocate a @code{sasl-mechanism} object.
+This function takes two parameters---name of the mechanism, and a list
+of authentication functions.
+
address@hidden
+(defconst sasl-anonymous-steps
+  '(identity                           ;no initial response
+    sasl-anonymous-response))
+
+(put 'sasl-anonymous 'sasl-mechanism
+     (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps))
address@hidden example
+
address@hidden defun
+
address@hidden Clients
address@hidden Clients
+
+A client (@code{sasl-client} object) initialized with four
+parameters---a mechanism, a user name, name of the service and name of
+the server.
+
address@hidden sasl-make-client mechanism name service server
+Prepare a @code{sasl-client} object.
address@hidden defun
+
address@hidden sasl-client-mechanism client
+Return the mechanism (@code{sasl-mechanism} object) of client.
address@hidden defun
+
address@hidden sasl-client-name client
+Return the authorization name of client, a string.
address@hidden defun
+
address@hidden sasl-client-service client
+Return the service name of client, a string.
address@hidden defun
+
address@hidden sasl-client-server client
+Return the server name of client, a string.
address@hidden defun
+
+If you want to specify additional configuration properties, please use
address@hidden
+
address@hidden sasl-client-set-property client property value
+Add the given property/value to client.
address@hidden defun
+
address@hidden sasl-client-property client property
+Return the value of the property of client.
address@hidden defun
+
address@hidden sasl-client-set-properties client plist
+Destructively set the properties of client.
+The second argument is the new property list.
address@hidden defun
+
address@hidden sasl-client-properties client
+Return the whole property list of client configuration.
address@hidden defun
+
address@hidden Steps
address@hidden Steps
+
+A step (@code{sasl-step} object) is an abstraction of authentication
+``step'' which holds the response value and the next entry point for the
+authentication process (the latter is not accessible).
+
address@hidden sasl-step-data step
+Return the data which @var{step} holds, a string.
address@hidden defun
+
address@hidden sasl-step-set-data step data
+Store @var{data} string to @var{step}.
address@hidden defun
+
+To get the initial response, you should call the function
address@hidden with the second argument @code{nil}.
+
address@hidden
+(setq name (sasl-mechanism-name mechanism))
address@hidden example
+
+At this point we could send the command which starts a SASL
+authentication protocol exchange.  For example,
+
address@hidden
+(process-send-string
+ process
+ (if (sasl-step-data step)             ;initial response
+     (format "AUTH %s %s\r\n" name (base64-encode-string (sasl-step-data step) 
t))
+   (format "AUTH %s\r\n" name)))
address@hidden example
+
+To go on with the authentication process, all you have to do is call
address@hidden consecutively.
+
address@hidden sasl-next-step client step
+Perform the authentication step.
+At the first time @var{step} should be set to @code{nil}.
address@hidden defun
+
address@hidden Back end drivers
address@hidden Back end drivers
+
+(Not yet written).
+
address@hidden Index
address@hidden Index
address@hidden cp
+
address@hidden Function Index
address@hidden Function Index
address@hidden fn
+
address@hidden Variable Index
address@hidden Variable Index
address@hidden vr
+
address@hidden
address@hidden
address@hidden
+
address@hidden End:
+
address@hidden
+   arch-tag: dc9650be-a953-40bf-bc55-24fe5f19d875
address@hidden ignore