Merge branch 'debian'

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

'\" t
.\"  <!-- Copyright 2004-2008 Double Precision, Inc.  See COPYING for -->
.\"  <!-- distribution information. -->
.\"     Title: auth_sasl
.\"    Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author]
.\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
.\"      Date: 09/08/2017
.\"    Manual: Double Precision, Inc.
.\"    Source: Double Precision, Inc.
.\"  Language: English
.\"
.TH "AUTH_SASL" "3" "09/08/2017" "Double Precision, Inc." "Double Precision, Inc."
.\" -----------------------------------------------------------------
.\" * Define some portability stuff
.\" -----------------------------------------------------------------
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.\" http://bugs.debian.org/507673
.\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html
.\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\" -----------------------------------------------------------------
.\" * set default formatting
.\" -----------------------------------------------------------------
.\" disable hyphenation
.nh
.\" disable justification (adjust text to left margin only)
.ad l
.\" -----------------------------------------------------------------
.\" * MAIN CONTENT STARTS HERE *
.\" -----------------------------------------------------------------
.SH "NAME"
auth_sasl, auth_sasl_ex \- SASL implementation
.SH "SYNOPSIS"
.sp
.nf
#include <courierauthsasl\&.h>
.fi
.HP \w'int\ rc=auth_sasl('u
.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 \w'int\ rc=auth_sasl_ex('u
.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
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
LOGIN
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
PLAIN
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CRAM\-MD5
.RE
.sp
.RS 4
.ie n \{\
\h'-04'\(bu\h'+03'\c
.\}
.el \{\
.sp -1
.IP \(bu 2.3
.\}
CRAM\-SHA1
.RE
.PP
\fIinitialresponse\fR
is a base64\-encoded initial response provided in the client\*(Aqs
SASL
request\&.
\fIinitialresponse\fR
must be
NULL
if an initial response was not included in the client\*(Aqs
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\*(Aqs 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
\m[blue]\fB\fBauth_generic\fR(3)\fR\m[]\&\s-2\u[1]\d\s+2\&. It is the application\*(Aqs responsibility to
\fBfree\fR(3)
these buffers when it\*(Aqs 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
\m[blue]\fB\fBauthlib\fR(3)\fR\m[]\&\s-2\u[2]\d\s+2,
\m[blue]\fB\fBauth_generic\fR(3)\fR\m[]\&\s-2\u[1]\d\s+2\&.
.SH "NOTES"
.IP " 1." 4
\fBauth_generic\fR(3)
.RS 4
\%http://www.courier-mta.org/authlib/auth_generic.html
.RE
.IP " 2." 4
\fBauthlib\fR(3)
.RS 4
\%http://www.courier-mta.org/authlib/authlib.html
.RE