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 | |
0e333c05 CE |
5 | .\" Author: [FIXME: author] [see http://www.docbook.org/tdg5/en/html/author] |
6 | .\" Generator: DocBook XSL Stylesheets vsnapshot <http://docbook.sf.net/> | |
7 | .\" Date: 09/08/2017 | |
d9898ee8 | 8 | .\" Manual: Double Precision, Inc. |
9 | .\" Source: Double Precision, Inc. | |
b0322a85 | 10 | .\" Language: English |
d9898ee8 | 11 | .\" |
0e333c05 | 12 | .TH "AUTH_SASL" "3" "09/08/2017" "Double Precision, Inc." "Double Precision, Inc." |
b0322a85 CE |
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 | |
0e333c05 CE |
139 | EXTERNAL |
140 | SASL | |
b0322a85 CE |
141 | method\&. It takes an extra parameter, |
142 | \fIexternalauth\fR\&. This parameter should be set to indicate an login that was authenticated via some other means, such as, perhaps, an | |
8d138742 CE |
143 | SSL |
144 | certificate, or | |
145 | NULL | |
b0322a85 | 146 | if no externally\-authenticated identity was established\&. |
8d138742 CE |
147 | .PP |
148 | If | |
149 | \fImethod\fR | |
150 | is not | |
151 | EXTERNAL, | |
152 | \fBauth_sasl_ex\fR | |
153 | is identical to | |
154 | \fBauth_sasl\fR, and | |
155 | \fIexternalauth\fR | |
b0322a85 | 156 | is ignored\&. Otherwise, if |
8d138742 CE |
157 | \fImethod\fR |
158 | is | |
159 | EXTERNAL | |
160 | and | |
161 | \fIexternalauth\fR | |
162 | is not | |
163 | NULL, | |
164 | \fBauth_sasl_ex\fR | |
165 | returns | |
166 | AUTHSASL_OK, and sets | |
167 | \fI*authtype_ret\fR | |
168 | and | |
169 | \fI*authdata_ret\fR | |
170 | accordingly, so that the subsequent invocation of | |
171 | \fBauth_generic\fR() returns authentication information for the login ID specified by | |
b0322a85 | 172 | \fIexternalauth\fR\&. |
d9898ee8 | 173 | .SH "RETURNS" |
174 | .PP | |
175 | If the | |
176 | SASL | |
177 | conversation succesfully completes, | |
178 | \fBauth_sasl\fR | |
8d138742 CE |
179 | or |
180 | \fBauth_sasl_ex\fR | |
d9898ee8 | 181 | initializes |
182 | \fI*authtype_ret\fR | |
183 | and | |
b0322a85 | 184 | \fI*authdata_ret\fR\&. They will be set to a |
d9898ee8 | 185 | \fBmalloc\fR(3)\-ed buffers that can be directly passed as arguments to |
b0322a85 | 186 | \m[blue]\fB\fBauth_generic\fR(3)\fR\m[]\&\s-2\u[1]\d\s+2\&. It is the application\*(Aqs responsibility to |
d9898ee8 | 187 | \fBfree\fR(3) |
b0322a85 | 188 | these buffers when it\*(Aqs done with them\&. |
d9898ee8 | 189 | .PP |
d9898ee8 | 190 | \fBauth_sasl\fR |
8d138742 CE |
191 | or |
192 | \fBauth_sasl_ex\fR | |
d9898ee8 | 193 | returns |
194 | AUTHSASL_OK | |
195 | when the | |
196 | SASL | |
197 | conversation succesfully completes, and | |
198 | \fI*authtype_ret\fR | |
199 | and | |
200 | \fI*authdata_ret\fR | |
b0322a85 | 201 | are succesfully assembled\&. Any other return indicates an error condition\&. Right now two error conditions are defined: |
d9898ee8 | 202 | .PP |
203 | AUTHSASL_ABORTED | |
204 | .RS 4 | |
205 | The | |
206 | SASL | |
b0322a85 | 207 | conversation was aborted by the client\&. |
d9898ee8 | 208 | .RE |
209 | .PP | |
210 | AUTHSASL_ERROR | |
211 | .RS 4 | |
b0322a85 | 212 | General error (insufficient memory, or some other reason)\&. Check |
d9898ee8 | 213 | \fIerrno\fR |
b0322a85 | 214 | for any clues\&. |
d9898ee8 | 215 | .RE |
216 | .SH "SEE ALSO" | |
217 | .PP | |
b0322a85 CE |
218 | \m[blue]\fB\fBauthlib\fR(3)\fR\m[]\&\s-2\u[2]\d\s+2, |
219 | \m[blue]\fB\fBauth_generic\fR(3)\fR\m[]\&\s-2\u[1]\d\s+2\&. | |
8d138742 | 220 | .SH "NOTES" |
d9898ee8 | 221 | .IP " 1." 4 |
222 | \fBauth_generic\fR(3) | |
223 | .RS 4 | |
d50284c4 | 224 | \%http://www.courier-mta.org/authlib/auth_generic.html |
d9898ee8 | 225 | .RE |
226 | .IP " 2." 4 | |
227 | \fBauthlib\fR(3) | |
228 | .RS 4 | |
d50284c4 | 229 | \%http://www.courier-mta.org/authlib/authlib.html |
d9898ee8 | 230 | .RE |