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