diff options
Diffstat (limited to 'crypto/heimdal/lib/krb5/krb5_storage.3')
| -rw-r--r-- | crypto/heimdal/lib/krb5/krb5_storage.3 | 427 |
1 files changed, 427 insertions, 0 deletions
diff --git a/crypto/heimdal/lib/krb5/krb5_storage.3 b/crypto/heimdal/lib/krb5/krb5_storage.3 new file mode 100644 index 0000000..cc03c5b --- /dev/null +++ b/crypto/heimdal/lib/krb5/krb5_storage.3 @@ -0,0 +1,427 @@ +.\" 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 |
