projects/libpws

view pws3_file_create.3.xml @ 13:2bb1bbac1d0a

Added tag version-1.0.0 for changeset 1926dfc9feb0
author Guido Berhoerster <guido+libpws@berhoerster.name>
date Sun Aug 04 21:37:56 2019 +0200 (2019-08-04)
parents b3fc9f7e2b43
children
line source
1 <?xml version="1.0"?>
2 <!--
4 Copyright (C) 2015 Guido Berhoerster <guido+libpws@berhoerster.name>
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:
14 The above copyright notice and this permission notice shall be included
15 in all copies or substantial portions of the Software.
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.
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>pws3_file_create</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>
446 <constant>PWS3_MAX_FIELD_LEN</constant>
448 <constant>PWS3_MAX_PASSWORD_LEN</constant>
450 <constant>PWS3_UUID_SIZE</constant>
452 struct pws3_field;
454 struct pws3_record;
456 struct pws3_file;
458 enum pws_error_code;
460 enum pws_data_type;
462 enum pws3_header_field_type;
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 <row>
762 <entry><constant>PWS3_&#8203;HEADER_&#8203;FIELD_&#8203;PASSWORD_&#8203;TIMESTAMP</constant></entry>
763 <entry><literal>0x13</literal></entry>
764 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
765 <entry>time the master password was last changed</entry>
766 </row>
767 </tbody>
768 </tgroup>
769 </table>
770 </para>
771 <para>The <function>pws3_file_set_header_field()</function> function sets
772 the header field on the given file. An existing field of the same type is
773 replaced with the exception of fields of type
774 <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> for which
775 <function>pws3_file_set_header_field()</function> has the same effect as
776 calling the <function>pws3_file_insert_empty_group()</function>
777 function.</para>
778 <para>The <function>pws3_file_get_header_field()</function> function
779 returns a pointer to the header field data structure of the given header
780 field type. In case of the
781 <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> field type a pointer
782 to the first empty group field is returned.</para>
783 <para>The <function>pws3_file_remove_header_field()</function> function
784 removes the header field from the given file and returns a pointer to it.
785 It is the responsibility of the caller to deallocate the header field
786 data structure. In case of the
787 <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> field type the first
788 empty group is removed.</para>
789 <para>The <function>pws3_file_insert_empty_group()</function> function
790 inserts the given empty groups field into the file, an existing field for
791 a group of the same name is replaced.</para>
792 <para>The <function>pws3_file_get_empty_group()</function> function
793 returns a pointer to the header field datat structure representing an
794 empty group of the given name.</para>
795 <para>The <function>pws3_file_remove_empty_group()</function> function
796 removes the field representing the empty group of the given name from the
797 file and returns a pointer to the header field data structure. It is the
798 responsibility of the caller to deallocate the header field data
799 structure.</para>
800 <para>The <function>pws3_file_first_empty_group()</function> function
801 returns a pointer to the first empty group header field.</para>
802 <para>The <function>pws3_file_last_empty_group()</function> function
803 returns a pointer to the last empty group header field.</para>
804 <para>The <function>pws3_file_next_empty_group()</function> function
805 returns a pointer to the next empty group header filed data structure
806 following the given <parameter>field</parameter>.</para>
807 <para>The <function>pws3_file_prev_empty_groupious()</function> function
808 returns a pointer to the previous empty group header filed data structure
809 preceding the given <parameter>field</parameter>.</para>
810 </refsect2>
811 <refsect2>
812 <title>Records</title>
813 <para>Records consist of at least one or more typed fields, they are
814 identified by an UUID which is the only mandatory field and must not be
815 removed. For presentational purposes records may be organized in
816 hierarchical groups. The following record fields are supported:
817 <table xml:id="table-record-fields">
818 <title>Record Fields</title>
819 <tgroup cols="4" align="left" colsep="1" rowsep="1">
820 <thead>
821 <row>
822 <entry>Record Field Type</entry>
823 <entry>Numeric Value</entry>
824 <entry>Data Type</entry>
825 <entry>Description</entry>
826 </row>
827 </thead>
828 <tbody>
829 <row>
830 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;UUID</constant></entry>
831 <entry><literal>0x01</literal></entry>
832 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UUID</constant></entry>
833 <entry>UUID identifying the record</entry>
834 </row>
835 <row>
836 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;GROUP</constant></entry>
837 <entry><literal>0x02</literal></entry>
838 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
839 <entry>group name the record is a member of</entry>
840 </row>
841 <row>
842 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;TITLE</constant></entry>
843 <entry><literal>0x03</literal></entry>
844 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
845 <entry>title</entry>
846 </row>
847 <row>
848 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;USERNAME</constant></entry>
849 <entry><literal>0x04</literal></entry>
850 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
851 <entry>username</entry>
852 </row>
853 <row>
854 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;NOTES</constant></entry>
855 <entry><literal>0x05</literal></entry>
856 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
857 <entry>notes</entry>
858 </row>
859 <row>
860 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD</constant></entry>
861 <entry><literal>0x06</literal></entry>
862 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
863 <entry>password</entry>
864 </row>
865 <row>
866 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;CREATION_&#8203;TIME</constant></entry>
867 <entry><literal>0x07</literal></entry>
868 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
869 <entry>time when the record was created</entry>
870 </row>
871 <row>
872 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;MODIFICATION_&#8203;TIME</constant></entry>
873 <entry><literal>0x08</literal></entry>
874 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
875 <entry>time when the password was last modified</entry>
876 </row>
877 <row>
878 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;ACCESS_&#8203;TIME</constant></entry>
879 <entry><literal>0x09</literal></entry>
880 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
881 <entry>time when the record was last accessed</entry>
882 </row>
883 <row>
884 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;EXPIRY_&#8203;TIME</constant></entry>
885 <entry><literal>0x0a</literal></entry>
886 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
887 <entry>time when the password expires</entry>
888 </row>
889 <row>
890 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;RESERVED_&#8203;1</constant></entry>
891 <entry><literal>0x0b</literal></entry>
892 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
893 <entry>reserved</entry>
894 </row>
895 <row>
896 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;MODIFICATION_&#8203;TIME</constant></entry>
897 <entry><literal>0x0c</literal></entry>
898 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TIME</constant></entry>
899 <entry>time at whcih the record was last modified</entry>
900 </row>
901 <row>
902 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;URL</constant></entry>
903 <entry><literal>0x0d</literal></entry>
904 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
905 <entry>URL</entry>
906 </row>
907 <row>
908 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;AUTOTYPE</constant></entry>
909 <entry><literal>0x0e</literal></entry>
910 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
911 <entry>text to be typed when using the autotype feature</entry>
912 </row>
913 <row>
914 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;HISTORY</constant></entry>
915 <entry><literal>0x0f</literal></entry>
916 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
917 <entry>creation time and values of previously used passwords</entry>
918 </row>
919 <row>
920 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;POLICY</constant></entry>
921 <entry><literal>0x10</literal></entry>
922 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
923 <entry>password policy</entry>
924 </row>
925 <row>
926 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;EXPIRY_&#8203;INTERVAL</constant></entry>
927 <entry><literal>0x11</literal></entry>
928 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT32</constant></entry>
929 <entry>days until the password expires</entry>
930 </row>
931 <row>
932 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;RUN_&#8203;COMMAND</constant></entry>
933 <entry><literal>0x12</literal></entry>
934 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
935 <entry>command</entry>
936 </row>
937 <row>
938 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;DOUBLE_&#8203;CLICK_&#8203;ACTION</constant></entry>
939 <entry><literal>0x13</literal></entry>
940 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
941 <entry>action on double clicking</entry>
942 </row>
943 <row>
944 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;EMAIL_&#8203;ADDRESS</constant></entry>
945 <entry><literal>0x14</literal></entry>
946 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
947 <entry>email address</entry>
948 </row>
949 <row>
950 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PROTECTED</constant></entry>
951 <entry><literal>0x15</literal></entry>
952 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UINT8</constant></entry>
953 <entry>flag whether the record is protected from modification</entry>
954 </row>
955 <row>
956 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;ALLOWED_&#8203;PASSWORD_&#8203;SYMBOLS</constant></entry>
957 <entry><literal>0x16</literal></entry>
958 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
959 <entry>allowed symbols for generating passwords</entry>
960 </row>
961 <row>
962 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;SHIFT_&#8203;DOUBLE_&#8203;CLICK_&#8203;ACTION</constant></entry>
963 <entry><literal>0x17</literal></entry>
964 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
965 <entry>action on pressing shift and double clicking</entry>
966 </row>
967 <row>
968 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;PASSWORD_&#8203;POLICY_&#8203;NAME</constant></entry>
969 <entry><literal>0x18</literal></entry>
970 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
971 <entry>name of password policy saved in the header</entry>
972 </row>
973 <row>
974 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;KEYBOARD_&#8203;SHORTCUT</constant></entry>
975 <entry><literal>0x19</literal></entry>
976 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
977 <entry>keyboard shortcut</entry>
978 </row>
979 <row>
980 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;RESERVED_&#8203;2</constant></entry>
981 <entry><literal>0x1a</literal></entry>
982 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;UUID</constant></entry>
983 <entry>reserved</entry>
984 </row>
985 <row>
986 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;TWO_&#8203;FACTOR_&#8203;KEY</constant></entry>
987 <entry><literal>0x1b</literal></entry>
988 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
989 <entry>two factor key</entry>
990 </row>
991 <row>
992 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;CREDIT_&#8203;CARD_&#8203;NUMBER</constant></entry>
993 <entry><literal>0x1c</literal></entry>
994 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
995 <entry>credit card number</entry>
996 </row>
997 <row>
998 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;CREDIT_&#8203;CARD_&#8203;EXPIRATION</constant></entry>
999 <entry><literal>0x1d</literal></entry>
1000 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
1001 <entry>credit card expiration</entry>
1002 </row>
1003 <row>
1004 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;CREDIT_&#8203;CARD_&#8203;VERIFICATION_&#8203;VALUE</constant></entry>
1005 <entry><literal>0x1e</literal></entry>
1006 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
1007 <entry>credit card verification value</entry>
1008 </row>
1009 <row>
1010 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;CREDIT_&#8203;CARD_&#8203;PIN</constant></entry>
1011 <entry><literal>0x1f</literal></entry>
1012 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
1013 <entry>credit card PIN</entry>
1014 </row>
1015 <row>
1016 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;QR_&#8203;CODE</constant></entry>
1017 <entry><literal>0x20</literal></entry>
1018 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;TEXT</constant></entry>
1019 <entry>QR code</entry>
1020 </row>
1021 <row>
1022 <entry><constant>PWS3_&#8203;RECORD_&#8203;FIELD_&#8203;TESTING_&#8203;1</constant></entry>
1023 <entry><literal>0xdf</literal></entry>
1024 <entry><constant>PWS_&#8203;DATA_&#8203;TYPE_&#8203;BYTES</constant></entry>
1025 <entry>testing</entry>
1026 </row>
1027 </tbody>
1028 </tgroup>
1029 </table>
1030 </para>
1031 <para>The <function>pws3_record_create()</function> function allocates
1032 and creates a record data structure, generates an UUID record field and
1033 adds it to the record.</para>
1034 <para>The <function>pws3_record_destroy()</function> function deallocates
1035 the given record data structure and all its record fields.</para>
1036 <para>The <function>pws3_file_record_field_set()</function> function sets
1037 the record field on the given record, replacing an existing field of the
1038 same type.</para>
1039 <para>The <function>pws3_file_record_field_get()</function> function
1040 returns a pointer to the record field data structure of the given record
1041 field type.</para>
1042 <para>The <function>pws3_file_record_field_remove()</function> function
1043 removes the record field from the given record and returns a pointer to
1044 it. It is the responsibility of the caller to deallocate the record field
1045 data structure.</para>
1046 <para>The <function>pws3_file_insert_record()</function> function inserts
1047 the given record into the file, an existing record with the same UUID is
1048 replaced.</para>
1049 <para>The <function>pws3_file_get_record()</function> function returns a
1050 pointer to the record structure representing a record with the given
1051 UUID.</para>
1052 <para>The <function>pws3_file_remove_record()</function> function removes
1053 the record with the given UUID from the file and returns a pointer to the
1054 record data structure. It is the responsibility of the caller to
1055 deallocate the record data structure.</para>
1056 <para>The <function>pws3_file_first_record()</function> function returns a
1057 pointer to the first record.</para>
1058 <para>The <function>pws3_file_last_record()</function> function returns a
1059 pointer to the last record.</para>
1060 <para>The <function>pws3_file_next_record()</function> function returns a
1061 pointer to the next record following the given
1062 <parameter>record</parameter>.</para>
1063 <para>The <function>pws3_file_prev_record()</function>
1064 function returns a pointer to the previous group preceding the given
1065 <parameter>record</parameter>.</para>
1066 </refsect2>
1067 <refsect2>
1068 <title>Macros</title>
1069 <para>The macro <constant>PWS3_VERSION</constant> contains the supported
1070 version of the Password Safe version 3 file format.</para>
1071 <para>The macro <constant>PWS3_MAX_FIELD_SIZE</constant> contains the
1072 maxium size for header and record fields in bytes and
1073 <constant>PWS3_MAX_PASSWORD_LEN</constant> contains the maxium password
1074 length in bytes.</para>
1075 <para>The macro <constant>PWS3_UUID_SIZE</constant> contains the size of
1076 UUIDs in bytes.</para>
1077 </refsect2>
1078 </refsect1>
1079 <refsect1>
1080 <title>Return Values</title>
1081 <para>The <function>pws3_file_create()</function> function returns a
1082 pointer to a Password Safe file data structure if successful and
1083 <constant>NULL</constant> in case of an error.</para>
1084 <para>The <function>pws3_file_read_mem()</function>,
1085 <function>pws3_file_read_stream()</function>,
1086 <function>pws3_file_write_mem()</function>, and
1087 <function>pws3_file_write_stream()</function> functions return
1088 <returnvalue>0</returnvalue> on success and <returnvalue>-1</returnvalue>
1089 to indicate an error.</para>
1090 <para>The <function>pws3_file_get_header_field()</function> function
1091 returns a pointer to the header field data structure of the requested type
1092 and <constant>NULL</constant> if such a field does not exist.</para>
1093 <para>The <function>pws3_file_remove_header_field()</function> function
1094 returns a pointer to the header field data structure which was removed from
1095 the file or <constant>NULL</constant> if such a field does not exist.</para>
1096 <para>The <function>pws3_file_get_empty_group()</function> function returns
1097 a pointer to the header field data structure corresponding to the requested
1098 empty group and <constant>NULL</constant> if a group of that name does not
1099 exist.</para>
1100 <para>The <function>pws3_file_remove_empty_group()</function> function
1101 returns a pointer to the header field data structure of the empty group
1102 which was removed from the file or <constant>NULL</constant> if a group of
1103 that name does not exist.</para>
1104 <para>The <function>pws3_file_first_empty_group()</function> function
1105 returns a pointer to the first of the empty group header fields or
1106 <constant>NULL</constant> if there are no such fields.</para>
1107 <para>The <function>pws3_file_last_empty_group()</function> function
1108 returns a pointer to the last of the empty group header fields or
1109 <constant>NULL</constant> if there are no such fields.</para>
1110 <para>The <function>pws3_file_next_empty_group()</function> function
1111 returns a pointer to the next empty group header field or
1112 <constant>NULL</constant> if there are no more such fields.</para>
1113 <para>The <function>pws3_file_prev_empty_group()</function> function
1114 returns a pointer to the previous empty group header field or
1115 <constant>NULL</constant> if there are no more such fields.</para>
1116 <para>The <function>pws3_file_get_record()</function> function returns a
1117 pointer to the record data structure of the requested record or
1118 <constant>NULL</constant> if that record does not exist.</para>
1119 <para>The <function>pws3_file_remove_record()</function> function returns a
1120 pointer to the record data structure which was removed from the file or
1121 <constant>NULL</constant> if no such record exists.</para>
1122 <para>The <function>pws3_file_first_record()</function> function returns a
1123 pointer to the record data structure of the first record or
1124 <constant>NULL</constant> if no records exist.</para>
1125 <para>The <function>pws3_file_last_record()</function> function returns a
1126 pointer to the record data structure of the last record or
1127 <constant>NULL</constant> if no records exist.</para>
1128 <para>The <function>pws3_file_next_record()</function> function returns a
1129 pointer to the record data structure of the next record or
1130 <constant>NULL</constant> if no records exist.</para>
1131 <para>The <function>pws3_file_prev_record()</function> function returns a
1132 pointer to the record data structure of the previous record or
1133 <constant>NULL</constant> if no records exist.</para>
1134 <para>The <function>pws3_field_create()</function> function returns a
1135 pointer to the new header field data structure on success and
1136 <constant>NULL</constant> on failure.</para>
1137 <para>The <function>pws3_field_get_type()</function> function returns
1138 the field type of the header field structure.</para>
1139 <para>The <function>pws3_field_get_data_type()</function> function
1140 returns the data type of the header field structure.</para>
1141 <para>The <function>pws3_field_set_uuid()</function>,
1142 <function>pws3_field_set_text()</function>,
1143 <function>pws3_field_set_time()</function>,
1144 <function>pws3_field_set_uint8()</function>,
1145 <function>pws3_field_set_uint16()</function>,
1146 <function>pws3_field_set_uint32()</function>, and
1147 <function>pws3_field_set_bytes()</function> functions return
1148 <returnvalue>0</returnvalue> on success and <returnvalue>-1</returnvalue>
1149 on failure.</para>
1150 <para>The <function>pws3_field_get_time()</function>,
1151 <function>pws3_field_get_uint8()</function>,
1152 <function>pws3_field_get_uint16()</function>, and
1153 <function>pws3_field_get_uint32()</function> functions return a
1154 value of the type corresponding to the type of header field.</para>
1155 <para>The <function>pws3_field_get_uuid()</function> function
1156 returns a pointer to a UUID.</para>
1157 <para>The <function>pws3_field_get_text()</function> function
1158 returns a pointer to a string or <constant>NULL</constant> if no value has
1159 been set.</para>
1160 <para>The <function>pws3_record_create()</function> function returns a
1161 pointer to a record data structure if successful and
1162 <constant>NULL</constant> on failure.</para>
1163 <para>The <function>pws3_record_get_field()</function> function returns a
1164 pointer to the record field data structure of the requested type or
1165 <constant>NULL</constant> if such a field does not exist.</para>
1166 <para>The <function>pws3_record_remove_field()</function> function returns
1167 a pointer to the record field data structure which was removed from the
1168 record or <constant>NULL</constant> if such a field does not exist.</para>
1169 </refsect1>
1170 <refsect1>
1171 <title>Errors</title>
1172 <para>If the <function>pws3_file_read_mem()</function>,
1173 <function>pws3_file_read_stream()</function>,
1174 <function>pws3_file_write_mem()</function>, and
1175 <function>pws3_file_write_stream()</function> functions fail, an error code
1176 indicating the nature of the error may be obtained using the
1177 <function>pws3_file_get_error_code()</function> function and a pointer to a
1178 detailed error message may be retrieved using the
1179 <function>pws3_file_get_error_message()</function> function. The above
1180 functions may fail if:</para>
1181 <variablelist>
1182 <varlistentry>
1183 <term><errorname>PWS_ERR_GENERIC_ERROR</errorname></term>
1184 <listitem>
1185 <para>An unknown error occurred.</para>
1186 </listitem>
1187 </varlistentry>
1188 <varlistentry>
1189 <term><errorname>PWS_ERR_NO_MEMORY</errorname></term>
1190 <listitem>
1191 <para>There was not enough space to allocate memory.</para>
1192 </listitem>
1193 </varlistentry>
1194 <varlistentry>
1195 <term><errorname>PWS_ERR_IO_ERROR</errorname></term>
1196 <listitem>
1197 <para>An I/O error occurred.</para>
1198 </listitem>
1199 </varlistentry>
1200 <varlistentry>
1201 <term><errorname>PWS_ERR_TRUNCATED_FILE</errorname></term>
1202 <listitem>
1203 <para>The file appears to be truncated.</para>
1204 </listitem>
1205 </varlistentry>
1206 <varlistentry>
1207 <term><errorname>PWS_ERR_INVALID_CHECKSUM</errorname></term>
1208 <listitem>
1209 <para>The calculated checksum does not match the checksum of the
1210 file.</para>
1211 </listitem>
1212 </varlistentry>
1213 <varlistentry>
1214 <term><errorname>PWS_ERR_INVALID_RECORD</errorname></term>
1215 <listitem>
1216 <para>A record is invalid.</para>
1217 </listitem>
1218 </varlistentry>
1219 <varlistentry>
1220 <term><errorname>PWS_ERR_INVALID_HEADER</errorname></term>
1221 <listitem>
1222 <para>A header is invalid.</para>
1223 </listitem>
1224 </varlistentry>
1225 <varlistentry>
1226 <term><errorname>PWS_ERR_UNSUPPORTED_VERSION</errorname></term>
1227 <listitem>
1228 <para>The file format version is not supported.</para>
1229 </listitem>
1230 </varlistentry>
1231 </variablelist>
1232 </refsect1>
1233 <refsect1>
1234 <title>Examples</title>
1235 <example>
1236 <title>Creating a Password Safe file</title>
1237 <para>The following code creates a new Password Safe file and sets the
1238 save application header field:</para>
1239 <programlisting>
1240 <![CDATA[
1241 #include <pws.h>
1243 /* ... */
1245 struct pws3_file *file;
1246 struct pws3_field *application_field;
1248 /* ... */
1250 /* initialize libpws */
1251 if (pws_init() != 0) {
1252 /* handle error */
1255 /* ... */
1257 /* create a new empty file structure */
1258 file = pws3_file_create();
1259 if (file == NULL) {
1260 /* handle error */
1262 /* create new empty save application field */
1263 application_field = pws3_field_create(1, PWS3_HEADER_FIELD_SAVE_APPLICATION);
1264 if (application_field == NULL) {
1265 /* handle error */
1267 /* set the value of the field */
1268 if (pws3_field_set_text(application_field, "PasswordManager 2.0") != 0) {
1269 /* handle error */
1271 /* set the header save application field in the file to the new field */
1272 pws3_file_set_field(file, application_field);
1273 ]]>
1274 </programlisting>
1275 </example>
1276 <example>
1277 <title>Print the title of each record</title>
1278 <para>The following code loops over each record of an existing Password
1279 Safe file and prints the content of the title field if it exists:</para>
1280 <programlisting>
1281 <![CDATA[
1282 #include <stdio.h>
1283 #include <pws.h>
1285 /* ... */
1287 struct pws3_file *file;
1288 struct pws3_record *record;
1289 struct pws3_field *title_field;
1291 /* ... */
1293 /* interate over each record */
1294 for (record = pws3_file_first_record(file); record != NULL;
1295 record = pws3_file_next_record(file, record)) {
1296 /* retrieve title field */
1297 title_field = pws3_record_get_field(record, PWS3_RECORD_FIELD_TITLE);
1298 /* print the title field or "No title" if it does not exitst */
1299 printf("Title: %s\n", (title_field != NULL) ?
1300 pws3_record_field_get_text(PWS3_RECORD_FIELD_TITLE) : "No title");
1302 ]]>
1303 </programlisting>
1304 </example>
1305 <example>
1306 <title>Add a new record to a file</title>
1307 <para>The following code creates a new record with a password field, a
1308 title field, and a creation time field and adds it to an existing
1309 Password Safe file:</para>
1310 <programlisting>
1311 <![CDATA[
1312 #include <time.h>
1313 #include <pws.h>
1315 /* ... */
1317 struct pws3_file *file;
1318 struct pws3_record *record;
1319 struct pws3_field *password_field;
1320 struct pws3_field *title_field;
1321 struct pws3_field *ctime_field;
1322 time_t now;
1324 /* ... */
1326 /* create new record */
1327 record = pws3_record_create();
1328 if (record == NULL) {
1329 /* handle error */
1332 /* create a password field */
1333 password_field = pws3_record_field_create(PWS3_RECORD_FIELD_PASSWORD);
1334 if (password_field == NULL) {
1335 /* handle error */
1337 /* set the value of the password field to "PaSsWoRd" */
1338 if (pws3_record_field_set_text(password_field, "PaSsWoRd") != 0) {
1339 /* handle error */
1341 /* set the password field of the record to the new field */
1342 pws3_record_set_field(record, password_field);
1344 /* create a title field */
1345 title_field = pws3_record_field_create(PWS3_RECORD_FIELD_TITLE);
1346 if (title_field == NULL) {
1347 /* handle error */
1349 /* set the value of the title field to "Foo Bar" */
1350 if (pws3_record_field_set_text(title_field, "Foo Bar") != 0) {
1351 /* handle error */
1353 /* set the title field of the record to the new field */
1354 pws3_record_set_field(record, title_field);
1356 /* create a new creation time field */
1357 ctime_field = pws3_record_field_create(PWS3_RECORD_FIELD_CREATION_TIME);
1358 if (ctime_field == NULL) {
1359 /* handle error */
1361 /* set the value of the creation time field to the current time */
1362 pws3_record_field_set_time(ctime_field, time(NULL));
1363 /* set the creation time field of the record to the new field */
1364 pws3_record_set_field(record, ctime_field);
1366 /* insert the new record into the file */
1367 pws3_file_insert_record(file, record);
1368 ]]>
1369 </programlisting>
1370 </example>
1371 <example>
1372 <title>Reading a Password Safe file</title>
1373 <para>The following code opens a Password Safe file named
1374 <filename>example.pwsafe3</filename> and parses it:</para>
1375 <programlisting>
1376 <![CDATA[
1377 #include <stdio.h>
1378 #include <pws.h>
1380 /* ... */
1382 FILE *fp;
1383 struct pws3_file *file;
1385 /* ... */
1387 /* initialize libpws */
1388 if (pws_init() != 0) {
1389 /* handle error */
1392 /* ... */
1394 /* create a new empty file structure */
1395 file = pws3_file_create();
1396 if (file == NULL) {
1397 /* handle error */
1400 /* open the file */
1401 fp = fopen("example.pwsafe3", "r");
1402 if (fp == NULL) {
1403 /* handle error */
1406 /* read and parse the file contents into the file structure */
1407 if (pws3_file_read_stream(file, "PaSsWoRd", fp) != 0) {
1408 fprintf(stderr, "error: %s\n",
1409 pws3_file_get_error_message(file));
1410 /* handle error */
1412 ]]>
1413 </programlisting>
1414 </example>
1415 <example>
1416 <title>Writing a Password Safe file</title>
1417 <para>The following code writes a Password Safe file to a file
1418 named <filename>example.pwsafe3</filename>:</para>
1419 <programlisting>
1420 <![CDATA[
1421 #include <stdio.h>
1422 #include <pws.h>
1424 /* ... */
1426 FILE *fp;
1427 struct pws3_file *file;
1429 /* ... */
1431 fp = fopen("example.pwsafe3", "w");
1432 if (fp == NULL) {
1433 /* handle error */
1436 if (pws3_file_write_stream(file, "FoOBaR", 10000, fp) != 0) {
1437 /* handle error */
1440 fflush(fp);
1441 fclose(fp);
1442 ]]>
1443 </programlisting>
1444 </example>
1445 </refsect1>
1446 <refsect1>
1447 <title>See Also</title>
1448 <para><citerefentry><refentrytitle>libpws</refentrytitle>
1449 <manvolnum>3</manvolnum></citerefentry>,
1450 <citerefentry><refentrytitle>pws_init</refentrytitle>
1451 <manvolnum>3</manvolnum></citerefentry>,
1452 <link xlink:href="https://pwsafe.org/"/></para>
1453 </refsect1>
1454 </refentry>