authuserdb: Try using a separate get-token script.

[hcoop/debian/courier-authlib.git] / auth_sasl.3

.\"  <!-- $Id: auth_sasl.sgml,v 1.3 2007/04/01 00:21:34 mrsam Exp $ -->
.\"  <!-- Copyright 2004 Double Precision, Inc.  See COPYING for -->
.\"  <!-- distribution information. -->
.\"     Title: auth_sasl
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.72.0 <http://docbook.sf.net/>
.\"      Date: 04/06/2007
.\"    Manual: Double Precision, Inc.
.\"    Source: Double Precision, Inc.
.\"
.TH "AUTH_SASL" "3" "04/06/2007" "Double Precision, Inc." "Double Precision, Inc."
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
auth_sasl \- SASL implementation
.SH "SYNOPSIS"
.sp
.RS 4
.nf
#include <courierauthsasl.h>
.fi
.RE
.HP 17
.BI "int rc=auth_sasl(const\ char\ *" "method" ", const\ char\ *" "initialresponse" ", char\ *(*" "conversation_func" ")(const\ char\ *,\ void\ *), void\ *" "callback_arg" ", char\ **" "authtype_ret" ", char\ **" "authdata_ret" ");"
.SH "DESCRIPTION"
.PP

\fBauth_sasl\fR
is a generic
SASL
server implementation.
\fImethod\fR
is the requested
SASL
method. At this time
\fBauth_sasl\fR
knows how to handle the following SASL methods:
.RS 4
\h'-04'\(bu\h'+03'LOGIN
.RE
.RS 4
\h'-04'\(bu\h'+03'PLAIN
.RE
.RS 4
\h'-04'\(bu\h'+03'CRAM\-MD5
.RE
.RS 4
\h'-04'\(bu\h'+03'CRAM\-SHA1
.RE
.PP

\fIinitialresponse\fR
is a base64\-encoded initial response provided in the client's
SASL
request.
\fIinitialresponse\fR
must be
NULL
if an initial response was not included in the client's
SASL
request.
.PP

\fIconversation_func\fR
is the application\-implemented
SASL
conversation callback function.
\fIconversation_func\fR
receives a base64\-encoded
SASL
prompt, and the
\fIcallback_arg\fR
argument to
\fBauth_sasl\fR.
\fIconversation_func\fR
must return a buffer containing the base64\-encoded reply from the client.
\fBauth_sasl\fR
will
\fBfree\fR(3)
this buffer when it's done.
\fIconversation_func\fR
should return
NULL
to abort the
SASL
conversation.
.SH "RETURNS"
.PP
If the
SASL
conversation succesfully completes,
\fBauth_sasl\fR
initializes
\fI*authtype_ret\fR
and
\fI*authdata_ret\fR. They will be set to a
\fBmalloc\fR(3)\-ed buffers that can be directly passed as arguments to
\fI\fBauth_generic\fR(3)\fR\&[1]. It is the application's responsibility to
\fBfree\fR(3)
these buffers when it's done with them.
.PP

\fBauth_sasl\fR
returns
AUTHSASL_OK
when the
SASL
conversation succesfully completes, and
\fI*authtype_ret\fR
and
\fI*authdata_ret\fR
are succesfully assembled. Any other return indicates an error condition. Right now two error conditions are defined:
.PP
AUTHSASL_ABORTED
.RS 4
The
SASL
conversation was aborted by the client.
.RE
.PP
AUTHSASL_ERROR
.RS 4
General error (insufficient memory, or some other reason). Check
\fIerrno\fR
for any clues.
.RE
.SH "SEE ALSO"
.PP

\fI\fBauthlib\fR(3)\fR\&[2],
\fI\fBauth_generic\fR(3)\fR\&[1].
.SH "REFERENCES"
.IP " 1." 4
\fBauth_generic\fR(3)
.RS 4
\%auth_generic.html
.RE
.IP " 2." 4
\fBauthlib\fR(3)
.RS 4
\%authlib.html
.RE