Mercurial > projects > libpws

comparison libpws.3.xml @ 1:e1309515d111

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add README file and manpages
author Guido Berhoerster <guido+libpws@berhoerster.name>
date Wed, 25 Mar 2015 17:10:23 +0100
parents
children
comparison
equal deleted inserted replaced
0:d541e748cfd8 1:e1309515d111
1 <?xml version="1.0"?>
2 <!--
3
4 Copyright (C) 2015 Guido Berhoerster <guido+libpws@berhoerster.name>
5
6 Permission is hereby granted, free of charge, to any person obtaining
7 a copy of this software and associated documentation files (the
8 "Software"), to deal in the Software without restriction, including
9 without limitation the rights to use, copy, modify, merge, publish,
10 distribute, sublicense, and/or sell copies of the Software, and to
11 permit persons to whom the Software is furnished to do so, subject to
12 the following conditions:
13
14 The above copyright notice and this permission notice shall be included
15 in all copies or substantial portions of the Software.
16
17 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
18 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
19 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
20 IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
21 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
22 TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
23 SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
24
25 -->
26 <refentry xmlns="http://docbook.org/ns/docbook"
27 xmlns:xlink="http://www.w3.org/1999/xlink" xml:lang="en">
28 <info>
29 <author>
30 <personname>
31 <firstname>Guido</firstname>
32 <surname>Berhoerster</surname>
33 </personname>
34 <email>guido+libpws@berhoerster.name</email>
35 <personblurb/>
36 </author>
37 <date>21 March, 2015</date>
38 </info>
39 <refmeta>
40 <refentrytitle>libpws</refentrytitle>
41 <manvolnum>3</manvolnum>
42 <refmiscinfo class="source"/>
43 <refmiscinfo class="version"/>
44 <refmiscinfo class="manual">Library Functions</refmiscinfo>
45 </refmeta>
46 <refnamediv>
47 <refname>libpws</refname>
48 <refpurpose>library for creating and manipulating Password Safe files</refpurpose>
49 </refnamediv>
50 <refsynopsisdiv>
51 <cmdsynopsis>
52 <command>cc</command>
53 <arg choice="opt" rep="repeat">
54 <option>flag</option>
55 </arg>
56 <arg choice="plain" rep="repeat">
57 <option>file</option>
58 </arg>
59 <arg choice="plain">
60 <option>-lpws</option>
61 </arg>
62 <arg choice="plain">
63 <option>-lnettle</option>
64 </arg>
65 <arg choice="opt" rep="repeat">
66 <option>library</option>
67 </arg>
68 </cmdsynopsis>
69 <funcsynopsis>
70 <funcsynopsisinfo>
71 #include &lt;pws.h&gt;
72 </funcsynopsisinfo>
73 </funcsynopsis>
74 </refsynopsisdiv>
75 <refsect1>
76 <title>Description</title>
77 <para>libpws provides an API for creating, reading, manipulating and
78 writing Password Safe files. The Password Safe file format is intended
79 for the platform-independent secure storage of passwords and associated
80 metadata and offers protection from unauthorized access to the file by
81 encrypting it using a key derived from a master password. Its design
82 ensures both confidentiality and integrity of its contents.</para>
83 <para>libpws currently supports version 3 of the Password Safe file
84 format.</para>
85 <para>The <literal>&lt;<filename
86 class="header">pws.h</filename>&gt;</literal> header provides type and
87 function declarations for all library services.</para>
88 <para>With the exception of <function>pws_set_alloc_functions</function>
89 all functions are reentrant. Functions operating on a Password Safe file
90 structure, a header field structure, a record field structure, and a record
91 structure provide no locking. A multithreaded application must either
92 provide its own synchronization mechanisms or restrict operations on any of
93 the above structures to a single thread.</para>
94 </refsect1>
95 <refsect1>
96 <title>Interfaces</title>
97 <para>The static library <filename class="libraryfile">libpws.a</filename>
98 provides following the public interfaces:
99 <simplelist type="vert" columns="2">
100 <member><function>pws_init</function></member>
101 <member><function>pws_finalize</function></member>
102 <member><function>pws_set_alloc_functions</function></member>
103 <member><function>pws_generate_uuid</function></member>
104 <member><function>pws3_field_create</function></member>
105 <member><function>pws3_field_destroy</function></member>
106 <member><function>pws3_field_is_header</function></member>
107 <member><function>pws3_field_get_type</function></member>
108 <member><function>pws3_field_get_data_type</function></member>
109 <member><function>pws3_field_set_uuid</function></member>
110 <member><function>pws3_field_set_text</function></member>
111 <member><function>pws3_field_set_time</function></member>
112 <member><function>pws3_field_set_uint8</function></member>
113 <member><function>pws3_field_set_uint16</function></member>
114 <member><function>pws3_field_set_uint32</function></member>
115 <member><function>pws3_field_set_bytes</function></member>
116 <member><function>pws3_field_get_uuid</function></member>
117 <member><function>pws3_field_get_text</function></member>
118 <member><function>pws3_field_get_time</function></member>
119 <member><function>pws3_field_get_uint8</function></member>
120 <member><function>pws3_field_get_uint16</function></member>
121 <member><function>pws3_field_get_uint32</function></member>
122 <member><function>pws3_field_get_bytes</function></member>
123 <member><function>pws3_file_create</function></member>
124 <member><function>pws3_file_destroy</function></member>
125 <member><function>pws3_file_get_error_code</function></member>
126 <member><function>pws3_file_get_error_message</function></member>
127 <member><function>pws3_file_read_mem</function></member>
128 <member><function>pws3_file_read_stream</function></member>
129 <member><function>pws3_file_write_mem</function></member>
130 <member><function>pws3_file_write_stream</function></member>
131 <member><function>pws3_file_set_header_field</function></member>
132 <member><function>pws3_file_get_header_field</function></member>
133 <member><function>pws3_file_remove_header_field</function></member>
134 <member><function>pws3_file_insert_empty_group</function></member>
135 <member><function>pws3_file_get_empty_group</function></member>
136 <member><function>pws3_file_remove_empty_group</function></member>
137 <member><function>pws3_file_first_empty_group</function></member>
138 <member><function>pws3_file_last_empty_group</function></member>
139 <member><function>pws3_file_next_empty_group</function></member>
140 <member><function>pws3_file_prev_empty_group</function></member>
141 <member><function>pws3_file_insert_record</function></member>
142 <member><function>pws3_file_get_record</function></member>
143 <member><function>pws3_file_remove_record</function></member>
144 <member><function>pws3_file_first_record</function></member>
145 <member><function>pws3_file_last_record</function></member>
146 <member><function>pws3_file_next_record</function></member>
147 <member><function>pws3_file_prev_record</function></member>
148 </simplelist></para>
149 <para>It defines the following C preprocessor macros which are documented
150 in the
151 <citerefentry><refentrytitle>pws_init</refentrytitle><manvolnum>3</manvolnum></citerefentry>
152 manual page:
153 <simplelist type="vert">
154 <member><function>LIBPWS_VERSION_MAJOR</function></member>
155 <member><function>LIBPWS_VERSION_MINOR</function></member>
156 <member><function>LIBPWS_VERSION_MICRO</function></member>
157 <member><function>PWS3_VERSION</function></member>
158 <member><function>PWS3_MAX_FIELD_SIZE</function></member>
159 <member><function>PWS3_MAX_PASSWORD_LEN</function></member>
160 <member><function>PWS3_UUID_SIZE</function></member>
161 </simplelist></para>
162 </refsect1>
163 <refsect1>
164 <title>Types</title>
165 <para>libpws provides the following data structures:
166 <variablelist>
167 <varlistentry>
168 <term>struct pws3_file</term>
169 <listitem>
170 <para>Opaque data structure representing a Password Safe version 3
171 file.</para>
172 </listitem>
173 </varlistentry>
174 <varlistentry>
175 <term>struct pws3_record</term>
176 <listitem>
177 <para>Opaque data structure representing a Password Safe version 3
178 record.</para>
179 </listitem>
180 </varlistentry>
181 <varlistentry>
182 <term>struct pws3_field</term>
183 <listitem>
184 <para>Opaque data structure representing a Password Safe version 3
185 typed field belonging to the header or a record, depending on the
186 type it may hold a UUID, string, time, 8-bit, 16-bit, or 32-bit
187 wide unsigned integer or raw data.</para>
188 </listitem>
189 </varlistentry>
190 </variablelist></para>
191 </refsect1>
192 <refsect1>
193 <title>Security</title>
194 <para>The aforementioned protection of confidentiality and integrity of
195 the file contents only applies to the stored file. When reading a Password
196 Safe file using libpws, the file contents are decrypted and stored in
197 memory where they might be compromised, e.g. by a malicious application or
198 a privileged user. Furthermore, parts of the process memory may be paged to
199 the swap area by the operating system.</para>
200 <para>libpws provides hooks for allocating and freeing memory used to
201 store sensitive information which may be used to mitigate such issues
202 using operating system specific facilities.</para>
203 <para>libpws has not been formally audited, use at your own risk.</para>
204 </refsect1>
205 <refsect1>
206 <title>See Also</title>
207 <para><citerefentry><refentrytitle>pws_init</refentrytitle>
208 <manvolnum>3</manvolnum></citerefentry>,
209 <citerefentry><refentrytitle>pws3_file_create</refentrytitle>
210 <manvolnum>3</manvolnum></citerefentry>, <link
211 xlink:href="https://pwsafe.org/"/></para>
212 </refsect1>
213 </refentry>