--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/libpws.3.xml	Wed Mar 25 17:10:23 2015 +0100
@@ -0,0 +1,213 @@
+<?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>libpws</refname>
+    <refpurpose>library for creating and manipulating Password Safe 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 &lt;pws.h&gt;
+</funcsynopsisinfo>
+    </funcsynopsis>
+  </refsynopsisdiv>
+  <refsect1>
+    <title>Description</title>
+    <para>libpws provides an API for creating, reading, manipulating and
+    writing Password Safe files. The Password Safe file format is intended
+    for the platform-independent secure storage of passwords and associated
+    metadata and offers protection from unauthorized access to the file by
+    encrypting it using a key derived from a master password. Its design
+    ensures both confidentiality and integrity of its contents.</para>
+    <para>libpws currently supports version 3 of the Password Safe file
+    format.</para>
+    <para>The <literal>&lt;<filename
+    class="header">pws.h</filename>&gt;</literal> header provides type and
+    function declarations for all library services.</para>
+    <para>With the exception of <function>pws_set_alloc_functions</function>
+    all functions are reentrant. Functions operating on a Password Safe file
+    structure, a header field structure, a record field structure, and a record
+    structure provide no locking. A multithreaded application must either
+    provide its own synchronization mechanisms or restrict operations on any of
+    the above structures to a single thread.</para>
+  </refsect1>
+  <refsect1>
+    <title>Interfaces</title>
+    <para>The static library <filename class="libraryfile">libpws.a</filename>
+    provides following the public interfaces:
+    <simplelist type="vert" columns="2">
+      <member><function>pws_init</function></member>
+      <member><function>pws_finalize</function></member>
+      <member><function>pws_set_alloc_functions</function></member>
+      <member><function>pws_generate_uuid</function></member>
+      <member><function>pws3_field_create</function></member>
+      <member><function>pws3_field_destroy</function></member>
+      <member><function>pws3_field_is_header</function></member>
+      <member><function>pws3_field_get_type</function></member>
+      <member><function>pws3_field_get_data_type</function></member>
+      <member><function>pws3_field_set_uuid</function></member>
+      <member><function>pws3_field_set_text</function></member>
+      <member><function>pws3_field_set_time</function></member>
+      <member><function>pws3_field_set_uint8</function></member>
+      <member><function>pws3_field_set_uint16</function></member>
+      <member><function>pws3_field_set_uint32</function></member>
+      <member><function>pws3_field_set_bytes</function></member>
+      <member><function>pws3_field_get_uuid</function></member>
+      <member><function>pws3_field_get_text</function></member>
+      <member><function>pws3_field_get_time</function></member>
+      <member><function>pws3_field_get_uint8</function></member>
+      <member><function>pws3_field_get_uint16</function></member>
+      <member><function>pws3_field_get_uint32</function></member>
+      <member><function>pws3_field_get_bytes</function></member>
+      <member><function>pws3_file_create</function></member>
+      <member><function>pws3_file_destroy</function></member>
+      <member><function>pws3_file_get_error_code</function></member>
+      <member><function>pws3_file_get_error_message</function></member>
+      <member><function>pws3_file_read_mem</function></member>
+      <member><function>pws3_file_read_stream</function></member>
+      <member><function>pws3_file_write_mem</function></member>
+      <member><function>pws3_file_write_stream</function></member>
+      <member><function>pws3_file_set_header_field</function></member>
+      <member><function>pws3_file_get_header_field</function></member>
+      <member><function>pws3_file_remove_header_field</function></member>
+      <member><function>pws3_file_insert_empty_group</function></member>
+      <member><function>pws3_file_get_empty_group</function></member>
+      <member><function>pws3_file_remove_empty_group</function></member>
+      <member><function>pws3_file_first_empty_group</function></member>
+      <member><function>pws3_file_last_empty_group</function></member>
+      <member><function>pws3_file_next_empty_group</function></member>
+      <member><function>pws3_file_prev_empty_group</function></member>
+      <member><function>pws3_file_insert_record</function></member>
+      <member><function>pws3_file_get_record</function></member>
+      <member><function>pws3_file_remove_record</function></member>
+      <member><function>pws3_file_first_record</function></member>
+      <member><function>pws3_file_last_record</function></member>
+      <member><function>pws3_file_next_record</function></member>
+      <member><function>pws3_file_prev_record</function></member>
+    </simplelist></para>
+    <para>It defines the following C preprocessor macros which are documented
+        in the
+        <citerefentry><refentrytitle>pws_init</refentrytitle><manvolnum>3</manvolnum></citerefentry>
+        manual page:
+    <simplelist type="vert">
+      <member><function>LIBPWS_VERSION_MAJOR</function></member>
+      <member><function>LIBPWS_VERSION_MINOR</function></member>
+      <member><function>LIBPWS_VERSION_MICRO</function></member>
+      <member><function>PWS3_VERSION</function></member>
+      <member><function>PWS3_MAX_FIELD_SIZE</function></member>
+      <member><function>PWS3_MAX_PASSWORD_LEN</function></member>
+      <member><function>PWS3_UUID_SIZE</function></member>
+    </simplelist></para>
+  </refsect1>
+  <refsect1>
+    <title>Types</title>
+    <para>libpws provides the following data structures:
+    <variablelist>
+      <varlistentry>
+        <term>struct pws3_file</term>
+        <listitem>
+          <para>Opaque data structure representing a Password Safe version 3
+          file.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>struct pws3_record</term>
+        <listitem>
+          <para>Opaque data structure representing a Password Safe version 3
+          record.</para>
+        </listitem>
+      </varlistentry>
+      <varlistentry>
+        <term>struct pws3_field</term>
+        <listitem>
+          <para>Opaque data structure representing a Password Safe version 3
+            typed field belonging to the header or a record, depending on the
+            type it may hold a UUID, string, time, 8-bit, 16-bit, or 32-bit
+            wide unsigned integer or raw data.</para>
+        </listitem>
+      </varlistentry>
+    </variablelist></para>
+  </refsect1>
+  <refsect1>
+    <title>Security</title>
+    <para>The aforementioned protection of confidentiality and integrity of
+    the file contents only applies to the stored file. When reading a Password
+    Safe file using libpws, the file contents are decrypted and stored in
+    memory where they might be compromised, e.g. by a malicious application or
+    a privileged user. Furthermore, parts of the process memory may be paged to
+    the swap area by the operating system.</para>
+    <para>libpws provides hooks for allocating and freeing memory used to
+    store sensitive information which may be used to mitigate such issues
+    using operating system specific facilities.</para>
+    <para>libpws has not been formally audited, use at your own risk.</para>
+  </refsect1>
+  <refsect1>
+    <title>See Also</title>
+    <para><citerefentry><refentrytitle>pws_init</refentrytitle>
+      <manvolnum>3</manvolnum></citerefentry>,
+      <citerefentry><refentrytitle>pws3_file_create</refentrytitle>
+      <manvolnum>3</manvolnum></citerefentry>, <link
+      xlink:href="https://pwsafe.org/"/></para>
+  </refsect1>
+</refentry>