crypto/heimdal/lib/krb5/krb5_auth_context.3

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