This file describes the Emacs SASL library.

Copyright © 2000, 2004, 2005, 2006, 2007, 2008 Free Software Foundation, Inc.

     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 the Front-Cover texts being ``A GNU Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the license is included in the section entitled ``GNU Free Documentation License'' in the Emacs manual.

     (a) The FSF's Back-Cover Text is: ``You have the freedom to copy and modify this GNU manual.  Buying copies from the FSF supports it in developing GNU and promoting software freedom.''

     This document is part of a collection distributed under the GNU Free Documentation License.  If you want to distribute this document separately from the collection, you can do so by adding a copy of the license to the document, as described in section 6 of the license.

Emacs SASL
**********

This manual describes the Emacs SASL library.

A common interface to share several authentication mechanisms between applications using different protocols.

Overview
********

SASL is short for 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 SASL Application Program Interface.  It defines an abstraction over a series of authentication mechanism drivers (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.

How to use
**********

(Not yet written).

To use Emacs SASL library, please evaluate following expression at the beginning of your application program.

     (require 'sasl)

If you want to check existence of sasl.el at runtime, instead you can list autoload settings for functions you want.

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.

Mechanisms
==========

A mechanism (sasl-mechanism object) is a schema of the SASL authentication mechanism driver.

 -- Variable: sasl-mechanisms
     A list of mechanism names.

 -- Function: sasl-find-mechanism mechanisms

     Retrieve an apropriate mechanism. This function compares MECHANISMS and sasl-mechanisms then returns apropriate sasl-mechanism object.

          (let ((sasl-mechanisms '("CRAM-MD5" "DIGEST-MD5")))
            (setq mechanism (sasl-find-mechanism server-supported-mechanisms)))

 -- Function: sasl-mechanism-name mechanism
     Return name of mechanism, a string.

If you want to write an authentication mechanism driver (Back end drivers), use sasl-make-mechanism and modify sasl-mechanisms and sasl-mechanism-alist correctly.

 -- Function: sasl-make-mechanism name steps
     Allocate a sasl-mechanism object. This function takes two parameters---name of the mechanism, and a list of authentication functions.

          (defconst sasl-anonymous-steps
            '(identity				;no initial response
              sasl-anonymous-response))

          (put 'sasl-anonymous 'sasl-mechanism
               (sasl-make-mechanism "ANONYMOUS" sasl-anonymous-steps))

Clients
=======

A client (sasl-client object) initialized with four parameters---a mechanism, a user name, name of the service and name of the server.

 -- Function: sasl-make-client mechanism name service server
     Prepare a sasl-client object.

 -- Function: sasl-client-mechanism client
     Return the mechanism (sasl-mechanism object) of client.

 -- Function: sasl-client-name client
     Return the authorization name of client, a string.

 -- Function: sasl-client-service client
     Return the service name of client, a string.

 -- Function: sasl-client-server client
     Return the server name of client, a string.

If you want to specify additional configuration properties, please use sasl-client-set-property.

 -- Function: sasl-client-set-property client property value
     Add the given property/value to client.

 -- Function: sasl-client-property client property
     Return the value of the property of client.

 -- Function: sasl-client-set-properties client plist
     Destructively set the properties of client. The second argument is the new property list.

 -- Function: sasl-client-properties client
     Return the whole property list of client configuration.

Steps
=====

A step (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).

 -- Function: sasl-step-data step
     Return the data which STEP holds, a string.

 -- Function: sasl-step-set-data step data
     Store DATA string to STEP.

To get the initial response, you should call the function sasl-next-step with the second argument nil.

     (setq name (sasl-mechanism-name mechanism))

At this point we could send the command which starts a SASL authentication protocol exchange.  For 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)))

To go on with the authentication process, all you have to do is call sasl-next-step consecutively.

 -- Function: sasl-next-step client step
     Perform the authentication step. At the first time STEP should be set to nil.

Back end drivers
****************

(Not yet written).