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