source4/heimdal/lib/krb5/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