auth_sasl.3

   1 .\"  <!-- $Id: auth_sasl.sgml,v 1.4 2008/07/13 21:58:26 mrsam Exp $ -->
   2 .\"  <!-- Copyright 2004-2008 Double Precision, Inc.  See COPYING for -->
   3 .\"  <!-- distribution information. -->
   4 .\"     Title: auth_sasl
   5 .\"    Author:
   6 .\" Generator: DocBook XSL Stylesheets v1.73.2 <http://docbook.sf.net/>
   7 .\"      Date: 08/23/2008
   8 .\"    Manual: Double Precision, Inc.
   9 .\"    Source: Double Precision, Inc.
  10 .\"
  11 .TH "AUTH_SASL" "3" "08/23/2008" "Double Precision, Inc." "Double Precision, Inc."
  12 .\" disable hyphenation
  13 .nh
  14 .\" disable justification (adjust text to left margin only)
  15 .ad l
  16 .SH "NAME"
  17 auth_sasl, auth_sasl_ex - SASL implementation
  18 .SH "SYNOPSIS"
  19 .sp
  20 .RS 4
  21 .nf
  22 #include <courierauthsasl\.h>
  23 .fi
  24 .RE
  25 .HP 17
  26 .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" ");"
  27 .HP 20
  28 .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" ");"
  29 .SH "DESCRIPTION"
  30 .PP
  31
  32 \fBauth_sasl\fR
  33 is a generic
  34 SASL
  35 server implementation\.
  36 \fImethod\fR
  37 is the requested
  38 SASL
  39 method\. At this time
  40 \fBauth_sasl\fR
  41 knows how to handle the following SASL methods:
  42 .sp
  43 .RS 4
  44 \h'-04'\(bu\h'+03'LOGIN
  45 .RE
  46 .sp
  47 .RS 4
  48 \h'-04'\(bu\h'+03'PLAIN
  49 .RE
  50 .sp
  51 .RS 4
  52 \h'-04'\(bu\h'+03'CRAM\-MD5
  53 .RE
  54 .sp
  55 .RS 4
  56 \h'-04'\(bu\h'+03'CRAM\-SHA1
  57 .RE
  58 .PP
  59
  60 \fIinitialresponse\fR
  61 is a base64\-encoded initial response provided in the client\'s
  62 SASL
  63 request\.
  64 \fIinitialresponse\fR
  65 must be
  66 NULL
  67 if an initial response was not included in the client\'s
  68 SASL
  69 request\.
  70 .PP
  71
  72 \fIconversation_func\fR
  73 is the application\-implemented
  74 SASL
  75 conversation callback function\.
  76 \fIconversation_func\fR
  77 receives a base64\-encoded
  78 SASL
  79 prompt, and the
  80 \fIcallback_arg\fR
  81 argument to
  82 \fBauth_sasl\fR\.
  83 \fIconversation_func\fR
  84 must return a buffer containing the base64\-encoded reply from the client\.
  85 \fBauth_sasl\fR
  86 will
  87 \fBfree\fR(3)
  88 this buffer when it\'s done\.
  89 \fIconversation_func\fR
  90 should return
  91 NULL
  92 to abort the
  93 SASL
  94 conversation\.
  95 .PP
  96
  97 \fBauth_sasl_ex\fR
  98 is a version of
  99 \fBauth_sasl\fR
 100 that recognizes the
 101 EXTERNAL
 102 SASL
 103 method\. It takes an extra parameter,
 104 \fIexternalauth\fR\. This parameter should be set to indicate an login that was authenticated via some other means, such as, perhaps, an
 105 SSL
 106 certificate, or
 107 NULL
 108 if no externally\-authenticated identity was established\.
 109 .PP
 110 If
 111 \fImethod\fR
 112 is not
 113 EXTERNAL,
 114 \fBauth_sasl_ex\fR
 115 is identical to
 116 \fBauth_sasl\fR, and
 117 \fIexternalauth\fR
 118 is ignored\. Otherwise, if
 119 \fImethod\fR
 120 is
 121 EXTERNAL
 122 and
 123 \fIexternalauth\fR
 124 is not
 125 NULL,
 126 \fBauth_sasl_ex\fR
 127 returns
 128 AUTHSASL_OK, and sets
 129 \fI*authtype_ret\fR
 130 and
 131 \fI*authdata_ret\fR
 132 accordingly, so that the subsequent invocation of
 133 \fBauth_generic\fR() returns authentication information for the login ID specified by
 134 \fIexternalauth\fR\.
 135 .SH "RETURNS"
 136 .PP
 137 If the
 138 SASL
 139 conversation succesfully completes,
 140 \fBauth_sasl\fR
 141 or
 142 \fBauth_sasl_ex\fR
 143 initializes
 144 \fI*authtype_ret\fR
 145 and
 146 \fI*authdata_ret\fR\. They will be set to a
 147 \fBmalloc\fR(3)\-ed buffers that can be directly passed as arguments to
 148 \fI\fBauth_generic\fR(3)\fR\&[1]\. It is the application\'s responsibility to
 149 \fBfree\fR(3)
 150 these buffers when it\'s done with them\.
 151 .PP
 152
 153 \fBauth_sasl\fR
 154 or
 155 \fBauth_sasl_ex\fR
 156 returns
 157 AUTHSASL_OK
 158 when the
 159 SASL
 160 conversation succesfully completes, and
 161 \fI*authtype_ret\fR
 162 and
 163 \fI*authdata_ret\fR
 164 are succesfully assembled\. Any other return indicates an error condition\. Right now two error conditions are defined:
 165 .PP
 166 AUTHSASL_ABORTED
 167 .RS 4
 168 The
 169 SASL
 170 conversation was aborted by the client\.
 171 .RE
 172 .PP
 173 AUTHSASL_ERROR
 174 .RS 4
 175 General error (insufficient memory, or some other reason)\. Check
 176 \fIerrno\fR
 177 for any clues\.
 178 .RE
 179 .SH "SEE ALSO"
 180 .PP
 181
 182 \fI\fBauthlib\fR(3)\fR\&[2],
 183 \fI\fBauth_generic\fR(3)\fR\&[1]\.
 184 .SH "NOTES"
 185 .IP " 1." 4
 186 \fBauth_generic\fR(3)
 187 .RS 4
 188 \%auth_generic.html
 189 .RE
 190 .IP " 2." 4
 191 \fBauthlib\fR(3)
 192 .RS 4
 193 \%authlib.html
 194 .RE