libpws — libpws(3) Manual Page

Name

libpws — library for creating and manipulating Password Safe files

Synopsis

cc [ flag ...] file ... -lpws -lnettle [ library ...]

#include <pws.h>

Description

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.

libpws currently supports version 3 of the Password Safe file format.

The <pws.h> header provides type and function declarations for all library services.

With the exception of pws_set_alloc_functions 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.

Interfaces

The static library libpws.a provides following the public interfaces:

`pws_init`	`pws3_file_destroy`
`pws_finalize`	`pws3_file_get_error_code`
`pws_set_alloc_functions`	`pws3_file_get_error_message`
`pws_generate_uuid`	`pws3_file_read_mem`
`pws3_field_create`	`pws3_file_read_stream`
`pws3_field_destroy`	`pws3_file_write_mem`
`pws3_field_is_header`	`pws3_file_write_stream`
`pws3_field_get_type`	`pws3_file_set_header_field`
`pws3_field_get_data_type`	`pws3_file_get_header_field`
`pws3_field_set_uuid`	`pws3_file_remove_header_field`
`pws3_field_set_text`	`pws3_file_insert_empty_group`
`pws3_field_set_time`	`pws3_file_get_empty_group`
`pws3_field_set_uint8`	`pws3_file_remove_empty_group`
`pws3_field_set_uint16`	`pws3_file_first_empty_group`
`pws3_field_set_uint32`	`pws3_file_last_empty_group`
`pws3_field_set_bytes`	`pws3_file_next_empty_group`
`pws3_field_get_uuid`	`pws3_file_prev_empty_group`
`pws3_field_get_text`	`pws3_file_insert_record`
`pws3_field_get_time`	`pws3_file_get_record`
`pws3_field_get_uint8`	`pws3_file_remove_record`
`pws3_field_get_uint16`	`pws3_file_first_record`
`pws3_field_get_uint32`	`pws3_file_last_record`
`pws3_field_get_bytes`	`pws3_file_next_record`
`pws3_file_create`	`pws3_file_prev_record`

It defines the following C preprocessor macros which are documented in the pws_init(3) manual page:

LIBPWS_VERSION_MAJOR

LIBPWS_VERSION_MINOR

LIBPWS_VERSION_MICRO

PWS3_VERSION

PWS3_MAX_FIELD_SIZE

PWS3_MAX_PASSWORD_LEN

PWS3_UUID_SIZE

Types

libpws provides the following data structures:

struct pws3_file: Opaque data structure representing a Password Safe version 3 file.
struct pws3_record: Opaque data structure representing a Password Safe version 3 record.
struct pws3_field: 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.

Security

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.

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.

libpws has not been formally audited, use at your own risk.