krb5_auth_context.3
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 74 Kerberos 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 181 The 182 .Nm krb5_auth_context 183 structure holds all context related to an authenticated connection, in 184 a similar way to 185 .Nm krb5_context 186 that holds the context for the thread or process. 187 .Nm krb5_auth_context 188 is used by various functions that are directly related to 189 authentication between the server/client. Example of data that this 190 structure contains are various flags, addresses of client and server, 191 port numbers, keyblocks (and subkeys), sequence numbers, replay cache, 192 and checksum-type. 193 .Pp 194 .Fn krb5_auth_con_init 195 allocates and initializes the 196 .Nm krb5_auth_context 197 structure. Default values can be changed with 198 .Fn krb5_auth_con_setcksumtype 199 and 200 .Fn krb5_auth_con_setflags . 201 The 202 .Nm auth_context 203 structure 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 209 and 210 .Fn krb5_auth_con_removeflags 211 gets and modifies the flags for a 212 .Nm krb5_auth_context 213 structure. Possible flags to set are: 214 .Bl -tag -width Ds 215 .It Dv KRB5_AUTH_CONTEXT_DO_SEQUENCE 216 Generate and check sequence-number on each packet. 217 .It Dv KRB5_AUTH_CONTEXT_DO_TIME 218 Check timestamp on incoming packets. 219 .It Dv KRB5_AUTH_CONTEXT_RET_SEQUENCE , Dv KRB5_AUTH_CONTEXT_RET_TIME 220 Return sequence numbers and time stamps in the outdata parameters. 221 .It Dv KRB5_AUTH_CONTEXT_CLEAR_FORWARDED_CRED 222 will force 223 .Fn krb5_get_forwarded_creds 224 and 225 .Fn krb5_fwd_tgt_creds 226 to create unencrypted ) 227 .Dv KRB5_ENCTYPE_NULL ) 228 credentials. 229 This is for use with old MIT server and JAVA based servers as 230 they can't handle encrypted 231 .Dv KRB-CRED . 232 Note that sending such 233 .Dv KRB-CRED 234 is clear exposes crypto keys and tickets and is insecure, 235 make 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 240 and 241 .Xr krb5_mk_safe 3 . 242 Setting this flag requires that parameter to be passed to these 243 functions. 244 .Pp 245 The flags 246 .Dv KRB5_AUTH_CONTEXT_DO_TIME 247 also modifies the behavior the function 248 .Fn krb5_get_forwarded_creds 249 by removing the timestamp in the forward credential message, this have 250 backward compatibility problems since not all versions of the heimdal 251 supports timeless credentional messages. 252 Is very useful since it always the sender of the message to cache 253 forward message and thus avoiding a round trip to the KDC for each 254 time a credential is forwarded. 255 The 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 261 and 262 .Fn krb5_auth_con_getaddrs 263 gets and sets the addresses that are checked when a packet is received. 264 It is mandatory to set an address for the remote 265 host. If the local address is not set, it iss deduced from the underlaying 266 operating system. 267 .Fn krb5_auth_con_getaddrs 268 will call 269 .Fn krb5_free_address 270 on any address that is passed in 271 .Fa local_addr 272 or 273 .Fa remote_addr . 274 .Fn krb5_auth_con_setaddr 275 allows passing in a 276 .Dv NULL 277 pointer as 278 .Fa local_addr 279 and 280 .Fa remote_addr , 281 in that case it will just not set that address. 282 .Pp 283 .Fn krb5_auth_con_setaddrs_from_fd 284 fetches the addresses from a file descriptor. 285 .Pp 286 .Fn krb5_auth_con_genaddrs 287 fetches the address information from the given file descriptor 288 .Fa fd 289 depending on the bitmap argument 290 .Fa flags . 291 .Pp 292 Possible values on 293 .Fa flags 294 are: 295 .Bl -tag -width Ds 296 .It Va KRB5_AUTH_CONTEXT_GENERATE_LOCAL_ADDR 297 fetches the local address from 298 .Fa fd . 299 .It Va KRB5_AUTH_CONTEXT_GENERATE_REMOTE_ADDR 300 fetches the remote address from 301 .Fa fd . 302 .El 303 .Pp 304 .Fn krb5_auth_con_setkey , 305 .Fn krb5_auth_con_setuserkey 306 and 307 .Fn krb5_auth_con_getkey 308 gets and sets the key used for this auth context. The keyblock returned by 309 .Fn krb5_auth_con_getkey 310 should be freed with 311 .Fn krb5_free_keyblock . 312 The keyblock send into 313 .Fn krb5_auth_con_setkey 314 is copied into the 315 .Nm krb5_auth_context , 316 and thus no special handling is needed. 317 .Dv NULL 318 is not a valid keyblock to 319 .Fn krb5_auth_con_setkey . 320 .Pp 321 .Fn krb5_auth_con_setuserkey 322 is only useful when doing user to user authentication. 323 .Fn krb5_auth_con_setkey 324 is 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 330 and 331 .Fn krb5_auth_con_setremotesubkey 332 gets and sets the keyblock for the local and remote subkey. 333 The keyblock returned by 334 .Fn krb5_auth_con_getlocalsubkey 335 and 336 .Fn krb5_auth_con_getremotesubkey 337 must be freed with 338 .Fn krb5_free_keyblock . 339 .Pp 340 .Fn krb5_auth_setcksumtype 341 and 342 .Fn krb5_auth_getcksumtype 343 sets and gets the checksum type that should be used for this 344 connection. 345 .Pp 346 .Fn krb5_auth_con_generatelocalsubkey 347 generates 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 353 and 354 .Fn krb5_auth_setlocalseqnumber 355 gets and sets the sequence-number for the local and remote 356 sequence-number counter. 357 .Pp 358 .Fn krb5_auth_setkeytype 359 and 360 .Fn krb5_auth_getkeytype 361 gets and gets the keytype of the keyblock in 362 .Nm krb5_auth_context . 363 .Pp 364 .Fn krb5_auth_con_getauthenticator 365 Retrieves the authenticator that was used during mutual 366 authentication. The 367 .Dv authenticator 368 returned should be freed by calling 369 .Fn krb5_free_authenticator . 370 .Pp 371 .Fn krb5_auth_con_getrcache 372 and 373 .Fn krb5_auth_con_setrcache 374 gets and sets the replay-cache. 375 .Pp 376 .Fn krb5_auth_con_initivector 377 allocates memory for and zeros the initial vector in the 378 .Fa auth_context 379 keyblock. 380 .Pp 381 .Fn krb5_auth_con_setivector 382 sets the i_vector portion of 383 .Fa auth_context 384 to 385 .Fa ivector . 386 .Pp 387 .Fn krb5_free_authenticator 388 free the content of 389 .Fa authenticator 390 and 391 .Fa authenticator 392 itself. 393 .Sh SEE ALSO 394 .Xr krb5_context 3 , 395 .Xr kerberos 8