X-Git-Url: https://git.hcoop.net/hcoop/debian/courier-authlib.git/blobdiff_plain/d9898ee81388d1eff40cf71e85d9ce9b5c1401fe..781cfcb8fd50934c470e0dabf79d32ab333dec68:/auth_sasl.3

diff --git a/auth_sasl.3 b/auth_sasl.3
index 7adcd30..4ba75d3 100644
--- a/auth_sasl.3
+++ b/auth_sasl.3
@@ -1,108 +1,158 @@
-.\"  <!-- $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
@@ -111,27 +161,27 @@ 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:
+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