crypto/heimdal-0.6.3/lib/krb5/krb5_auth_context.3

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