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