1.\" Copyright (c) 2001 - 2002 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: krb5_auth_context.3,v 1.8 2003/04/16 13:58:13 lha Exp $ 33.\" 34.Dd January 21, 2001 35.Dt KRB5_AUTH_CONTEXT 3 36.Os HEIMDAL 37.Sh NAME 38.Nm krb5_auth_context , 39.Nm krb5_auth_con_init , 40.Nm krb5_auth_con_free , 41.Nm krb5_auth_con_setflags , 42.Nm krb5_auth_con_getflags , 43.Nm krb5_auth_con_setaddrs , 44.Nm krb5_auth_con_setaddrs_from_fd , 45.Nm krb5_auth_con_getaddrs , 46.Nm krb5_auth_con_genaddrs , 47.Nm krb5_auth_con_getkey , 48.Nm krb5_auth_con_setkey , 49.Nm krb5_auth_con_getuserkey , 50.Nm krb5_auth_con_setuserkey , 51.Nm krb5_auth_con_getlocalsubkey , 52.Nm krb5_auth_con_setlocalsubkey , 53.Nm krb5_auth_con_getremotesubkey , 54.Nm krb5_auth_con_setremotesubkey , 55.Nm krb5_auth_setcksumtype , 56.Nm krb5_auth_getcksumtype , 57.Nm krb5_auth_setkeytype , 58.Nm krb5_auth_getkeytype , 59.Nm krb5_auth_getlocalseqnumber , 60.Nm krb5_auth_setlocalseqnumber , 61.Nm krb5_auth_getremoteseqnumber , 62.Nm krb5_auth_setremoteseqnumber , 63.Nm krb5_auth_getauthenticator , 64.Nm krb5_auth_con_getrcache , 65.Nm krb5_auth_con_setrcache , 66.Nm krb5_auth_con_initivector , 67.Nm krb5_auth_con_setivector 68.Nd manage authentication on connection level 69.Sh LIBRARY 70Kerberos 5 Library (libkrb5, -lkrb5) 71.Sh SYNOPSIS 72.In krb5.h 73.Ft krb5_error_code 74.Fo krb5_auth_con_init 75.Fa "krb5_context context" 76.Fa "krb5_auth_context *auth_context" 77.Fc 78.Ft void 79.Fo krb5_auth_con_free 80.Fa "krb5_context context" 81.Fa "krb5_auth_context auth_context" 82.Fc 83.Ft krb5_error_code 84.Fo krb5_auth_con_setflags 85.Fa "krb5_context context" 86.Fa "krb5_auth_context auth_context" 87.Fa "int32_t flags" 88.Fc 89.Ft krb5_error_code 90.Fo krb5_auth_con_getflags 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_setaddrs 97.Fa "krb5_context context" 98.Fa "krb5_auth_context auth_context" 99.Fa "krb5_address *local_addr" 100.Fa "krb5_address *remote_addr" 101.Fc 102.Ft krb5_error_code 103.Fo krb5_auth_con_getaddrs 104.Fa "krb5_context context" 105.Fa "krb5_auth_context auth_context" 106.Fa "krb5_address **local_addr" 107.Fa "krb5_address **remote_addr" 108.Fc 109.Ft krb5_error_code 110.Fo krb5_auth_con_genaddrs 111.Fa "krb5_context context" 112.Fa "krb5_auth_context auth_context" 113.Fa "int fd" 114.Fa "int flags" 115.Fc 116.Ft krb5_error_code 117.Fo krb5_auth_con_setaddrs_from_fd 118.Fa "krb5_context context" 119.Fa "krb5_auth_context auth_context" 120.Fa "void *p_fd" 121.Fc 122.Ft krb5_error_code 123.Fo krb5_auth_con_getkey 124.Fa "krb5_context context" 125.Fa "krb5_auth_context auth_context" 126.Fa "krb5_keyblock **keyblock" 127.Fc 128.Ft krb5_error_code 129.Fo krb5_auth_con_getlocalsubkey 130.Fa "krb5_context context" 131.Fa "krb5_auth_context auth_context" 132.Fa "krb5_keyblock **keyblock" 133.Fc 134.Ft krb5_error_code 135.Fo krb5_auth_con_getremotesubkey 136.Fa "krb5_context context" 137.Fa "krb5_auth_context auth_context" 138.Fa "krb5_keyblock **keyblock" 139.Fc 140.Ft krb5_error_code 141.Fo krb5_auth_con_initivector 142.Fa "krb5_context context" 143.Fa "krb5_auth_context auth_context" 144.Fc 145.Ft krb5_error_code 146.Fo krb5_auth_con_setivector 147.Fa "krb5_context context" 148.Fa "krb5_auth_context *auth_context" 149.Fa "krb5_pointer ivector" 150.Fc 151.Sh DESCRIPTION 152The 153.Nm krb5_auth_context 154structure holds all context related to an authenticated connection, in 155a similar way to 156.Nm krb5_context 157that holds the context for the thread or process. 158.Nm krb5_auth_context 159is used by various functions that are directly related to 160authentication between the server/client. Example of data that this 161structure contains are various flags, addresses of client and server, 162port numbers, keyblocks (and subkeys), sequence numbers, replay cache, 163and checksum-type. 164.Pp 165.Fn krb5_auth_con_init 166allocates and initializes the 167.Nm krb5_auth_context 168structure. Default values can be changed with 169.Fn krb5_auth_con_setcksumtype 170and 171.Fn krb5_auth_con_setflags . 172The 173.Nm auth_context 174structure must be freed by 175.Fn krb5_auth_con_free . 176.Pp 177.Fn krb5_auth_con_getflags 178and 179.Fn krb5_auth_con_setflags 180gets and modifies the flags for a 181.Nm krb5_auth_context 182structure. Possible flags to set are: 183.Bl -tag -width Ds 184.It Dv KRB5_AUTH_CONTEXT_DO_TIME 185check timestamp on incoming packets. 186.\".It Dv KRB5_AUTH_CONTEXT_RET_TIME 187.It Dv KRB5_AUTH_CONTEXT_DO_SEQUENCE 188Generate and check sequence-number on each packet. 189.\".It Dv KRB5_AUTH_CONTEXT_RET_SEQUENCE 190.\".It Dv KRB5_AUTH_CONTEXT_PERMIT_ALL 191.El 192.Pp 193.Fn krb5_auth_con_setaddrs , 194.Fn krb5_auth_con_setaddrs_from_fd 195and 196.Fn krb5_auth_con_getaddrs 197gets and sets the addresses that are checked when a packet is received. 198It is mandatory to set an address for the remote 199host. If the local address is not set, it iss deduced from the underlaying 200operating system. 201.Fn krb5_auth_con_getaddrs 202will call 203.Fn krb5_free_address 204on any address that is passed in 205.Fa local_addr 206or 207.Fa remote_addr . 208.Fn krb5_auth_con_setaddr 209allows passing in a 210.Dv NULL 211pointer as 212.Fa local_addr 213and 214.Fa remote_addr , 215in that case it will just not set that address. 216.Pp 217.Fn krb5_auth_con_setaddrs_from_fd 218fetches the addresses from a file descriptor. 219.Pp 220.Fn krb5_auth_con_genaddrs 221fetches the address information from the given file descriptor 222.Fa fd 223depending on the bitmap argument 224.Fa flags . 225.Pp 226Possible values on 227.Fa flags 228are: 229.Bl -tag -width Ds 230.It Va KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR 231fetches the local address from 232.Fa fd . 233.It Va KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR 234fetches the remote address from 235.Fa fd . 236.El 237.Pp 238.Fn krb5_auth_con_setkey , 239.Fn krb5_auth_con_setuserkey 240and 241.Fn krb5_auth_con_getkey 242gets and sets the key used for this auth context. The keyblock returned by 243.Fn krb5_auth_con_getkey 244should be freed with 245.Fn krb5_free_keyblock . 246The keyblock send into 247.Fn krb5_auth_con_setkey 248is copied into the 249.Nm krb5_auth_context , 250and thus no special handling is needed. 251.Dv NULL 252is not a valid keyblock to 253.Fn krb5_auth_con_setkey . 254.Pp 255.Fn krb5_auth_con_setuserkey 256is only useful when doing user to user authentication. 257.Fn krb5_auth_con_setkey 258is equivalent to 259.Fn krb5_auth_con_setuserkey . 260.Pp 261.Fn krb5_auth_con_getlocalsubkey , 262.Fn krb5_auth_con_setlocalsubkey , 263.Fn krb5_auth_con_getremotesubkey 264and 265.Fn krb5_auth_con_setremotesubkey 266gets and sets the keyblock for the local and remote subkey. The keyblock returned by 267.Fn krb5_auth_con_getlocalsubkey 268and 269.Fn krb5_auth_con_getremotesubkey 270must be freed with 271.Fn krb5_free_keyblock . 272.Pp 273.Fn krb5_auth_setcksumtype 274and 275.Fn krb5_auth_getcksumtype 276sets and gets the checksum type that should be used for this 277connection. 278.Pp 279.Fn krb5_auth_getremoteseqnumber 280.Fn krb5_auth_setremoteseqnumber , 281.Fn krb5_auth_getlocalseqnumber 282and 283.Fn krb5_auth_setlocalseqnumber 284gets and sets the sequence-number for the local and remote 285sequence-number counter. 286.Pp 287.Fn krb5_auth_setkeytype 288and 289.Fn krb5_auth_getkeytype 290gets and gets the keytype of the keyblock in 291.Nm krb5_auth_context . 292.Pp 293.Fn krb5_auth_getauthenticator 294Retrieves the authenticator that was used during mutual 295authentication. The 296.Dv authenticator 297returned should be freed by calling 298.Fn krb5_free_authenticator . 299.Pp 300.Fn krb5_auth_con_getrcache 301and 302.Fn krb5_auth_con_setrcache 303gets and sets the replay-cache. 304.Pp 305.Fn krb5_auth_con_initivector 306allocates memory for and zeros the initial vector in the 307.Fa auth_context 308keyblock. 309.Pp 310.Fn krb5_auth_con_setivector 311sets the i_vector portion of 312.Fa auth_context 313to 314.Fa ivector . 315.Sh SEE ALSO 316.Xr krb5_context 3 , 317.Xr kerberos 8 318