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