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
76Kerberos 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
183The
184.Nm krb5_auth_context
185structure holds all context related to an authenticated connection, in
186a similar way to
187.Nm krb5_context
188that holds the context for the thread or process.
189.Nm krb5_auth_context
190is used by various functions that are directly related to
191authentication between the server/client. Example of data that this
192structure contains are various flags, addresses of client and server,
193port numbers, keyblocks (and subkeys), sequence numbers, replay cache,
194and checksum-type.
195.Pp
196.Fn krb5_auth_con_init
197allocates and initializes the
198.Nm krb5_auth_context
199structure. Default values can be changed with
200.Fn krb5_auth_con_setcksumtype
201and
202.Fn krb5_auth_con_setflags .
203The
204.Nm auth_context
205structure 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
211and
212.Fn krb5_auth_con_removeflags
213gets and modifies the flags for a
214.Nm krb5_auth_context
215structure. Possible flags to set are:
216.Bl -tag -width Ds
217.It Dv KRB5_AUTH_CONTEXT_DO_SEQUENCE
218Generate and check sequence-number on each packet.
219.It Dv KRB5_AUTH_CONTEXT_DO_TIME
220Check timestamp on incoming packets.
221.It Dv KRB5_AUTH_CONTEXT_RET_SEQUENCE , Dv KRB5_AUTH_CONTEXT_RET_TIME
222Return sequence numbers and time stamps in the outdata parameters.
223.It Dv KRB5_AUTH_CONTEXT_CLEAR_FORWARDED_CRED
224will force
225.Fn krb5_get_forwarded_creds
226and
227.Fn krb5_fwd_tgt_creds
228to create unencrypted )
229.Dv ENCTYPE_NULL )
230credentials.
231This is for use with old MIT server and JAVA based servers as
232they can't handle encrypted
233.Dv KRB-CRED .
234Note that sending such
235.Dv KRB-CRED
236is clear exposes crypto keys and tickets and is insecure,
237make 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
242and
243.Xr krb5_mk_safe 3 .
244Setting this flag requires that parameter to be passed to these
245functions.
246.Pp
247The flags
248.Dv KRB5_AUTH_CONTEXT_DO_TIME
249also modifies the behavior the function
250.Fn krb5_get_forwarded_creds
251by removing the timestamp in the forward credential message, this have
252backward compatibility problems since not all versions of the heimdal
253supports timeless credentional messages.
254Is very useful since it always the sender of the message to cache
255forward message and thus avoiding a round trip to the KDC for each
256time a credential is forwarded.
257The 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
263and
264.Fn krb5_auth_con_getaddrs
265gets and sets the addresses that are checked when a packet is received.
266It is mandatory to set an address for the remote
267host. If the local address is not set, it iss deduced from the underlaying
268operating system.
269.Fn krb5_auth_con_getaddrs
270will call
271.Fn krb5_free_address
272on any address that is passed in
273.Fa local_addr
274or
275.Fa remote_addr .
276.Fn krb5_auth_con_setaddr
277allows passing in a
278.Dv NULL
279pointer as
280.Fa local_addr
281and
282.Fa remote_addr ,
283in that case it will just not set that address.
284.Pp
285.Fn krb5_auth_con_setaddrs_from_fd
286fetches the addresses from a file descriptor.
287.Pp
288.Fn krb5_auth_con_genaddrs
289fetches the address information from the given file descriptor
290.Fa fd
291depending on the bitmap argument
292.Fa flags .
293.Pp
294Possible values on
295.Fa flags
296are:
297.Bl -tag -width Ds
298.It Va KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR
299fetches the local address from
300.Fa fd .
301.It Va KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR
302fetches the remote address from
303.Fa fd .
304.El
305.Pp
306.Fn krb5_auth_con_setkey ,
307.Fn krb5_auth_con_setuserkey
308and
309.Fn krb5_auth_con_getkey
310gets and sets the key used for this auth context. The keyblock returned by
311.Fn krb5_auth_con_getkey
312should be freed with
313.Fn krb5_free_keyblock .
314The keyblock send into
315.Fn krb5_auth_con_setkey
316is copied into the
317.Nm krb5_auth_context ,
318and thus no special handling is needed.
319.Dv NULL
320is not a valid keyblock to
321.Fn krb5_auth_con_setkey .
322.Pp
323.Fn krb5_auth_con_setuserkey
324is only useful when doing user to user authentication.
325.Fn krb5_auth_con_setkey
326is 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
332and
333.Fn krb5_auth_con_setremotesubkey
334gets and sets the keyblock for the local and remote subkey.
335The keyblock returned by
336.Fn krb5_auth_con_getlocalsubkey
337and
338.Fn krb5_auth_con_getremotesubkey
339must be freed with
340.Fn krb5_free_keyblock .
341.Pp
342.Fn krb5_auth_setcksumtype
343and
344.Fn krb5_auth_getcksumtype
345sets and gets the checksum type that should be used for this
346connection.
347.Pp
348.Fn krb5_auth_con_generatelocalsubkey
349generates 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
355and
356.Fn krb5_auth_setlocalseqnumber
357gets and sets the sequence-number for the local and remote
358sequence-number counter.
359.Pp
360.Fn krb5_auth_setkeytype
361and
362.Fn krb5_auth_getkeytype
363gets and gets the keytype of the keyblock in
364.Nm krb5_auth_context .
365.Pp
366.Fn krb5_auth_con_getauthenticator
367Retrieves the authenticator that was used during mutual
368authentication. The
369.Dv authenticator
370returned should be freed by calling
371.Fn krb5_free_authenticator .
372.Pp
373.Fn krb5_auth_con_getrcache
374and
375.Fn krb5_auth_con_setrcache
376gets and sets the replay-cache.
377.Pp
378.Fn krb5_auth_con_initivector
379allocates memory for and zeros the initial vector in the
380.Fa auth_context
381keyblock.
382.Pp
383.Fn krb5_auth_con_setivector
384sets the i_vector portion of
385.Fa auth_context
386to
387.Fa ivector .
388.Pp
389.Fn krb5_free_authenticator
390free the content of
391.Fa authenticator
392and
393.Fa authenticator
394itself.
395.Sh SEE ALSO
396.Xr krb5_context 3 ,
397.Xr kerberos 8
398