1 \input texinfo @c -*- mode: texinfo; coding: us-ascii; -*-
2 @c This file is part of GNU SASL.
3 @c See below for copyright and license.
5 @setfilename gsasl.info
7 @settitle GNU Simple Authentication and Security Layer @value{VERSION}
10 @c Unify some of the indices.
15 This manual is last updated @value{UPDATED} for version
16 @value{VERSION} of GNU SASL.
18 Copyright @copyright{} 2002, 2003, 2004, 2005, 2006 Simon Josefsson.
21 Permission is granted to copy, distribute and/or modify this document
22 under the terms of the GNU Free Documentation License, Version 1.2 or
23 any later version published by the Free Software Foundation; with no
24 Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts. A
25 copy of the license is included in the section entitled ``GNU Free
26 Documentation License''.
30 @dircategory GNU Libraries
32 * libgsasl: (gsasl). Simple Authentication and Security Layer Library.
35 @dircategory GNU utilities
37 * gsasl: (gsasl)Invoking gsasl. Command line interface to GNU SASL.
42 @subtitle Simple Authentication and Security Layer for the GNU system
43 @subtitle for version @value{VERSION}, @value{UPDATED}
44 @author Simon Josefsson
46 @vskip 0pt plus 1filll
54 @top GNU Simple Authentication and Security Layer
59 * Introduction:: How to use this manual.
60 * Preparation:: What you should do before using the library.
61 * Using the Library:: High level overview of how to use the library.
62 * Properties:: How to specify username, password, etc.
63 * Mechanisms:: Mechanism specific information.
64 * Global Functions:: Functions that can be used at all times.
65 * Callback Functions:: Set and use callbacks.
66 * Property Functions:: Specify username, password etc.
67 * Session Functions:: Perform an authentication.
68 * Utilities:: Functions for various odd things.
69 * Error Handling:: Error codes and such.
70 * Examples:: Demonstrate how to use the library.
71 * Acknowledgements:: Whom to blame.
73 * Invoking gsasl:: Command line interface to the library.
77 * Protocol Clarifications:: Our notes on the SASL protocol.
78 * Old Functions:: Descriptions of old API functions.
79 * Copying This Manual:: How you can copy and share this manual.
83 * Concept Index:: Index of concepts and programs.
84 * Function and Data Index:: Index of functions, variables and data types.
87 @c **********************************************************
88 @c ******************* Introduction ***********************
89 @c **********************************************************
93 GNU SASL is an implementation of the Simple Authentication and
94 Security Layer framework and a few common SASL mechanisms.
95 @acronym{SASL} is used by network servers (e.g., @acronym{IMAP},
96 @acronym{SMTP}) to request authentication from clients, and in clients
97 to authenticate against servers.
99 GNU SASL consists of a library (`libgsasl'), a command line utility
100 (`gsasl') to access the library from the shell, and a manual. The
101 library includes support for the framework (with authentication
102 functions and application data privacy and integrity functions) and at
103 least partial support for the CRAM-MD5, EXTERNAL, GSSAPI, ANONYMOUS,
104 PLAIN, SECURID, DIGEST-MD5, LOGIN, and NTLM mechanisms.
106 The library is easily ported because it does not do network
107 communication by itself, but rather leaves it up to the calling
108 application. The library is flexible with regards to the
109 authorization infrastructure used, as it utilize a callback into the
110 application to decide whether a user is authorized or not.
112 GNU SASL is developed for the GNU/Linux system, but runs on over 20
113 platforms including most major Unix platforms and Windows, and many
114 kind of devices including iPAQ handhelds and S/390 mainframes.
116 GNU SASL is written in pure ANSI C89 to be portable to embedded and
117 otherwise limited platforms. The entire library, with full support
118 for ANONYMOUS, EXTERNAL, PLAIN, LOGIN and CRAM-MD5, and the front-end
119 that support client and server mode, and the IMAP and SMTP protocols,
120 fits in under 60kb on an Intel x86 platform, without any modifications
121 to the code. (This figure was accurate as of version 0.0.13.)
123 The library is licensed under the GNU Lesser General Public License,
124 and the command-line interface, self-tests and examples are licensed
125 under the GNU General Public License.
127 @float Illustration,fig:abstraction
128 @image{abstraction,10cm,5cm}
130 @caption{Logical overview showing how applications use authentication
131 mechanisms through an abstract interface.}
140 * Supported Platforms::
142 * Commercial Support::
143 * Downloading and Installing::
148 @node Getting Started
149 @section Getting Started
151 This manual documents the GNU SASL Library programming interface. All
152 functions and data types provided by the library are explained.
154 The reader is assumed to possess basic familiarity with SASL and
155 network programming in C or C++.
157 This manual can be used in several ways. If read from the beginning
158 to the end, it gives a good introduction into the library and how it
159 can be used in an application. Forward references are included where
160 necessary. Later on, the manual can be used as a reference manual to
161 get just the information needed about any particular interface of the
162 library. Experienced programmers might want to start looking at the
163 examples at the end of the manual, and then only read up those parts
164 of the interface which are unclear.
169 GNU SASL might have a couple of advantages over other libraries doing
173 @item It's Free Software
174 Anybody can use, modify, and redistribute it under the terms of the
175 GNU General Public License. The library can even be distributed under
176 the GNU Lesser General Public License.
178 @item It's thread-safe
179 No global variables are used and multiple library handles and session
180 handles may be used in parallel.
182 @item It's internationalized
183 It handles non-ASCII username and passwords and user visible strings
184 used in the library (error messages) can be translated into the users'
188 It should work on all Unix like operating systems, including Windows.
189 The library itself should be portable to any C89 system, not even
194 Note that the library do not implement any policy to decide whether a
195 certain user is ``authenticated'' or ``authorized'' or not. Rather,
196 it uses a callback into the application to answer these questions.
199 @section SASL Overview
201 This section describes SASL from a protocol point of view.
203 The Simple Authentication and Security Layer (SASL) is a method for
204 adding authentication support to connection-based protocols. A
205 protocol includes a command for identifying and authenticating a user
206 to a server and for optionally negotiating a security layer for
207 subsequent protocol interactions.
209 The command has a required argument identifying a SASL mechanism.
210 SASL mechanisms are named by strings, from 1 to 20 characters in
211 length, consisting of upper-case letters, digits, hyphens, and/or
214 If a server supports the requested mechanism, it initiates an
215 authentication protocol exchange. This consists of a series of
216 server challenges and client responses that are specific to the
217 requested mechanism. The challenges and responses are defined by the
218 mechanisms as binary tokens of arbitrary length. The protocol's
219 profile then specifies how these binary tokens are then encoded for
220 transfer over the connection.
222 After receiving the authentication command or any client response, a
223 server may issue a challenge, indicate failure, or indicate
224 completion. The protocol's profile specifies how the server
225 indicates which of the above it is doing.
227 After receiving a challenge, a client may issue a response or abort
228 the exchange. The protocol's profile specifies how the client
229 indicates which of the above it is doing.
231 During the authentication protocol exchange, the mechanism performs
232 authentication, transmits an authorization identity (frequently known
233 as a userid) from the client to server, and negotiates the use of a
234 mechanism-specific security layer. If the use of a security layer is
235 agreed upon, then the mechanism must also define or negotiate the
236 maximum cipher-text buffer size that each side is able to receive.
238 The transmitted authorization identity may be different than the
239 identity in the client's authentication credentials. This permits
240 agents such as proxy servers to authenticate using their own
241 credentials, yet request the access privileges of the identity for
242 which they are proxying. With any mechanism, transmitting an
243 authorization identity of the empty string directs the server to
244 derive an authorization identity from the client's authentication
247 If use of a security layer is negotiated, it is applied to all
248 subsequent data sent over the connection. The security layer takes
249 effect immediately following the last response of the authentication
250 exchange for data sent by the client and the completion indication
251 for data sent by the server. Once the security layer is in effect,
252 the protocol stream is processed by the security layer into buffers
253 of cipher-text. Each buffer is transferred over the connection as a
254 stream of octets prepended with a four octet field in network byte
255 order that represents the length of the following buffer. The length
256 of the cipher-text buffer must be no larger than the maximum size
257 that was defined or negotiated by the other side.
260 @section Requirements
262 The GNU SASL library does not have any required external dependencies,
263 but some optional features are enabled if you have a specific external
268 The NTLM mechanism requires the library LibNTLM,
269 @url{http://josefsson.org/libntlm/}.
272 The GSS-API mechanism requires a GSS-API library, such as GNU GSS
273 (@url{http://josefsson.org/gss/}, MIT Kerberos or Heimdal.
276 Processing of non-ASCII username and passwords requires the SASLprep
277 implementation in GNU LibIDN (@url{http://josefsson.org/libidn/}.
278 This is needed for full conformance with the latest SASL protocol
279 drafts, but is optional in the library for improved portability.
282 The GNU SASL library ships with its own cryptographic implementation,
283 but it can use the one in libgcrypt (@url{http://www.gnupg.org/}
284 instead, if it is available. This is typically useful for desktop
285 machines which have libgcrypt installed.
288 The command-line interface to GNU SASL requires a POSIX or Windows
289 platform for network connectivity. The command-line tool can make use
290 of GnuTLS (@url{http://josefsson.org/gnutls/} to support the STARTTLS
291 modes of IMAP and SMTP, but GnuTLS is not required.
293 Note that the library does not need a POSIX platform or network
296 @node Supported Platforms
297 @section Supported Platforms
299 GNU SASL has at some point in time been tested on the following
304 @item Debian GNU/Linux 3.0 (Woody)
307 GCC 2.95.4 and GNU Make. This is the main development platform.
308 @code{alphaev67-unknown-linux-gnu}, @code{alphaev6-unknown-linux-gnu},
309 @code{arm-unknown-linux-gnu}, @code{hppa-unknown-linux-gnu},
310 @code{hppa64-unknown-linux-gnu}, @code{i686-pc-linux-gnu},
311 @code{ia64-unknown-linux-gnu}, @code{m68k-unknown-linux-gnu},
312 @code{mips-unknown-linux-gnu}, @code{mipsel-unknown-linux-gnu},
313 @code{powerpc-unknown-linux-gnu}, @code{s390-ibm-linux-gnu},
314 @code{sparc-unknown-linux-gnu}.
316 @item Debian GNU/Linux 2.1
319 GCC 2.95.1 and GNU Make. @code{armv4l-unknown-linux-gnu}.
324 Tru64 UNIX C compiler and Tru64 Make. @code{alphaev67-dec-osf5.1},
325 @code{alphaev68-dec-osf5.1}.
330 GCC 2.96 and GNU Make. @code{alphaev6-unknown-linux-gnu},
331 @code{alphaev67-unknown-linux-gnu}.
333 @item SuSE Linux 7.2a
336 GCC 3.0 and GNU Make. @code{ia64-unknown-linux-gnu}.
338 @item RedHat Linux 7.2
341 GCC 2.96 and GNU Make. @code{alphaev6-unknown-linux-gnu},
342 @code{alphaev67-unknown-linux-gnu}, @code{ia64-unknown-linux-gnu}.
344 @item RedHat Linux 8.0
347 GCC 3.2 and GNU Make. @code{i686-pc-linux-gnu}.
349 @item RedHat Advanced Server 2.1
350 @cindex RedHat Advanced Server
352 GCC 2.96 and GNU Make. @code{i686-pc-linux-gnu}.
354 @item Slackware Linux 8.0.01
357 GCC 2.95.3 and GNU Make. @code{i686-pc-linux-gnu}.
359 @item Mandrake Linux 9.0
362 GCC 3.2 and GNU Make. @code{i686-pc-linux-gnu}.
367 MIPS C compiler, IRIX Make. @code{mips-sgi-irix6.5}.
372 IBM C for AIX compiler, AIX Make. @code{rs6000-ibm-aix4.3.2.0}.
374 @item Microsoft Windows 2000 (Cygwin)
377 GCC 3.2, GNU make. @code{i686-pc-cygwin}.
382 HP-UX C compiler and HP Make. @code{ia64-hp-hpux11.22},
383 @code{hppa2.0w-hp-hpux11.11}.
385 @item SUN Solaris 2.8
388 Sun WorkShop Compiler C 6.0 and SUN Make. @code{sparc-sun-solaris2.8}.
390 @item SUN Solaris 2.9
393 Sun Forte Developer 7 C compiler and GNU
394 Make. @code{sparc-sun-solaris2.9}.
399 GCC 2.95.3 and GNU Make. @code{alpha-unknown-netbsd1.6},
400 @code{i386-unknown-netbsdelf1.6}.
402 @item OpenBSD 3.1 and 3.2
405 GCC 2.95.3 and GNU Make. @code{alpha-unknown-openbsd3.1},
406 @code{i386-unknown-openbsd3.1}.
411 GCC 2.95.4 and GNU Make. @code{alpha-unknown-freebsd4.7},
412 @code{i386-unknown-freebsd4.7}.
414 @item Cross compiled to uClinux/uClibc on Motorola Coldfire.
415 @cindex Motorola Coldfire
419 GCC 3.4 and GNU Make @code{m68k-uclinux-elf}.
423 If you port GNU SASL to a new platform, please report it to the author
424 so this list can be updated.
427 @section Getting help
429 A mailing list where users may help each other exists, and you can
430 reach it by sending e-mail to @email{help-gsasl@@gnu.org}. Archives
431 of the mailing list discussions, and an interface to manage
432 subscriptions, is available through the World Wide Web at
433 @url{http://lists.gnu.org/mailman/listinfo/help-gsasl}.
435 @node Commercial Support
436 @section Commercial Support
438 Commercial support is available for users of GNU SASL. The kind of
439 support that can be purchased may include:
443 @item Implement new features.
444 Such as a new SASL mechanism.
446 @item Port GNU SASL to new platforms.
447 This could include porting to an embedded platforms that may need
448 memory or size optimization.
450 @item Integrating SASL as a security environment in your existing project.
452 @item System design of components related to SASL.
456 If you are interested, please write to:
459 Simon Josefsson Datakonsult
464 E-mail: simon@josefsson.org
467 If your company provide support related to GNU SASL and would like to
468 be mentioned here, contact the author (@pxref{Bug Reports}).
470 @node Downloading and Installing
471 @section Downloading and Installing
475 The package can be downloaded from several places, including:
477 @url{http://josefsson.org/gsasl/releases/}
479 The latest version is stored in a file, e.g.,
480 @samp{gsasl-@value{VERSION}.tar.gz} where the @samp{@value{VERSION}}
481 value is the highest version number in the directory.
483 The package is then extracted, configured and built like many other
484 packages that use Autoconf. For detailed information on configuring
485 and building it, refer to the @file{INSTALL} file that is part of the
486 distribution archive.
488 Here is an example terminal session that download, configure, build
489 and install the package. You will need a few basic tools, such as
490 @samp{sh}, @samp{make} and @samp{cc}.
493 $ wget -q http://josefsson.org/gsasl/releases/gsasl-@value{VERSION}.tar.gz
494 $ tar xfz gsasl-@value{VERSION}.tar.gz
495 $ cd gsasl-@value{VERSION}/
504 After that gsasl should be properly installed and ready for use.
506 A few @code{configure} options may be relevant, summarized in the
511 @item --disable-client
512 @itemx --disable-server
513 If your target system require a minimal implementation, you may wish
514 to disable the client or the server part of the code. This do not
515 remove symbols from the library, so if you attempt to call an
516 application that uses server functions in a library built with
517 @code{--disable-server}, the function will return an error code.
519 @item --disable-obsolete
520 This remove backwards compatibility (@pxref{Old Functions}). Use if
521 you want to limit the size of the library.
523 @item --disable-anonymous
524 @itemx --disable-external
525 @itemx --disable-plain
526 @itemx --disable-login
527 @itemx --disable-securid
528 @itemx --disable-ntlm
529 @itemx --disable-cram-md5
530 @itemx --disable-digest-md5
531 @itemx --disable-gssapi
532 @itemx --enable-kerberos_v5
533 Disable or enable individual mechanisms (@pxref{Mechanisms}).
535 @item --without-stringprep
536 Disable internationalized string processing. Note that this will
537 result in a SASL library that is only compatible with RFC 2222.
541 For the complete list, refer to the output from @code{configure
546 @cindex Reporting Bugs
548 If you think you have found a bug in GNU SASL, please investigate it
553 @item Please make sure that the bug is really in GNU SASL, and
554 preferably also check that it hasn't already been fixed in the latest
557 @item You have to send us a test case that makes it possible for us to
560 @item You also have to explain what is wrong; if you get a crash, or
561 if the results printed are not good and in that case, in what way.
562 Make sure that the bug report includes all information you would need
563 to fix this kind of bug for someone else.
567 Please make an effort to produce a self-contained report, with
568 something definite that can be tested or debugged. Vague queries or
569 piecemeal messages are difficult to act on and don't help the
572 If your bug report is good, we will do our best to help you to get a
573 corrected version of the software; if the bug report is poor, we won't
574 do anything about it (apart from asking you to send better bug
577 If you think something in this manual is unclear, or downright
578 incorrect, or if the language needs to be improved, please also send a
581 Send your bug report to:
583 @center @samp{bug-gsasl@@gnu.org}
586 @section Contributing
590 If you want to submit a patch for inclusion -- from solve a typo you
591 discovered, up to adding support for a new feature -- you should
592 submit it as a bug report (@pxref{Bug Reports}). There are some
593 things that you can do to increase the chances for it to be included
594 in the official package.
596 Unless your patch is very small (say, under 10 lines) we require that
597 you assign the copyright of your work to the Free Software Foundation.
598 This is to protect the freedom of the project. If you have not
599 already signed papers, we will send you the necessary information when
600 you submit your contribution.
602 For contributions that doesn't consist of actual programming code, the
603 only guidelines are common sense. Use it.
605 For code contributions, a number of style guides will help you:
610 Follow the GNU Standards document (@pxref{top, GNU Coding Standards,,
613 If you normally code using another coding standard, there is no
614 problem, but you should use @samp{indent} to reformat the code
615 (@pxref{top, GNU Indent,, indent}) before submitting your work.
617 @item Use the unified diff format @samp{diff -u}.
620 No reason whatsoever should abort the execution of the library. Even
621 memory allocation errors, e.g. when malloc return NULL, should work
622 although result in an error code.
624 @item Design with thread safety in mind.
625 Don't use global variables. Don't even write to per-handle global
626 variables unless the documented behaviour of the function you write is
627 to write to the per-handle global variable.
629 @item Avoid using the C math library.
630 It causes problems for embedded implementations, and in most
631 situations it is very easy to avoid using it.
633 @item Document your functions.
634 Use comments before each function headers, that, if properly
635 formatted, are extracted into Texinfo manuals and GTK-DOC web pages.
637 @item Supply a ChangeLog and NEWS entries, where appropriate.
641 @c **********************************************************
642 @c ******************* Preparation ************************
643 @c **********************************************************
647 To use GNU SASL, you have to perform some changes to your sources and
648 the build system. The necessary changes are small and explained in
649 the following sections. At the end of this chapter, it is described
650 how the library is initialized, and how the requirements of the
651 library are verified.
653 A faster way to find out how to adapt your application for use with
654 GNU SASL may be to look at the examples at the end of this manual
661 * Building the source::
668 All interfaces (data types and functions) of the library are defined
669 in the header file `gsasl.h'. You must include this in all programs
670 using the library, either directly or through some other header file,
677 The name space is @code{gsasl_*} for function names, @code{Gsasl*} for
678 data types and @code{GSASL_*} for other symbols. In addition the same
679 name prefixes with one prepended underscore are reserved for internal
680 use and should never be used by an application.
683 @section Initialization
685 The library must be initialized before it can be used. The library is
686 initialized by calling @code{gsasl_init} (@pxref{Global Functions}).
687 The resources allocated by the initialization process can be released
688 if the application no longer has a need to call `Libgsasl' functions,
689 this is done by calling @code{gsasl_done}. For example:
693 main (int argc, char *argv[])
698 rc = gsasl_init (&ctx);
701 printf ("SASL initialization failure (%d): %s\n",
702 rc, gsasl_strerror (rc));
708 In order to make error messages from @code{gsasl_strerror} be
709 translated (@pxref{Top,,,gettext,GNU Gettext}) the application must
710 set the current locale using @code{setlocale} before calling
711 @code{gsasl_init}. For example:
715 main (int argc, char *argv[])
720 setlocale (LC_ALL, "");
722 rc = gsasl_init (&ctx);
725 printf (gettext ("SASL initialization failure (%d): %s\n"),
726 rc, gsasl_strerror (rc));
732 In order to take advantage of the secure memory features in
733 Libgcrypt@footnote{Note that GNU SASL normally use its own internal
734 implementation of the cryptographic functions. Take care to verify
735 that GNU SASL really use Libgcrypt, if this is what you want.}, you
736 need to initialize secure memory in your application, and for some
737 platforms even make your application setuid root. See the Libgcrypt
738 documentation for more information. Example code to initialize secure
745 main (int argc, char *argv[])
750 /* Check version of libgcrypt. */
751 if (!gcry_check_version (GCRYPT_VERSION))
752 die ("version mismatch\n");
754 /* Allocate a pool of 16k secure memory. This also drops priviliges
756 gcry_control (GCRYCTL_INIT_SECMEM, 16384, 0);
758 /* Tell Libgcrypt that initialization has completed. */
759 gcry_control (GCRYCTL_INITIALIZATION_FINISHED, 0);
761 rc = gsasl_init (&ctx);
764 printf ("SASL initialization failure (%d): %s\n",
765 rc, gsasl_strerror (rc));
771 If you do not do this, keying material will not be allocated in secure
772 memory (which for most application is not the biggest secure problem
773 anyway). Note that the GNU SASL Library has not been audited to make
774 sure it only ever stores passwords or keys in secure memory.
777 @section Version Check
779 It is often desirable to check that the version of the library used is
780 indeed one which fits all requirements. Even with binary
781 compatibility new features may have been introduced but due to problem
782 with the dynamic linker an old version is actually used. So you may
783 want to check that the version is okay right after program startup.
785 @include texi/gsasl_check_version.texi
787 The normal way to use the function is to put something similar to the
788 following early in your @code{main}:
791 if (!gsasl_check_version (GSASL_VERSION))
793 printf ("gsasl_check_version failed:\n"
794 "Header file incompatible with shared library.\n");
799 @node Building the source
800 @section Building the source
801 @cindex Compiling your application
803 If you want to compile a source file including the `gsasl.h' header
804 file, you must make sure that the compiler can find it in the
805 directory hierarchy. This is accomplished by adding the path to the
806 directory in which the header file is located to the compilers include
807 file search path (via the @option{-I} option).
809 However, the path to the include file is determined at the time the
810 source is configured. To solve this problem, the library uses the
811 external package @command{pkg-config} that knows the path to the
812 include file and other configuration options. The options that need
813 to be added to the compiler invocation at compile time are output by
814 the @option{--cflags} option to @command{pkg-config libgsasl}. The
815 following example shows how it can be used at the command line:
818 gcc -c foo.c `pkg-config libgsasl --cflags`
821 Adding the output of @samp{pkg-config libgsasl --cflags} to the
822 compilers command line will ensure that the compiler can find the
823 `gsasl.h' header file.
825 A similar problem occurs when linking the program with the library.
826 Again, the compiler has to find the library files. For this to work,
827 the path to the library files has to be added to the library search path
828 (via the @option{-L} option). For this, the option @option{--libs} to
829 @command{pkg-config libgsasl} can be used. For convenience, this option
830 also outputs all other options that are required to link the program
831 with the `libgsasl' libarary (for instance, the @samp{-lidn}
832 option). The example shows how to link @file{foo.o} with the `libgsasl'
833 library to a program @command{foo}.
836 gcc -o foo foo.o `pkg-config libgsasl --libs`
839 Of course you can also combine both examples to a single command by
840 specifying both options to @command{pkg-config}:
843 gcc -o foo foo.c `pkg-config libgsasl --cflags --libs`
847 @section Autoconf tests
848 @cindex Autoconf tests
849 @cindex Configure tests
851 If you work on a project that uses Autoconf (@pxref{top, GNU
852 Autoconf,, autoconf}) to help find installed libraries, the
853 suggestions in the previous section are not the entire story. There
854 are a few methods to detect and incorporate the GNU SASL Library into
855 your Autoconf based package. The preferred approach, is to use
856 Libtool in your project, and use the normal Autoconf header file and
859 @subsection Autoconf test via @samp{pkg-config}
861 If your audience is a typical GNU/Linux desktop, you can often assume
862 they have the @samp{pkg-config} tool installed, in which you can use
863 its Autoconf M4 macro to find and set up your package for use with
864 Libgsasl. The following illustrate this scenario.
868 AC_HELP_STRING([--disable-gsasl], [don't use GNU SASL]),
870 if test "$gsal" != "no" ; then
871 PKG_CHECK_MODULES(GSASL, libgsasl >= @value{VERSION},
874 if test "$gsasl" != "yes" ; then
876 AC_MSG_WARN([Cannot find GNU SASL, disabling])
879 AC_DEFINE(USE_GSASL, 1, [Define to 1 if you want GNU SASL.])
882 AC_MSG_CHECKING([if GNU SASL should be used])
883 AC_MSG_RESULT($gsasl)
886 @subsection Standalone Autoconf test using Libtool
888 If your package uses Libtool(@pxref{top, GNU Libtool,, libtool}), you
889 can use the normal Autoconf tests to find Libgsasl and rely on the
890 Libtool dependency tracking to include the proper dependency libraries
891 (e.g., Libidn). The following illustrate this scenario.
894 AC_CHECK_HEADER(gsasl.h,
895 AC_CHECK_LIB(gsasl, gsasl_check_version,
896 [gsasl=yes AC_SUBST(GSASL_LIBS, -lgsasl)],
900 AC_HELP_STRING([--disable-gsasl], [don't use GNU SASL]),
902 if test "$gsasl" != "no" ; then
903 AC_DEFINE(USE_SASL, 1, [Define to 1 if you want GNU SASL.])
905 AC_MSG_WARN([Cannot find GNU SASL, diabling])
907 AC_MSG_CHECKING([if GNU SASL should be used])
908 AC_MSG_RESULT($gsasl)
911 @c **********************************************************
912 @c ***************** Using the Library ********************
913 @c **********************************************************
914 @node Using the Library
915 @chapter Using the Library
917 Your application's use of the library can be roughly modeled into the
918 following steps: initialize the library, optionally specify the
919 callback, perform the authentication, and finally clean up. The
920 following image illustrate this.
922 @image{controlflow,15cm,5cm}
924 The third step may look the most complex, but for a simple client it
925 will actually not involve any code. If your application need to
926 handle several concurrent clients, or if it is a server that need to
927 serve many clients simultaneous, things do get a bit more complicated.
929 For illustration, we will write a simple client. Writing a server
930 would be similar, the only difference is that, later on, instead of
931 supplying username or passwords, you need to decide whether someone
932 should be allowed to log in or not. The code for what we have
933 discussed so far make up our @code{main} function in our client
937 int main (int argc, char *argv[])
942 if ((rc = gsasl_init (&ctx)) != GSASL_OK)
944 printf ("Cannot initialize libgsasl (%d): %s",
945 rc, gsasl_strerror (rc));
957 Here, the call to the function @code{client} correspond to the third
958 step in the image above.
960 For a more complicated application, that have several clients running
961 simultaneous, instead of simply calling @code{client}, it may have
962 created new threads for each session, and call @code{client} within
963 each thread. The library is thread safe.
965 An actual authentication session is more complicated than what we have
966 seen so far. The steps that make up it are: decide which mechanism to
967 use, start the session, optionally specify the callback, optionally
968 set any properties, perform the authentication loop, and clean up.
969 Naturally, your application will start to talk its own protocol (e.g.,
970 SMTP or IMAP) after these steps have concluded.
972 The authentication loop is based on sending tokens (typically short
973 messages encoded in base 64) back and forth between the client and
974 server. It continue until authentication succeeds or there is an
975 error. The format of the data to transfer, the number of iterations
976 in the loop, and other details are specified by each mechanism. The
977 goal of the library is to isolate your application from the details of
978 all different mechanisms.
980 Note that the library do not send data to the server itself, but
981 return it in an buffer. You must send it to the server yourself,
982 according to an application protocol profile. For example, the
983 @acronym{SASL} application protocol profile for @acronym{SMTP} is
984 described in @acronym{RFC} 2554.
986 The following image illustrate the steps we have been talking about.
988 @image{controlflow2,16cm,12cm}
990 We will now show the implementation of the @code{client} function used
994 void client (Gsasl *ctx)
996 Gsasl_session *session;
997 const char *mech = "PLAIN";
1000 /* Create new authentication session. */
1001 if ((rc = gsasl_client_start (ctx, mech, &session)) != GSASL_OK)
1003 printf ("Cannot initialize client (%d): %s\n",
1004 rc, gsasl_strerror (rc));
1008 /* Set username and password in session handle. This info will be
1009 lost when this session is deallocated below. */
1010 gsasl_property_set (session, GSASL_AUTHID, "jas");
1011 gsasl_property_set (session, GSASL_PASSWORD, "secret");
1014 client_authenticate (ctx, session);
1017 gsasl_finish (session);
1021 This function is responsible for deciding which mechanism to use. In
1022 this case, the @samp{PLAIN} mechanism is hard coded, but you will see
1023 later how this can be made more flexible. The function create a new
1024 session, store the username and password in the session handle, then
1025 call another function @code{client_authenticate} to handle the
1026 authentication loop, and end by cleaning up. Let's continue with the
1027 implementation of @code{client_authenticate}.
1030 void client_authenticate (Gsasl * ctx, Gsasl_session * session)
1032 char buf[BUFSIZ] = "";
1036 /* This loop mimic a protocol where the server get to send data
1041 printf ("Input base64 encoded data from server:\n");
1042 fgets (buf, sizeof (buf) - 1, stdin);
1043 if (buf[strlen (buf) - 1] == '\n')
1044 buf[strlen (buf) - 1] = '\0';
1046 rc = gsasl_step64 (session, buf, &p);
1048 if (rc == GSASL_NEEDS_MORE || rc == GSASL_OK)
1050 printf ("Output:\n%s\n", p);
1054 while (rc == GSASL_NEEDS_MORE);
1060 printf ("Authentication error (%d): %s\n",
1061 rc, gsasl_strerror (rc));
1065 /* The client is done. Here you would typically check if the
1066 server let the client in. If not, you could try again. */
1068 printf ("If server accepted us, we're done.\n");
1072 This last function need to be discussed in some detail. First, you
1073 should be aware that there are two versions of this function, that
1074 differ in a subtle way. The version above (@pxref{Example 2}) is used
1075 for application profiles where the server send data first. For some
1076 mechanisms, this may waste a roundtrip, because the server need input
1077 from the client to proceed. Therefor, today the recommended approach
1078 is to permit client to send data first (@pxref{Example 1}). Which
1079 version you should use depend on which application protocol you are
1082 Further, you should realize that it is bad programming style to use a
1083 fixed size buffer. On GNU systems, you may use the @code{getline}
1084 functions instead of @code{fgets}. However, in practice, there are
1085 few mechanisms that use very large tokens. In typical configurations,
1086 the mechanism with the largest tokens (GSSAPI) can use at least 500
1087 bytes. A fixed buffer size of 8192 bytes may thus be sufficient for
1088 now. But don't say I didn't warn you, when a future mechanism doesn't
1089 work in your application, because of a fixed size buffer.
1091 The @code{gsasl_step64} (and of course also @code{gasl_step}) return
1092 two non-error return codes. @code{GSASL_OK} is used for success,
1093 indicating that the library consider the authentication finished.
1094 That may include a successful server authentication, depending on the
1095 mechanism. You must not let the client continue to the application
1096 protocol part unless you receive @code{GSASL_OK} from these functions.
1097 In particular, don't be fooled into believing authentication were
1098 successful if the server reply ``OK'' but these function has failed
1099 with an error. The server may have been hacked, and could be tricking
1100 you into sending confidential data, without having successfully
1101 authenticated the server.
1103 The non-error return code @code{GSASL_NEEDS_MORE} is used to signal to
1104 your application that you should send the output token to the peer,
1105 and wait for a new token, and do another iteration. If the server
1106 conclude the authentication process, with no data, you should call
1107 @code{gsasl_step64} (or @code{gsasl_step}) specifying a zero-length
1110 If the functions (@code{gsasl_step} and @code{gsasl_step64}) return
1111 any non-error code, the content of the output buffer is undefined.
1112 Otherwise, it is the callers responsibility to deallocate the buffer,
1113 by calling @code{free}. Note that in some situations, where the
1114 buffer is empty, @code{NULL} is returned as the buffer value. You
1115 should treat this as an empty buffer.
1117 @section Choosing a mechanism
1119 Our earlier code was hard coded to use a specific mechanism. This is
1120 rarely a good idea. Instead, it is recommended to select the best
1121 mechanism available from the list of mechanism supported by the
1122 server. Note that without TLS or similar, the list may have been
1123 maliciously altered, by an attacker. This means that you should abort
1124 if you cannot find any mechanism that exceeds your minimum security
1125 level. There is a function @code{gsasl_client_suggest_mechanism}
1126 (@pxref{Global Functions}) that will try to pick the ``best''
1127 available mechanism from a list of mechanisms. Our simple interactive
1128 example client (@pxref{Example 3}) include the following function to
1129 decide which mechanism to use. Note that the code doesn't blindly use
1130 what is returned from @code{gsasl_client_suggest_mechanism}, but
1131 rather let some logic (in this case the user, through an interactive
1132 query) decide which mechanism is acceptable.
1135 const char *client_mechanism (Gsasl *ctx)
1137 static char mech[GSASL_MAX_MECHANISM_SIZE + 1] = "";
1138 char mechlist[BUFSIZ] = "";
1139 const char *suggestion;
1141 printf ("Enter list of mechanism that server support, separate by SPC:\n");
1142 fgets (mechlist, sizeof (mechlist) - 1, stdin);
1144 suggestion = gsasl_client_suggest_mechanism (ctx, mechlist);
1146 printf ("Library suggest use of `%s'.\n", suggestion);
1148 printf ("Enter mechanism to use:\n");
1149 fgets (mech, sizeof (mech) - 1, stdin);
1150 mech[strlen (mech) - 1] = '\0';
1156 When running this example code, it might look like in the following
1160 Enter list of mechanism that server support, separate by SPC:
1161 CRAM-MD5 DIGEST-MD5 GSSAPI FOO BAR
1162 Library suggest use of `GSSAPI'.
1163 Enter mechanism to use:
1165 Input base64 encoded data from server:
1168 amFzIDkyY2U1NWE5MTM2ZTY4NzEyMTUyZTFjYmFmNjVkZjgx
1170 If server accepted us, we're done.
1173 @section Using a callback
1175 Our earlier code specified the username and password before the
1176 authentication loop, as in:
1179 gsasl_property_set (ctx, GSASL_AUTHID, "jas");
1180 gsasl_property_set (ctx, GSASL_PASSWORD, "secret");
1183 This may work for simple mechanisms, that only ever need an username
1184 and a password. But some mechanism require more information, such as
1185 an authorization identity, a special PIN or passcode, a realm, a
1186 hostname, a service name, or an anonymous identifier. Querying the
1187 user for all that information, without knowing exactly which of it is
1188 really needed will result in a poor user interface. The user should
1189 not have to input private information, if it isn't required.
1191 The approach is a bad idea for another reason. What if the server
1192 abort the authentication process? Then your application have already
1193 queried the user for a username and password. It would be better if
1194 you only asked the user for this information, annoying to input, when
1195 it is known to be needed.
1197 A better approach to this problem is to use a callback. Then the
1198 mechanism may query your application whenever it need some
1199 information, like the username and password. It will only do this at
1200 the precise step in the authentication when the information is
1201 actually needed. Further, if the user abort, e.g., a password prompt,
1202 the mechanism is directly informed of this (because it invoked the
1203 callback), and could recover somehow.
1205 Our final example (@pxref{Example 4}) specify a callback function,
1206 inside @code{main} as below.
1209 /* Set the callback handler for the library. */
1210 gsasl_callback_set (ctx, callback);
1213 The function itself is implemented as follows.
1216 int callback (Gsasl * ctx, Gsasl_session * sctx, Gsasl_property prop)
1218 char buf[BUFSIZ] = "";
1219 int rc = GSASL_NO_CALLBACK;
1221 /* Get user info from user. */
1223 printf ("Callback invoked, for property %d.\n", prop);
1227 case GSASL_PASSCODE:
1228 printf ("Enter passcode:\n");
1229 fgets (buf, sizeof (buf) - 1, stdin);
1230 buf[strlen (buf) - 1] = '\0';
1232 gsasl_property_set (sctx, GSASL_PASSCODE, buf);
1237 printf ("Enter username:\n");
1238 fgets (buf, sizeof (buf) - 1, stdin);
1239 buf[strlen (buf) - 1] = '\0';
1241 gsasl_property_set (sctx, GSASL_AUTHID, buf);
1246 printf ("Unknown property! Don't worry.\n");
1254 Again, it is bad style to use a fixed size buffer. Mmm'kay.
1256 Which properties you should handle is up to you. If you don't know
1257 how to respond to a certain property, simply return
1258 @code{GSASL_NO_CALLBACK}. The basic properties to support are
1259 authentication identity (@code{GSASL_AUTHID}), authorization identity
1260 (@code{GSASL_AUTHZID}), and password (@code{GSASL_PASSWORD}). See
1261 @xref{Properties}, for the list of all properties, and what your
1262 callback should (ideally) do for them, and which properties each
1263 mechanism require in order to work.
1265 @c **********************************************************
1266 @c ******************* Properties *************************
1267 @c **********************************************************
1271 @c FIXME: Write introductions to properties. Discuss differences
1272 @c between client and server properties. Discuss validating
1275 Properties with associated data:
1279 @item @code{GSASL_AUTHID}
1281 The authentication identity.
1283 @item @code{GSASL_AUTHZID}
1285 The authorization identity.
1287 @item @code{GSASL_PASSWORD}
1289 The password of the authentication identity.
1291 @item @code{GSASL_ANONYMOUS_TOKEN}
1293 The anonymous token. This is typically the email address of the user.
1295 @item @code{GSASL_SERVICE}
1297 The registered GSSAPI service name of the application service,
1298 e.g. ``imap''. While the names are registered for GSSAPI, other
1299 mechanisms such as DIGEST-MD5 may also use this.
1301 @item @code{GSASL_HOSTNAME}
1303 Should be the local host name of the machine.
1305 @item @code{GSASL_GSSAPI_DISPLAY_NAME}
1307 Contain the GSSAPI ``display name'', set by the server GSSAPI
1308 mechanism. Typically you retrieve this property in your callback,
1309 when invoked for @code{GSASL_VALIDATE_GSSAPI}.
1311 @item @code{GSASL_REALM}
1313 The name of the authentication domain. This is used by several
1314 mechanisms, including DIGEST-MD5, GSS-API, KERBEROS_V5 and NTLM.
1316 @item @code{GSASL_PASSCODE}
1318 The SecurID passcode.
1320 @item @code{GSASL_PIN}
1322 The SecurID personal identification number (PIN).
1324 @item @code{GSASL_SUGGESTED_PIN}
1326 A SecurID personal identification number (PIN) suggested by the server.
1330 Abstract properties, used to trigger the callback, typically used in
1331 servers to validate client credentials:
1335 @item @code{GSASL_VALIDATE_SIMPLE}
1337 You may retrieve GSASL_AUTHID, GSASL_AUTHZID and GSASL_PASSWORD and
1338 use them to make an authentication and authorization decision.
1340 @item @code{GSASL_VALIDATE_EXTERNAL}
1342 Used by EXTERNAL mechanism on the server side to validate the client.
1343 The GSASL_AUTHID will contain the authorization identity of the
1346 @item @code{GSASL_VALIDATE_ANONYMOUS}
1348 Used by ANONYMOUS mechanism on the server side to validate the client.
1349 The GSASL_ANONYMOUS_TOKEN will contain token that identity the client.
1351 @item @code{GSASL_VALIDATE_GSSAPI}
1353 Used by the GSSAPI mechanism on the server side, to validate the
1354 client. You may retrieve the authorization identity from
1355 GSASL_AUTHZID and the GSS-API display name from
1356 GSASL_GSSAPI_DISPLAY_NAME.
1358 @item @code{GSASL_VALIDATE_SECURID}
1360 Used by SECURID mechanism on the server side to validate client. The
1361 GSASL_AUTHID, GSASL_AUTHZID, GSASL_PASSCODE, and GSASL_PIN will be
1362 set. It can return GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODE to
1363 ask the client to supply another passcode, and
1364 GSASL_SECURID_SERVER_NEED_NEW_PIN to require the client to supply a
1370 @c **********************************************************
1371 @c ******************* Mechanisms *************************
1372 @c **********************************************************
1376 Different SASL mechanisms have different requirements on the
1377 application using it. To handle these differences the library can use
1378 a callback function into your application in several different ways.
1379 Some mechanisms, such as @samp{PLAIN}, are simple to explain and use.
1380 The client callback query the user for a username and password. The
1381 server callback hand the username and password into any local policy
1382 deciding authentication system (such as @file{/etc/passwd} via PAM).
1384 Mechanism such as @samp{CRAM-MD5} and @samp{DIGEST-MD5} uses hashed
1385 passwords. The client callback behaviour is the same as for PLAIN.
1386 However, the server do not receive the plain text password over the
1387 network but rather a hash of it. Existing policy deciding systems
1388 like PAM cannot handle this, so the server callback for these
1389 mechanisms are more complicated.
1391 Further, mechanisms like GSSAPI (Kerberos 5) assume a specific
1392 authentication system. In theory this means that the SASL library
1393 would not need to interact with the application, but rather call this
1394 specific authentication system directly. However, some callbacks are
1395 supported anyway, to modify the behaviour of how the specific
1396 authentication system is used (i.e., to handle ``super-user'' login as
1399 Some mechanisms, like @samp{EXTERNAL} and @samp{ANONYMOUS} are
1400 entirely dependent on callbacks.
1403 * EXTERNAL:: Authentication via out of band information.
1404 * ANONYMOUS:: Mechanism for anonymous access to resources.
1405 * PLAIN:: Clear text username and password.
1406 * LOGIN:: Non-standard clear text username and password.
1407 * CRAM-MD5:: Challenge-Response Authentication Mechanism.
1408 * DIGEST-MD5:: Digest Authentication.
1409 * NTLM:: Microsoft NTLM authentication.
1410 * SECURID:: Authentication using tokens.
1411 * GSSAPI:: GSSAPI (Kerberos 5) authentication.
1412 * KERBEROS_V5:: Experimental KERBEROS_V5 authentication.
1416 @section The EXTERNAL mechanism
1418 The EXTERNAL mechanism is used to authenticate a user to a server
1419 based on out-of-band authentication. EXTERNAL is typically used over
1420 TLS authenticated channels. Note that in the server, you need to make
1421 sure that TLS actually authenticated the client successfully. It is
1422 normally not sufficient that TLS is used, since they also support
1425 In the client, this mechanism is always enabled, and will send the
1426 @code{GSASL_AUTHZID} property as the authorization name to the server,
1427 if the property is set. If the property is not set, the empty
1428 authorization name is sent. You need not implement a callback.
1430 In the server, this mechanism will invoke the
1431 @code{GSASL_VALIDATE_EXTERNAL} callback to decide whether the client
1432 is authenticated and authorized to log in. Your callback can retrieve
1433 the @code{GSASL_AUTHZID} property to inspect the requested
1434 authorization name from the client.
1437 @section The ANONYMOUS mechanism
1439 The ANONYMOUS mechanism is used to ``authenticate'' clients to
1440 anonymous services; or rather, just indicate that the client wishes to
1441 use the service anonymously. The client sends a token, usually her
1442 email address, which serve the purpose of some trace information
1443 suitable for log files. The token is not permitted to be empty.
1445 In the client, this mechanism is always enabled, and will send the
1446 @code{GSASL_ANONYMOUS_TOKEN} property as the trace information to the
1449 In the server, this mechanism will invoke the
1450 @code{GSASL_VALIDATE_ANONYMOUS} callback to decide whether the client
1451 should be permitted to log in. Your callback can retrieve the
1452 @code{GSASL_ANONYMOUS_TOKEN} property to, for example, save it in a
1453 log file. The token is normally not used to decide whether the client
1454 should be permitted to log in or not.
1457 @section The PLAIN mechanism
1459 The PLAIN mechanism uses username and password to authenticate users.
1460 Two user names are relevant. The first, the authentication identity,
1461 indicate the credential holder, i.e., whom the provided password
1462 belongs to. The second, the authorization identity, is typically
1463 empty, to indicate that the user requests to log on to the server as
1464 herself. However, if the authorization identity is not empty, the
1465 server should decide whether the authenticated user may log on as the
1466 authorization identity. Normally, only ``super-user'' accounts such
1467 as @samp{admin} or similar should be allowed this.
1469 In the client, this mechanism is always enabled, and require the
1470 @code{GSASL_AUTHID} and @code{GSASL_PASSWORD} properties. If set,
1471 @code{GSASL_AUTHZID} will also be used.
1473 In the server, the mechanism is always enabled. Two approaches to
1474 authenticate and authorize the client is provided.
1476 In the first approach, the server side of the mechanism will invoke
1477 the @code{GSASL_VALIDATE_SIMPLE} callback property to decide whether
1478 the client should be accepted or not. The callback may inspect the
1479 @code{GSASL_AUTHID}, @code{GSASL_AUTHID}, and @code{GSASL_PASSWORD}
1480 properties. These properties values will be normalized.
1482 If the first approach fails (because, e.g., your callback return
1483 @samp{GSASL_NO_CALLBACK} to signal that it does not implement
1484 @code{GSASL_VALIDATE_SIMPLE}) the mechanism will continue to query the
1485 application for a password, via the @code{GSASL_PASSWORD} property.
1486 Your callback may use the @code{GSASL_AUTHID} and @code{GSASL_AUTHZID}
1487 properties to select the proper password. The password is then
1488 normalized and compared to the client credential.
1490 Which approach to use? If your database store hashed passwords, you
1491 have no option, but must use the first approach. If passwords in your
1492 user database are stored in prepared (@acronym{SASLprep}) form, the
1493 first approach will be faster. If you do not have prepared passwords
1494 available, you can use the second approach to make sure the password
1495 is prepared properly before comparison.
1498 @section The LOGIN mechanism
1500 The LOGIN mechanism is a non-standard mechanism, and is similar to the
1501 PLAIN mechanism except that LOGIN lack the support for authorization
1502 identities. Always use PLAIN instead of LOGIN in new applications.
1504 The callback behaviour is the same as for PLAIN, except that
1505 @code{GSASL_AUTHZID} is not used nor required, and that the server do
1506 not normalize the password using @acronym{SASLprep}.
1508 @xref{Use of SASLprep in LOGIN}, for a proposed clarification of the
1509 interpretation of a hypothetical LOGIN specification.
1512 @section The CRAM-MD5 mechanism
1514 The CRAM-MD5 is a widely used, but officially deprecated (apparently
1515 in favor of DIGEST-MD5), challenge-response mechanism that transfer
1516 hashed passwords instead of clear text passwords. For insecure
1517 channels (e.g., when @acronym{TLS} is not used), it is safer than
1518 PLAIN. The CRAM-MD5 mechanism do not support authorization
1519 identities; making the relationship between CRAM-MD5 and DIGEST-MD5
1520 similar to the relationship between LOGIN and PLAIN.
1522 The disadvantage with hashed passwords is that the server cannot use
1523 normal authentication infrastructures such as PAM, because the server
1524 must have access to the correct password in order to validate an
1525 authentication attempt.
1527 In the client, this mechanism is always enabled, and require the
1528 @code{GSASL_AUTHID} and @code{GSASL_PASSWORD} properties.
1530 In the server, the mechanism will invoke the @code{GSASL_PASSWORD}
1531 callback, which may use the @code{GSASL_AUTHID} property to determine
1532 which users' password should be used. The @code{GSASL_AUTHID} will be
1533 in normalized form. The server will then normalize the returned
1534 password, and compare the client response with the computed correct
1535 response, and accept the user accordingly.
1537 @xref{Use of SASLprep in CRAM-MD5}, for a clarification on the
1538 interpretation of the CRAM-MD5 specification that this implementation
1542 @section The DIGEST-MD5 mechanism
1544 The DIGEST-MD5 mechanism is based on repeated hashing using MD5, which
1545 after the MD5 break may be argued to be weaker than HMAC-MD5, but
1546 supports more features. For example, authorization identities and
1547 data integrity and privacy protection are supported. Like CRAM-MD5,
1548 only a hashed password is transfered. Consequently, DIGEST-MD5 need
1549 access to the correct password (although it may be hashed, another
1550 improvement compared to CRAM-MD5) to verify the client response.
1551 Alas, this make it impossible to use, e.g., @acronym{PAM} on the
1554 In the client, this mechanism is always enabled, and require the
1555 @code{GSASL_AUTHID}, @code{GSASL_PASSWORD}, @code{GSASL_SERVICE}, and
1556 @code{GSASL_HOSTNAME} properties. If set, @code{GSASL_AUTHZID} and
1557 @code{GSASL_REALM} will also be used.
1559 In the server, the mechanism will invoke the @code{GSASL_PASSWORD}
1560 callback, which may use the @code{GSASL_AUTHID}, @code{GSASL_AUTHZID}
1561 and @code{GSASL_REALM} properties to determine which users' password
1562 should be used. The server will then compare the client response with
1563 a computed correct response, and accept the user accordingly.
1565 Currently only the authentication quality of service is implemented.
1566 In other words, payload integrity or privacy protection are not
1567 supported. Consequently, there are no properties for the maximum
1568 buffer size, quality of protection, and cipher fields.
1571 @section The NTLM mechanism
1573 The NTLM is a non-standard mechanism. Do not use it in new
1574 applications, and do not expect it to be secure. Currently only the
1575 client side is supported.
1577 In the client, this mechanism is always enabled, and require the
1578 @code{GSASL_AUTHID} and @code{GSASL_PASSWORD} properties. It will set
1579 the @samp{domain} field in the NTLM request to the value of
1580 @code{GSASL_REALM}. Some servers reportedly need non-empty but
1581 arbitrary values in that field.
1584 @section The SECURID mechanism
1586 The SECURID mechanism uses authentication and authorization identity
1587 together with a passcode from a hardware token to authenticate users.
1589 In the client, this mechanism is always enabled, and require the
1590 @code{GSASL_AUTHID} and @code{GSASL_PASSCODE} properties. If set,
1591 @code{GSASL_AUTHZID} will also be used. If the server requests it,
1592 the @code{GSASL_PIN} property is also required, and its callback may
1593 inspect the @code{GSASL_SUGGESTED_PIN} property to discover a
1594 server-provided PIN to use.
1596 In the server, this mechanism will invoke the
1597 @code{GSASL_VALIDATE_SECURID} callback. The callback may inspect the
1598 @code{GSASL_AUTHID}, @code{GSASL_AUTHZID}, and @code{GSASL_PASSCODE}
1599 properties. The callback can return
1600 @code{GSASL_SECURID_SERVER_NEED_ADDITIONAL_PASSCODE} to ask for
1601 another additional passcode from the client. The callback can return
1602 @code{GSASL_SECURID_SERVER_NEED_NEW_PIN} to ask for a new PIN code
1603 from the client, in which case it may also set the
1604 @code{GSASL_SUGGESTED_PIN} property to indicate a recommended new PIN.
1605 If the callbacks has invoked again, after having returned
1606 @code{GSASL_SECURID_SERVER_NEED_NEW_PIN}, it may also inspect the
1607 @code{GSASL_PIN} property, in addition to the other properties, to
1608 find out the client selected PIN code.
1611 @section The GSSAPI mechanism
1613 GSS-API is a framework, similar to SASL, for authentication. The
1614 GSSAPI mechanism only support the Kerberos 5 GSS-API mechanism,
1615 though. (A new SASL mechanism to support non-Kerberos 5 GSS-API
1616 mechanisms may be supported in the future.)
1618 In the client, the mechanism is enabled only if the user has acquired
1619 credentials (i.e., a ticket granting ticket), and require the
1620 @code{GSASL_AUTHID}, @code{GSASL_SERVICE}, and @code{GSASL_HOSTNAME}
1623 In the server, the mechanism require the @code{GSASL_SERVICE}, and
1624 @code{GSASL_HOSTNAME} properties, and will invoke the
1625 @code{GSASL_VALIDATE_GSSAPI} callback in order to validate the user.
1626 The callback may inspect the @code{GSASL_AUTHZID} and
1627 @code{GSASL_GSSAPI_DISPLAY_NAME} properties to decide whether to
1628 authorize the user. Note that authentication is performed by the
1631 XXX: explain more about quality of service, maximum buffer size, etc.
1634 @section The KERBEROS_V5 mechanism
1636 The KERBEROS_V5 is an experimental mechanism, the protocol
1637 specification is available on the GNU SASL homepage. It can operate
1638 in three modes, non-infrastructure mode, infrastructure mode and
1639 proxied infrastructure mode. Currently only non-infrastructure mode
1642 In the non-infrastructure mode, it works as a superset of most
1643 features provided by PLAIN, CRAM-MD5, DIGEST-MD5 and GSSAPI while at
1644 the same time building on what is believed to be proven technology
1645 (the RFC 1510 network security system). In the non-infrastructure
1646 mode, the client must specify (via callbacks) the name of the user,
1647 and optionally the server name and realm. The server must be able to
1648 retrieve passwords given the name of the user.
1650 In the infrastructure mode (proxied or otherwise), it allows clients
1651 and servers to authenticate via SASL in an RFC 1510 environment, using
1652 a trusted third party, a ``Key Distribution Central''. In the normal
1653 mode, clients aquire tickets out of band and then invokes a one
1654 roundtrip AP-REQ and AP-REP exchange. In the proxied mode, which can
1655 be used by clients without IP addresses or without connectivity to the
1656 KDC (e.g., when the KDC is IPv4 and the client is IPV6-only), the
1657 client uses the server to proxy ticket requests and finishes with the
1658 AP-REQ/AP-REP exchange. In infrastructure mode (proxied or
1659 otherwise), the client nor server need to implement any callbacks
1660 (this will likely change later, to allow a server to authorize users,
1661 similar to the GSSAPI callback).
1663 XXX: update when implementation has matured
1665 @c **********************************************************
1666 @c ***************** Global Functions *********************
1667 @c **********************************************************
1668 @node Global Functions
1669 @chapter Global Functions
1671 @include texi/init.c.texi
1672 @include texi/done.c.texi
1673 @include texi/listmech.c.texi
1674 @include texi/supportp.c.texi
1675 @include texi/suggest.c.texi
1676 @include texi/register.c.texi
1679 @c **********************************************************
1680 @c ****************** Callback Functions ******************
1681 @c **********************************************************
1682 @node Callback Functions
1683 @chapter Callback Functions
1686 The callback is used by mechanisms to retrieve information, such as
1687 username and password, from the application. In a server, the
1688 callback is used to decide whether a user is permitted to log in or
1689 not. You tell the library of your callback function by calling
1690 @code{gsasl_callback_set}.
1692 Since your callback may need to access to data from other parts of
1693 your application, there are hooks to store and retrieve application
1694 specific pointers. This avoid the use of global variables in your
1695 application, which wouldn't be thread safe. You store a pointer to
1696 some information (opaque from the point of view of the library) by
1697 calling @code{gsasl_callback_hook_set} and can later retrieve this
1698 data in your callback by calling @code{gsasl_callback_hook_get}.
1700 @include texi/callback.c.texi
1702 @c **********************************************************
1703 @c ****************** Property Functions ******************
1704 @c **********************************************************
1705 @node Property Functions
1706 @chapter Property Functions
1709 @include texi/property.c.texi
1712 @c **********************************************************
1713 @c ***************** Session Functions ********************
1714 @c **********************************************************
1715 @node Session Functions
1716 @chapter Session Functions
1717 @cindex SASL sessions
1719 @include texi/xstart.c.texi
1720 @include texi/xstep.c.texi
1721 @include texi/xfinish.c.texi
1722 @include texi/xcode.c.texi
1726 @c **********************************************************
1727 @c ******************* Utilities **************************
1728 @c **********************************************************
1732 @include texi/saslprep.c.texi
1733 @include texi/base64.c.texi
1734 @include texi/md5pwd.c.texi
1735 @include texi/crypto.c.texi
1739 @c **********************************************************
1740 @c ******************* Errors ****************************
1741 @c **********************************************************
1742 @node Error Handling
1743 @chapter Error Handling
1744 @cindex Error Handling
1746 Most functions in the GNU SASL Library are returning an error if they
1747 fail. For this reason, the application should always catch the error
1748 condition and take appropriate measures, for example by releasing the
1749 resources and passing the error up to the caller, or by displaying a
1750 descriptive message to the user and cancelling the operation.
1752 Some error values do not indicate a system error or an error in the
1753 operation, but the result of an operation that failed properly.
1756 * Error values:: A list of all error values used.
1757 * Error strings:: How to get a descriptive string from a value.
1761 @section Error values
1763 Errors are returned as an @code{int}. Except for the OK case an
1764 application should always use the constants instead of their numeric
1765 value. Applications are encouraged to use the constants even for OK
1766 as it improves readability. Possible values are:
1769 @item @code{GSASL_OK}
1770 This value indicates success. The value of this error is guaranteed
1771 to always be @code{0} so you may use it in boolean constructs.
1773 @include gsasl-api-error-labels.texi
1778 @section Error strings
1780 @include texi/error.c.texi
1782 @c **********************************************************
1783 @c *********************** Examples ***********************
1784 @c **********************************************************
1789 This chapter contains example code which illustrate how the GNU SASL
1790 Library can be used when writing your own application.
1793 * Example 1:: SASL client.
1794 * Example 2:: SASL client where server send data first.
1795 * Example 3:: SASL client, with a choice of mechanism to use.
1796 * Example 4:: SASL client, with callback for user info.
1803 @verbatiminclude client.c
1810 @verbatiminclude client-serverfirst.c
1817 @verbatiminclude client-mech.c
1824 @verbatiminclude client-callback.c
1828 @c **********************************************************
1829 @c ******************* Acknowledgements *******************
1830 @c **********************************************************
1831 @node Acknowledgements
1832 @chapter Acknowledgements
1834 The makefiles, manuals, etc borrowed much from Libgcrypt written by
1837 Cryptographic functions for some SASL mechanisms uses Libgcrypt by
1838 Werner Koch et al. The NTLM mechanism uses Libntlm by Grant Edwards
1839 et al, using code from Samba written by Andrew Tridgell, and now
1840 maintained by Simon Josefsson. The KERBEROS_V5 mechanism uses Shishi
1841 by Simon Josefsson. The GSSAPI mechanism uses a GSS-API
1842 implementation, such as GSSLib by Simon Josefsson.
1844 Gnulib is used to simplify portability.
1846 This manual borrows text from the SASL specification.
1848 @c **********************************************************
1849 @c ******************** Invoking gsasl ********************
1850 @c **********************************************************
1851 @node Invoking gsasl
1852 @chapter Invoking gsasl
1855 @cindex invoking @command{gsasl}
1856 @cindex command line
1860 GNU SASL (gsasl) -- Command line interface to libgsasl.
1862 @majorheading Description
1863 @code{gsasl} is the main program of GNU SASL.
1865 This section only lists the commands and options available.
1867 Mandatory or optional arguments to long options are also mandatory or
1868 optional for any corresponding short options.
1870 @majorheading Commands
1871 @code{gsasl} recognizes these commands:
1874 -c, --client Act as client (the default).
1875 --client-mechanisms Write name of supported client mechanisms
1876 separated by space to stdout.
1877 -s, --server Act as server.
1878 --server-mechanisms Write name of supported server mechanisms
1879 separated by space to stdout.
1882 @majorheading Network Options
1884 Normally the SASL negotiation is performed on the terminal, with
1885 reading from stdin and writing to stdout. It is also possible to
1886 perform the negotiation with a server over a TCP network connection.
1889 --connect=HOSTNAME[:SERVICE]
1890 Connect to TCP server and negotiate on stream
1891 instead of stdin/stdout. SERVICE is the protocol
1892 service, or an integer denoting the port, and
1893 defaults to 143 (imap) if not specified. Also sets
1894 the --hostname default.
1897 @majorheading Miscellaneous Options:
1899 These parameters affect overall behaviour.
1902 -d, --application-data After authentication, read data from stdin and run
1903 it through the mechanism's security layer and
1904 print it base64 encoded to stdout. The default is
1905 to terminate after authentication.
1906 --imap Use a IMAP-like logon procedure (client only).
1907 Also sets the --service default to "imap".
1908 -m, --mechanism=STRING Mechanism to use.
1909 --no-client-first Disallow client to send data first (client only).
1912 @majorheading SASL Mechanism Options
1914 These options modify the behaviour of the callbacks (@pxref{Callback
1915 Functions}) in the library. The default is the query the user on the
1919 -n, --anonymous-token=STRING Token for anonymous authentication, usually
1920 mail address (ANONYMOUS only).
1921 -a, --authentication-id=STRING Identity of credential owner.
1922 -z, --authorization-id=STRING Identity to request service for.
1923 --disable-cleartext-validate
1924 Disable cleartext validate hook, forcing server to
1925 prompt for password.
1926 --enable-cram-md5-validate Validate CRAM-MD5 challenge and response
1928 --hostname=STRING Set the name of the server with the requested
1930 -p, --password=STRING Password for authentication (insecure for
1931 non-testing purposes).
1932 --passcode=NUMBER Passcode for authentication (SECURID only).
1933 --quality-of-protection=<auth | auth-int | auth-conf>
1934 How application payload will be protected. "auth"
1935 means no protection, "auth-int" means integrity
1936 protection, "auth-conf" means integrity and
1937 confidentialiy protection. Currently only used by
1938 DIGEST-MD5, where the default is "auth-conf".
1939 -r, --realm=STRING Realm. Defaults to hostname.
1940 --service=STRING Set the requested service name (should be a
1941 registered GSSAPI host based service name).
1942 --service-name=STRING Set the generic server name in case of a
1943 replicated server (DIGEST-MD5 only).
1944 -x, --maxbuf=NUMBER Indicate maximum buffer size (DIGEST-MD5 only).
1947 @majorheading STARTTLS options
1950 --starttls Force use of STARTTLS. The default is to use
1951 STARTTLS when available. (default=off)
1952 --no-starttls Unconditionally disable STARTTLS.
1954 --x509-ca-file=FILE File containing one or more X.509 Certificate
1955 Authorities certificates in PEM format, used
1956 to verify the certificate received from the
1957 server. If not specified, no verification of
1958 the remote server certificate will be done.
1959 --x509-cert-file=FILE File containing client X.509 certificate in PEM
1960 format. Used together with --x509-key-file
1961 to specify the certificate/key pair.
1962 --x509-key-file=FILE Private key for the client X.509 certificate in
1963 PEM format. Used together with
1964 --x509-key-file to specify the
1965 certificate/key pair.
1968 @majorheading Other Options
1970 These are some standard parameters.
1973 -q, --quiet, --silent Don't produce any diagnostic output.
1974 -v, --verbose Produce verbose output.
1976 -?, --help Give this help list
1977 --usage Give a short usage message
1978 -V, --version Print program version
1981 @c **********************************************************
1982 @c ******************* Appendices *************************
1983 @c **********************************************************
1985 @node Protocol Clarifications
1986 @appendix Protocol Clarifications
1988 This appendix contain clarification to various SASL specification that
1989 we felt were necessary to include, if for nothing else it may serve as
1990 a guide for other implementors that worry about the same issues.
1993 * Use of SASLprep in CRAM-MD5::
1994 * Use of SASLprep in LOGIN::
1997 @node Use of SASLprep in CRAM-MD5
1998 @section Use of SASLprep in CRAM-MD5
2000 The specification, as of @file{draft-ietf-sasl-crammd5-04.txt}, is
2001 silent on whether a SASL server implementation applying
2002 @acronym{SASLprep} on a password received from an external, non-SASL
2003 specific database (i.e., the passwords are not stored in
2004 @acronym{SASLprep} form in the database), should set or clear the
2005 AllowUnassigned bit. The motivation for the AU-bit in
2006 @acronym{StringPrep}/@acronym{SASLprep} is for stored vs query
2007 strings. It could be argued that in this situation the server can
2008 treat the external password either as a stored string (from a
2009 database) or as a query (the server uses the string as a query into
2010 the fixed HMAC-MD5 hash).
2012 The specification is also unclear on whether clients should set or
2013 clear the AllowUnassigned flag.
2015 In the server, GNU SASL apply @acronym{SASLprep} to the password with
2016 the AllowUnassigned bit cleared.
2018 @node Use of SASLprep in LOGIN
2019 @section Use of SASLprep in LOGIN
2021 The non-standard mechanism LOGIN presumably does not support
2022 non-ASCII. We suggest that the client should send unprepared UTF-8
2023 and that the server apply SASLprep with the AllowUnassigned bit
2024 cleared on the received username and password.
2026 @c **********************************************************
2027 @c ******************* Old Functions **********************
2028 @c **********************************************************
2030 @appendix Old Functions
2031 @cindex Deprecated functions
2032 @cindex Obsolete functions
2034 As GNU SASL is still under heavy development, some API functions have
2035 been found to be less useful. Those old API functions will be
2036 supported during a transition period. Refer to the NEWS file to find
2037 out since when a function has been deprecated.
2039 @include texi/obsolete.c.texi
2041 @section Obsolete callback function prototypes
2043 @deftypefn Prototype int (*Gsasl_client_callback_anonymous) (Gsasl_session_ctx * @var{ctx}, char * @var{out}, size_t * @var{outlen})
2045 @var{ctx}: libgsasl handle.
2047 @var{out}: output array with client token.
2049 @var{outlen}: on input the maximum size of the output array, on output
2050 contains the actual size of the output array.
2052 Type of callback function the application implements. It should
2053 populate the output array with some input from the user and set the
2054 output array length, and return @code{GSASL_OK}, or fail with an error
2057 If OUT is NULL, the function should only populate the output length
2058 field with the length, and return GSASL_OK. This usage may be used by
2059 the caller to allocate the proper buffer size.
2063 @deftypefn Prototype int (*Gsasl_server_callback_anonymous) (Gsasl_session_ctx * @var{ctx}, const char * @var{token})
2065 @var{ctx}: libgsasl handle.
2067 @var{ctx}: output array with client token.
2069 @var{ctx}: on input the maximum size of the output array, on output
2070 contains the actual size of the output array. If OUT is
2072 Type of callback function the application implements. It should
2073 return @code{GSASL_OK} if user should be permitted anonymous access,
2074 otherwise @code{GSASL_AUTHENTICATION_ERROR}.
2078 @include gsasl-callback-authentication.texi
2079 @include gsasl-callback-authorization.texi
2080 @include gsasl-callback-client-service.texi
2081 @include gsasl-callback-cram-md5.texi
2082 @include gsasl-callback-digest-md5.texi
2084 @deftypefn Prototype int (*Gsasl_server_callback_external) (Gsasl_session_ctx * @var{ctx})
2086 @var{ctx}: libgsasl handle.
2088 Type of callback function the application implements. It should
2089 return @code{GSASL_OK} if user is authenticated by out of band means,
2090 otherwise @code{GSASL_AUTHENTICATION_ERROR}.
2094 @include gsasl-callback-gssapi.texi
2095 @include gsasl-callback-passcode.texi
2096 @include gsasl-callback-password.texi
2097 @include gsasl-callback-retrieve.texi
2098 @include gsasl-callback-securid.texi
2099 @include gsasl-callback-server-service.texi
2100 @include gsasl-callback-validate.texi
2102 @node Copying This Manual
2103 @appendix Copying This Manual
2106 * GNU Free Documentation License:: License for copying this manual.
2112 @unnumbered Concept Index
2116 @node Function and Data Index
2117 @unnumbered Function and Data Index