auth_sasl.3

   1 .\"  <!-- $Id: auth_sasl.sgml,v 1.3 2007/04/01 00:21:34 mrsam Exp $ -->
   2 .\"  <!-- Copyright 2004 Double Precision, Inc.  See COPYING for -->
   3 .\"  <!-- distribution information. -->
   4 .\"     Title: auth_sasl
   5 .\"    Author:
   6 .\" Generator: DocBook XSL Stylesheets v1.72.0 <http://docbook.sf.net/>
   7 .\"      Date: 04/06/2007
   8 .\"    Manual: Double Precision, Inc.
   9 .\"    Source: Double Precision, Inc.
  10 .\"
  11 .TH "AUTH_SASL" "3" "04/06/2007" "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 \- 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 .SH "DESCRIPTION"
  28 .PP
  29
  30 \fBauth_sasl\fR
  31 is a generic
  32 SASL
  33 server implementation.
  34 \fImethod\fR
  35 is the requested
  36 SASL
  37 method. At this time
  38 \fBauth_sasl\fR
  39 knows how to handle the following SASL methods:
  40 .RS 4
  41 \h'-04'\(bu\h'+03'LOGIN
  42 .RE
  43 .RS 4
  44 \h'-04'\(bu\h'+03'PLAIN
  45 .RE
  46 .RS 4
  47 \h'-04'\(bu\h'+03'CRAM\-MD5
  48 .RE
  49 .RS 4
  50 \h'-04'\(bu\h'+03'CRAM\-SHA1
  51 .RE
  52 .PP
  53
  54 \fIinitialresponse\fR
  55 is a base64\-encoded initial response provided in the client's
  56 SASL
  57 request.
  58 \fIinitialresponse\fR
  59 must be
  60 NULL
  61 if an initial response was not included in the client's
  62 SASL
  63 request.
  64 .PP
  65
  66 \fIconversation_func\fR
  67 is the application\-implemented
  68 SASL
  69 conversation callback function.
  70 \fIconversation_func\fR
  71 receives a base64\-encoded
  72 SASL
  73 prompt, and the
  74 \fIcallback_arg\fR
  75 argument to
  76 \fBauth_sasl\fR.
  77 \fIconversation_func\fR
  78 must return a buffer containing the base64\-encoded reply from the client.
  79 \fBauth_sasl\fR
  80 will
  81 \fBfree\fR(3)
  82 this buffer when it's done.
  83 \fIconversation_func\fR
  84 should return
  85 NULL
  86 to abort the
  87 SASL
  88 conversation.
  89 .SH "RETURNS"
  90 .PP
  91 If the
  92 SASL
  93 conversation succesfully completes,
  94 \fBauth_sasl\fR
  95 initializes
  96 \fI*authtype_ret\fR
  97 and
  98 \fI*authdata_ret\fR. They will be set to a
  99 \fBmalloc\fR(3)\-ed buffers that can be directly passed as arguments to
 100 \fI\fBauth_generic\fR(3)\fR\&[1]. It is the application's responsibility to
 101 \fBfree\fR(3)
 102 these buffers when it's done with them.
 103 .PP
 104
 105 \fBauth_sasl\fR
 106 returns
 107 AUTHSASL_OK
 108 when the
 109 SASL
 110 conversation succesfully completes, and
 111 \fI*authtype_ret\fR
 112 and
 113 \fI*authdata_ret\fR
 114 are succesfully assembled. Any other return indicates an error condition. Right now two error conditions are defined:
 115 .PP
 116 AUTHSASL_ABORTED
 117 .RS 4
 118 The
 119 SASL
 120 conversation was aborted by the client.
 121 .RE
 122 .PP
 123 AUTHSASL_ERROR
 124 .RS 4
 125 General error (insufficient memory, or some other reason). Check
 126 \fIerrno\fR
 127 for any clues.
 128 .RE
 129 .SH "SEE ALSO"
 130 .PP
 131
 132 \fI\fBauthlib\fR(3)\fR\&[2],
 133 \fI\fBauth_generic\fR(3)\fR\&[1].
 134 .SH "REFERENCES"
 135 .IP " 1." 4
 136 \fBauth_generic\fR(3)
 137 .RS 4
 138 \%auth_generic.html
 139 .RE
 140 .IP " 2." 4
 141 \fBauthlib\fR(3)
 142 .RS 4
 143 \%authlib.html
 144 .RE