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