<?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>