<?xml version="1.0"?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN" 
          "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd">
<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
  <bookinfo>
    <title>GNU SASL API Reference Manual</title>
  </bookinfo>

  <chapter>
    <title>GNU SASL API Reference Manual</title>

    <para>
GNU SASL is an implementation of the Simple Authentication and
Security Layer framework and a few common SASL mechanisms.  SASL is
used by network servers (e.g., IMAP, SMTP) to request authentication
from clients, and in clients to authenticate against servers.
    </para>

    <para>
GNU SASL consists of a library (`libgsasl'), a command line utility
(`gsasl') to access the library from the shell, and a manual.  The
library includes support for the framework (with authentication
functions and application data privacy and integrity functions) and at
least partial support for the CRAM-MD5, EXTERNAL, GSSAPI, ANONYMOUS,
PLAIN, SECURID, DIGEST-MD5, LOGIN, and NTLM mechanisms.
    </para>

    <para>
The library is easily ported because it does not do network
communication by itself, but rather leaves it up to the calling
application.  The library is flexible with regards to the
authorization infrastructure used, as it utilize a callback into the
application to decide whether a user is authorized or not.
    </para>

    <para>
GNU SASL is developed for the GNU/Linux system, but runs on over 20
platforms including most major Unix platforms and Windows, and many
kind of devices including iPAQ handhelds and S/390 mainframes.
    </para>

    <para>
GNU SASL is written in pure ANSI C89 to be portable to embedded and
otherwise limited platforms.  The entire library, with full support
for ANONYMOUS, EXTERNAL, PLAIN, LOGIN and CRAM-MD5, and the front-end
that support client and server mode, and the IMAP and SMTP protocols,
fits in under 60kb on an Intel x86 platform, without any modifications
to the code.  (This figure was accurate as of version 0.0.13.)
    </para>

    <para>
The library is licensed under the GNU Lesser General Public License
version 2.1.  The command-line application (src/), examples
(examples/), self-test suite (tests/) are licensed under the GNU
General Public License license version 3.0.  The documentation (doc/)
is licensed under the GNU Free Documentation License version 1.2.
    </para>

    <para>
A conceptual view of how your application, the library, and each
mechanism interact is shown in <xref linkend="abstraction"/>.
    </para>

    <figure id="abstraction">
      <title>Illustration of separation between application and
	individual mechanism</title>
      <graphic fileref="abstraction.png" format="PNG"></graphic>
    </figure>

    <para>
      The operation of an application using the library can best be
      understood in terms of a flow chart diagram, as shown in
      <xref linkend="controlflow"/>.  The details on how the actual
      negotiation are carried out are illustrated in
      <xref linkend="controlflow2"/>.
    </para>

    <figure id="controlflow">
      <title>High-level control flow of SASL application</title>
      <graphic fileref="controlflow.png" format="PNG"></graphic>
    </figure>

    <figure id="controlflow2">
      <title>Low-level control flow of SASL application</title>
      <graphic fileref="controlflow2.png" format="PNG"></graphic>
    </figure>

    <xi:include href="xml/gsasl.xml"/>
    <xi:include href="xml/gsasl-mech.xml"/>
    <xi:include href="xml/gsasl-compat.xml"/>
  </chapter>

  <index>
    <title>Index</title>
  </index>
  <index role="deprecated">
    <title>Index of deprecated symbols</title>
  </index>
  <index role="0.2.0">
    <title>Index of new symbols in 0.2.0</title>
  </index>
  <index role="0.2.19">
    <title>Index of new symbols in 0.2.19</title>
  </index>
</book>
