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://www.docbook.org/tdg5/en/html/author]
   6 .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/>
   7 .\"      Date: 09/08/2017
   8 .\"    Manual: Double Precision, Inc.
   9 .\"    Source: Double Precision, Inc.
  10 .\"  Language: English
  11 .\"
  12 .TH "AUTH_SASL" "3" "09/08/2017" "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 EXTERNAL
 140 SASL
 141 method\&. It takes an extra parameter,
 142 \fIexternalauth\fR\&. This parameter should be set to indicate an login that was authenticated via some other means, such as, perhaps, an
 143 SSL
 144 certificate, or
 145 NULL
 146 if no externally\-authenticated identity was established\&.
 147 .PP
 148 If
 149 \fImethod\fR
 150 is not
 151 EXTERNAL,
 152 \fBauth_sasl_ex\fR
 153 is identical to
 154 \fBauth_sasl\fR, and
 155 \fIexternalauth\fR
 156 is ignored\&. Otherwise, if
 157 \fImethod\fR
 158 is
 159 EXTERNAL
 160 and
 161 \fIexternalauth\fR
 162 is not
 163 NULL,
 164 \fBauth_sasl_ex\fR
 165 returns
 166 AUTHSASL_OK, and sets
 167 \fI*authtype_ret\fR
 168 and
 169 \fI*authdata_ret\fR
 170 accordingly, so that the subsequent invocation of
 171 \fBauth_generic\fR() returns authentication information for the login ID specified by
 172 \fIexternalauth\fR\&.
 173 .SH "RETURNS"
 174 .PP
 175 If the
 176 SASL
 177 conversation succesfully completes,
 178 \fBauth_sasl\fR
 179 or
 180 \fBauth_sasl_ex\fR
 181 initializes
 182 \fI*authtype_ret\fR
 183 and
 184 \fI*authdata_ret\fR\&. They will be set to a
 185 \fBmalloc\fR(3)\-ed buffers that can be directly passed as arguments to
 186 \m[blue]\fB\fBauth_generic\fR(3)\fR\m[]\&\s-2\u[1]\d\s+2\&. It is the application\*(Aqs responsibility to
 187 \fBfree\fR(3)
 188 these buffers when it\*(Aqs done with them\&.
 189 .PP
 190 \fBauth_sasl\fR
 191 or
 192 \fBauth_sasl_ex\fR
 193 returns
 194 AUTHSASL_OK
 195 when the
 196 SASL
 197 conversation succesfully completes, and
 198 \fI*authtype_ret\fR
 199 and
 200 \fI*authdata_ret\fR
 201 are succesfully assembled\&. Any other return indicates an error condition\&. Right now two error conditions are defined:
 202 .PP
 203 AUTHSASL_ABORTED
 204 .RS 4
 205 The
 206 SASL
 207 conversation was aborted by the client\&.
 208 .RE
 209 .PP
 210 AUTHSASL_ERROR
 211 .RS 4
 212 General error (insufficient memory, or some other reason)\&. Check
 213 \fIerrno\fR
 214 for any clues\&.
 215 .RE
 216 .SH "SEE ALSO"
 217 .PP
 218 \m[blue]\fB\fBauthlib\fR(3)\fR\m[]\&\s-2\u[2]\d\s+2,
 219 \m[blue]\fB\fBauth_generic\fR(3)\fR\m[]\&\s-2\u[1]\d\s+2\&.
 220 .SH "NOTES"
 221 .IP " 1." 4
 222 \fBauth_generic\fR(3)
 223 .RS 4
 224 \%http://www.courier-mta.org/authlib/auth_generic.html
 225 .RE
 226 .IP " 2." 4
 227 \fBauthlib\fR(3)
 228 .RS 4
 229 \%http://www.courier-mta.org/authlib/authlib.html
 230 .RE