Commit | Line | Data |
---|---|---|
b0322a85 | 1 | '\" t |
8d138742 | 2 | .\" <!-- Copyright 2004-2008 Double Precision, Inc. See COPYING for --> |
d9898ee8 | 3 | .\" <!-- distribution information. --> |
4 | .\" Title: auth_sasl | |
b0322a85 CE |
5 | .\" Author: [FIXME: author] [see http://docbook.sf.net/el/author] |
6 | .\" Generator: DocBook XSL Stylesheets v1.78.1 <http://docbook.sf.net/> | |
7 | .\" Date: 08/25/2013 | |
d9898ee8 | 8 | .\" Manual: Double Precision, Inc. |
9 | .\" Source: Double Precision, Inc. | |
b0322a85 | 10 | .\" Language: English |
d9898ee8 | 11 | .\" |
b0322a85 CE |
12 | .TH "AUTH_SASL" "3" "08/25/2013" "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 | .\" ----------------------------------------------------------------- | |
d9898ee8 | 25 | .\" disable hyphenation |
26 | .nh | |
27 | .\" disable justification (adjust text to left margin only) | |
28 | .ad l | |
b0322a85 CE |
29 | .\" ----------------------------------------------------------------- |
30 | .\" * MAIN CONTENT STARTS HERE * | |
31 | .\" ----------------------------------------------------------------- | |
d9898ee8 | 32 | .SH "NAME" |
b0322a85 | 33 | auth_sasl, auth_sasl_ex \- SASL implementation |
d9898ee8 | 34 | .SH "SYNOPSIS" |
35 | .sp | |
d9898ee8 | 36 | .nf |
b0322a85 | 37 | #include <courierauthsasl\&.h> |
d9898ee8 | 38 | .fi |
b0322a85 | 39 | .HP \w'int\ rc=auth_sasl('u |
8d138742 | 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" ");" |
b0322a85 | 41 | .HP \w'int\ rc=auth_sasl_ex('u |
8d138742 | 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" ");" |
d9898ee8 | 43 | .SH "DESCRIPTION" |
44 | .PP | |
d9898ee8 | 45 | \fBauth_sasl\fR |
46 | is a generic | |
47 | SASL | |
b0322a85 | 48 | server implementation\&. |
d9898ee8 | 49 | \fImethod\fR |
50 | is the requested | |
51 | SASL | |
b0322a85 | 52 | method\&. At this time |
d9898ee8 | 53 | \fBauth_sasl\fR |
54 | knows how to handle the following SASL methods: | |
8d138742 | 55 | .sp |
d9898ee8 | 56 | .RS 4 |
b0322a85 CE |
57 | .ie n \{\ |
58 | \h'-04'\(bu\h'+03'\c | |
59 | .\} | |
60 | .el \{\ | |
61 | .sp -1 | |
62 | .IP \(bu 2.3 | |
63 | .\} | |
64 | LOGIN | |
d9898ee8 | 65 | .RE |
8d138742 | 66 | .sp |
d9898ee8 | 67 | .RS 4 |
b0322a85 CE |
68 | .ie n \{\ |
69 | \h'-04'\(bu\h'+03'\c | |
70 | .\} | |
71 | .el \{\ | |
72 | .sp -1 | |
73 | .IP \(bu 2.3 | |
74 | .\} | |
75 | PLAIN | |
d9898ee8 | 76 | .RE |
8d138742 | 77 | .sp |
d9898ee8 | 78 | .RS 4 |
b0322a85 CE |
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 | |
d9898ee8 | 87 | .RE |
8d138742 | 88 | .sp |
d9898ee8 | 89 | .RS 4 |
b0322a85 CE |
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 | |
d9898ee8 | 98 | .RE |
99 | .PP | |
d9898ee8 | 100 | \fIinitialresponse\fR |
b0322a85 | 101 | is a base64\-encoded initial response provided in the client\*(Aqs |
d9898ee8 | 102 | SASL |
b0322a85 | 103 | request\&. |
d9898ee8 | 104 | \fIinitialresponse\fR |
105 | must be | |
106 | NULL | |
b0322a85 | 107 | if an initial response was not included in the client\*(Aqs |
d9898ee8 | 108 | SASL |
b0322a85 | 109 | request\&. |
d9898ee8 | 110 | .PP |
d9898ee8 | 111 | \fIconversation_func\fR |
112 | is the application\-implemented | |
113 | SASL | |
b0322a85 | 114 | conversation callback function\&. |
d9898ee8 | 115 | \fIconversation_func\fR |
116 | receives a base64\-encoded | |
117 | SASL | |
118 | prompt, and the | |
119 | \fIcallback_arg\fR | |
120 | argument to | |
b0322a85 | 121 | \fBauth_sasl\fR\&. |
d9898ee8 | 122 | \fIconversation_func\fR |
b0322a85 | 123 | must return a buffer containing the base64\-encoded reply from the client\&. |
d9898ee8 | 124 | \fBauth_sasl\fR |
125 | will | |
126 | \fBfree\fR(3) | |
b0322a85 | 127 | this buffer when it\*(Aqs done\&. |
d9898ee8 | 128 | \fIconversation_func\fR |
129 | should return | |
130 | NULL | |
131 | to abort the | |
132 | SASL | |
b0322a85 | 133 | conversation\&. |
8d138742 | 134 | .PP |
8d138742 CE |
135 | \fBauth_sasl_ex\fR |
136 | is a version of | |
137 | \fBauth_sasl\fR | |
138 | that recognizes the | |
b0322a85 CE |
139 | EXTERNALSASL |
140 | method\&. It takes an extra parameter, | |
141 | \fIexternalauth\fR\&. This parameter should be set to indicate an login that was authenticated via some other means, such as, perhaps, an | |
8d138742 CE |
142 | SSL |
143 | certificate, or | |
144 | NULL | |
b0322a85 | 145 | if no externally\-authenticated identity was established\&. |
8d138742 CE |
146 | .PP |
147 | If | |
148 | \fImethod\fR | |
149 | is not | |
150 | EXTERNAL, | |
151 | \fBauth_sasl_ex\fR | |
152 | is identical to | |
153 | \fBauth_sasl\fR, and | |
154 | \fIexternalauth\fR | |
b0322a85 | 155 | is ignored\&. Otherwise, if |
8d138742 CE |
156 | \fImethod\fR |
157 | is | |
158 | EXTERNAL | |
159 | and | |
160 | \fIexternalauth\fR | |
161 | is not | |
162 | NULL, | |
163 | \fBauth_sasl_ex\fR | |
164 | returns | |
165 | AUTHSASL_OK, and sets | |
166 | \fI*authtype_ret\fR | |
167 | and | |
168 | \fI*authdata_ret\fR | |
169 | accordingly, so that the subsequent invocation of | |
170 | \fBauth_generic\fR() returns authentication information for the login ID specified by | |
b0322a85 | 171 | \fIexternalauth\fR\&. |
d9898ee8 | 172 | .SH "RETURNS" |
173 | .PP | |
174 | If the | |
175 | SASL | |
176 | conversation succesfully completes, | |
177 | \fBauth_sasl\fR | |
8d138742 CE |
178 | or |
179 | \fBauth_sasl_ex\fR | |
d9898ee8 | 180 | initializes |
181 | \fI*authtype_ret\fR | |
182 | and | |
b0322a85 | 183 | \fI*authdata_ret\fR\&. They will be set to a |
d9898ee8 | 184 | \fBmalloc\fR(3)\-ed buffers that can be directly passed as arguments to |
b0322a85 | 185 | \m[blue]\fB\fBauth_generic\fR(3)\fR\m[]\&\s-2\u[1]\d\s+2\&. It is the application\*(Aqs responsibility to |
d9898ee8 | 186 | \fBfree\fR(3) |
b0322a85 | 187 | these buffers when it\*(Aqs done with them\&. |
d9898ee8 | 188 | .PP |
d9898ee8 | 189 | \fBauth_sasl\fR |
8d138742 CE |
190 | or |
191 | \fBauth_sasl_ex\fR | |
d9898ee8 | 192 | returns |
193 | AUTHSASL_OK | |
194 | when the | |
195 | SASL | |
196 | conversation succesfully completes, and | |
197 | \fI*authtype_ret\fR | |
198 | and | |
199 | \fI*authdata_ret\fR | |
b0322a85 | 200 | are succesfully assembled\&. Any other return indicates an error condition\&. Right now two error conditions are defined: |
d9898ee8 | 201 | .PP |
202 | AUTHSASL_ABORTED | |
203 | .RS 4 | |
204 | The | |
205 | SASL | |
b0322a85 | 206 | conversation was aborted by the client\&. |
d9898ee8 | 207 | .RE |
208 | .PP | |
209 | AUTHSASL_ERROR | |
210 | .RS 4 | |
b0322a85 | 211 | General error (insufficient memory, or some other reason)\&. Check |
d9898ee8 | 212 | \fIerrno\fR |
b0322a85 | 213 | for any clues\&. |
d9898ee8 | 214 | .RE |
215 | .SH "SEE ALSO" | |
216 | .PP | |
b0322a85 CE |
217 | \m[blue]\fB\fBauthlib\fR(3)\fR\m[]\&\s-2\u[2]\d\s+2, |
218 | \m[blue]\fB\fBauth_generic\fR(3)\fR\m[]\&\s-2\u[1]\d\s+2\&. | |
8d138742 | 219 | .SH "NOTES" |
d9898ee8 | 220 | .IP " 1." 4 |
221 | \fBauth_generic\fR(3) | |
222 | .RS 4 | |
b0322a85 | 223 | \%[set $man.base.url.for.relative.links]/auth_generic.html |
d9898ee8 | 224 | .RE |
225 | .IP " 2." 4 | |
226 | \fBauthlib\fR(3) | |
227 | .RS 4 | |
b0322a85 | 228 | \%[set $man.base.url.for.relative.links]/authlib.html |
d9898ee8 | 229 | .RE |