| 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 |