mirror of
https://git.savannah.gnu.org/git/emacs.git
synced 2024-12-11 09:20:51 +00:00
276 lines
6.9 KiB
Plaintext
276 lines
6.9 KiB
Plaintext
\input texinfo @c -*-texinfo-*-
|
|
|
|
@include gnus-overrides.texi
|
|
|
|
@setfilename ../../info/sasl.info
|
|
|
|
@set VERSION 0.2
|
|
@settitle Emacs SASL Library @value{VERSION}
|
|
@include docstyle.texi
|
|
|
|
@copying
|
|
This file describes the Emacs SASL library, version @value{VERSION}.
|
|
|
|
Copyright @copyright{} 2000, 2004--2017 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:
|