Merge changes made in Emacs trunk

[gnus] / texi / sasl.texi

\input texinfo                  @c -*-texinfo-*-

@include gnus-overrides.texi

@setfilename sasl.info

@set VERSION 0.2
@settitle Emacs SASL Library @value{VERSION}

@copying
This file describes the Emacs SASL library, version @value{VERSION}.

Copyright @copyright{} 2000, 2004--2013 Free Software Foundation, Inc.

@quotation
Permission is granted to copy, distribute and/or modify this document
under the terms of the GNU Free Documentation License, Version 1.3 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''.

(a) The FSF's Back-Cover Text is: ``You have the freedom to copy and
modify this GNU manual.''
@end quotation
@end copying

@dircategory Emacs network features
@direntry
* SASL: (sasl).                 The Emacs SASL library.
@end direntry


@titlepage
@ifset WEBHACKDEVEL
@title Emacs SASL Library @value{VERSION} (DEVELOPMENT VERSION)
@end ifset
@ifclear WEBHACKDEVEL
@title Emacs SASL Library @value{VERSION}
@end ifclear

@author by Daiki Ueno
@page

@vskip 0pt plus 1filll
@insertcopying
@end titlepage


@node Top
@top Emacs SASL

SASL is a common interface to share several authentication mechanisms between
applications using different protocols.

@ifnottex
@insertcopying
@end ifnottex

@menu
* Overview::                    What Emacs SASL library is.
* How to use::                  Adding authentication support to your applications.
* Data types::
* Back end drivers::             Writing your own drivers.
* GNU Free Documentation License::  The license for this documentation.
* 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{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.

@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 appropriate mechanism.
This function compares @var{mechanisms} and @code{sasl-mechanisms} then
returns appropriate @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{Back end
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 @var{step} holds, a string.
@end defun

@defun sasl-step-set-data step data
Store @var{data} string to @var{step}.
@end defun

To get the initial response, you should call the function
@code{sasl-next-step} with the second argument @code{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 @var{step} should be set to @code{nil}.
@end defun

@node Back end drivers
@chapter Back end drivers

(Not yet written).

@node GNU Free Documentation License
@appendix GNU Free Documentation License
@include doclicense.texi

@node Index
@unnumbered Index
@printindex cp

@node Function Index
@unnumbered Function Index
@printindex fn

@node Variable Index
@unnumbered Variable Index
@printindex vr

@summarycontents
@contents
@bye

@c End: