-.\" <!-- $Id: auth_sasl.sgml,v 1.4 2008/07/13 21:58:26 mrsam Exp $ -->
+'\" t
.\" <!-- 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
+.\" Author: [FIXME: author] [see http://docbook.sf.net/el/author]
+.\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/>
+.\" Date: 08/25/2013
.\" Manual: Double Precision, Inc.
.\" Source: Double Precision, Inc.
+.\" Language: English
.\"
-.TH "AUTH_SASL" "3" "08/23/2008" "Double Precision, Inc." "Double Precision, Inc."
+.TH "AUTH_SASL" "3" "08/25/2013" "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
+auth_sasl, auth_sasl_ex \- SASL implementation
.SH "SYNOPSIS"
.sp
-.RS 4
.nf
-#include <courierauthsasl\.h>
+#include <courierauthsasl\&.h>
.fi
-.RE
-.HP 17
+.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 20
+.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
+EXTERNALSASL
+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\.
+if no externally\-authenticated identity was established\&.
.PP
If
\fImethod\fR
is identical to
\fBauth_sasl\fR, and
\fIexternalauth\fR
-is ignored\. Otherwise, if
+is ignored\&. Otherwise, if
\fImethod\fR
is
EXTERNAL
\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\.
+\fIexternalauth\fR\&.
.SH "RETURNS"
.PP
If the
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
\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]\.
+\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
+\%[set $man.base.url.for.relative.links]/auth_generic.html
.RE
.IP " 2." 4
\fBauthlib\fR(3)
.RS 4
-\%authlib.html
+\%[set $man.base.url.for.relative.links]/authlib.html
.RE
HCoop / hcoop / debian / courier-authlib.git / blobdiff