Mercurial > projects > libpws

comparison pws3_file_create.3.xml @ 1:e1309515d111

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add README file and manpages
author Guido Berhoerster <guido+libpws@berhoerster.name>
date Wed, 25 Mar 2015 17:10:23 +0100
parents
children b3fc9f7e2b43
comparison
equal deleted inserted replaced
0:d541e748cfd8 1:e1309515d111
1 <?xml version="1.0"?>
2 <!--
3
4 Copyright (C) 2015 Guido Berhoerster <guido+libpws@berhoerster.name>
5
6 Permission is hereby granted, free of charge, to any person obtaining
7 a copy of this software and associated documentation files (the
8 "Software"), to deal in the Software without restriction, including
9 without limitation the rights to use, copy, modify, merge, publish,
10 distribute, sublicense, and/or sell copies of the Software, and to
11 permit persons to whom the Software is furnished to do so, subject to
12 the following conditions:
13
14 The above copyright notice and this permission notice shall be included
15 in all copies or substantial portions of the Software.
16
17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
20 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
21 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
22 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
23 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24
25 -->
26 <refentry xmlns="http://docbook.org/ns/docbook"
27 xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
28 <info>
29 <author>
30 <personname>
31 <firstname>Guido</firstname>
32 <surname>Berhoerster</surname>
33 </personname>
34 <email>guido+libpws@berhoerster.name</email>
35 <personblurb/>
36 </author>
37 <date>21 March, 2015</date>
38 </info>
39 <refmeta>
40 <refentrytitle>libpws</refentrytitle>
41 <manvolnum>3</manvolnum>
42 <refmiscinfo class="source"/>
43 <refmiscinfo class="version"/>
44 <refmiscinfo class="manual">Library Functions</refmiscinfo>
45 </refmeta>
46 <refnamediv>
47 <refname>pws3_file_create</refname>
48 <refname>pws3_file_destroy</refname>
49 <refname>pws3_file_get_error_code</refname>
50 <refname>pws3_file_get_error_message</refname>
51 <refname>pws3_file_read_mem</refname>
52 <refname>pws3_file_read_stream</refname>
53 <refname>pws3_file_write_mem</refname>
54 <refname>pws3_file_write_stream</refname>
55 <refname>pws3_file_set_header_field</refname>
56 <refname>pws3_file_get_header_field</refname>
57 <refname>pws3_file_remove_header_field</refname>
58 <refname>pws3_file_insert_empty_group</refname>
59 <refname>pws3_file_get_empty_group</refname>
60 <refname>pws3_file_remove_empty_group</refname>
61 <refname>pws3_file_first_empty_group</refname>
62 <refname>pws3_file_last_empty_group</refname>
63 <refname>pws3_file_next_empty_group</refname>
64 <refname>pws3_file_prev_empty_group</refname>
65 <refname>pws3_file_insert_record</refname>
66 <refname>pws3_file_get_record</refname>
67 <refname>pws3_file_remove_record</refname>
68 <refname>pws3_file_first_record</refname>
69 <refname>pws3_file_last_record</refname>
70 <refname>pws3_file_next_record</refname>
71 <refname>pws3_file_prev_record</refname>
72 <refname>pws3_field_create</refname>
73 <refname>pws3_field_destroy</refname>
74 <refname>pws3_field_is_header</refname>
75 <refname>pws3_field_get_type</refname>
76 <refname>pws3_field_get_data_type</refname>
77 <refname>pws3_field_set_uuid</refname>
78 <refname>pws3_field_set_text</refname>
79 <refname>pws3_field_set_time</refname>
80 <refname>pws3_field_set_uint8</refname>
81 <refname>pws3_field_set_uint16</refname>
82 <refname>pws3_field_set_uint32</refname>
83 <refname>pws3_field_set_bytes</refname>
84 <refname>pws3_field_get_uuid</refname>
85 <refname>pws3_field_get_text</refname>
86 <refname>pws3_field_get_time</refname>
87 <refname>pws3_field_get_uint8</refname>
88 <refname>pws3_field_get_uint16</refname>
89 <refname>pws3_field_get_uint32</refname>
90 <refname>pws3_field_get_bytes</refname>
91 <refname>pws3_record_create</refname>
92 <refname>pws3_record_destroy</refname>
93 <refname>pws3_record_set_field</refname>
94 <refname>pws3_record_get_field</refname>
95 <refname>pws3_record_remove_field</refname>
96 <refpurpose>create and manipulate Password Safe File Version 3
97 files</refpurpose>
98 </refnamediv>
99 <refsynopsisdiv>
100 <cmdsynopsis>
101 <command>cc</command>
102 <arg choice="opt" rep="repeat">
103 <option>flag</option>
104 </arg>
105 <arg choice="plain" rep="repeat">
106 <option>file</option>
107 </arg>
108 <arg choice="plain">
109 <option>-lpws</option>
110 </arg>
111 <arg choice="plain">
112 <option>-lnettle</option>
113 </arg>
114 <arg choice="opt" rep="repeat">
115 <option>library</option>
116 </arg>
117 </cmdsynopsis>
118 <funcsynopsis>
119 <funcsynopsisinfo>
120 #include &lt;pws.h&gt;
121 </funcsynopsisinfo>
122 <funcprototype>
123 <funcdef>struct pws3_file
124 *<function>pws3_file_create</function></funcdef>
125 <void/>
126 </funcprototype>
127 <funcprototype>
128 <funcdef>void <function>pws3_file_destroy</function></funcdef>
129 <paramdef>struct pws3_file
130 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
131 </funcprototype>
132 <funcprototype>
133 <funcdef>enum pws_error_code
134 <function>pws3_file_get_error_code</function></funcdef>
135 <paramdef>struct pws3_file
136 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
137 </funcprototype>
138 <funcprototype>
139 <funcdef>const char *
140 <function>pws3_file_get_error_message</function></funcdef>
141 <paramdef>struct pws3_file
142 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
143 </funcprototype>
144 <funcprototype>
145 <funcdef>int <function>pws3_file_read_mem</function></funcdef>
146 <paramdef>struct pws3_file
147 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
148 <paramdef>const char
149 *<parameter><replaceable>password</replaceable></parameter></paramdef>
150 <paramdef>unsigned char
151 *<parameter><replaceable>s</replaceable></parameter></paramdef>
152 <paramdef>size_t
153 <parameter><replaceable>n</replaceable></parameter></paramdef>
154 </funcprototype>
155 <funcprototype>
156 <funcdef>int <function>pws3_file_read_stream</function></funcdef>
157 <paramdef>struct pws3_file
158 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
159 <paramdef>const char
160 *<parameter><replaceable>password</replaceable></parameter></paramdef>
161 <paramdef>FILE
162 *<parameter><replaceable>fp</replaceable></parameter></paramdef>
163 </funcprototype>
164 <funcprototype>
165 <funcdef>int <function>pws3_file_write_mem</function></funcdef>
166 <paramdef>struct pws3_file
167 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
168 <paramdef>const char
169 *<parameter><replaceable>password</replaceable></parameter></paramdef>
170 <paramdef>uint32_t
171 <parameter><replaceable>n_iter</replaceable></parameter></paramdef>
172 <paramdef>unsigned char
173 **<parameter><replaceable>memp</replaceable></parameter></paramdef>
174 <paramdef>size_t
175 *<parameter><replaceable>mem_sizep</replaceable></parameter></paramdef>
176 </funcprototype>
177 <funcprototype>
178 <funcdef>int <function>pws3_file_write_stream</function></funcdef>
179 <paramdef>struct pws3_file
180 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
181 <paramdef>const char
182 *<parameter><replaceable>password</replaceable></parameter></paramdef>
183 <paramdef>uint32_t
184 <parameter><replaceable>n_iter</replaceable></parameter></paramdef>
185 </funcprototype>
186 <funcprototype>
187 <funcdef>void <function>pws3_file_set_header_field</function></funcdef>
188 <paramdef>struct pws3_file
189 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
190 <paramdef>struct pws3_field
191 *<parameter><replaceable>field</replaceable></parameter></paramdef>
192 </funcprototype>
193 <funcprototype>
194 <funcdef>struct pws3_field *
195 <function>pws3_file_get_header_field</function></funcdef>
196 <paramdef>struct pws3_file
197 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
198 <paramdef>uint8_t
199 <parameter><replaceable>field_type</replaceable></parameter></paramdef>
200 </funcprototype>
201 <funcprototype>
202 <funcdef>struct pws3_field *
203 <function>pws3_file_remove_header_field</function></funcdef>
204 <paramdef>struct pws3_file
205 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
206 <paramdef>uint8_t
207 <parameter><replaceable>field_type</replaceable></parameter></paramdef>
208 </funcprototype>
209 <funcprototype>
210 <funcdef>void
211 <function>pws3_file_insert_empty_group</function></funcdef>
212 <paramdef>struct pws3_file
213 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
214 <paramdef>struct pws3_field
215 *<parameter><replaceable>field</replaceable></parameter></paramdef>
216 </funcprototype>
217 <funcprototype>
218 <funcdef>struct pws3_field *
219 <function>pws3_file_get_empty_group</function></funcdef>
220 <paramdef>struct pws3_file
221 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
222 <paramdef>const char
223 *<parameter><replaceable>group_name</replaceable></parameter></paramdef>
224 </funcprototype>
225 <funcprototype>
226 <funcdef>struct pws3_field *
227 <function>pws3_file_remove_empty_group</function></funcdef>
228 <paramdef>struct pws3_file
229 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
230 <paramdef>const char
231 *<parameter><replaceable>group_name</replaceable></parameter></paramdef>
232 </funcprototype>
233 <funcprototype>
234 <funcdef>struct pws3_field *
235 <function>pws3_file_first_empty_group</function></funcdef>
236 <paramdef>struct pws3_file
237 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
238 </funcprototype>
239 <funcprototype>
240 <funcdef>struct pws3_field *
241 <function>pws3_file_last_empty_group</function></funcdef>
242 <paramdef>struct pws3_file
243 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
244 </funcprototype>
245 <funcprototype>
246 <funcdef>struct pws3_field *
247 <function>pws3_file_next_empty_group</function></funcdef>
248 <paramdef>struct pws3_file
249 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
250 <paramdef>struct pws3_field
251 *<parameter><replaceable>field</replaceable></parameter></paramdef>
252 </funcprototype>
253 <funcprototype>
254 <funcdef>struct pws3_field *
255 <function>pws3_file_prev_empty_group</function></funcdef>
256 <paramdef>struct pws3_file
257 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
258 <paramdef>struct pws3_field
259 *<parameter><replaceable>field</replaceable></parameter></paramdef>
260 </funcprototype>
261 <funcprototype>
262 <funcdef>void <function>pws3_file_insert_record</function></funcdef>
263 <paramdef>struct pws3_file
264 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
265 <paramdef>struct pws3_record
266 *<parameter><replaceable>record</replaceable></parameter></paramdef>
267 </funcprototype>
268 <funcprototype>
269 <funcdef>struct pws3_record *
270 <function>pws3_file_get_record</function></funcdef>
271 <paramdef>struct pws3_file
272 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
273 <paramdef>const unsigned char
274 <parameter><replaceable>uuid</replaceable>[static
275 PWS3_UUID_SIZE]</parameter></paramdef>
276 </funcprototype>
277 <funcprototype>
278 <funcdef>struct pws3_record *
279 <function>pws3_file_remove_record</function></funcdef>
280 <paramdef>struct pws3_file
281 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
282 <paramdef>const unsigned char
283 <parameter><replaceable>uuid</replaceable>[static
284 PWS3_UUID_SIZE]</parameter></paramdef>
285 </funcprototype>
286 <funcprototype>
287 <funcdef>struct pws3_record *
288 <function>pws3_file_first_record</function></funcdef>
289 <paramdef>struct pws3_file
290 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
291 </funcprototype>
292 <funcprototype>
293 <funcdef>struct pws3_record *
294 <function>pws3_file_last_record</function></funcdef>
295 <paramdef>struct pws3_file
296 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
297 </funcprototype>
298 <funcprototype>
299 <funcdef>struct pws3_record *
300 <function>pws3_file_next_record</function></funcdef>
301 <paramdef>struct pws3_file
302 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
303 <paramdef>struct pws3_record
304 *<parameter><replaceable>record</replaceable></parameter></paramdef>
305 </funcprototype>
306 <funcprototype>
307 <funcdef>struct pws3_record *
308 <function>pws3_file_prev_record</function></funcdef>
309 <paramdef>struct pws3_file
310 *<parameter><replaceable>pws_file</replaceable></parameter></paramdef>
311 <paramdef>struct pws3_record
312 *<parameter><replaceable>record</replaceable></parameter></paramdef>
313 </funcprototype>
314 <funcprototype>
315 <funcdef>struct pws3_field *
316 <function>pws3_field_create</function></funcdef>
317 <paramdef>int
318 <parameter><replaceable>is_header</replaceable></parameter></paramdef>
319 <paramdef>uint8_t
320 <parameter><replaceable>field_type</replaceable></parameter></paramdef>
321 </funcprototype>
322 <funcprototype>
323 <funcdef>void <function>pws3_field_destroy</function></funcdef>
324 <paramdef>struct pws3_field
325 *<parameter><replaceable>field</replaceable></parameter></paramdef>
326 </funcprototype>
327 <funcprototype>
328 <funcdef>int
329 <function>pws3_field_is_header</function></funcdef>
330 <paramdef>struct pws3_field
331 *<parameter><replaceable>field</replaceable></parameter></paramdef>
332 </funcprototype>
333 <funcprototype>
334 <funcdef>uint8_t *
335 <function>pws3_field_get_type</function></funcdef>
336 <paramdef>struct pws3_field
337 *<parameter><replaceable>field</replaceable></parameter></paramdef>
338 </funcprototype>
339 <funcprototype>
340 <funcdef>enum pws_data_type *
341 <function>pws3_field_get_data_type</function></funcdef>
342 <paramdef>struct pws3_field
343 *<parameter><replaceable>field</replaceable></parameter></paramdef>
344 </funcprototype>
345 <funcprototype>
346 <funcdef>int <function>pws3_field_set_uuid</function></funcdef>
347 <paramdef>struct pws3_field
348 *<parameter><replaceable>field</replaceable></parameter></paramdef>
349 <paramdef>const unsigned char
350 <parameter><replaceable>uuid</replaceable>[static
351 PWS3_UUID_SIZE]</parameter></paramdef>
352 </funcprototype>
353 <funcprototype>
354 <funcdef>int <function>pws3_field_set_text</function></funcdef>
355 <paramdef>struct pws3_field
356 *<parameter><replaceable>field</replaceable></parameter></paramdef>
357 <paramdef>const char
358 <parameter><replaceable>s</replaceable>[static 1]</parameter></paramdef>
359 </funcprototype>
360 <funcprototype>
361 <funcdef>int <function>pws3_field_set_time</function></funcdef>
362 <paramdef>struct pws3_field
363 *<parameter><replaceable>field</replaceable></parameter></paramdef>
364 <paramdef>time_t
365 <parameter><replaceable>time</replaceable></parameter></paramdef>
366 </funcprototype>
367 <funcprototype>
368 <funcdef>int <function>pws3_field_set_uint8</function></funcdef>
369 <paramdef>struct pws3_field
370 *<parameter><replaceable>field</replaceable></parameter></paramdef>
371 <paramdef>uint8_t
372 <parameter><replaceable>u8</replaceable></parameter></paramdef>
373 </funcprototype>
374 <funcprototype>
375 <funcdef>int <function>pws3_field_set_uint16</function></funcdef>
376 <paramdef>struct pws3_field
377 *<parameter><replaceable>field</replaceable></parameter></paramdef>
378 <paramdef>uint16_t
379 <parameter><replaceable>u16</replaceable></parameter></paramdef>
380 </funcprototype>
381 <funcprototype>
382 <funcdef>int <function>pws3_field_set_uint32</function></funcdef>
383 <paramdef>struct pws3_field
384 *<parameter><replaceable>field</replaceable></parameter></paramdef>
385 <paramdef>uint32_t
386 <parameter><replaceable>u32</replaceable></parameter></paramdef>
387 </funcprototype>
388 <funcprototype>
389 <funcdef>int <function>pws3_field_set_bytes</function></funcdef>
390 <paramdef>struct pws3_field
391 *<parameter><replaceable>field</replaceable></parameter></paramdef>
392 <paramdef>const unsigned char
393 <parameter><replaceable>s</replaceable>[static 1]</parameter></paramdef>
394 <paramdef>size_t
395 <parameter><replaceable>n</replaceable></parameter></paramdef>
396 </funcprototype>
397 <funcprototype>
398 <funcdef>const unsigned char *
399 <function>pws3_field_get_uuid</function></funcdef>
400 <paramdef>struct pws3_field
401 *<parameter><replaceable>field</replaceable></parameter></paramdef>
402 </funcprototype>
403 <funcprototype>
404 <funcdef>const char *
405 <function>pws3_field_get_text</function></funcdef>
406 <paramdef>struct pws3_field
407 *<parameter><replaceable>field</replaceable></parameter></paramdef>
408 </funcprototype>
409 <funcprototype>
410 <funcdef>time_t
411 <function>pws3_field_get_time</function></funcdef>
412 <paramdef>struct pws3_field
413 *<parameter><replaceable>field</replaceable></parameter></paramdef>
414 </funcprototype>
415 <funcprototype>
416 <funcdef>uint8_t
417 <function>pws3_field_get_uint8</function></funcdef>
418 <paramdef>struct pws3_field
419 *<parameter><replaceable>field</replaceable></parameter></paramdef>
420 </funcprototype>
421 <funcprototype>
422 <funcdef>uint16_t
423 <function>pws3_field_get_uint16</function></funcdef>
424 <paramdef>struct pws3_field
425 *<parameter><replaceable>field</replaceable></parameter></paramdef>
426 </funcprototype>
427 <funcprototype>
428 <funcdef>uint32_t
429 <function>pws3_field_get_uint32</function></funcdef>
430 <paramdef>struct pws3_field
431 *<parameter><replaceable>field</replaceable></parameter></paramdef>
432 </funcprototype>
433 <funcprototype>
434 <funcdef>void <function>pws3_field_get_bytes</function></funcdef>
435 <paramdef>struct pws3_field
436 *<parameter><replaceable>field</replaceable></parameter></paramdef>
437 <paramdef>const unsigned char
438 **<parameter><replaceable>pp</replaceable></parameter></paramdef>
439 <paramdef>size_t
440 *<parameter><replaceable>np</replaceable></parameter></paramdef>
441 </funcprototype>
442 </funcsynopsis>
443 <synopsis>
444 <constant>PWS3_VERSION</constant>
445
446 <constant>PWS3_MAX_FIELD_LEN</constant>
447
448 <constant>PWS3_MAX_PASSWORD_LEN</constant>
449
450 <constant>PWS3_UUID_SIZE</constant>
451
452 struct pws3_field;
453
454 struct pws3_record;
455
456 struct pws3_file;
457
458 enum pws_error_code;
459
460 enum pws_data_type;
461
462 enum pws3_header_field_type;
463
464 enum pws3_record_field_type;
465 </synopsis>
466 </refsynopsisdiv>
467 <refsect1>
468 <title>Description</title>
469 <refsect2>
470 <title>Introduction</title>
471 <para>The <function>pws3_*()</function> family of functions allows
472 creating, reading, writing, and manipulating Password Safe version 3
473 files. Password Safe version 3 files consist of a header and a body part.
474 The header is comprised of both mandatory and optional typed header
475 fields which hold file-wide metadata. The body consists of records which
476 in turn hold passwords and associated metadata in typed record
477 fields.</para>
478 <para>A header or record field value can be of one of seven basic data
479 types defined below:
480 <table xml:id="table-data-types">
481 <title>Header and Record Field Value Data Types</title>
482 <tgroup cols="3" align="left" colsep="1" rowsep="1">
483 <thead>
484 <row>
485 <entry>Data Type</entry>
486 <entry>C Type</entry>
487 <entry>Description</entry>
488 </row>
489 </thead>
490 <tbody>
491 <row>
492 <entry><constant>PWS_DATA_TYPE_UUID</constant></entry>
493 <entry><code>unsigned char [PWS3_UUID_SIZE]</code></entry>
494 <entry>UUID</entry>
495 </row>
496 <row>
497 <entry><constant>PWS_DATA_TYPE_TEXT</constant></entry>
498 <entry><code>char *</code></entry>
499 <entry>NUL-delimited UTF-8 encoded string</entry>
500 </row>
501 <row>
502 <entry><constant>PWS_DATA_TYPE_TIME</constant></entry>
503 <entry><code>time_t</code></entry>
504 <entry>system-specific representation of time</entry>
505 </row>
506 <row>
507 <entry><constant>PWS_DATA_TYPE_UINT8</constant></entry>
508 <entry><code>uint8_t</code></entry>
509 <entry>8-bit wide unsigned integer</entry>
510 </row>
511 <row>
512 <entry><constant>PWS_DATA_TYPE_UINT16</constant></entry>
513 <entry><code>uint16_t</code></entry>
514 <entry>16-bit wide unsigned integer</entry>
515 </row>
516 <row>
517 <entry><constant>PWS_DATA_TYPE_UINT32</constant></entry>
518 <entry><code>uint32_t</code></entry>
519 <entry>32-bit wide unsigned integer</entry>
520 </row>
521 <row>
522 <entry><constant>PWS_DATA_TYPE_BYTES</constant></entry>
523 <entry><code>unsigned char *</code></entry>
524 <entry>array of bytes</entry>
525 </row>
526 </tbody>
527 </tgroup>
528 </table>
529 </para>
530 <para>The data type of each header field is defined in
531 <xref linkend="table-header-fields"/> and the data type of each record
532 field is defined in <xref linkend="table-record-fields"/>. Each header
533 field, with the exception of the empty groups header field, can only
534 occur once. The version header field
535 (<constant>PWS3_HEADER_FIELD_VERSION</constant>) is mandatory and must
536 not be removed. When reading a file its value is checked and an error is
537 returned if the file format version newer than the one supported by
538 <citerefentry><refentrytitle>libpws</refentrytitle><manvolnum>3</manvolnum></citerefentry>.
539 The supported version is defined by the <constant>PWS3_VERSION</constant>
540 macro, when creating a new file structure the version header field will be
541 set to its value by default. Non-standard header and record fields will
542 be preserved when a file is read and subsequently written again, they may
543 be read and manipulated as if they had
544 <constant>PWS_DATA_TYPE_BYTES</constant> data type. All strings are
545 expected to be in UTF-8 encoding.</para>
546 <para>The only mandatory record field is the UUID field which uniquely
547 identifies a record in the file.</para>
548 <para>The complete and authoritative specification of the file format is
549 included with the original Password Safe application available from <link
550 xlink:href="https://pwsafe.org/"/>.</para>
551 </refsect2>
552 <refsect2>
553 <title>Password Safe File Data Structure</title>
554 <para>The <function>pws3_file_create()</function> function allocates and
555 intializes a Password Safe file data structure representing a Password
556 Safe version 3 file. It automatically creates the mandatory version header
557 field and initializes it to the value of the
558 <constant>PWS3_VERSION</constant> macro.</para>
559 <para>The <function>pws3_file_destroy()</function> function deallocates
560 all header fields and records of the file structure passed to it and then
561 deallocates the file structure itself.</para>
562 <para>The <function>pws3_file_read_mem()</function> and
563 <function>pws3_file_read_stream()</function> functions read and parse a
564 Password Safe file into the given data structure passed via the
565 <parameter>pws_file</parameter> argument, replacing any existing header
566 fields and records. The key used to decrypt the file is derived from the
567 given <parameter>password</parameter> parameter. The
568 <function>pws3_file_read_mem()</function> function reads the file from a
569 block of memory <parameter>s</parameter> with the size of
570 <parameter>n</parameter> bytes. The
571 <function>pws3_file_read_stream()</function> reads the file from the
572 stream of the <parameter>fp</parameter> file pointer.</para>
573 <para>The <function>pws3_file_write_mem()</function> and
574 <function>pws3_file_write_stream()</function> functions write a new
575 Password Safe file from the given datat structure. The key used to
576 encrypt the file is derived from the <parameter>password</parameter>
577 argument using the number of iterations to stretch the key determined by
578 the <parameter>n_iter</parameter> argument. The
579 <function>pws3_file_write_mem()</function> will allocate and place the
580 file contents into memory and return the location and size to the
581 locations <parameter>sp</parameter> and <parameter>np</parameter>
582 point to. The <function>pws3_file_write_stream()</function> will write the
583 file contents to the stream of the <parameter>fp</parameter> file
584 pointer.</para>
585 </refsect2>
586 <refsect2>
587 <title>Fields</title>
588 <para>Both header and record fields are stored in
589 <varname>pws3_field</varname> structures which are allocated and
590 initialized with the <function>pws3_field_create()</function> function.
591 Depending on whether <parameter>is_header</parameter> is non-zero either
592 a header field or a record field data structure of the given field type
593 will be created.</para>
594 <para>The <function>pws3_field_destroy()</function> function
595 deallocates the given field data structure and its content.</para>
596 <para>The <function>pws3_field_is_header()</function> function
597 can be used to test whether the given field data structure refers to a
598 header field or a record field.</para>
599 <para>The <function>pws3_field_get_type()</function> function
600 returns the field type of the given field data structure.</para>
601 <para>The <function>pws3_field_get_data_type()</function> function
602 returns the data type of the given field structure.</para>
603 <para>The <function>pws3_field_set_uuid()</function>,
604 <function>pws3_field_set_text()</function>,
605 <function>pws3_field_set_time()</function>,
606 <function>pws3_field_set_uint8()</function>,
607 <function>pws3_field_set_uint16()</function>,
608 <function>pws3_field_set_uint32()</function>, and
609 <function>pws3_field_set_bytes()</function> functions set the
610 content of the given field. The given data is always copied and
611 existing content is replaced. The data type used by the function must
612 match the data type of the field specified in <xref
613 linkend="table-header-fields"/> in case of header fields or that in <xref
614 linkend="table-record-fields"/> in case of record fields.</para>
615 <para>The <function>pws3_field_get_time()</function>,
616 <function>pws3_field_get_uint8()</function>,
617 <function>pws3_field_get_uint16()</function>, and
618 <function>pws3_field_get_uint32()</function> functions return the
619 value of the given field. The
620 <function>pws3_field_get_uuid()</function>,
621 <function>pws3_field_get_text()</function>, and
622 <function>pws3_field_get_bytes()</function> functions return a
623 pointer to the data of the given field if it has been set. The data type
624 used by the function must match the data type of the field specified in
625 <xref linkend="table-header-fields"/> in case of header fields and that
626 in <xref linkend="table-record-fields"/> in case of record fields.
627 Returned pointers are only valid until a field is modified or
628 deallocated.</para>
629 </refsect2>
630 <refsect2>
631 <title>Header Fields</title>
632 <para>Header fields are used to store metadata for the whole file, each
633 type of header field with the exception of the empty groups header field
634 only occurs once. The following header fields are supported:
635 <table xml:id="table-header-fields">
636 <title>Header Fields</title>
637 <tgroup cols="4" align="left" colsep="1" rowsep="1">
638 <thead>
639 <row>
640 <entry>Header Field Type</entry>
641 <entry>Numeric Value</entry>
642 <entry>Data Type</entry>
643 <entry>Description</entry>
644 </row>
645 </thead>
646 <tbody>
647 <row>
648 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;VERSION</constant></entry>
649 <entry><literal>0x00</literal></entry>
650 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT16</constant></entry>
651 <entry>file format version</entry>
652 </row>
653 <row>
654 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;UUID</constant></entry>
655 <entry><literal>0x01</literal></entry>
656 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UUID</constant></entry>
657 <entry>UUID</entry>
658 </row>
659 <row>
660 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;NON_&#8203;DEFAULT_&#8203;PREFERENCES</constant></entry>
661 <entry><literal>0x02</literal></entry>
662 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
663 <entry>non-default preferences</entry>
664 </row>
665 <row>
666 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;TREE_&#8203;DISPLAY_&#8203;STATUS</constant></entry>
667 <entry><literal>0x03</literal></entry>
668 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
669 <entry>expandended/&#8203;collapsed state of the tree of groups</entry>
670 </row>
671 <row>
672 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;TIMESTAMP</constant></entry>
673 <entry><literal>0x04</literal></entry>
674 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
675 <entry>time when the file was last saved</entry>
676 </row>
677 <row>
678 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;USER_&#8203;HOST</constant></entry>
679 <entry><literal>0x05</literal></entry>
680 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
681 <entry>name of the user who last saved the file and name of the host where the file was saved</entry>
682 </row>
683 <row>
684 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;APPLICATION</constant></entry>
685 <entry><literal>0x06</literal></entry>
686 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
687 <entry>name of the application used to save the file</entry>
688 </row>
689 <row>
690 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;USER</constant></entry>
691 <entry><literal>0x07</literal></entry>
692 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
693 <entry>name of the user who last saved the file</entry>
694 </row>
695 <row>
696 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;SAVE_&#8203;HOST</constant></entry>
697 <entry><literal>0x08</literal></entry>
698 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
699 <entry>name of the host where the file was last saved</entry>
700 </row>
701 <row>
702 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;DATABASE_&#8203;NAME</constant></entry>
703 <entry><literal>0x09</literal></entry>
704 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
705 <entry>logical name for referring to the file</entry>
706 </row>
707 <row>
708 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;DATABASE_&#8203;DESCRIPTION</constant></entry>
709 <entry><literal>0x0a</literal></entry>
710 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
711 <entry>description of the file</entry>
712 </row>
713 <row>
714 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;DATABASE_&#8203;FILTERS</constant></entry>
715 <entry><literal>0x0b</literal></entry>
716 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
717 <entry>filters for this file</entry>
718 </row>
719 <row>
720 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RESERVED_&#8203;1</constant></entry>
721 <entry><literal>0x0c</literal></entry>
722 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
723 <entry>reserved</entry>
724 </row>
725 <row>
726 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RESERVED_&#8203;2</constant></entry>
727 <entry><literal>0x0d</literal></entry>
728 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
729 <entry>reserved</entry>
730 </row>
731 <row>
732 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RESERVED_&#8203;3</constant></entry>
733 <entry><literal>0x0e</literal></entry>
734 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
735 <entry>reseved</entry>
736 </row>
737 <row>
738 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;RECENTLY_&#8203;USED_&#8203;ENTRIES</constant></entry>
739 <entry><literal>0x0f</literal></entry>
740 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
741 <entry>list of recently used entries</entry>
742 </row>
743 <row>
744 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;NAMED_&#8203;PASSWORD_&#8203;POLICIES</constant></entry>
745 <entry><literal>0x10</literal></entry>
746 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
747 <entry>named password policies</entry>
748 </row>
749 <row>
750 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;EMPTY_&#8203;GROUPS</constant></entry>
751 <entry><literal>0x11</literal></entry>
752 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
753 <entry>empty groups which contain no entries</entry>
754 </row>
755 <row>
756 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;YUBICO</constant></entry>
757 <entry><literal>0x12</literal></entry>
758 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
759 <entry>reserved</entry>
760 </row>
761 </tbody>
762 </tgroup>
763 </table>
764 </para>
765 <para>The <function>pws3_file_set_header_field()</function> function sets
766 the header field on the given file. An existing field of the same type is
767 replaced with the exception of fields of type
768 <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> for which
769 <function>pws3_file_set_header_field()</function> has the same effect as
770 calling the <function>pws3_file_insert_empty_group()</function>
771 function.</para>
772 <para>The <function>pws3_file_get_header_field()</function> function
773 returns a pointer to the header field data structure of the given header
774 field type. In case of the
775 <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> field type a pointer
776 to the first empty group field is returned.</para>
777 <para>The <function>pws3_file_remove_header_field()</function> function
778 removes the header field from the given file and returns a pointer to it.
779 It is the responsibility of the caller to deallocate the header field
780 data structure. In case of the
781 <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> field type the first
782 empty group is removed.</para>
783 <para>The <function>pws3_file_insert_empty_group()</function> function
784 inserts the given empty groups field into the file, an existing field for
785 a group of the same name is replaced.</para>
786 <para>The <function>pws3_file_get_empty_group()</function> function
787 returns a pointer to the header field datat structure representing an
788 empty group of the given name.</para>
789 <para>The <function>pws3_file_remove_empty_group()</function> function
790 removes the field representing the empty group of the given name from the
791 file and returns a pointer to the header field data structure. It is the
792 responsibility of the caller to deallocate the header field data
793 structure.</para>
794 <para>The <function>pws3_file_first_empty_group()</function> function
795 returns a pointer to the first empty group header field.</para>
796 <para>The <function>pws3_file_last_empty_group()</function> function
797 returns a pointer to the last empty group header field.</para>
798 <para>The <function>pws3_file_next_empty_group()</function> function
799 returns a pointer to the next empty group header filed data structure
800 following the given <parameter>field</parameter>.</para>
801 <para>The <function>pws3_file_prev_empty_groupious()</function> function
802 returns a pointer to the previous empty group header filed data structure
803 preceding the given <parameter>field</parameter>.</para>
804 </refsect2>
805 <refsect2>
806 <title>Records</title>
807 <para>Records consist of at least one or more typed fields, they are
808 identified by an UUID which is the only mandatory field and must not be
809 removed. For presentational purposes records may be organized in
810 hierarchical groups. The following record fields are supported:
811 <table xml:id="table-record-fields">
812 <title>Record Fields</title>
813 <tgroup cols="4" align="left" colsep="1" rowsep="1">
814 <thead>
815 <row>
816 <entry>Record Field Type</entry>
817 <entry>Numeric Value</entry>
818 <entry>Data Type</entry>
819 <entry>Description</entry>
820 </row>
821 </thead>
822 <tbody>
823 <row>
824 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;UUID</constant></entry>
825 <entry><literal>0x01</literal></entry>
826 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UUID</constant></entry>
827 <entry>UUID identifying the record</entry>
828 </row>
829 <row>
830 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;GROUP</constant></entry>
831 <entry><literal>0x02</literal></entry>
832 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
833 <entry>group name the record is a member of</entry>
834 </row>
835 <row>
836 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;TITLE</constant></entry>
837 <entry><literal>0x03</literal></entry>
838 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
839 <entry>title</entry>
840 </row>
841 <row>
842 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;USERNAME</constant></entry>
843 <entry><literal>0x04</literal></entry>
844 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
845 <entry>username</entry>
846 </row>
847 <row>
848 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;NOTES</constant></entry>
849 <entry><literal>0x05</literal></entry>
850 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
851 <entry>notes</entry>
852 </row>
853 <row>
854 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD</constant></entry>
855 <entry><literal>0x06</literal></entry>
856 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
857 <entry>password</entry>
858 </row>
859 <row>
860 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;CREATION_&#8203;TIME</constant></entry>
861 <entry><literal>0x07</literal></entry>
862 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
863 <entry>time when the record was created</entry>
864 </row>
865 <row>
866 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;MODIFICATION_&#8203;TIME</constant></entry>
867 <entry><literal>0x08</literal></entry>
868 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
869 <entry>time when the password was last modified</entry>
870 </row>
871 <row>
872 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;ACCESS_&#8203;TIME</constant></entry>
873 <entry><literal>0x09</literal></entry>
874 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
875 <entry>time when the record was last accessed</entry>
876 </row>
877 <row>
878 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;EXPIRY_&#8203;TIME</constant></entry>
879 <entry><literal>0x0a</literal></entry>
880 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
881 <entry>time when the password expires</entry>
882 </row>
883 <row>
884 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;RESERVED_&#8203;1</constant></entry>
885 <entry><literal>0x0b</literal></entry>
886 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
887 <entry>reserved</entry>
888 </row>
889 <row>
890 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;MODIFICATION_&#8203;TIME</constant></entry>
891 <entry><literal>0x0c</literal></entry>
892 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
893 <entry>time at whcih the record was last modified</entry>
894 </row>
895 <row>
896 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;URL</constant></entry>
897 <entry><literal>0x0d</literal></entry>
898 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
899 <entry>URL</entry>
900 </row>
901 <row>
902 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;AUTOTYPE</constant></entry>
903 <entry><literal>0x0e</literal></entry>
904 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
905 <entry>text to be typed when using the autotype feature</entry>
906 </row>
907 <row>
908 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;HISTORY</constant></entry>
909 <entry><literal>0x0f</literal></entry>
910 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
911 <entry>creation time and values of previously used passwords</entry>
912 </row>
913 <row>
914 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;POLICY</constant></entry>
915 <entry><literal>0x10</literal></entry>
916 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
917 <entry>password policy</entry>
918 </row>
919 <row>
920 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;EXPIRY_&#8203;INTERVAL</constant></entry>
921 <entry><literal>0x11</literal></entry>
922 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT32</constant></entry>
923 <entry>days until the password expires</entry>
924 </row>
925 <row>
926 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;RUN_&#8203;COMMAND</constant></entry>
927 <entry><literal>0x12</literal></entry>
928 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
929 <entry>command</entry>
930 </row>
931 <row>
932 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;DOUBLE_&#8203;CLICK_&#8203;ACTION</constant></entry>
933 <entry><literal>0x13</literal></entry>
934 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
935 <entry>action on double clicking</entry>
936 </row>
937 <row>
938 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;EMAIL_&#8203;ADDRESS</constant></entry>
939 <entry><literal>0x14</literal></entry>
940 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
941 <entry>email address</entry>
942 </row>
943 <row>
944 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PROTECTED</constant></entry>
945 <entry><literal>0x15</literal></entry>
946 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT8</constant></entry>
947 <entry>flag whether the record is protected from modification</entry>
948 </row>
949 <row>
950 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;ALLOWED_&#8203;PASSWORD_&#8203;SYMBOLS</constant></entry>
951 <entry><literal>0x16</literal></entry>
952 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
953 <entry>allowed symbols for generating passwords</entry>
954 </row>
955 <row>
956 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;SHIFT_&#8203;DOUBLE_&#8203;CLICK_&#8203;ACTION</constant></entry>
957 <entry><literal>0x17</literal></entry>
958 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
959 <entry>action on pressing shift and double clicking</entry>
960 </row>
961 <row>
962 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;POLICY_&#8203;NAME</constant></entry>
963 <entry><literal>0x18</literal></entry>
964 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
965 <entry>name of password policy saved in the header</entry>
966 </row>
967 <row>
968 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;KEYBOARD_&#8203;SHORTCUT</constant></entry>
969 <entry><literal>0x19</literal></entry>
970 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
971 <entry>keyboard shortcut</entry>
972 </row>
973 </tbody>
974 </tgroup>
975 </table>
976 </para>
977 <para>The <function>pws3_record_create()</function> function allocates
978 and creates a record data structure, generates an UUID record field and
979 adds it to the record.</para>
980 <para>The <function>pws3_record_destroy()</function> function deallocates
981 the given record data structure and all its record fields.</para>
982 <para>The <function>pws3_file_record_field_set()</function> function sets
983 the record field on the given record, replacing an existing field of the
984 same type.</para>
985 <para>The <function>pws3_file_record_field_get()</function> function
986 returns a pointer to the record field data structure of the given record
987 field type.</para>
988 <para>The <function>pws3_file_record_field_remove()</function> function
989 removes the record field from the given record and returns a pointer to
990 it. It is the responsibility of the caller to deallocate the record field
991 data structure.</para>
992 <para>The <function>pws3_file_insert_record()</function> function inserts
993 the given record into the file, an existing record with the same UUID is
994 replaced.</para>
995 <para>The <function>pws3_file_get_record()</function> function returns a
996 pointer to the record structure representing a record with the given
997 UUID.</para>
998 <para>The <function>pws3_file_remove_record()</function> function removes
999 the record with the given UUID from the file and returns a pointer to the
1000 record data structure. It is the responsibility of the caller to
1001 deallocate the record data structure.</para>
1002 <para>The <function>pws3_file_first_record()</function> function returns a
1003 pointer to the first record.</para>
1004 <para>The <function>pws3_file_last_record()</function> function returns a
1005 pointer to the last record.</para>
1006 <para>The <function>pws3_file_next_record()</function> function returns a
1007 pointer to the next record following the given
1008 <parameter>record</parameter>.</para>
1009 <para>The <function>pws3_file_prev_record()</function>
1010 function returns a pointer to the previous group preceding the given
1011 <parameter>record</parameter>.</para>
1012 </refsect2>
1013 <refsect2>
1014 <title>Macros</title>
1015 <para>The macro <constant>PWS3_VERSION</constant> contains the supported
1016 version of the Password Safe version 3 file format.</para>
1017 <para>The macro <constant>PWS3_MAX_FIELD_SIZE</constant> contains the
1018 maxium size for header and record fields in bytes and
1019 <constant>PWS3_MAX_PASSWORD_LEN</constant> contains the maxium password
1020 length in bytes.</para>
1021 <para>The macro <constant>PWS3_UUID_SIZE</constant> contains the size of
1022 UUIDs in bytes.</para>
1023 </refsect2>
1024 </refsect1>
1025 <refsect1>
1026 <title>Return Values</title>
1027 <para>The <function>pws3_file_create()</function> function returns a
1028 pointer to a Password Safe file data structure if successful and
1029 <constant>NULL</constant> in case of an error.</para>
1030 <para>The <function>pws3_file_read_mem()</function>,
1031 <function>pws3_file_read_stream()</function>,
1032 <function>pws3_file_write_mem()</function>, and
1033 <function>pws3_file_write_stream()</function> functions return
1034 <returnvalue>0</returnvalue> on success and <returnvalue>-1</returnvalue>
1035 to indicate an error.</para>
1036 <para>The <function>pws3_file_get_header_field()</function> function
1037 returns a pointer to the header field data structure of the requested type
1038 and <constant>NULL</constant> if such a field does not exist.</para>
1039 <para>The <function>pws3_file_remove_header_field()</function> function
1040 returns a pointer to the header field data structure which was removed from
1041 the file or <constant>NULL</constant> if such a field does not exist.</para>
1042 <para>The <function>pws3_file_get_empty_group()</function> function returns
1043 a pointer to the header field data structure corresponding to the requested
1044 empty group and <constant>NULL</constant> if a group of that name does not
1045 exist.</para>
1046 <para>The <function>pws3_file_remove_empty_group()</function> function
1047 returns a pointer to the header field data structure of the empty group
1048 which was removed from the file or <constant>NULL</constant> if a group of
1049 that name does not exist.</para>
1050 <para>The <function>pws3_file_first_empty_group()</function> function
1051 returns a pointer to the first of the empty group header fields or
1052 <constant>NULL</constant> if there are no such fields.</para>
1053 <para>The <function>pws3_file_last_empty_group()</function> function
1054 returns a pointer to the last of the empty group header fields or
1055 <constant>NULL</constant> if there are no such fields.</para>
1056 <para>The <function>pws3_file_next_empty_group()</function> function
1057 returns a pointer to the next empty group header field or
1058 <constant>NULL</constant> if there are no more such fields.</para>
1059 <para>The <function>pws3_file_prev_empty_group()</function> function
1060 returns a pointer to the previous empty group header field or
1061 <constant>NULL</constant> if there are no more such fields.</para>
1062 <para>The <function>pws3_file_get_record()</function> function returns a
1063 pointer to the record data structure of the requested record or
1064 <constant>NULL</constant> if that record does not exist.</para>
1065 <para>The <function>pws3_file_remove_record()</function> function returns a
1066 pointer to the record data structure which was removed from the file or
1067 <constant>NULL</constant> if no such record exists.</para>
1068 <para>The <function>pws3_file_first_record()</function> function returns a
1069 pointer to the record data structure of the first record or
1070 <constant>NULL</constant> if no records exist.</para>
1071 <para>The <function>pws3_file_last_record()</function> function returns a
1072 pointer to the record data structure of the last record or
1073 <constant>NULL</constant> if no records exist.</para>
1074 <para>The <function>pws3_file_next_record()</function> function returns a
1075 pointer to the record data structure of the next record or
1076 <constant>NULL</constant> if no records exist.</para>
1077 <para>The <function>pws3_file_prev_record()</function> function returns a
1078 pointer to the record data structure of the previous record or
1079 <constant>NULL</constant> if no records exist.</para>
1080 <para>The <function>pws3_field_create()</function> function returns a
1081 pointer to the new header field data structure on success and
1082 <constant>NULL</constant> on failure.</para>
1083 <para>The <function>pws3_field_get_type()</function> function returns
1084 the field type of the header field structure.</para>
1085 <para>The <function>pws3_field_get_data_type()</function> function
1086 returns the data type of the header field structure.</para>
1087 <para>The <function>pws3_field_set_uuid()</function>,
1088 <function>pws3_field_set_text()</function>,
1089 <function>pws3_field_set_time()</function>,
1090 <function>pws3_field_set_uint8()</function>,
1091 <function>pws3_field_set_uint16()</function>,
1092 <function>pws3_field_set_uint32()</function>, and
1093 <function>pws3_field_set_bytes()</function> functions return
1094 <returnvalue>0</returnvalue> on success and <returnvalue>-1</returnvalue>
1095 on failure.</para>
1096 <para>The <function>pws3_field_get_time()</function>,
1097 <function>pws3_field_get_uint8()</function>,
1098 <function>pws3_field_get_uint16()</function>, and
1099 <function>pws3_field_get_uint32()</function> functions return a
1100 value of the type corresponding to the type of header field.</para>
1101 <para>The <function>pws3_field_get_uuid()</function> function
1102 returns a pointer to a UUID.</para>
1103 <para>The <function>pws3_field_get_text()</function> function
1104 returns a pointer to a string or <constant>NULL</constant> if no value has
1105 been set.</para>
1106 <para>The <function>pws3_record_create()</function> function returns a
1107 pointer to a record data structure if successful and
1108 <constant>NULL</constant> on failure.</para>
1109 <para>The <function>pws3_record_get_field()</function> function returns a
1110 pointer to the record field data structure of the requested type or
1111 <constant>NULL</constant> if such a field does not exist.</para>
1112 <para>The <function>pws3_record_remove_field()</function> function returns
1113 a pointer to the record field data structure which was removed from the
1114 record or <constant>NULL</constant> if such a field does not exist.</para>
1115 </refsect1>
1116 <refsect1>
1117 <title>Errors</title>
1118 <para>If the <function>pws3_file_read_mem()</function>,
1119 <function>pws3_file_read_stream()</function>,
1120 <function>pws3_file_write_mem()</function>, and
1121 <function>pws3_file_write_stream()</function> functions fail, an error code
1122 indicating the nature of the error may be obtained using the
1123 <function>pws3_file_get_error_code()</function> function and a pointer to a
1124 detailed error message may be retrieved using the
1125 <function>pws3_file_get_error_message()</function> function. The above
1126 functions may fail if:</para>
1127 <variablelist>
1128 <varlistentry>
1129 <term><errorname>PWS_ERR_GENERIC_ERROR</errorname></term>
1130 <listitem>
1131 <para>An unknown error occurred.</para>
1132 </listitem>
1133 </varlistentry>
1134 <varlistentry>
1135 <term><errorname>PWS_ERR_NO_MEMORY</errorname></term>
1136 <listitem>
1137 <para>There was not enough space to allocate memory.</para>
1138 </listitem>
1139 </varlistentry>
1140 <varlistentry>
1141 <term><errorname>PWS_ERR_IO_ERROR</errorname></term>
1142 <listitem>
1143 <para>An I/O error occurred.</para>
1144 </listitem>
1145 </varlistentry>
1146 <varlistentry>
1147 <term><errorname>PWS_ERR_TRUNCATED_FILE</errorname></term>
1148 <listitem>
1149 <para>The file appears to be truncated.</para>
1150 </listitem>
1151 </varlistentry>
1152 <varlistentry>
1153 <term><errorname>PWS_ERR_INVALID_CHECKSUM</errorname></term>
1154 <listitem>
1155 <para>The calculated checksum does not match the checksum of the
1156 file.</para>
1157 </listitem>
1158 </varlistentry>
1159 <varlistentry>
1160 <term><errorname>PWS_ERR_INVALID_RECORD</errorname></term>
1161 <listitem>
1162 <para>A record is invalid.</para>
1163 </listitem>
1164 </varlistentry>
1165 <varlistentry>
1166 <term><errorname>PWS_ERR_INVALID_HEADER</errorname></term>
1167 <listitem>
1168 <para>A header is invalid.</para>
1169 </listitem>
1170 </varlistentry>
1171 <varlistentry>
1172 <term><errorname>PWS_ERR_UNSUPPORTED_VERSION</errorname></term>
1173 <listitem>
1174 <para>The file format version is not supported.</para>
1175 </listitem>
1176 </varlistentry>
1177 </variablelist>
1178 </refsect1>
1179 <refsect1>
1180 <title>Examples</title>
1181 <example>
1182 <title>Creating a Password Safe file</title>
1183 <para>The following code creates a new Password Safe file and sets the
1184 save application header field:</para>
1185 <programlisting>
1186 <![CDATA[
1187 #include <pws.h>
1188
1189 /* ... */
1190
1191 struct pws3_file *file;
1192 struct pws3_field *application_field;
1193
1194 /* ... */
1195
1196 /* initialize libpws */
1197 if (pws_init() != 0) {
1198 /* handle error */
1199 }
1200
1201 /* ... */
1202
1203 /* create a new empty file structure */
1204 file = pws3_file_create();
1205 if (file == NULL) {
1206 /* handle error */
1207 }
1208 /* create new empty save application field */
1209 application_field = pws3_field_create(1, PWS3_HEADER_FIELD_SAVE_APPLICATION);
1210 if (application_field == NULL) {
1211 /* handle error */
1212 }
1213 /* set the value of the field */
1214 if (pws3_field_set_text(application_field, "PasswordManager 2.0") != 0) {
1215 /* handle error */
1216 }
1217 /* set the header save application field in the file to the new field */
1218 pws3_file_set_field(file, application_field);
1219 ]]>
1220 </programlisting>
1221 </example>
1222 <example>
1223 <title>Print the title of each record</title>
1224 <para>The following code loops over each record of an existing Password
1225 Safe file and prints the content of the title field if it exists:</para>
1226 <programlisting>
1227 <![CDATA[
1228 #include <stdio.h>
1229 #include <pws.h>
1230
1231 /* ... */
1232
1233 struct pws3_file *file;
1234 struct pws3_record *record;
1235 struct pws3_field *title_field;
1236
1237 /* ... */
1238
1239 /* interate over each record */
1240 for (record = pws3_file_first_record(file); record != NULL;
1241 record = pws3_file_next_record(file, record)) {
1242 /* retrieve title field */
1243 title_field = pws3_record_get_field(record, PWS3_RECORD_FIELD_TITLE);
1244 /* print the title field or "No title" if it does not exitst */
1245 printf("Title: %s\n", (title_field != NULL) ?
1246 pws3_record_field_get_text(PWS3_RECORD_FIELD_TITLE) : "No title");
1247 }
1248 ]]>
1249 </programlisting>
1250 </example>
1251 <example>
1252 <title>Add a new record to a file</title>
1253 <para>The following code creates a new record with a password field, a
1254 title field, and a creation time field and adds it to an existing
1255 Password Safe file:</para>
1256 <programlisting>
1257 <![CDATA[
1258 #include <time.h>
1259 #include <pws.h>
1260
1261 /* ... */
1262
1263 struct pws3_file *file;
1264 struct pws3_record *record;
1265 struct pws3_field *password_field;
1266 struct pws3_field *title_field;
1267 struct pws3_field *ctime_field;
1268 time_t now;
1269
1270 /* ... */
1271
1272 /* create new record */
1273 record = pws3_record_create();
1274 if (record == NULL) {
1275 /* handle error */
1276 }
1277
1278 /* create a password field */
1279 password_field = pws3_record_field_create(PWS3_RECORD_FIELD_PASSWORD);
1280 if (password_field == NULL) {
1281 /* handle error */
1282 }
1283 /* set the value of the password field to "PaSsWoRd" */
1284 if (pws3_record_field_set_text(password_field, "PaSsWoRd") != 0) {
1285 /* handle error */
1286 }
1287 /* set the password field of the record to the new field */
1288 pws3_record_set_field(record, password_field);
1289
1290 /* create a title field */
1291 title_field = pws3_record_field_create(PWS3_RECORD_FIELD_TITLE);
1292 if (title_field == NULL) {
1293 /* handle error */
1294 }
1295 /* set the value of the title field to "Foo Bar" */
1296 if (pws3_record_field_set_text(title_field, "Foo Bar") != 0) {
1297 /* handle error */
1298 }
1299 /* set the title field of the record to the new field */
1300 pws3_record_set_field(record, title_field);
1301
1302 /* create a new creation time field */
1303 ctime_field = pws3_record_field_create(PWS3_RECORD_FIELD_CREATION_TIME);
1304 if (ctime_field == NULL) {
1305 /* handle error */
1306 }
1307 /* set the value of the creation time field to the current time */
1308 pws3_record_field_set_time(ctime_field, time(NULL));
1309 /* set the creation time field of the record to the new field */
1310 pws3_record_set_field(record, ctime_field);
1311
1312 /* insert the new record into the file */
1313 pws3_file_insert_record(file, record);
1314 ]]>
1315 </programlisting>
1316 </example>
1317 <example>
1318 <title>Reading a Password Safe file</title>
1319 <para>The following code opens a Password Safe file named
1320 <filename>example.pwsafe3</filename> and parses it:</para>
1321 <programlisting>
1322 <![CDATA[
1323 #include <stdio.h>
1324 #include <pws.h>
1325
1326 /* ... */
1327
1328 FILE *fp;
1329 struct pws3_file *file;
1330
1331 /* ... */
1332
1333 /* initialize libpws */
1334 if (pws_init() != 0) {
1335 /* handle error */
1336 }
1337
1338 /* ... */
1339
1340 /* create a new empty file structure */
1341 file = pws3_file_create();
1342 if (file == NULL) {
1343 /* handle error */
1344 }
1345
1346 /* open the file */
1347 fp = fopen("example.pwsafe3", "r");
1348 if (fp == NULL) {
1349 /* handle error */
1350 }
1351
1352 /* read and parse the file contents into the file structure */
1353 if (pws3_file_read_stream(file, "PaSsWoRd", fp) != 0) {
1354 fprintf(stderr, "error: %s\n",
1355 pws3_file_get_error_message(file));
1356 /* handle error */
1357 }
1358 ]]>
1359 </programlisting>
1360 </example>
1361 <example>
1362 <title>Writing a Password Safe file</title>
1363 <para>The following code writes a Password Safe file to a file
1364 named <filename>example.pwsafe3</filename>:</para>
1365 <programlisting>
1366 <![CDATA[
1367 #include <stdio.h>
1368 #include <pws.h>
1369
1370 /* ... */
1371
1372 FILE *fp;
1373 struct pws3_file *file;
1374
1375 /* ... */
1376
1377 fp = fopen("example.pwsafe3", "w");
1378 if (fp == NULL) {
1379 /* handle error */
1380 }
1381
1382 if (pws3_file_write_stream(file, "FoOBaR", 10000, fp) != 0) {
1383 /* handle error */
1384 }
1385
1386 fflush(fp);
1387 fclose(fp);
1388 ]]>
1389 </programlisting>
1390 </example>
1391 </refsect1>
1392 <refsect1>
1393 <title>See Also</title>
1394 <para><citerefentry><refentrytitle>libpws</refentrytitle>
1395 <manvolnum>3</manvolnum></citerefentry>,
1396 <citerefentry><refentrytitle>pws_init</refentrytitle>
1397 <manvolnum>3</manvolnum></citerefentry>,
1398 <link xlink:href="https://pwsafe.org/"/></para>
1399 </refsect1>
1400 </refentry>