Mercurial > projects > libpws
diff pws3_file_create.3.xml @ 1:e1309515d111
Add README file and manpages
| author | Guido Berhoerster <guido+libpws@berhoerster.name> |
|---|---|
| date | Wed, 25 Mar 2015 17:10:23 +0100 |
| parents | |
| children | b3fc9f7e2b43 |
line wrap: on
line diff
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/pws3_file_create.3.xml Wed Mar 25 17:10:23 2015 +0100 @@ -0,0 +1,1400 @@ +<?xml version="1.0"?> +<!-- + +Copyright (C) 2015 Guido Berhoerster <guido+libpws@berhoerster.name> + +Permission is hereby granted, free of charge, to any person obtaining +a copy of this software and associated documentation files (the +"Software"), to deal in the Software without restriction, including +without limitation the rights to use, copy, modify, merge, publish, +distribute, sublicense, and/or sell copies of the Software, and to +permit persons to whom the Software is furnished to do so, subject to +the following conditions: + +The above copyright notice and this permission notice shall be included +in all copies or substantial portions of the Software. + +THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, +EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF +MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. +IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY +CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, +TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE +SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +--> +<refentry xmlns="http://docbook.org/ns/docbook" + xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en"> + <info> + <author> + <personname> + <firstname>Guido</firstname> + <surname>Berhoerster</surname> + </personname> + <email>guido+libpws@berhoerster.name</email> + <personblurb/> + </author> + <date>21 March, 2015</date> + </info> + <refmeta> + <refentrytitle>libpws</refentrytitle> + <manvolnum>3</manvolnum> + <refmiscinfo class="source"/> + <refmiscinfo class="version"/> + <refmiscinfo class="manual">Library Functions</refmiscinfo> + </refmeta> + <refnamediv> + <refname>pws3_file_create</refname> + <refname>pws3_file_destroy</refname> + <refname>pws3_file_get_error_code</refname> + <refname>pws3_file_get_error_message</refname> + <refname>pws3_file_read_mem</refname> + <refname>pws3_file_read_stream</refname> + <refname>pws3_file_write_mem</refname> + <refname>pws3_file_write_stream</refname> + <refname>pws3_file_set_header_field</refname> + <refname>pws3_file_get_header_field</refname> + <refname>pws3_file_remove_header_field</refname> + <refname>pws3_file_insert_empty_group</refname> + <refname>pws3_file_get_empty_group</refname> + <refname>pws3_file_remove_empty_group</refname> + <refname>pws3_file_first_empty_group</refname> + <refname>pws3_file_last_empty_group</refname> + <refname>pws3_file_next_empty_group</refname> + <refname>pws3_file_prev_empty_group</refname> + <refname>pws3_file_insert_record</refname> + <refname>pws3_file_get_record</refname> + <refname>pws3_file_remove_record</refname> + <refname>pws3_file_first_record</refname> + <refname>pws3_file_last_record</refname> + <refname>pws3_file_next_record</refname> + <refname>pws3_file_prev_record</refname> + <refname>pws3_field_create</refname> + <refname>pws3_field_destroy</refname> + <refname>pws3_field_is_header</refname> + <refname>pws3_field_get_type</refname> + <refname>pws3_field_get_data_type</refname> + <refname>pws3_field_set_uuid</refname> + <refname>pws3_field_set_text</refname> + <refname>pws3_field_set_time</refname> + <refname>pws3_field_set_uint8</refname> + <refname>pws3_field_set_uint16</refname> + <refname>pws3_field_set_uint32</refname> + <refname>pws3_field_set_bytes</refname> + <refname>pws3_field_get_uuid</refname> + <refname>pws3_field_get_text</refname> + <refname>pws3_field_get_time</refname> + <refname>pws3_field_get_uint8</refname> + <refname>pws3_field_get_uint16</refname> + <refname>pws3_field_get_uint32</refname> + <refname>pws3_field_get_bytes</refname> + <refname>pws3_record_create</refname> + <refname>pws3_record_destroy</refname> + <refname>pws3_record_set_field</refname> + <refname>pws3_record_get_field</refname> + <refname>pws3_record_remove_field</refname> + <refpurpose>create and manipulate Password Safe File Version 3 + files</refpurpose> + </refnamediv> + <refsynopsisdiv> + <cmdsynopsis> + <command>cc</command> + <arg choice="opt" rep="repeat"> + <option>flag</option> + </arg> + <arg choice="plain" rep="repeat"> + <option>file</option> + </arg> + <arg choice="plain"> + <option>-lpws</option> + </arg> + <arg choice="plain"> + <option>-lnettle</option> + </arg> + <arg choice="opt" rep="repeat"> + <option>library</option> + </arg> + </cmdsynopsis> + <funcsynopsis> + <funcsynopsisinfo> +#include <pws.h> +</funcsynopsisinfo> + <funcprototype> + <funcdef>struct pws3_file + *<function>pws3_file_create</function></funcdef> + <void/> + </funcprototype> + <funcprototype> + <funcdef>void <function>pws3_file_destroy</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>enum pws_error_code + <function>pws3_file_get_error_code</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>const char * + <function>pws3_file_get_error_message</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>pws3_file_read_mem</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>const char + *<parameter><replaceable>password</replaceable></parameter></paramdef> + <paramdef>unsigned char + *<parameter><replaceable>s</replaceable></parameter></paramdef> + <paramdef>size_t + <parameter><replaceable>n</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>pws3_file_read_stream</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>const char + *<parameter><replaceable>password</replaceable></parameter></paramdef> + <paramdef>FILE + *<parameter><replaceable>fp</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>pws3_file_write_mem</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>const char + *<parameter><replaceable>password</replaceable></parameter></paramdef> + <paramdef>uint32_t + <parameter><replaceable>n_iter</replaceable></parameter></paramdef> + <paramdef>unsigned char + **<parameter><replaceable>memp</replaceable></parameter></paramdef> + <paramdef>size_t + *<parameter><replaceable>mem_sizep</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>pws3_file_write_stream</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>const char + *<parameter><replaceable>password</replaceable></parameter></paramdef> + <paramdef>uint32_t + <parameter><replaceable>n_iter</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>void <function>pws3_file_set_header_field</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_field * + <function>pws3_file_get_header_field</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>uint8_t + <parameter><replaceable>field_type</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_field * + <function>pws3_file_remove_header_field</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>uint8_t + <parameter><replaceable>field_type</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>void + <function>pws3_file_insert_empty_group</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_field * + <function>pws3_file_get_empty_group</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>const char + *<parameter><replaceable>group_name</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_field * + <function>pws3_file_remove_empty_group</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>const char + *<parameter><replaceable>group_name</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_field * + <function>pws3_file_first_empty_group</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_field * + <function>pws3_file_last_empty_group</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_field * + <function>pws3_file_next_empty_group</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_field * + <function>pws3_file_prev_empty_group</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>void <function>pws3_file_insert_record</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>struct pws3_record + *<parameter><replaceable>record</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_record * + <function>pws3_file_get_record</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>const unsigned char + <parameter><replaceable>uuid</replaceable>[static + PWS3_UUID_SIZE]</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_record * + <function>pws3_file_remove_record</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>const unsigned char + <parameter><replaceable>uuid</replaceable>[static + PWS3_UUID_SIZE]</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_record * + <function>pws3_file_first_record</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_record * + <function>pws3_file_last_record</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_record * + <function>pws3_file_next_record</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>struct pws3_record + *<parameter><replaceable>record</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_record * + <function>pws3_file_prev_record</function></funcdef> + <paramdef>struct pws3_file + *<parameter><replaceable>pws_file</replaceable></parameter></paramdef> + <paramdef>struct pws3_record + *<parameter><replaceable>record</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>struct pws3_field * + <function>pws3_field_create</function></funcdef> + <paramdef>int + <parameter><replaceable>is_header</replaceable></parameter></paramdef> + <paramdef>uint8_t + <parameter><replaceable>field_type</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>void <function>pws3_field_destroy</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int + <function>pws3_field_is_header</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>uint8_t * + <function>pws3_field_get_type</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>enum pws_data_type * + <function>pws3_field_get_data_type</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>pws3_field_set_uuid</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + <paramdef>const unsigned char + <parameter><replaceable>uuid</replaceable>[static + PWS3_UUID_SIZE]</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>pws3_field_set_text</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + <paramdef>const char + <parameter><replaceable>s</replaceable>[static 1]</parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>pws3_field_set_time</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + <paramdef>time_t + <parameter><replaceable>time</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>pws3_field_set_uint8</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + <paramdef>uint8_t + <parameter><replaceable>u8</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>pws3_field_set_uint16</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + <paramdef>uint16_t + <parameter><replaceable>u16</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>pws3_field_set_uint32</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + <paramdef>uint32_t + <parameter><replaceable>u32</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>int <function>pws3_field_set_bytes</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + <paramdef>const unsigned char + <parameter><replaceable>s</replaceable>[static 1]</parameter></paramdef> + <paramdef>size_t + <parameter><replaceable>n</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>const unsigned char * + <function>pws3_field_get_uuid</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>const char * + <function>pws3_field_get_text</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>time_t + <function>pws3_field_get_time</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>uint8_t + <function>pws3_field_get_uint8</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>uint16_t + <function>pws3_field_get_uint16</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>uint32_t + <function>pws3_field_get_uint32</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + </funcprototype> + <funcprototype> + <funcdef>void <function>pws3_field_get_bytes</function></funcdef> + <paramdef>struct pws3_field + *<parameter><replaceable>field</replaceable></parameter></paramdef> + <paramdef>const unsigned char + **<parameter><replaceable>pp</replaceable></parameter></paramdef> + <paramdef>size_t + *<parameter><replaceable>np</replaceable></parameter></paramdef> + </funcprototype> + </funcsynopsis> + <synopsis> +<constant>PWS3_VERSION</constant> + +<constant>PWS3_MAX_FIELD_LEN</constant> + +<constant>PWS3_MAX_PASSWORD_LEN</constant> + +<constant>PWS3_UUID_SIZE</constant> + +struct pws3_field; + +struct pws3_record; + +struct pws3_file; + +enum pws_error_code; + +enum pws_data_type; + +enum pws3_header_field_type; + +enum pws3_record_field_type; +</synopsis> + </refsynopsisdiv> + <refsect1> + <title>Description</title> + <refsect2> + <title>Introduction</title> + <para>The <function>pws3_*()</function> family of functions allows + creating, reading, writing, and manipulating Password Safe version 3 + files. Password Safe version 3 files consist of a header and a body part. + The header is comprised of both mandatory and optional typed header + fields which hold file-wide metadata. The body consists of records which + in turn hold passwords and associated metadata in typed record + fields.</para> + <para>A header or record field value can be of one of seven basic data + types defined below: + <table xml:id="table-data-types"> + <title>Header and Record Field Value Data Types</title> + <tgroup cols="3" align="left" colsep="1" rowsep="1"> + <thead> + <row> + <entry>Data Type</entry> + <entry>C Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><constant>PWS_DATA_TYPE_UUID</constant></entry> + <entry><code>unsigned char [PWS3_UUID_SIZE]</code></entry> + <entry>UUID</entry> + </row> + <row> + <entry><constant>PWS_DATA_TYPE_TEXT</constant></entry> + <entry><code>char *</code></entry> + <entry>NUL-delimited UTF-8 encoded string</entry> + </row> + <row> + <entry><constant>PWS_DATA_TYPE_TIME</constant></entry> + <entry><code>time_t</code></entry> + <entry>system-specific representation of time</entry> + </row> + <row> + <entry><constant>PWS_DATA_TYPE_UINT8</constant></entry> + <entry><code>uint8_t</code></entry> + <entry>8-bit wide unsigned integer</entry> + </row> + <row> + <entry><constant>PWS_DATA_TYPE_UINT16</constant></entry> + <entry><code>uint16_t</code></entry> + <entry>16-bit wide unsigned integer</entry> + </row> + <row> + <entry><constant>PWS_DATA_TYPE_UINT32</constant></entry> + <entry><code>uint32_t</code></entry> + <entry>32-bit wide unsigned integer</entry> + </row> + <row> + <entry><constant>PWS_DATA_TYPE_BYTES</constant></entry> + <entry><code>unsigned char *</code></entry> + <entry>array of bytes</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para>The data type of each header field is defined in + <xref linkend="table-header-fields"/> and the data type of each record + field is defined in <xref linkend="table-record-fields"/>. Each header + field, with the exception of the empty groups header field, can only + occur once. The version header field + (<constant>PWS3_HEADER_FIELD_VERSION</constant>) is mandatory and must + not be removed. When reading a file its value is checked and an error is + returned if the file format version newer than the one supported by + <citerefentry><refentrytitle>libpws</refentrytitle><manvolnum>3</manvolnum></citerefentry>. + The supported version is defined by the <constant>PWS3_VERSION</constant> + macro, when creating a new file structure the version header field will be + set to its value by default. Non-standard header and record fields will + be preserved when a file is read and subsequently written again, they may + be read and manipulated as if they had + <constant>PWS_DATA_TYPE_BYTES</constant> data type. All strings are + expected to be in UTF-8 encoding.</para> + <para>The only mandatory record field is the UUID field which uniquely + identifies a record in the file.</para> + <para>The complete and authoritative specification of the file format is + included with the original Password Safe application available from <link + xlink:href="https://pwsafe.org/"/>.</para> + </refsect2> + <refsect2> + <title>Password Safe File Data Structure</title> + <para>The <function>pws3_file_create()</function> function allocates and + intializes a Password Safe file data structure representing a Password + Safe version 3 file. It automatically creates the mandatory version header + field and initializes it to the value of the + <constant>PWS3_VERSION</constant> macro.</para> + <para>The <function>pws3_file_destroy()</function> function deallocates + all header fields and records of the file structure passed to it and then + deallocates the file structure itself.</para> + <para>The <function>pws3_file_read_mem()</function> and + <function>pws3_file_read_stream()</function> functions read and parse a + Password Safe file into the given data structure passed via the + <parameter>pws_file</parameter> argument, replacing any existing header + fields and records. The key used to decrypt the file is derived from the + given <parameter>password</parameter> parameter. The + <function>pws3_file_read_mem()</function> function reads the file from a + block of memory <parameter>s</parameter> with the size of + <parameter>n</parameter> bytes. The + <function>pws3_file_read_stream()</function> reads the file from the + stream of the <parameter>fp</parameter> file pointer.</para> + <para>The <function>pws3_file_write_mem()</function> and + <function>pws3_file_write_stream()</function> functions write a new + Password Safe file from the given datat structure. The key used to + encrypt the file is derived from the <parameter>password</parameter> + argument using the number of iterations to stretch the key determined by + the <parameter>n_iter</parameter> argument. The + <function>pws3_file_write_mem()</function> will allocate and place the + file contents into memory and return the location and size to the + locations <parameter>sp</parameter> and <parameter>np</parameter> + point to. The <function>pws3_file_write_stream()</function> will write the + file contents to the stream of the <parameter>fp</parameter> file + pointer.</para> + </refsect2> + <refsect2> + <title>Fields</title> + <para>Both header and record fields are stored in + <varname>pws3_field</varname> structures which are allocated and + initialized with the <function>pws3_field_create()</function> function. + Depending on whether <parameter>is_header</parameter> is non-zero either + a header field or a record field data structure of the given field type + will be created.</para> + <para>The <function>pws3_field_destroy()</function> function + deallocates the given field data structure and its content.</para> + <para>The <function>pws3_field_is_header()</function> function + can be used to test whether the given field data structure refers to a + header field or a record field.</para> + <para>The <function>pws3_field_get_type()</function> function + returns the field type of the given field data structure.</para> + <para>The <function>pws3_field_get_data_type()</function> function + returns the data type of the given field structure.</para> + <para>The <function>pws3_field_set_uuid()</function>, + <function>pws3_field_set_text()</function>, + <function>pws3_field_set_time()</function>, + <function>pws3_field_set_uint8()</function>, + <function>pws3_field_set_uint16()</function>, + <function>pws3_field_set_uint32()</function>, and + <function>pws3_field_set_bytes()</function> functions set the + content of the given field. The given data is always copied and + existing content is replaced. The data type used by the function must + match the data type of the field specified in <xref + linkend="table-header-fields"/> in case of header fields or that in <xref + linkend="table-record-fields"/> in case of record fields.</para> + <para>The <function>pws3_field_get_time()</function>, + <function>pws3_field_get_uint8()</function>, + <function>pws3_field_get_uint16()</function>, and + <function>pws3_field_get_uint32()</function> functions return the + value of the given field. The + <function>pws3_field_get_uuid()</function>, + <function>pws3_field_get_text()</function>, and + <function>pws3_field_get_bytes()</function> functions return a + pointer to the data of the given field if it has been set. The data type + used by the function must match the data type of the field specified in + <xref linkend="table-header-fields"/> in case of header fields and that + in <xref linkend="table-record-fields"/> in case of record fields. + Returned pointers are only valid until a field is modified or + deallocated.</para> + </refsect2> + <refsect2> + <title>Header Fields</title> + <para>Header fields are used to store metadata for the whole file, each + type of header field with the exception of the empty groups header field + only occurs once. The following header fields are supported: + <table xml:id="table-header-fields"> + <title>Header Fields</title> + <tgroup cols="4" align="left" colsep="1" rowsep="1"> + <thead> + <row> + <entry>Header Field Type</entry> + <entry>Numeric Value</entry> + <entry>Data Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​VERSION</constant></entry> + <entry><literal>0x00</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​UINT16</constant></entry> + <entry>file format version</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​UUID</constant></entry> + <entry><literal>0x01</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​UUID</constant></entry> + <entry>UUID</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​NON_​DEFAULT_​PREFERENCES</constant></entry> + <entry><literal>0x02</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>non-default preferences</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​TREE_​DISPLAY_​STATUS</constant></entry> + <entry><literal>0x03</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>expandended/​collapsed state of the tree of groups</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​SAVE_​TIMESTAMP</constant></entry> + <entry><literal>0x04</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TIME</constant></entry> + <entry>time when the file was last saved</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​SAVE_​USER_​HOST</constant></entry> + <entry><literal>0x05</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>name of the user who last saved the file and name of the host where the file was saved</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​SAVE_​APPLICATION</constant></entry> + <entry><literal>0x06</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>name of the application used to save the file</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​SAVE_​USER</constant></entry> + <entry><literal>0x07</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>name of the user who last saved the file</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​SAVE_​HOST</constant></entry> + <entry><literal>0x08</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>name of the host where the file was last saved</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​DATABASE_​NAME</constant></entry> + <entry><literal>0x09</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>logical name for referring to the file</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​DATABASE_​DESCRIPTION</constant></entry> + <entry><literal>0x0a</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>description of the file</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​DATABASE_​FILTERS</constant></entry> + <entry><literal>0x0b</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>filters for this file</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​RESERVED_​1</constant></entry> + <entry><literal>0x0c</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​BYTES</constant></entry> + <entry>reserved</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​RESERVED_​2</constant></entry> + <entry><literal>0x0d</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​BYTES</constant></entry> + <entry>reserved</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​RESERVED_​3</constant></entry> + <entry><literal>0x0e</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​BYTES</constant></entry> + <entry>reseved</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​RECENTLY_​USED_​ENTRIES</constant></entry> + <entry><literal>0x0f</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>list of recently used entries</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​NAMED_​PASSWORD_​POLICIES</constant></entry> + <entry><literal>0x10</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>named password policies</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​EMPTY_​GROUPS</constant></entry> + <entry><literal>0x11</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>empty groups which contain no entries</entry> + </row> + <row> + <entry><constant>PWS3_​HEADER_​FIELD_​YUBICO</constant></entry> + <entry><literal>0x12</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>reserved</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para>The <function>pws3_file_set_header_field()</function> function sets + the header field on the given file. An existing field of the same type is + replaced with the exception of fields of type + <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> for which + <function>pws3_file_set_header_field()</function> has the same effect as + calling the <function>pws3_file_insert_empty_group()</function> + function.</para> + <para>The <function>pws3_file_get_header_field()</function> function + returns a pointer to the header field data structure of the given header + field type. In case of the + <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> field type a pointer + to the first empty group field is returned.</para> + <para>The <function>pws3_file_remove_header_field()</function> function + removes the header field from the given file and returns a pointer to it. + It is the responsibility of the caller to deallocate the header field + data structure. In case of the + <constant>PWS3_HEADER_FIELD_EMPTY_GROUPS</constant> field type the first + empty group is removed.</para> + <para>The <function>pws3_file_insert_empty_group()</function> function + inserts the given empty groups field into the file, an existing field for + a group of the same name is replaced.</para> + <para>The <function>pws3_file_get_empty_group()</function> function + returns a pointer to the header field datat structure representing an + empty group of the given name.</para> + <para>The <function>pws3_file_remove_empty_group()</function> function + removes the field representing the empty group of the given name from the + file and returns a pointer to the header field data structure. It is the + responsibility of the caller to deallocate the header field data + structure.</para> + <para>The <function>pws3_file_first_empty_group()</function> function + returns a pointer to the first empty group header field.</para> + <para>The <function>pws3_file_last_empty_group()</function> function + returns a pointer to the last empty group header field.</para> + <para>The <function>pws3_file_next_empty_group()</function> function + returns a pointer to the next empty group header filed data structure + following the given <parameter>field</parameter>.</para> + <para>The <function>pws3_file_prev_empty_groupious()</function> function + returns a pointer to the previous empty group header filed data structure + preceding the given <parameter>field</parameter>.</para> + </refsect2> + <refsect2> + <title>Records</title> + <para>Records consist of at least one or more typed fields, they are + identified by an UUID which is the only mandatory field and must not be + removed. For presentational purposes records may be organized in + hierarchical groups. The following record fields are supported: + <table xml:id="table-record-fields"> + <title>Record Fields</title> + <tgroup cols="4" align="left" colsep="1" rowsep="1"> + <thead> + <row> + <entry>Record Field Type</entry> + <entry>Numeric Value</entry> + <entry>Data Type</entry> + <entry>Description</entry> + </row> + </thead> + <tbody> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​UUID</constant></entry> + <entry><literal>0x01</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​UUID</constant></entry> + <entry>UUID identifying the record</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​GROUP</constant></entry> + <entry><literal>0x02</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>group name the record is a member of</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​TITLE</constant></entry> + <entry><literal>0x03</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>title</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​USERNAME</constant></entry> + <entry><literal>0x04</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>username</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​NOTES</constant></entry> + <entry><literal>0x05</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>notes</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​PASSWORD</constant></entry> + <entry><literal>0x06</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>password</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​CREATION_​TIME</constant></entry> + <entry><literal>0x07</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TIME</constant></entry> + <entry>time when the record was created</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​PASSWORD_​MODIFICATION_​TIME</constant></entry> + <entry><literal>0x08</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TIME</constant></entry> + <entry>time when the password was last modified</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​ACCESS_​TIME</constant></entry> + <entry><literal>0x09</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TIME</constant></entry> + <entry>time when the record was last accessed</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​PASSWORD_​EXPIRY_​TIME</constant></entry> + <entry><literal>0x0a</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TIME</constant></entry> + <entry>time when the password expires</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​RESERVED_​1</constant></entry> + <entry><literal>0x0b</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​BYTES</constant></entry> + <entry>reserved</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​MODIFICATION_​TIME</constant></entry> + <entry><literal>0x0c</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TIME</constant></entry> + <entry>time at whcih the record was last modified</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​URL</constant></entry> + <entry><literal>0x0d</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>URL</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​AUTOTYPE</constant></entry> + <entry><literal>0x0e</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>text to be typed when using the autotype feature</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​PASSWORD_​HISTORY</constant></entry> + <entry><literal>0x0f</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>creation time and values of previously used passwords</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​PASSWORD_​POLICY</constant></entry> + <entry><literal>0x10</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>password policy</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​PASSWORD_​EXPIRY_​INTERVAL</constant></entry> + <entry><literal>0x11</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​UINT32</constant></entry> + <entry>days until the password expires</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​RUN_​COMMAND</constant></entry> + <entry><literal>0x12</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>command</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​DOUBLE_​CLICK_​ACTION</constant></entry> + <entry><literal>0x13</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​BYTES</constant></entry> + <entry>action on double clicking</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​EMAIL_​ADDRESS</constant></entry> + <entry><literal>0x14</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>email address</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​PROTECTED</constant></entry> + <entry><literal>0x15</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​UINT8</constant></entry> + <entry>flag whether the record is protected from modification</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​ALLOWED_​PASSWORD_​SYMBOLS</constant></entry> + <entry><literal>0x16</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>allowed symbols for generating passwords</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​SHIFT_​DOUBLE_​CLICK_​ACTION</constant></entry> + <entry><literal>0x17</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​BYTES</constant></entry> + <entry>action on pressing shift and double clicking</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​PASSWORD_​POLICY_​NAME</constant></entry> + <entry><literal>0x18</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​TEXT</constant></entry> + <entry>name of password policy saved in the header</entry> + </row> + <row> + <entry><constant>PWS3_​RECORD_​FIELD_​KEYBOARD_​SHORTCUT</constant></entry> + <entry><literal>0x19</literal></entry> + <entry><constant>PWS_​DATA_​TYPE_​BYTES</constant></entry> + <entry>keyboard shortcut</entry> + </row> + </tbody> + </tgroup> + </table> + </para> + <para>The <function>pws3_record_create()</function> function allocates + and creates a record data structure, generates an UUID record field and + adds it to the record.</para> + <para>The <function>pws3_record_destroy()</function> function deallocates + the given record data structure and all its record fields.</para> + <para>The <function>pws3_file_record_field_set()</function> function sets + the record field on the given record, replacing an existing field of the + same type.</para> + <para>The <function>pws3_file_record_field_get()</function> function + returns a pointer to the record field data structure of the given record + field type.</para> + <para>The <function>pws3_file_record_field_remove()</function> function + removes the record field from the given record and returns a pointer to + it. It is the responsibility of the caller to deallocate the record field + data structure.</para> + <para>The <function>pws3_file_insert_record()</function> function inserts + the given record into the file, an existing record with the same UUID is + replaced.</para> + <para>The <function>pws3_file_get_record()</function> function returns a + pointer to the record structure representing a record with the given + UUID.</para> + <para>The <function>pws3_file_remove_record()</function> function removes + the record with the given UUID from the file and returns a pointer to the + record data structure. It is the responsibility of the caller to + deallocate the record data structure.</para> + <para>The <function>pws3_file_first_record()</function> function returns a + pointer to the first record.</para> + <para>The <function>pws3_file_last_record()</function> function returns a + pointer to the last record.</para> + <para>The <function>pws3_file_next_record()</function> function returns a + pointer to the next record following the given + <parameter>record</parameter>.</para> + <para>The <function>pws3_file_prev_record()</function> + function returns a pointer to the previous group preceding the given + <parameter>record</parameter>.</para> + </refsect2> + <refsect2> + <title>Macros</title> + <para>The macro <constant>PWS3_VERSION</constant> contains the supported + version of the Password Safe version 3 file format.</para> + <para>The macro <constant>PWS3_MAX_FIELD_SIZE</constant> contains the + maxium size for header and record fields in bytes and + <constant>PWS3_MAX_PASSWORD_LEN</constant> contains the maxium password + length in bytes.</para> + <para>The macro <constant>PWS3_UUID_SIZE</constant> contains the size of + UUIDs in bytes.</para> + </refsect2> + </refsect1> + <refsect1> + <title>Return Values</title> + <para>The <function>pws3_file_create()</function> function returns a + pointer to a Password Safe file data structure if successful and + <constant>NULL</constant> in case of an error.</para> + <para>The <function>pws3_file_read_mem()</function>, + <function>pws3_file_read_stream()</function>, + <function>pws3_file_write_mem()</function>, and + <function>pws3_file_write_stream()</function> functions return + <returnvalue>0</returnvalue> on success and <returnvalue>-1</returnvalue> + to indicate an error.</para> + <para>The <function>pws3_file_get_header_field()</function> function + returns a pointer to the header field data structure of the requested type + and <constant>NULL</constant> if such a field does not exist.</para> + <para>The <function>pws3_file_remove_header_field()</function> function + returns a pointer to the header field data structure which was removed from + the file or <constant>NULL</constant> if such a field does not exist.</para> + <para>The <function>pws3_file_get_empty_group()</function> function returns + a pointer to the header field data structure corresponding to the requested + empty group and <constant>NULL</constant> if a group of that name does not + exist.</para> + <para>The <function>pws3_file_remove_empty_group()</function> function + returns a pointer to the header field data structure of the empty group + which was removed from the file or <constant>NULL</constant> if a group of + that name does not exist.</para> + <para>The <function>pws3_file_first_empty_group()</function> function + returns a pointer to the first of the empty group header fields or + <constant>NULL</constant> if there are no such fields.</para> + <para>The <function>pws3_file_last_empty_group()</function> function + returns a pointer to the last of the empty group header fields or + <constant>NULL</constant> if there are no such fields.</para> + <para>The <function>pws3_file_next_empty_group()</function> function + returns a pointer to the next empty group header field or + <constant>NULL</constant> if there are no more such fields.</para> + <para>The <function>pws3_file_prev_empty_group()</function> function + returns a pointer to the previous empty group header field or + <constant>NULL</constant> if there are no more such fields.</para> + <para>The <function>pws3_file_get_record()</function> function returns a + pointer to the record data structure of the requested record or + <constant>NULL</constant> if that record does not exist.</para> + <para>The <function>pws3_file_remove_record()</function> function returns a + pointer to the record data structure which was removed from the file or + <constant>NULL</constant> if no such record exists.</para> + <para>The <function>pws3_file_first_record()</function> function returns a + pointer to the record data structure of the first record or + <constant>NULL</constant> if no records exist.</para> + <para>The <function>pws3_file_last_record()</function> function returns a + pointer to the record data structure of the last record or + <constant>NULL</constant> if no records exist.</para> + <para>The <function>pws3_file_next_record()</function> function returns a + pointer to the record data structure of the next record or + <constant>NULL</constant> if no records exist.</para> + <para>The <function>pws3_file_prev_record()</function> function returns a + pointer to the record data structure of the previous record or + <constant>NULL</constant> if no records exist.</para> + <para>The <function>pws3_field_create()</function> function returns a + pointer to the new header field data structure on success and + <constant>NULL</constant> on failure.</para> + <para>The <function>pws3_field_get_type()</function> function returns + the field type of the header field structure.</para> + <para>The <function>pws3_field_get_data_type()</function> function + returns the data type of the header field structure.</para> + <para>The <function>pws3_field_set_uuid()</function>, + <function>pws3_field_set_text()</function>, + <function>pws3_field_set_time()</function>, + <function>pws3_field_set_uint8()</function>, + <function>pws3_field_set_uint16()</function>, + <function>pws3_field_set_uint32()</function>, and + <function>pws3_field_set_bytes()</function> functions return + <returnvalue>0</returnvalue> on success and <returnvalue>-1</returnvalue> + on failure.</para> + <para>The <function>pws3_field_get_time()</function>, + <function>pws3_field_get_uint8()</function>, + <function>pws3_field_get_uint16()</function>, and + <function>pws3_field_get_uint32()</function> functions return a + value of the type corresponding to the type of header field.</para> + <para>The <function>pws3_field_get_uuid()</function> function + returns a pointer to a UUID.</para> + <para>The <function>pws3_field_get_text()</function> function + returns a pointer to a string or <constant>NULL</constant> if no value has + been set.</para> + <para>The <function>pws3_record_create()</function> function returns a + pointer to a record data structure if successful and + <constant>NULL</constant> on failure.</para> + <para>The <function>pws3_record_get_field()</function> function returns a + pointer to the record field data structure of the requested type or + <constant>NULL</constant> if such a field does not exist.</para> + <para>The <function>pws3_record_remove_field()</function> function returns + a pointer to the record field data structure which was removed from the + record or <constant>NULL</constant> if such a field does not exist.</para> + </refsect1> + <refsect1> + <title>Errors</title> + <para>If the <function>pws3_file_read_mem()</function>, + <function>pws3_file_read_stream()</function>, + <function>pws3_file_write_mem()</function>, and + <function>pws3_file_write_stream()</function> functions fail, an error code + indicating the nature of the error may be obtained using the + <function>pws3_file_get_error_code()</function> function and a pointer to a + detailed error message may be retrieved using the + <function>pws3_file_get_error_message()</function> function. The above + functions may fail if:</para> + <variablelist> + <varlistentry> + <term><errorname>PWS_ERR_GENERIC_ERROR</errorname></term> + <listitem> + <para>An unknown error occurred.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorname>PWS_ERR_NO_MEMORY</errorname></term> + <listitem> + <para>There was not enough space to allocate memory.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorname>PWS_ERR_IO_ERROR</errorname></term> + <listitem> + <para>An I/O error occurred.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorname>PWS_ERR_TRUNCATED_FILE</errorname></term> + <listitem> + <para>The file appears to be truncated.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorname>PWS_ERR_INVALID_CHECKSUM</errorname></term> + <listitem> + <para>The calculated checksum does not match the checksum of the + file.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorname>PWS_ERR_INVALID_RECORD</errorname></term> + <listitem> + <para>A record is invalid.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorname>PWS_ERR_INVALID_HEADER</errorname></term> + <listitem> + <para>A header is invalid.</para> + </listitem> + </varlistentry> + <varlistentry> + <term><errorname>PWS_ERR_UNSUPPORTED_VERSION</errorname></term> + <listitem> + <para>The file format version is not supported.</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + <refsect1> + <title>Examples</title> + <example> + <title>Creating a Password Safe file</title> + <para>The following code creates a new Password Safe file and sets the + save application header field:</para> + <programlisting> +<![CDATA[ +#include <pws.h> + +/* ... */ + +struct pws3_file *file; +struct pws3_field *application_field; + +/* ... */ + +/* initialize libpws */ +if (pws_init() != 0) { + /* handle error */ +} + +/* ... */ + +/* create a new empty file structure */ +file = pws3_file_create(); +if (file == NULL) { + /* handle error */ +} +/* create new empty save application field */ +application_field = pws3_field_create(1, PWS3_HEADER_FIELD_SAVE_APPLICATION); +if (application_field == NULL) { + /* handle error */ +} +/* set the value of the field */ +if (pws3_field_set_text(application_field, "PasswordManager 2.0") != 0) { + /* handle error */ +} +/* set the header save application field in the file to the new field */ +pws3_file_set_field(file, application_field); +]]> +</programlisting> + </example> + <example> + <title>Print the title of each record</title> + <para>The following code loops over each record of an existing Password + Safe file and prints the content of the title field if it exists:</para> + <programlisting> +<![CDATA[ +#include <stdio.h> +#include <pws.h> + +/* ... */ + +struct pws3_file *file; +struct pws3_record *record; +struct pws3_field *title_field; + +/* ... */ + +/* interate over each record */ +for (record = pws3_file_first_record(file); record != NULL; + record = pws3_file_next_record(file, record)) { + /* retrieve title field */ + title_field = pws3_record_get_field(record, PWS3_RECORD_FIELD_TITLE); + /* print the title field or "No title" if it does not exitst */ + printf("Title: %s\n", (title_field != NULL) ? + pws3_record_field_get_text(PWS3_RECORD_FIELD_TITLE) : "No title"); +} +]]> +</programlisting> + </example> + <example> + <title>Add a new record to a file</title> + <para>The following code creates a new record with a password field, a + title field, and a creation time field and adds it to an existing + Password Safe file:</para> + <programlisting> +<![CDATA[ +#include <time.h> +#include <pws.h> + +/* ... */ + +struct pws3_file *file; +struct pws3_record *record; +struct pws3_field *password_field; +struct pws3_field *title_field; +struct pws3_field *ctime_field; +time_t now; + +/* ... */ + +/* create new record */ +record = pws3_record_create(); +if (record == NULL) { + /* handle error */ +} + +/* create a password field */ +password_field = pws3_record_field_create(PWS3_RECORD_FIELD_PASSWORD); +if (password_field == NULL) { + /* handle error */ +} +/* set the value of the password field to "PaSsWoRd" */ +if (pws3_record_field_set_text(password_field, "PaSsWoRd") != 0) { + /* handle error */ +} +/* set the password field of the record to the new field */ +pws3_record_set_field(record, password_field); + +/* create a title field */ +title_field = pws3_record_field_create(PWS3_RECORD_FIELD_TITLE); +if (title_field == NULL) { + /* handle error */ +} +/* set the value of the title field to "Foo Bar" */ +if (pws3_record_field_set_text(title_field, "Foo Bar") != 0) { + /* handle error */ +} +/* set the title field of the record to the new field */ +pws3_record_set_field(record, title_field); + +/* create a new creation time field */ +ctime_field = pws3_record_field_create(PWS3_RECORD_FIELD_CREATION_TIME); +if (ctime_field == NULL) { + /* handle error */ +} +/* set the value of the creation time field to the current time */ +pws3_record_field_set_time(ctime_field, time(NULL)); +/* set the creation time field of the record to the new field */ +pws3_record_set_field(record, ctime_field); + +/* insert the new record into the file */ +pws3_file_insert_record(file, record); +]]> +</programlisting> + </example> + <example> + <title>Reading a Password Safe file</title> + <para>The following code opens a Password Safe file named + <filename>example.pwsafe3</filename> and parses it:</para> + <programlisting> +<![CDATA[ +#include <stdio.h> +#include <pws.h> + +/* ... */ + +FILE *fp; +struct pws3_file *file; + +/* ... */ + +/* initialize libpws */ +if (pws_init() != 0) { + /* handle error */ +} + +/* ... */ + +/* create a new empty file structure */ +file = pws3_file_create(); +if (file == NULL) { + /* handle error */ +} + +/* open the file */ +fp = fopen("example.pwsafe3", "r"); +if (fp == NULL) { + /* handle error */ +} + +/* read and parse the file contents into the file structure */ +if (pws3_file_read_stream(file, "PaSsWoRd", fp) != 0) { + fprintf(stderr, "error: %s\n", + pws3_file_get_error_message(file)); + /* handle error */ +} +]]> +</programlisting> + </example> + <example> + <title>Writing a Password Safe file</title> + <para>The following code writes a Password Safe file to a file + named <filename>example.pwsafe3</filename>:</para> + <programlisting> +<![CDATA[ +#include <stdio.h> +#include <pws.h> + +/* ... */ + +FILE *fp; +struct pws3_file *file; + +/* ... */ + +fp = fopen("example.pwsafe3", "w"); +if (fp == NULL) { + /* handle error */ +} + +if (pws3_file_write_stream(file, "FoOBaR", 10000, fp) != 0) { + /* handle error */ +} + +fflush(fp); +fclose(fp); +]]> +</programlisting> + </example> + </refsect1> + <refsect1> + <title>See Also</title> + <para><citerefentry><refentrytitle>libpws</refentrytitle> + <manvolnum>3</manvolnum></citerefentry>, + <citerefentry><refentrytitle>pws_init</refentrytitle> + <manvolnum>3</manvolnum></citerefentry>, + <link xlink:href="https://pwsafe.org/"/></para> + </refsect1> +</refentry>