-.\" <!-- $Id: auth_sasl.sgml,v 1.3 2007/04/01 00:21:34 mrsam Exp $ -->
-.\" <!-- Copyright 2004 Double Precision, Inc. See COPYING for -->
+'\" t
+.\" <!-- 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
+.\" 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" "04/06/2007" "Double Precision, Inc." "Double Precision, Inc."
+.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 \- 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" ");"
+.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.
+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
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+LOGIN
.RE
+.sp
.RS 4
-\h'-04'\(bu\h'+03'PLAIN
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+PLAIN
.RE
+.sp
.RS 4
-\h'-04'\(bu\h'+03'CRAM\-MD5
+.ie n \{\
+\h'-04'\(bu\h'+03'\c
+.\}
+.el \{\
+.sp -1
+.IP \(bu 2.3
+.\}
+CRAM\-MD5
.RE
+.sp
.RS 4
-\h'-04'\(bu\h'+03'CRAM\-SHA1
+.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's
+is a base64\-encoded initial response provided in the client\*(Aqs
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\*(Aqs
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\*(Aqs 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
+\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's done with them.
+these buffers when it\*(Aqs 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"
+\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
-\%auth_generic.html
+\%http://www.courier-mta.org/authlib/auth_generic.html
.RE
.IP " 2." 4
\fBauthlib\fR(3)
.RS 4
-\%authlib.html
+\%http://www.courier-mta.org/authlib/authlib.html
.RE
HCoop / hcoop / debian / courier-authlib.git / blobdiff