| blob | d53f48374e30d6be7f9b6aab39d8283fd033e7ec |
1 .\" $NetBSD: krb5_auth_context.3,v 1.1.1.2 2011/04/14 14:09:22 elric Exp $
2 .\"
3 .\" Copyright (c) 2001 - 2005 Kungliga Tekniska Högskolan
4 .\" (Royal Institute of Technology, Stockholm, Sweden).
5 .\" All rights reserved.
6 .\"
7 .\" Redistribution and use in source and binary forms, with or without
8 .\" modification, are permitted provided that the following conditions
9 .\" are met:
10 .\"
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\"
14 .\" 2. Redistributions in binary form must reproduce the above copyright
15 .\" notice, this list of conditions and the following disclaimer in the
16 .\" documentation and/or other materials provided with the distribution.
17 .\"
18 .\" 3. Neither the name of the Institute nor the names of its contributors
19 .\" may be used to endorse or promote products derived from this software
20 .\" without specific prior written permission.
21 .\"
22 .\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
23 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
24 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
25 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
26 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
27 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
28 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
29 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
30 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
31 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" SUCH DAMAGE.
33 .\"
34 .\" Id
35 .\"
36 .Dd May 17, 2005
37 .Dt KRB5_AUTH_CONTEXT 3
38 .Os
39 .Sh NAME
40 .Nm krb5_auth_con_addflags ,
41 .Nm krb5_auth_con_free ,
42 .Nm krb5_auth_con_genaddrs ,
43 .Nm krb5_auth_con_generatelocalsubkey ,
44 .Nm krb5_auth_con_getaddrs ,
45 .Nm krb5_auth_con_getauthenticator ,
46 .Nm krb5_auth_con_getflags ,
47 .Nm krb5_auth_con_getkey ,
48 .Nm krb5_auth_con_getlocalsubkey ,
49 .Nm krb5_auth_con_getrcache ,
50 .Nm krb5_auth_con_getremotesubkey ,
51 .Nm krb5_auth_con_getuserkey ,
52 .Nm krb5_auth_con_init ,
53 .Nm krb5_auth_con_initivector ,
54 .Nm krb5_auth_con_removeflags ,
55 .Nm krb5_auth_con_setaddrs ,
56 .Nm krb5_auth_con_setaddrs_from_fd ,
57 .Nm krb5_auth_con_setflags ,
58 .Nm krb5_auth_con_setivector ,
59 .Nm krb5_auth_con_setkey ,
60 .Nm krb5_auth_con_setlocalsubkey ,
61 .Nm krb5_auth_con_setrcache ,
62 .Nm krb5_auth_con_setremotesubkey ,
63 .Nm krb5_auth_con_setuserkey ,
64 .Nm krb5_auth_context ,
65 .Nm krb5_auth_getcksumtype ,
66 .Nm krb5_auth_getkeytype ,
67 .Nm krb5_auth_getlocalseqnumber ,
68 .Nm krb5_auth_getremoteseqnumber ,
69 .Nm krb5_auth_setcksumtype ,
70 .Nm krb5_auth_setkeytype ,
71 .Nm krb5_auth_setlocalseqnumber ,
72 .Nm krb5_auth_setremoteseqnumber ,
73 .Nm krb5_free_authenticator
74 .Nd manage authentication on connection level
75 .Sh LIBRARY
76 Kerberos 5 Library (libkrb5, -lkrb5)
77 .Sh SYNOPSIS
78 .In krb5/krb5.h
79 .Ft krb5_error_code
80 .Fo krb5_auth_con_init
81 .Fa "krb5_context context"
82 .Fa "krb5_auth_context *auth_context"
83 .Fc
84 .Ft void
85 .Fo krb5_auth_con_free
86 .Fa "krb5_context context"
87 .Fa "krb5_auth_context auth_context"
88 .Fc
89 .Ft krb5_error_code
90 .Fo krb5_auth_con_setflags
91 .Fa "krb5_context context"
92 .Fa "krb5_auth_context auth_context"
93 .Fa "int32_t flags"
94 .Fc
95 .Ft krb5_error_code
96 .Fo krb5_auth_con_getflags
97 .Fa "krb5_context context"
98 .Fa "krb5_auth_context auth_context"
99 .Fa "int32_t *flags"
100 .Fc
101 .Ft krb5_error_code
102 .Fo krb5_auth_con_addflags
103 .Fa "krb5_context context"
104 .Fa "krb5_auth_context auth_context"
105 .Fa "int32_t addflags"
106 .Fa "int32_t *flags"
107 .Fc
108 .Ft krb5_error_code
109 .Fo krb5_auth_con_removeflags
110 .Fa "krb5_context context"
111 .Fa "krb5_auth_context auth_context"
112 .Fa "int32_t removelags"
113 .Fa "int32_t *flags"
114 .Fc
115 .Ft krb5_error_code
116 .Fo krb5_auth_con_setaddrs
117 .Fa "krb5_context context"
118 .Fa "krb5_auth_context auth_context"
119 .Fa "krb5_address *local_addr"
120 .Fa "krb5_address *remote_addr"
121 .Fc
122 .Ft krb5_error_code
123 .Fo krb5_auth_con_getaddrs
124 .Fa "krb5_context context"
125 .Fa "krb5_auth_context auth_context"
126 .Fa "krb5_address **local_addr"
127 .Fa "krb5_address **remote_addr"
128 .Fc
129 .Ft krb5_error_code
130 .Fo krb5_auth_con_genaddrs
131 .Fa "krb5_context context"
132 .Fa "krb5_auth_context auth_context"
133 .Fa "int fd"
134 .Fa "int flags"
135 .Fc
136 .Ft krb5_error_code
137 .Fo krb5_auth_con_setaddrs_from_fd
138 .Fa "krb5_context context"
139 .Fa "krb5_auth_context auth_context"
140 .Fa "void *p_fd"
141 .Fc
142 .Ft krb5_error_code
143 .Fo krb5_auth_con_getkey
144 .Fa "krb5_context context"
145 .Fa "krb5_auth_context auth_context"
146 .Fa "krb5_keyblock **keyblock"
147 .Fc
148 .Ft krb5_error_code
149 .Fo krb5_auth_con_getlocalsubkey
150 .Fa "krb5_context context"
151 .Fa "krb5_auth_context auth_context"
152 .Fa "krb5_keyblock **keyblock"
153 .Fc
154 .Ft krb5_error_code
155 .Fo krb5_auth_con_getremotesubkey
156 .Fa "krb5_context context"
157 .Fa "krb5_auth_context auth_context"
158 .Fa "krb5_keyblock **keyblock"
159 .Fc
160 .Ft krb5_error_code
161 .Fo krb5_auth_con_generatelocalsubkey
162 .Fa "krb5_context context"
163 .Fa "krb5_auth_context auth_context"
164 .Fa krb5_keyblock *key"
165 .Fc
166 .Ft krb5_error_code
167 .Fo krb5_auth_con_initivector
168 .Fa "krb5_context context"
169 .Fa "krb5_auth_context auth_context"
170 .Fc
171 .Ft krb5_error_code
172 .Fo krb5_auth_con_setivector
173 .Fa "krb5_context context"
174 .Fa "krb5_auth_context *auth_context"
175 .Fa "krb5_pointer ivector"
176 .Fc
177 .Ft void
178 .Fo krb5_free_authenticator
179 .Fa "krb5_context context"
180 .Fa "krb5_authenticator *authenticator"
181 .Fc
182 .Sh DESCRIPTION
183 The
184 .Nm krb5_auth_context
185 structure holds all context related to an authenticated connection, in
186 a similar way to
187 .Nm krb5_context
188 that holds the context for the thread or process.
189 .Nm krb5_auth_context
190 is used by various functions that are directly related to
191 authentication between the server/client. Example of data that this
192 structure contains are various flags, addresses of client and server,
193 port numbers, keyblocks (and subkeys), sequence numbers, replay cache,
194 and checksum-type.
195 .Pp
196 .Fn krb5_auth_con_init
197 allocates and initializes the
198 .Nm krb5_auth_context
199 structure. Default values can be changed with
200 .Fn krb5_auth_con_setcksumtype
201 and
202 .Fn krb5_auth_con_setflags .
203 The
204 .Nm auth_context
205 structure must be freed by
206 .Fn krb5_auth_con_free .
207 .Pp
208 .Fn krb5_auth_con_getflags ,
209 .Fn krb5_auth_con_setflags ,
210 .Fn krb5_auth_con_addflags
211 and
212 .Fn krb5_auth_con_removeflags
213 gets and modifies the flags for a
214 .Nm krb5_auth_context
215 structure. Possible flags to set are:
216 .Bl -tag -width Ds
217 .It Dv KRB5_AUTH_CONTEXT_DO_SEQUENCE
218 Generate and check sequence-number on each packet.
219 .It Dv KRB5_AUTH_CONTEXT_DO_TIME
220 Check timestamp on incoming packets.
221 .It Dv KRB5_AUTH_CONTEXT_RET_SEQUENCE , Dv KRB5_AUTH_CONTEXT_RET_TIME
222 Return sequence numbers and time stamps in the outdata parameters.
223 .It Dv KRB5_AUTH_CONTEXT_CLEAR_FORWARDED_CRED
224 will force
225 .Fn krb5_get_forwarded_creds
226 and
227 .Fn krb5_fwd_tgt_creds
228 to create unencrypted )
229 .Dv ENCTYPE_NULL )
230 credentials.
231 This is for use with old MIT server and JAVA based servers as
232 they can't handle encrypted
233 .Dv KRB-CRED .
234 Note that sending such
235 .Dv KRB-CRED
236 is clear exposes crypto keys and tickets and is insecure,
237 make sure the packet is encrypted in the protocol.
238 .Xr krb5_rd_cred 3 ,
239 .Xr krb5_rd_priv 3 ,
240 .Xr krb5_rd_safe 3 ,
241 .Xr krb5_mk_priv 3
242 and
243 .Xr krb5_mk_safe 3 .
244 Setting this flag requires that parameter to be passed to these
245 functions.
246 .Pp
247 The flags
248 .Dv KRB5_AUTH_CONTEXT_DO_TIME
249 also modifies the behavior the function
250 .Fn krb5_get_forwarded_creds
251 by removing the timestamp in the forward credential message, this have
252 backward compatibility problems since not all versions of the heimdal
253 supports timeless credentional messages.
254 Is very useful since it always the sender of the message to cache
255 forward message and thus avoiding a round trip to the KDC for each
256 time a credential is forwarded.
257 The same functionality can be obtained by using address-less tickets.
258 .\".It Dv KRB5_AUTH_CONTEXT_PERMIT_ALL
259 .El
260 .Pp
261 .Fn krb5_auth_con_setaddrs ,
262 .Fn krb5_auth_con_setaddrs_from_fd
263 and
264 .Fn krb5_auth_con_getaddrs
265 gets and sets the addresses that are checked when a packet is received.
266 It is mandatory to set an address for the remote
267 host. If the local address is not set, it iss deduced from the underlaying
268 operating system.
269 .Fn krb5_auth_con_getaddrs
270 will call
271 .Fn krb5_free_address
272 on any address that is passed in
273 .Fa local_addr
274 or
275 .Fa remote_addr .
276 .Fn krb5_auth_con_setaddr
277 allows passing in a
278 .Dv NULL
279 pointer as
280 .Fa local_addr
281 and
282 .Fa remote_addr ,
283 in that case it will just not set that address.
284 .Pp
285 .Fn krb5_auth_con_setaddrs_from_fd
286 fetches the addresses from a file descriptor.
287 .Pp
288 .Fn krb5_auth_con_genaddrs
289 fetches the address information from the given file descriptor
290 .Fa fd
291 depending on the bitmap argument
292 .Fa flags .
293 .Pp
294 Possible values on
295 .Fa flags
296 are:
297 .Bl -tag -width Ds
298 .It Va KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR
299 fetches the local address from
300 .Fa fd .
301 .It Va KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR
302 fetches the remote address from
303 .Fa fd .
304 .El
305 .Pp
306 .Fn krb5_auth_con_setkey ,
307 .Fn krb5_auth_con_setuserkey
308 and
309 .Fn krb5_auth_con_getkey
310 gets and sets the key used for this auth context. The keyblock returned by
311 .Fn krb5_auth_con_getkey
312 should be freed with
313 .Fn krb5_free_keyblock .
314 The keyblock send into
315 .Fn krb5_auth_con_setkey
316 is copied into the
317 .Nm krb5_auth_context ,
318 and thus no special handling is needed.
319 .Dv NULL
320 is not a valid keyblock to
321 .Fn krb5_auth_con_setkey .
322 .Pp
323 .Fn krb5_auth_con_setuserkey
324 is only useful when doing user to user authentication.
325 .Fn krb5_auth_con_setkey
326 is equivalent to
327 .Fn krb5_auth_con_setuserkey .
328 .Pp
329 .Fn krb5_auth_con_getlocalsubkey ,
330 .Fn krb5_auth_con_setlocalsubkey ,
331 .Fn krb5_auth_con_getremotesubkey
332 and
333 .Fn krb5_auth_con_setremotesubkey
334 gets and sets the keyblock for the local and remote subkey.
335 The keyblock returned by
336 .Fn krb5_auth_con_getlocalsubkey
337 and
338 .Fn krb5_auth_con_getremotesubkey
339 must be freed with
340 .Fn krb5_free_keyblock .
341 .Pp
342 .Fn krb5_auth_setcksumtype
343 and
344 .Fn krb5_auth_getcksumtype
345 sets and gets the checksum type that should be used for this
346 connection.
347 .Pp
348 .Fn krb5_auth_con_generatelocalsubkey
349 generates a local subkey that have the same encryption type as
350 .Fa key .
351 .Pp
352 .Fn krb5_auth_getremoteseqnumber
353 .Fn krb5_auth_setremoteseqnumber ,
354 .Fn krb5_auth_getlocalseqnumber
355 and
356 .Fn krb5_auth_setlocalseqnumber
357 gets and sets the sequence-number for the local and remote
358 sequence-number counter.
359 .Pp
360 .Fn krb5_auth_setkeytype
361 and
362 .Fn krb5_auth_getkeytype
363 gets and gets the keytype of the keyblock in
364 .Nm krb5_auth_context .
365 .Pp
366 .Fn krb5_auth_con_getauthenticator
367 Retrieves the authenticator that was used during mutual
368 authentication. The
369 .Dv authenticator
370 returned should be freed by calling
371 .Fn krb5_free_authenticator .
372 .Pp
373 .Fn krb5_auth_con_getrcache
374 and
375 .Fn krb5_auth_con_setrcache
376 gets and sets the replay-cache.
377 .Pp
378 .Fn krb5_auth_con_initivector
379 allocates memory for and zeros the initial vector in the
380 .Fa auth_context
381 keyblock.
382 .Pp
383 .Fn krb5_auth_con_setivector
384 sets the i_vector portion of
385 .Fa auth_context
386 to
387 .Fa ivector .
388 .Pp
389 .Fn krb5_free_authenticator
390 free the content of
391 .Fa authenticator
392 and
393 .Fa authenticator
394 itself.
395 .Sh SEE ALSO
396 .Xr krb5_context 3 ,
397 .Xr kerberos 8