Imported Upstream version 0.63.0

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

.\"  <!-- $Id: auth_sasl.sgml,v 1.4 2008/07/13 21:58:26 mrsam Exp $ -->
.\"  <!-- Copyright 2004-2008 Double Precision, Inc.  See COPYING for -->
.\"  <!-- distribution information. -->
.\"     Title: auth_sasl
.\"    Author: 
.\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
.\"      Date: 08/23/2008
.\"    Manual: Double Precision, Inc.
.\"    Source: Double Precision, Inc.
.\"
.TH "AUTH_SASL" "3" "08/23/2008" "Double Precision, Inc." "Double Precision, Inc."
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.SH "NAME"
auth_sasl, auth_sasl_ex - 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" ");"
.HP 20
.BI "int rc=auth_sasl_ex(const\ char\ *" "method" ", const\ char\ *" "initialresponse" ", const\ char\ *" "externalauth" ", 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:
.sp
.RS 4
\h'-04'\(bu\h'+03'LOGIN
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'PLAIN
.RE
.sp
.RS 4
\h'-04'\(bu\h'+03'CRAM\-MD5
.RE
.sp
.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\.
.PP

\fBauth_sasl_ex\fR
is a version of
\fBauth_sasl\fR
that recognizes the
EXTERNAL
SASL
method\. It takes an extra parameter,
\fIexternalauth\fR\. This parameter should be set to indicate an login that was authenticated via some other means, such as, perhaps, an
SSL
certificate, or
NULL
if no externally\-authenticated identity was established\.
.PP
If
\fImethod\fR
is not
EXTERNAL,
\fBauth_sasl_ex\fR
is identical to
\fBauth_sasl\fR, and
\fIexternalauth\fR
is ignored\. Otherwise, if
\fImethod\fR
is
EXTERNAL
and
\fIexternalauth\fR
is not
NULL,
\fBauth_sasl_ex\fR
returns
AUTHSASL_OK, and sets
\fI*authtype_ret\fR
and
\fI*authdata_ret\fR
accordingly, so that the subsequent invocation of
\fBauth_generic\fR() returns authentication information for the login ID specified by
\fIexternalauth\fR\.
.SH "RETURNS"
.PP
If the
SASL
conversation succesfully completes,
\fBauth_sasl\fR
or
\fBauth_sasl_ex\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
or
\fBauth_sasl_ex\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 "NOTES"
.IP " 1." 4
\fBauth_generic\fR(3)
.RS 4
\%auth_generic.html
.RE
.IP " 2." 4
\fBauthlib\fR(3)
.RS 4
\%authlib.html
.RE