-.\" <!-- $Id: auth_sasl.sgml,v 1.3 2007/04/01 00:21:34 mrsam Exp $ -->
-.\" <!-- Copyright 2004 Double Precision, Inc. See COPYING for -->
+.\" <!-- $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.72.0 <http://docbook.sf.net/>
-.\" Date: 04/06/2007
+.\" 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" "04/06/2007" "Double Precision, Inc." "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 \- SASL implementation
+auth_sasl, auth_sasl_ex - SASL implementation
.SH "SYNOPSIS"
.sp
.RS 4
.nf
-#include <courierauthsasl.h>
+#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" ");"
+.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.
+server implementation\.
\fImethod\fR
is the requested
SASL
-method. At this time
+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
+is a base64\-encoded initial response provided in the client\'s
SASL
-request.
+request\.
\fIinitialresponse\fR
must be
NULL
-if an initial response was not included in the client's
+if an initial response was not included in the client\'s
SASL
-request.
+request\.
.PP
\fIconversation_func\fR
is the application\-implemented
SASL
-conversation callback function.
+conversation callback function\.
\fIconversation_func\fR
receives a base64\-encoded
SASL
prompt, and the
\fIcallback_arg\fR
argument to
-\fBauth_sasl\fR.
+\fBauth_sasl\fR\.
\fIconversation_func\fR
-must return a buffer containing the base64\-encoded reply from the client.
+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.
+this buffer when it\'s done\.
\fIconversation_func\fR
should return
NULL
to abort the
SASL
-conversation.
+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
+\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
+\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.
+these buffers when it\'s done with them\.
.PP
\fBauth_sasl\fR
+or
+\fBauth_sasl_ex\fR
returns
AUTHSASL_OK
when the
\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:
+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.
+conversation was aborted by the client\.
.RE
.PP
AUTHSASL_ERROR
.RS 4
-General error (insufficient memory, or some other reason). Check
+General error (insufficient memory, or some other reason)\. Check
\fIerrno\fR
-for any clues.
+for any clues\.
.RE
.SH "SEE ALSO"
.PP
\fI\fBauthlib\fR(3)\fR\&[2],
-\fI\fBauth_generic\fR(3)\fR\&[1].
-.SH "REFERENCES"
+\fI\fBauth_generic\fR(3)\fR\&[1]\.
+.SH "NOTES"
.IP " 1." 4
\fBauth_generic\fR(3)
.RS 4
HCoop / hcoop / debian / courier-authlib.git / blobdiff