428 lines
12 KiB
Groff
428 lines
12 KiB
Groff
.\" Copyright (c) 2003 - 2006 Kungliga Tekniska Högskolan
|
|
.\" (Royal Institute of Technology, Stockholm, Sweden).
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" Redistribution and use in source and binary forms, with or without
|
|
.\" modification, are permitted provided that the following conditions
|
|
.\" are met:
|
|
.\"
|
|
.\" 1. Redistributions of source code must retain the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer.
|
|
.\"
|
|
.\" 2. Redistributions in binary form must reproduce the above copyright
|
|
.\" notice, this list of conditions and the following disclaimer in the
|
|
.\" documentation and/or other materials provided with the distribution.
|
|
.\"
|
|
.\" 3. Neither the name of the Institute nor the names of its contributors
|
|
.\" may be used to endorse or promote products derived from this software
|
|
.\" without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
|
|
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
|
|
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
|
|
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
|
|
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
|
|
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
|
|
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
|
|
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
|
|
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
|
|
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
|
|
.\" SUCH DAMAGE.
|
|
.\"
|
|
.\" $Id: krb5_storage.3 17884 2006-08-18 08:41:09Z lha $
|
|
.\"
|
|
.Dd Aug 18, 2006
|
|
.Dt KRB5_STORAGE 3
|
|
.Os HEIMDAL
|
|
.Sh NAME
|
|
.Nm krb5_storage ,
|
|
.Nm krb5_storage_emem ,
|
|
.Nm krb5_storage_from_data ,
|
|
.Nm krb5_storage_from_fd ,
|
|
.Nm krb5_storage_from_mem ,
|
|
.Nm krb5_storage_set_flags ,
|
|
.Nm krb5_storage_clear_flags ,
|
|
.Nm krb5_storage_is_flags ,
|
|
.Nm krb5_storage_set_byteorder ,
|
|
.Nm krb5_storage_get_byteorder ,
|
|
.Nm krb5_storage_set_eof_code ,
|
|
.Nm krb5_storage_seek ,
|
|
.Nm krb5_storage_read ,
|
|
.Nm krb5_storage_write ,
|
|
.Nm krb5_storage_free ,
|
|
.Nm krb5_storage_to_data ,
|
|
.Nm krb5_store_int32 ,
|
|
.Nm krb5_ret_int32 ,
|
|
.Nm krb5_store_uint32 ,
|
|
.Nm krb5_ret_uint32 ,
|
|
.Nm krb5_store_int16 ,
|
|
.Nm krb5_ret_int16 ,
|
|
.Nm krb5_store_uint16 ,
|
|
.Nm krb5_ret_uint16 ,
|
|
.Nm krb5_store_int8 ,
|
|
.Nm krb5_ret_int8 ,
|
|
.Nm krb5_store_uint8 ,
|
|
.Nm krb5_ret_uint8 ,
|
|
.Nm krb5_store_data ,
|
|
.Nm krb5_ret_data ,
|
|
.Nm krb5_store_string ,
|
|
.Nm krb5_ret_string ,
|
|
.Nm krb5_store_stringnl ,
|
|
.Nm krb5_ret_stringnl ,
|
|
.Nm krb5_store_stringz ,
|
|
.Nm krb5_ret_stringz ,
|
|
.Nm krb5_store_principal ,
|
|
.Nm krb5_ret_principal ,
|
|
.Nm krb5_store_keyblock ,
|
|
.Nm krb5_ret_keyblock ,
|
|
.Nm krb5_store_times ,
|
|
.Nm krb5_ret_times ,
|
|
.Nm krb5_store_address ,
|
|
.Nm krb5_ret_address ,
|
|
.Nm krb5_store_addrs ,
|
|
.Nm krb5_ret_addrs ,
|
|
.Nm krb5_store_authdata ,
|
|
.Nm krb5_ret_authdata ,
|
|
.Nm krb5_store_creds ,
|
|
.Nm krb5_ret_creds
|
|
.Nd operates on the Kerberos datatype krb5_storage
|
|
.Sh LIBRARY
|
|
Kerberos 5 Library (libkrb5, -lkrb5)
|
|
.Sh SYNOPSIS
|
|
.In krb5.h
|
|
.Pp
|
|
.Li "struct krb5_storage;"
|
|
.Pp
|
|
.Ft "krb5_storage *"
|
|
.Fn krb5_storage_from_fd "int fd"
|
|
.Ft "krb5_storage *"
|
|
.Fn krb5_storage_emem "void"
|
|
.Ft "krb5_storage *"
|
|
.Fn krb5_storage_from_mem "void *buf" "size_t len"
|
|
.Ft "krb5_storage *"
|
|
.Fn krb5_storage_from_data "krb5_data *data"
|
|
.Ft void
|
|
.Fn krb5_storage_set_flags "krb5_storage *sp" "krb5_flags flags"
|
|
.Ft void
|
|
.Fn krb5_storage_clear_flags "krb5_storage *sp" "krb5_flags flags"
|
|
.Ft krb5_boolean
|
|
.Fn krb5_storage_is_flags "krb5_storage *sp" "krb5_flags flags"
|
|
.Ft void
|
|
.Fn krb5_storage_set_byteorder "krb5_storage *sp" "krb5_flags byteorder"
|
|
.Ft krb5_flags
|
|
.Fn krb5_storage_get_byteorder "krb5_storage *sp" "krb5_flags byteorder"
|
|
.Ft void
|
|
.Fn krb5_storage_set_eof_code "krb5_storage *sp" "int code"
|
|
.Ft off_t
|
|
.Fn krb5_storage_seek "krb5_storage *sp" "off_t offset" "int whence"
|
|
.Ft krb5_ssize_t
|
|
.Fn krb5_storage_read "krb5_storage *sp" "void *buf" "size_t len"
|
|
.Ft krb5_ssize_t
|
|
.Fn krb5_storage_write "krb5_storage *sp" "const void *buf" "size_t len"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_storage_free "krb5_storage *sp"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_storage_to_data "krb5_storage *sp" "krb5_data *data"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_int32 "krb5_storage *sp" "int32_t value"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_int32 "krb5_storage *sp" "int32_t *value"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_uint32 "krb5_storage *sp" "uint32_t *value"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_uint32 "krb5_storage *sp" "uint32_t value"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_int16 "krb5_storage *sp" "int16_t value"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_int16 "krb5_storage *sp" "int16_t *value"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_uint16 "krb5_storage *sp" "uint16_t value"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_uint16 "krb5_storage *sp" "u_int16_t *value"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_int8 "krb5_storage *sp" "int8_t value"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_int8 "krb5_storage *sp" "int8_t *value"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_uint8 "krb5_storage *sp" "u_int8_t value"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_uint8 "krb5_storage *sp" "u_int8_t *value"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_data "krb5_storage *sp" "krb5_data data"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_data "krb5_storage *sp" "krb5_data *data"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_string "krb5_storage *sp" "const char *s"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_string "krb5_storage *sp" "char **string"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_stringnl "krb5_storage *sp" "const char *s"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_stringnl "krb5_storage *sp" "char **string"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_stringz "krb5_storage *sp" "const char *s"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_stringz "krb5_storage *sp" "char **string"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_principal "krb5_storage *sp" "krb5_const_principal p"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_principal "krb5_storage *sp" "krb5_principal *princ"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_keyblock "krb5_storage *sp" "krb5_keyblock p"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_keyblock "krb5_storage *sp" "krb5_keyblock *p"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_times "krb5_storage *sp" "krb5_times times"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_times "krb5_storage *sp" "krb5_times *times"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_address "krb5_storage *sp" "krb5_address p"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_address "krb5_storage *sp" "krb5_address *adr"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_addrs "krb5_storage *sp" "krb5_addresses p"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_addrs "krb5_storage *sp" "krb5_addresses *adr"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_authdata "krb5_storage *sp" "krb5_authdata auth"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_authdata "krb5_storage *sp" "krb5_authdata *auth"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_store_creds "krb5_storage *sp" "krb5_creds *creds"
|
|
.Ft krb5_error_code
|
|
.Fn krb5_ret_creds "krb5_storage *sp" "krb5_creds *creds"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Li krb5_storage
|
|
structure holds a storage element that is used for data manipulation.
|
|
The structure contains no public accessible elements.
|
|
.Pp
|
|
.Fn krb5_storage_emem
|
|
create a memory based krb5 storage unit that dynamicly resized to the
|
|
ammount of data stored in.
|
|
The storage never returns errors, on memory allocation errors
|
|
.Xr exit 3
|
|
will be called.
|
|
.Pp
|
|
.Fn krb5_storage_from_data
|
|
create a krb5 storage unit that will read is data from a
|
|
.Li krb5_data .
|
|
There is no copy made of the
|
|
.Fa data ,
|
|
so the caller must not free
|
|
.Fa data
|
|
until the storage is freed.
|
|
.Pp
|
|
.Fn krb5_storage_from_fd
|
|
create a krb5 storage unit that will read is data from a
|
|
file descriptor.
|
|
The descriptor must be seekable if
|
|
.Fn krb5_storage_seek
|
|
is used.
|
|
Caller must not free the file descriptor before the storage is freed.
|
|
.Pp
|
|
.Fn krb5_storage_from_mem
|
|
create a krb5 storage unit that will read is data from a
|
|
memory region.
|
|
There is no copy made of the
|
|
.Fa data ,
|
|
so the caller must not free
|
|
.Fa data
|
|
until the storage is freed.
|
|
.Pp
|
|
.Fn krb5_storage_set_flags
|
|
and
|
|
.Fn krb5_storage_clear_flags
|
|
modifies the behavior of the storage functions.
|
|
.Fn krb5_storage_is_flags
|
|
tests if the
|
|
.Fa flags
|
|
are set on the
|
|
.Li krb5_storage .
|
|
Valid flags to set, is and clear is are:
|
|
.Pp
|
|
.Bl -tag -width "Fan vet..." -compact -offset indent
|
|
.It KRB5_STORAGE_PRINCIPAL_WRONG_NUM_COMPONENTS
|
|
Stores the number of principal componets one too many when storing
|
|
principal namees, used for compatibility with version 1 of file
|
|
keytabs and version 1 of file credential caches.
|
|
.It KRB5_STORAGE_PRINCIPAL_NO_NAME_TYPE
|
|
Doesn't store the name type in when storing a principal name, used for
|
|
compatibility with version 1 of file keytabs and version 1 of file
|
|
credential caches.
|
|
.It KRB5_STORAGE_KEYBLOCK_KEYTYPE_TWICE
|
|
Stores the keyblock type twice storing a keyblock, used for
|
|
compatibility version 3 of file credential caches.
|
|
.It KRB5_STORAGE_BYTEORDER_MASK
|
|
bitmask that can be used to and out what type of byte order order is used.
|
|
.It KRB5_STORAGE_BYTEORDER_BE
|
|
Store integers in in big endian byte order, this is the default mode.
|
|
.It KRB5_STORAGE_BYTEORDER_LE
|
|
Store integers in in little endian byte order.
|
|
.It KRB5_STORAGE_BYTEORDER_HOST
|
|
Stores the integers in host byte order, used for compatibility with
|
|
version 1 of file keytabs and version 1 and 2 of file credential
|
|
caches.
|
|
.It KRB5_STORAGE_CREDS_FLAGS_WRONG_BITORDER
|
|
Store the credential flags in a krb5_creds in the reverse bit order.
|
|
.El
|
|
.Pp
|
|
.Fn krb5_storage_set_byteorder
|
|
and
|
|
.Fn krb5_storage_get_byteorder
|
|
modifies the byte order used in the storage for integers.
|
|
The flags used is same as above.
|
|
The valid flags are
|
|
.Dv KRB5_STORAGE_BYTEORDER_BE ,
|
|
.Dv KRB5_STORAGE_BYTEORDER_LE
|
|
and
|
|
.Dv KRB5_STORAGE_BYTEORDER_HOST .
|
|
.Pp
|
|
.Fn krb5_storage_set_eof_code
|
|
sets the error code that will be returned on end of file condition to
|
|
.Fa code .
|
|
.Pp
|
|
.Fn krb5_storage_seek
|
|
seeks
|
|
.Fa offset
|
|
bytes in the storage
|
|
.Fa sp .
|
|
The
|
|
.Fa whence
|
|
argument is one of
|
|
.Bl -tag -width SEEK_SET -compact -offset indent
|
|
.It SEEK_SET
|
|
offset is from begining of storage.
|
|
.It SEEK_CUR
|
|
offset is relative from current offset.
|
|
.It SEEK_END
|
|
offset is from end of storage.
|
|
.El
|
|
.Pp
|
|
.Fn krb5_storage_read
|
|
reads
|
|
.Fa len
|
|
(or less bytes in case of end of file) into
|
|
.Fa buf
|
|
from the current offset in the storage
|
|
.Fa sp .
|
|
.Pp
|
|
.Fn krb5_storage_write
|
|
writes
|
|
.Fa len
|
|
or (less bytes in case of end of file) from
|
|
.Fa buf
|
|
from the current offset in the storage
|
|
.Fa sp .
|
|
.Pp
|
|
.Fn krb5_storage_free
|
|
frees the storage
|
|
.Fa sp .
|
|
.Pp
|
|
.Fn krb5_storage_to_data
|
|
converts the data in storage
|
|
.Fa sp
|
|
into a
|
|
.Li krb5_data
|
|
structure.
|
|
.Fa data
|
|
must be freed with
|
|
.Fn krb5_data_free
|
|
by the caller when done with the
|
|
.Fa data .
|
|
.Pp
|
|
All
|
|
.Li krb5_store
|
|
and
|
|
.Li krb5_ret
|
|
functions move the current offset forward when the functions returns.
|
|
.Pp
|
|
.Fn krb5_store_int32 ,
|
|
.Fn krb5_ret_int32 ,
|
|
.Fn krb5_store_uint32 ,
|
|
.Fn krb5_ret_uint32 ,
|
|
.Fn krb5_store_int16 ,
|
|
.Fn krb5_ret_int16 ,
|
|
.Fn krb5_store_uint16 ,
|
|
.Fn krb5_ret_uint16 ,
|
|
.Fn krb5_store_int8 ,
|
|
.Fn krb5_ret_int8
|
|
.Fn krb5_store_uint8 ,
|
|
and
|
|
.Fn krb5_ret_uint8
|
|
stores and reads an integer from
|
|
.Fa sp
|
|
in the byte order specified by the flags set on the
|
|
.Fa sp .
|
|
.Pp
|
|
.Fn krb5_store_data
|
|
and
|
|
.Fn krb5_ret_data
|
|
store and reads a krb5_data.
|
|
The length of the data is stored with
|
|
.Fn krb5_store_int32 .
|
|
.Pp
|
|
.Fn krb5_store_string
|
|
and
|
|
.Fn krb5_ret_string
|
|
store and reads a string by storing the length of the string with
|
|
.Fn krb5_store_int32
|
|
followed by the string itself.
|
|
.Pp
|
|
.Fn krb5_store_stringnl
|
|
and
|
|
.Fn krb5_ret_stringnl
|
|
store and reads a string by storing string followed by a
|
|
.Dv '\n' .
|
|
.Pp
|
|
.Fn krb5_store_stringz
|
|
and
|
|
.Fn krb5_ret_stringz
|
|
store and reads a string by storing string followed by a
|
|
.Dv NUL .
|
|
.Pp
|
|
.Fn krb5_store_principal
|
|
and
|
|
.Fn krb5_ret_principal
|
|
store and reads a principal.
|
|
.Pp
|
|
.Fn krb5_store_keyblock
|
|
and
|
|
.Fn krb5_ret_keyblock
|
|
store and reads a
|
|
.Li krb5_keyblock .
|
|
.Pp
|
|
.Fn krb5_store_times
|
|
.Fn krb5_ret_times
|
|
store and reads
|
|
.Li krb5_times
|
|
structure .
|
|
.Pp
|
|
.Fn krb5_store_address
|
|
and
|
|
.Fn krb5_ret_address
|
|
store and reads a
|
|
.Li krb5_address .
|
|
.Pp
|
|
.Fn krb5_store_addrs
|
|
and
|
|
.Fn krb5_ret_addrs
|
|
store and reads a
|
|
.Li krb5_addresses .
|
|
.Pp
|
|
.Fn krb5_store_authdata
|
|
and
|
|
.Fn krb5_ret_authdata
|
|
store and reads a
|
|
.Li krb5_authdata .
|
|
.Pp
|
|
.Fn krb5_store_creds
|
|
and
|
|
.Fn krb5_ret_creds
|
|
store and reads a
|
|
.Li krb5_creds .
|
|
.Sh SEE ALSO
|
|
.Xr krb5 3 ,
|
|
.Xr krb5_data 3 ,
|
|
.Xr kerberos 8
|