1 .\" Copyright (c) 2003 - 2006 Kungliga Tekniska Högskolan
2 .\" (Royal Institute of Technology, Stockholm, Sweden).
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
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.
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.
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
32 .\" $Id: krb5_storage.3 17884 2006-08-18 08:41:09Z lha $
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 ,
56 .Nm krb5_store_uint32 ,
58 .Nm krb5_store_int16 ,
60 .Nm krb5_store_uint16 ,
64 .Nm krb5_store_uint8 ,
68 .Nm krb5_store_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 ,
80 .Nm krb5_store_address ,
81 .Nm krb5_ret_address ,
82 .Nm krb5_store_addrs ,
84 .Nm krb5_store_authdata ,
85 .Nm krb5_ret_authdata ,
86 .Nm krb5_store_creds ,
88 .Nd operates on the Kerberos datatype krb5_storage
90 Kerberos 5 Library (libkrb5, -lkrb5)
94 .Li "struct krb5_storage;"
97 .Fn krb5_storage_from_fd "int fd"
99 .Fn krb5_storage_emem "void"
101 .Fn krb5_storage_from_mem "void *buf" "size_t len"
103 .Fn krb5_storage_from_data "krb5_data *data"
105 .Fn krb5_storage_set_flags "krb5_storage *sp" "krb5_flags flags"
107 .Fn krb5_storage_clear_flags "krb5_storage *sp" "krb5_flags flags"
109 .Fn krb5_storage_is_flags "krb5_storage *sp" "krb5_flags flags"
111 .Fn krb5_storage_set_byteorder "krb5_storage *sp" "krb5_flags byteorder"
113 .Fn krb5_storage_get_byteorder "krb5_storage *sp" "krb5_flags byteorder"
115 .Fn krb5_storage_set_eof_code "krb5_storage *sp" "int code"
117 .Fn krb5_storage_seek "krb5_storage *sp" "off_t offset" "int whence"
119 .Fn krb5_storage_read "krb5_storage *sp" "void *buf" "size_t len"
121 .Fn krb5_storage_write "krb5_storage *sp" "const void *buf" "size_t len"
123 .Fn krb5_storage_free "krb5_storage *sp"
125 .Fn krb5_storage_to_data "krb5_storage *sp" "krb5_data *data"
127 .Fn krb5_store_int32 "krb5_storage *sp" "int32_t value"
129 .Fn krb5_ret_int32 "krb5_storage *sp" "int32_t *value"
131 .Fn krb5_ret_uint32 "krb5_storage *sp" "uint32_t *value"
133 .Fn krb5_store_uint32 "krb5_storage *sp" "uint32_t value"
135 .Fn krb5_store_int16 "krb5_storage *sp" "int16_t value"
137 .Fn krb5_ret_int16 "krb5_storage *sp" "int16_t *value"
139 .Fn krb5_store_uint16 "krb5_storage *sp" "uint16_t value"
141 .Fn krb5_ret_uint16 "krb5_storage *sp" "u_int16_t *value"
143 .Fn krb5_store_int8 "krb5_storage *sp" "int8_t value"
145 .Fn krb5_ret_int8 "krb5_storage *sp" "int8_t *value"
147 .Fn krb5_store_uint8 "krb5_storage *sp" "u_int8_t value"
149 .Fn krb5_ret_uint8 "krb5_storage *sp" "u_int8_t *value"
151 .Fn krb5_store_data "krb5_storage *sp" "krb5_data data"
153 .Fn krb5_ret_data "krb5_storage *sp" "krb5_data *data"
155 .Fn krb5_store_string "krb5_storage *sp" "const char *s"
157 .Fn krb5_ret_string "krb5_storage *sp" "char **string"
159 .Fn krb5_store_stringnl "krb5_storage *sp" "const char *s"
161 .Fn krb5_ret_stringnl "krb5_storage *sp" "char **string"
163 .Fn krb5_store_stringz "krb5_storage *sp" "const char *s"
165 .Fn krb5_ret_stringz "krb5_storage *sp" "char **string"
167 .Fn krb5_store_principal "krb5_storage *sp" "krb5_const_principal p"
169 .Fn krb5_ret_principal "krb5_storage *sp" "krb5_principal *princ"
171 .Fn krb5_store_keyblock "krb5_storage *sp" "krb5_keyblock p"
173 .Fn krb5_ret_keyblock "krb5_storage *sp" "krb5_keyblock *p"
175 .Fn krb5_store_times "krb5_storage *sp" "krb5_times times"
177 .Fn krb5_ret_times "krb5_storage *sp" "krb5_times *times"
179 .Fn krb5_store_address "krb5_storage *sp" "krb5_address p"
181 .Fn krb5_ret_address "krb5_storage *sp" "krb5_address *adr"
183 .Fn krb5_store_addrs "krb5_storage *sp" "krb5_addresses p"
185 .Fn krb5_ret_addrs "krb5_storage *sp" "krb5_addresses *adr"
187 .Fn krb5_store_authdata "krb5_storage *sp" "krb5_authdata auth"
189 .Fn krb5_ret_authdata "krb5_storage *sp" "krb5_authdata *auth"
191 .Fn krb5_store_creds "krb5_storage *sp" "krb5_creds *creds"
193 .Fn krb5_ret_creds "krb5_storage *sp" "krb5_creds *creds"
197 structure holds a storage element that is used for data manipulation.
198 The structure contains no public accessible elements.
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
207 .Fn krb5_storage_from_data
208 create a krb5 storage unit that will read is data from a
210 There is no copy made of the
212 so the caller must not free
214 until the storage is freed.
216 .Fn krb5_storage_from_fd
217 create a krb5 storage unit that will read is data from a
219 The descriptor must be seekable if
220 .Fn krb5_storage_seek
222 Caller must not free the file descriptor before the storage is freed.
224 .Fn krb5_storage_from_mem
225 create a krb5 storage unit that will read is data from a
227 There is no copy made of the
229 so the caller must not free
231 until the storage is freed.
233 .Fn krb5_storage_set_flags
235 .Fn krb5_storage_clear_flags
236 modifies the behavior of the storage functions.
237 .Fn krb5_storage_is_flags
242 Valid flags to set, is and clear is are:
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
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
266 .It KRB5_STORAGE_CREDS_FLAGS_WRONG_BITORDER
267 Store the credential flags in a krb5_creds in the reverse bit order.
270 .Fn krb5_storage_set_byteorder
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.
276 .Dv KRB5_STORAGE_BYTEORDER_BE ,
277 .Dv KRB5_STORAGE_BYTEORDER_LE
279 .Dv KRB5_STORAGE_BYTEORDER_HOST .
281 .Fn krb5_storage_set_eof_code
282 sets the error code that will be returned on end of file condition to
285 .Fn krb5_storage_seek
293 .Bl -tag -width SEEK_SET -compact -offset indent
295 offset is from begining of storage.
297 offset is relative from current offset.
299 offset is from end of storage.
302 .Fn krb5_storage_read
305 (or less bytes in case of end of file) into
307 from the current offset in the storage
310 .Fn krb5_storage_write
313 or (less bytes in case of end of file) from
315 from the current offset in the storage
318 .Fn krb5_storage_free
322 .Fn krb5_storage_to_data
323 converts the data in storage
331 by the caller when done with the
338 functions move the current offset forward when the functions returns.
340 .Fn krb5_store_int32 ,
342 .Fn krb5_store_uint32 ,
343 .Fn krb5_ret_uint32 ,
344 .Fn krb5_store_int16 ,
346 .Fn krb5_store_uint16 ,
347 .Fn krb5_ret_uint16 ,
348 .Fn krb5_store_int8 ,
350 .Fn krb5_store_uint8 ,
353 stores and reads an integer from
355 in the byte order specified by the flags set on the
361 store and reads a krb5_data.
362 The length of the data is stored with
363 .Fn krb5_store_int32 .
365 .Fn krb5_store_string
368 store and reads a string by storing the length of the string with
370 followed by the string itself.
372 .Fn krb5_store_stringnl
374 .Fn krb5_ret_stringnl
375 store and reads a string by storing string followed by a
378 .Fn krb5_store_stringz
381 store and reads a string by storing string followed by a
384 .Fn krb5_store_principal
386 .Fn krb5_ret_principal
387 store and reads a principal.
389 .Fn krb5_store_keyblock
391 .Fn krb5_ret_keyblock
401 .Fn krb5_store_address
413 .Fn krb5_store_authdata
415 .Fn krb5_ret_authdata