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