* sasl.texi: New file.

diff --git a/ChangeLog b/ChangeLog
index 80caf0e..4c9ad08 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,5 +1,9 @@
 2000-11-05   Daiki Ueno  <ueno@unixuser.org>
 
+       * sasl.texi: New file.
+
+2000-11-05   Daiki Ueno  <ueno@unixuser.org>
+
        * sasl.el (sasl-step-data): New function.
        (sasl-step-set-data): New function.
 

diff --git a/sasl.texi b/sasl.texi
new file mode 100644 (file)
index 0000000..7ae5ce4
--- /dev/null
+++ b/sasl.texi
@@ -0,0 +1,203 @@
+\input texinfo                  @c -*-texinfo-*-
+
+@setfilename sasl.info
+
+@set VERSION 0.2
+
+@direntry
+* SASL: (sasl).   The Emacs SASL library.
+@end direntry
+
+@settitle Emacs SASL Library @value{VERSION}
+
+@node Top
+@top Emacs SASL
+This manual describes the Emacs SASL library.
+
+This library provides a common interface to share several authentication
+mechanisms between applications using different protocols.
+
+
+@menu
+* Overview::                    
+* Mechanisms::                  
+* Clients::                     
+* Steps::                       
+* Backend Drivers::             
+* Index::                       
+* Function Index::              
+* Variable Index::              
+@end menu
+
+@node Overview
+@chapter Overview
+
+@sc{sasl} 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.
+
+There are three data types to be used for carrying a negotiated
+security layer---a mechanism, a client parameter and an authentication
+step.
+
+@node Mechanisms
+@chapter Mechanisms
+
+A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl}
+authentication process.
+
+@defvar sasl-mechanisms
+A list of mechanism names.
+@end defvar
+
+@defun sasl-find-mechanism mechanisms
+
+Retrieve an apropriate authentication mechanism.
+This function compares MECHANISMS and @code{sasl-mechanisms} then
+returns apropriate @sc{sasl} mechanism object.
+
+@example
+(let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5")))
+  (setq mechanism (sasl-find-mechanism server-supported-mechanisms)))
+@end example
+
+@end defun
+
+@defun sasl-mechanism-name mechanism
+Return name of mechanism, a string.
+@end defun
+
+If you want to write an authentication mechanism driver (@ref{Backend
+Drivers}), use @code{sasl-make-mechanism} and modify
+@code{sasl-mechanisms} and @code{sasl-mechanism-alist} correctly.
+
+@defun sasl-make-mechanism name steps
+Allocate an authentication mechanism.
+This function takes two parameters---name of the mechanism, and a list
+of authentication functions.
+
+@example
+(defconst sasl-anonymous-steps
+  '(identity                           ;no initial response
+    sasl-anonymous-response))
+
+(put 'sasl-anonymous 'sasl-mechanism
+     (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps))
+@end example
+
+@end defun
+
+@node Clients
+@chapter 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.
+
+@defun sasl-make-client mechanism name service server
+Prepare a client parameter object.
+@end defun
+
+@defun sasl-client-mechanism client
+Return the authentication mechanism driver of CLIENT.
+@end defun
+
+@defun sasl-client-name client
+Return the authorization name of CLIENT, a string.
+@end defun
+
+@defun sasl-client-service client
+Return the service name of CLIENT, a string.
+@end defun
+
+@defun sasl-client-server client
+Return the server name of CLIENT, a string.
+@end defun
+
+If you want to specify additional configuration properties, please use
+@code{sasl-client-set-property}.
+
+@defun sasl-client-set-property client property value
+Add the given property/value to CLIENT.
+@end defun
+
+@defun sasl-client-property client property
+Return the value of the PROPERTY of CLIENT.
+@end defun
+
+@defun sasl-client-set-properties client plist
+Destructively set the properties of CLIENT.
+The second argument PLIST is the new property list.
+@end defun
+
+@defun sasl-client-properties client
+Return the whole property list of CLIENT configuration.
+@end defun
+
+@node Steps
+@chapter 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).
+
+@defun sasl-step-data step
+Return the data which STEP holds, a string.
+@end defun
+
+@defun sasl-step-set-data step data
+Store DATA string to STEP.
+@end defun
+
+To get the initial response, you should call the function
+@code{sasl-next-step} with the second argument nil.
+
+@example
+(setq name (sasl-mechanism-name mechanism))
+@end example
+
+At this point we could send the command which starts a SASL
+authentication protocol exchange.  For example,
+
+@example
+(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)))
+@end example
+
+To go on with the authentication process, all you have to do is call
+@code{sasl-next-step} consecutively.
+
+@defun sasl-next-step client step
+Perform the authentication step.
+At the first time STEP should be set to nil.
+@end defun
+
+@node Backend Drivers
+@chapter Backend Drivers
+
+(Not yet written).
+
+@node Index
+@chapter Index
+@printindex cp
+
+@node Function Index
+@chapter Function Index
+@printindex fn
+
+@node Variable Index
+@chapter Variable Index
+@printindex vr
+
+@summarycontents
+@contents
+@bye
+
+@c End: