From 977f71c72e451706a8420fe89e50d1852749d99d Mon Sep 17 00:00:00 2001 From: Love Hornquist Astrand Date: Tue, 18 Aug 2009 19:08:01 +0200 Subject: [PATCH] most of krb5_storage documented --- lib/krb5/Makefile.am | 1 - lib/krb5/krb5_storage.3 | 427 ---------------------------------------- 2 files changed, 428 deletions(-) delete mode 100644 lib/krb5/krb5_storage.3 diff --git a/lib/krb5/Makefile.am b/lib/krb5/Makefile.am index c29490536..7b37d3160 100644 --- a/lib/krb5/Makefile.am +++ b/lib/krb5/Makefile.am @@ -241,7 +241,6 @@ man_MANS = \ krb5_rd_safe.3 \ krb5_set_default_realm.3 \ krb5_set_password.3 \ - krb5_storage.3 \ krb5_string_to_key.3 \ krb5_ticket.3 \ krb5_timeofday.3 \ diff --git a/lib/krb5/krb5_storage.3 b/lib/krb5/krb5_storage.3 deleted file mode 100644 index b83128f76..000000000 --- a/lib/krb5/krb5_storage.3 +++ /dev/null @@ -1,427 +0,0 @@ -.\" 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$ -.\" -.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