sasl.texi

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}

@ifinfo This file describes the Emacs SASL library.

Copyright (C) 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.1 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". @end ifinfo

@tex

@titlepage @title Emacs SASL Library

@author by Daiki Ueno @page

@vskip 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.1 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". @end titlepage @page

@end tex

@node Top @top Emacs SASL This manual describes the Emacs SASL library.

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

@menu * Overview:: What Emacs SASL library is. * How to use:: Adding authentication support to your applications. * Data types:: * Backend drivers:: Writing your own 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 (@ref{Backend drivers}).

Backend drivers are designed to be close as possible to the authentication mechanism. You can access the additional configuration information anywhere from the implementation.

@node How to use @chapter How to use

(Not yet written).

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

@lisp (require 'sasl) @end lisp

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

@node Data types @chapter 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.

@menu * Mechanisms:: * Clients:: * Steps:: @end menu

@node Mechanisms @section Mechanisms

A mechanism (@code{sasl-mechanism} object) is a schema of the @sc{sasl} authentication mechanism driver.

@defvar sasl-mechanisms A list of mechanism names. @end defvar

@defun sasl-find-mechanism mechanisms

Retrieve an apropriate mechanism. This function compares MECHANISMS and @code{sasl-mechanisms} then returns apropriate @code{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 a @code{sasl-mechanism} object. 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 @section 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 @code{sasl-client} object. @end defun

@defun sasl-client-mechanism client Return the mechanism (@code{sasl-mechanism} object) 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 is the new property list. @end defun

@defun sasl-client-properties client Return the whole property list of client configuration. @end defun

@node Steps @section 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 %s0 name (base64-encode-string (sasl-step-data step) t))
(format "AUTH %s0 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: