crypto/heimdal/lib/krb5/krb5_storage.3

   1 .\" Copyright (c) 2003 - 2006 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_storage.3 17884 2006-08-18 08:41:09Z lha $
  33 .\"
  34 .Dd Aug 18, 2006
  35 .Dt KRB5_STORAGE 3
  36 .Os HEIMDAL
  37 .Sh NAME
  38 .Nm krb5_storage ,
  39 .Nm krb5_storage_emem ,
  40 .Nm krb5_storage_from_data ,
  41 .Nm krb5_storage_from_fd ,
  42 .Nm krb5_storage_from_mem ,
  43 .Nm krb5_storage_set_flags ,
  44 .Nm krb5_storage_clear_flags ,
  45 .Nm krb5_storage_is_flags ,
  46 .Nm krb5_storage_set_byteorder ,
  47 .Nm krb5_storage_get_byteorder ,
  48 .Nm krb5_storage_set_eof_code ,
  49 .Nm krb5_storage_seek ,
  50 .Nm krb5_storage_read ,
  51 .Nm krb5_storage_write ,
  52 .Nm krb5_storage_free ,
  53 .Nm krb5_storage_to_data ,
  54 .Nm krb5_store_int32 ,
  55 .Nm krb5_ret_int32 ,
  56 .Nm krb5_store_uint32 ,
  57 .Nm krb5_ret_uint32 ,
  58 .Nm krb5_store_int16 ,
  59 .Nm krb5_ret_int16 ,
  60 .Nm krb5_store_uint16 ,
  61 .Nm krb5_ret_uint16 ,
  62 .Nm krb5_store_int8 ,
  63 .Nm krb5_ret_int8 ,
  64 .Nm krb5_store_uint8 ,
  65 .Nm krb5_ret_uint8 ,
  66 .Nm krb5_store_data ,
  67 .Nm krb5_ret_data ,
  68 .Nm krb5_store_string ,
  69 .Nm krb5_ret_string ,
  70 .Nm krb5_store_stringnl ,
  71 .Nm krb5_ret_stringnl ,
  72 .Nm krb5_store_stringz ,
  73 .Nm krb5_ret_stringz ,
  74 .Nm krb5_store_principal ,
  75 .Nm krb5_ret_principal ,
  76 .Nm krb5_store_keyblock ,
  77 .Nm krb5_ret_keyblock ,
  78 .Nm krb5_store_times ,
  79 .Nm krb5_ret_times ,
  80 .Nm krb5_store_address ,
  81 .Nm krb5_ret_address ,
  82 .Nm krb5_store_addrs ,
  83 .Nm krb5_ret_addrs ,
  84 .Nm krb5_store_authdata ,
  85 .Nm krb5_ret_authdata ,
  86 .Nm krb5_store_creds ,
  87 .Nm krb5_ret_creds
  88 .Nd operates on the Kerberos datatype krb5_storage
  89 .Sh LIBRARY
  90 Kerberos 5 Library (libkrb5, -lkrb5)
  91 .Sh SYNOPSIS
  92 .In krb5.h
  93 .Pp
  94 .Li "struct krb5_storage;"
  95 .Pp
  96 .Ft "krb5_storage *"
  97 .Fn krb5_storage_from_fd "int fd"
  98 .Ft "krb5_storage *"
  99 .Fn krb5_storage_emem "void"
 100 .Ft "krb5_storage *"
 101 .Fn krb5_storage_from_mem "void *buf" "size_t len"
 102 .Ft "krb5_storage *"
 103 .Fn krb5_storage_from_data "krb5_data *data"
 104 .Ft void
 105 .Fn krb5_storage_set_flags "krb5_storage *sp" "krb5_flags flags"
 106 .Ft void
 107 .Fn krb5_storage_clear_flags "krb5_storage *sp" "krb5_flags flags"
 108 .Ft krb5_boolean
 109 .Fn krb5_storage_is_flags "krb5_storage *sp" "krb5_flags flags"
 110 .Ft void
 111 .Fn krb5_storage_set_byteorder "krb5_storage *sp" "krb5_flags byteorder"
 112 .Ft krb5_flags
 113 .Fn krb5_storage_get_byteorder "krb5_storage *sp" "krb5_flags byteorder"
 114 .Ft void
 115 .Fn krb5_storage_set_eof_code "krb5_storage *sp" "int code"
 116 .Ft off_t
 117 .Fn krb5_storage_seek "krb5_storage *sp" "off_t offset" "int whence"
 118 .Ft krb5_ssize_t
 119 .Fn krb5_storage_read "krb5_storage *sp" "void *buf" "size_t len"
 120 .Ft krb5_ssize_t
 121 .Fn krb5_storage_write "krb5_storage *sp" "const void *buf" "size_t len"
 122 .Ft krb5_error_code
 123 .Fn krb5_storage_free "krb5_storage *sp"
 124 .Ft krb5_error_code
 125 .Fn krb5_storage_to_data "krb5_storage *sp" "krb5_data *data"
 126 .Ft krb5_error_code
 127 .Fn krb5_store_int32 "krb5_storage *sp" "int32_t value"
 128 .Ft krb5_error_code
 129 .Fn krb5_ret_int32 "krb5_storage *sp" "int32_t *value"
 130 .Ft krb5_error_code
 131 .Fn krb5_ret_uint32 "krb5_storage *sp" "uint32_t *value"
 132 .Ft krb5_error_code
 133 .Fn krb5_store_uint32 "krb5_storage *sp" "uint32_t value"
 134 .Ft krb5_error_code
 135 .Fn krb5_store_int16 "krb5_storage *sp" "int16_t value"
 136 .Ft krb5_error_code
 137 .Fn krb5_ret_int16 "krb5_storage *sp" "int16_t *value"
 138 .Ft krb5_error_code
 139 .Fn krb5_store_uint16 "krb5_storage *sp" "uint16_t value"
 140 .Ft krb5_error_code
 141 .Fn krb5_ret_uint16 "krb5_storage *sp" "u_int16_t *value"
 142 .Ft krb5_error_code
 143 .Fn krb5_store_int8 "krb5_storage *sp" "int8_t value"
 144 .Ft krb5_error_code
 145 .Fn krb5_ret_int8 "krb5_storage *sp" "int8_t *value"
 146 .Ft krb5_error_code
 147 .Fn krb5_store_uint8 "krb5_storage *sp" "u_int8_t value"
 148 .Ft krb5_error_code
 149 .Fn krb5_ret_uint8 "krb5_storage *sp" "u_int8_t *value"
 150 .Ft krb5_error_code
 151 .Fn krb5_store_data "krb5_storage *sp" "krb5_data data"
 152 .Ft krb5_error_code
 153 .Fn krb5_ret_data "krb5_storage *sp" "krb5_data *data"
 154 .Ft krb5_error_code
 155 .Fn krb5_store_string "krb5_storage *sp" "const char *s"
 156 .Ft krb5_error_code
 157 .Fn krb5_ret_string "krb5_storage *sp" "char **string"
 158 .Ft krb5_error_code
 159 .Fn krb5_store_stringnl "krb5_storage *sp" "const char *s"
 160 .Ft krb5_error_code
 161 .Fn krb5_ret_stringnl "krb5_storage *sp" "char **string"
 162 .Ft krb5_error_code
 163 .Fn krb5_store_stringz "krb5_storage *sp" "const char *s"
 164 .Ft krb5_error_code
 165 .Fn krb5_ret_stringz "krb5_storage *sp" "char **string"
 166 .Ft krb5_error_code
 167 .Fn krb5_store_principal "krb5_storage *sp" "krb5_const_principal p"
 168 .Ft krb5_error_code
 169 .Fn krb5_ret_principal "krb5_storage *sp" "krb5_principal *princ"
 170 .Ft krb5_error_code
 171 .Fn krb5_store_keyblock "krb5_storage *sp" "krb5_keyblock p"
 172 .Ft krb5_error_code
 173 .Fn krb5_ret_keyblock "krb5_storage *sp" "krb5_keyblock *p"
 174 .Ft krb5_error_code
 175 .Fn krb5_store_times "krb5_storage *sp" "krb5_times times"
 176 .Ft krb5_error_code
 177 .Fn krb5_ret_times "krb5_storage *sp" "krb5_times *times"
 178 .Ft krb5_error_code
 179 .Fn krb5_store_address "krb5_storage *sp" "krb5_address p"
 180 .Ft krb5_error_code
 181 .Fn krb5_ret_address "krb5_storage *sp" "krb5_address *adr"
 182 .Ft krb5_error_code
 183 .Fn krb5_store_addrs "krb5_storage *sp" "krb5_addresses p"
 184 .Ft krb5_error_code
 185 .Fn krb5_ret_addrs "krb5_storage *sp" "krb5_addresses *adr"
 186 .Ft krb5_error_code
 187 .Fn krb5_store_authdata "krb5_storage *sp" "krb5_authdata auth"
 188 .Ft krb5_error_code
 189 .Fn krb5_ret_authdata "krb5_storage *sp" "krb5_authdata *auth"
 190 .Ft krb5_error_code
 191 .Fn krb5_store_creds "krb5_storage *sp" "krb5_creds *creds"
 192 .Ft krb5_error_code
 193 .Fn krb5_ret_creds "krb5_storage *sp" "krb5_creds *creds"
 194 .Sh DESCRIPTION
 195 The
 196 .Li krb5_storage
 197 structure holds a storage element that is used for data manipulation.
 198 The structure contains no public accessible elements.
 199 .Pp
 200 .Fn krb5_storage_emem
 201 create a memory based krb5 storage unit that dynamicly resized to the
 202 ammount of data stored in.
 203 The storage never returns errors, on memory allocation errors
 204 .Xr exit 3
 205 will be called.
 206 .Pp
 207 .Fn krb5_storage_from_data
 208 create a krb5 storage unit that will read is data from a
 209 .Li krb5_data .
 210 There is no copy made of the
 211 .Fa data ,
 212 so the caller must not free
 213 .Fa data
 214 until the storage is freed.
 215 .Pp
 216 .Fn krb5_storage_from_fd
 217 create a krb5 storage unit that will read is data from a
 218 file descriptor.
 219 The descriptor must be seekable if
 220 .Fn krb5_storage_seek
 221 is used.
 222 Caller must not free the file descriptor before the storage is freed.
 223 .Pp
 224 .Fn krb5_storage_from_mem
 225 create a krb5 storage unit that will read is data from a
 226 memory region.
 227 There is no copy made of the
 228 .Fa data ,
 229 so the caller must not free
 230 .Fa data
 231 until the storage is freed.
 232 .Pp
 233 .Fn krb5_storage_set_flags
 234 and
 235 .Fn krb5_storage_clear_flags
 236 modifies the behavior of the storage functions.
 237 .Fn krb5_storage_is_flags
 238 tests if the
 239 .Fa flags
 240 are set on the
 241 .Li krb5_storage .
 242 Valid flags to set, is and clear is are:
 243 .Pp
 244 .Bl -tag -width "Fan vet..." -compact -offset indent
 245 .It KRB5_STORAGE_PRINCIPAL_WRONG_NUM_COMPONENTS
 246 Stores the number of principal componets one too many when storing
 247 principal namees, used for compatibility with version 1 of file
 248 keytabs and version 1 of file credential caches.
 249 .It KRB5_STORAGE_PRINCIPAL_NO_NAME_TYPE
 250 Doesn't store the name type in when storing a principal name, used for
 251 compatibility with version 1 of file keytabs and version 1 of file
 252 credential caches.
 253 .It KRB5_STORAGE_KEYBLOCK_KEYTYPE_TWICE
 254 Stores the keyblock type twice storing a keyblock, used for
 255 compatibility version 3 of file credential caches.
 256 .It KRB5_STORAGE_BYTEORDER_MASK
 257 bitmask that can be used to and out what type of byte order order is used.
 258 .It KRB5_STORAGE_BYTEORDER_BE
 259 Store integers in in big endian byte order, this is the default mode.
 260 .It KRB5_STORAGE_BYTEORDER_LE
 261 Store integers in in little endian byte order.
 262 .It KRB5_STORAGE_BYTEORDER_HOST
 263 Stores the integers in host byte order, used for compatibility with
 264 version 1 of file keytabs and version 1 and 2 of file credential
 265 caches.
 266 .It KRB5_STORAGE_CREDS_FLAGS_WRONG_BITORDER
 267 Store the credential flags in a krb5_creds in the reverse bit order.
 268 .El
 269 .Pp
 270 .Fn krb5_storage_set_byteorder
 271 and
 272 .Fn krb5_storage_get_byteorder
 273 modifies the byte order used in the storage for integers.
 274 The flags used is same as above.
 275 The valid flags are
 276 .Dv KRB5_STORAGE_BYTEORDER_BE ,
 277 .Dv KRB5_STORAGE_BYTEORDER_LE
 278 and
 279 .Dv KRB5_STORAGE_BYTEORDER_HOST .
 280 .Pp
 281 .Fn krb5_storage_set_eof_code
 282 sets the error code that will be returned on end of file condition to
 283 .Fa code .
 284 .Pp
 285 .Fn krb5_storage_seek
 286 seeks
 287 .Fa offset
 288 bytes in the storage
 289 .Fa sp .
 290 The
 291 .Fa whence
 292 argument is one of
 293 .Bl -tag -width SEEK_SET -compact -offset indent
 294 .It SEEK_SET
 295 offset is from begining of storage.
 296 .It SEEK_CUR
 297 offset is relative from current offset.
 298 .It SEEK_END
 299 offset is from end of storage.
 300 .El
 301 .Pp
 302 .Fn krb5_storage_read
 303 reads
 304 .Fa len
 305 (or less bytes in case of end of file) into
 306 .Fa buf
 307 from the current offset in the storage
 308 .Fa sp .
 309 .Pp
 310 .Fn krb5_storage_write
 311 writes
 312 .Fa len
 313 or (less bytes in case of end of file) from
 314 .Fa buf
 315 from the current offset in the storage
 316 .Fa sp .
 317 .Pp
 318 .Fn krb5_storage_free
 319 frees the storage
 320 .Fa sp .
 321 .Pp
 322 .Fn krb5_storage_to_data
 323 converts the data in storage
 324 .Fa sp
 325 into a
 326 .Li krb5_data
 327 structure.
 328 .Fa data
 329 must be freed with
 330 .Fn krb5_data_free
 331 by the caller when done with the
 332 .Fa data .
 333 .Pp
 334 All
 335 .Li krb5_store
 336 and
 337 .Li krb5_ret
 338 functions move the current offset forward when the functions returns.
 339 .Pp
 340 .Fn krb5_store_int32 ,
 341 .Fn krb5_ret_int32 ,
 342 .Fn krb5_store_uint32 ,
 343 .Fn krb5_ret_uint32 ,
 344 .Fn krb5_store_int16 ,
 345 .Fn krb5_ret_int16 ,
 346 .Fn krb5_store_uint16 ,
 347 .Fn krb5_ret_uint16 ,
 348 .Fn krb5_store_int8 ,
 349 .Fn krb5_ret_int8
 350 .Fn krb5_store_uint8 ,
 351 and
 352 .Fn krb5_ret_uint8
 353 stores and reads an integer from
 354 .Fa sp
 355 in the byte order specified by the flags set on the
 356 .Fa sp .
 357 .Pp
 358 .Fn krb5_store_data
 359 and
 360 .Fn krb5_ret_data
 361 store and reads a krb5_data.
 362 The length of the data is stored with
 363 .Fn krb5_store_int32 .
 364 .Pp
 365 .Fn krb5_store_string
 366 and
 367 .Fn krb5_ret_string
 368 store and reads a string by storing the length of the string with
 369 .Fn krb5_store_int32
 370 followed by the string itself.
 371 .Pp
 372 .Fn krb5_store_stringnl
 373 and
 374 .Fn krb5_ret_stringnl
 375 store and reads a string by storing string followed by a
 376 .Dv '\n' .
 377 .Pp
 378 .Fn krb5_store_stringz
 379 and
 380 .Fn krb5_ret_stringz
 381 store and reads a string by storing string followed by a
 382 .Dv NUL .
 383 .Pp
 384 .Fn krb5_store_principal
 385 and
 386 .Fn krb5_ret_principal
 387 store and reads a principal.
 388 .Pp
 389 .Fn krb5_store_keyblock
 390 and
 391 .Fn krb5_ret_keyblock
 392 store and reads a
 393 .Li krb5_keyblock .
 394 .Pp
 395 .Fn krb5_store_times
 396 .Fn krb5_ret_times
 397 store and reads
 398 .Li krb5_times
 399 structure .
 400 .Pp
 401 .Fn krb5_store_address
 402 and
 403 .Fn krb5_ret_address
 404 store and reads a
 405 .Li krb5_address .
 406 .Pp
 407 .Fn krb5_store_addrs
 408 and
 409 .Fn krb5_ret_addrs
 410 store and reads a
 411 .Li krb5_addresses .
 412 .Pp
 413 .Fn krb5_store_authdata
 414 and
 415 .Fn krb5_ret_authdata
 416 store and reads a
 417 .Li krb5_authdata .
 418 .Pp
 419 .Fn krb5_store_creds
 420 and
 421 .Fn krb5_ret_creds
 422 store and reads a
 423 .Li krb5_creds .
 424 .Sh SEE ALSO
 425 .Xr krb5 3 ,
 426 .Xr krb5_data 3 ,
 427 .Xr kerberos 8