auth_sasl.3

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