NAME
sqlbox —
database access library
LIBRARY
library “sqlbox”
SYNOPSIS
#include
<stdint.h>
#include <sqlbox.h>
#define SQLBOX_VMAJOR x
#define SQLBOX_VMINOR y
#define SQLBOX_VBUILD z
#define SQLBOX_VERSION x.y.z
#define SQLBOX_VSTAMP xxxyyyzzz
DESCRIPTION
The sqlbox library is a secure database
access library at this time limited to sqlite3 databases. Instead of
operating databases in-process, sqlbox uses a
multi-process, resource-separated approach to safe-guard the database from
the calling application. It is most effective on
OpenBSD when used with
pledge(2).
The typical usage scenario is as follows:
- allocate a context with sqlbox_alloc(3),
- open a database connection in that context with sqlbox_open(3),
- execute statements with sqlbox_prepare_bind(3) or sqlbox_exec(3),
- explicitly close databases with sqlbox_close(3),
- free the context with sqlbox_free(3).
There's also support for transactions sqlbox_trans_immediate(3) and sqlbox_trans_commit(3), which should be used instead of manually specifying SQL transactions to prevent nested requests.
The current version of sqlbox is defined
in SQLBOX_VERSION as a string of major number, minor
number, and build. These values are available seperately as
SQLBOX_VMAJOR,
SQLBOX_VMINOR, and
SQLBOX_VBUILD, respectively. A numeric concatenation
of the version is defined as SQLBOX_VSTAMP, which
may be used to test for version number applicability.
Compiling
Applications should use pkg-config(1) to configure compiler and linker flags.
Compiling sqlbox applications typically looks as
follows, assuming main.c is the source file:
% cc `pkg-config --cflags sqlbox` main.c `pkg-config --libs sqlbox`
Pledge Promises
The sqlbox library is built to operate
with applications that use pledge(2) on OpenBSD to limit file-system
access. This protects the database from direct tampering and forces the
application to use the socket channel for communication.
Prior to calling sqlbox_alloc(3), the application may pledge with stdio rpath cpath wpath flock proc fattr and only stdio afterward.
struct sqlbox *p;
struct sqlbox_cfg cfg;
struct sqlbox_src srcs[] = {
{ .fname = (char *)":memory:",
.mode = SQLBOX_SRC_RWC }
};
if (pledge("stdio rpath cpath "
"wpath flock proc fattr", NULL) == -1)
err(EXIT_FAILURE, "pledge");
memset(&cfg, 0, sizeof(struct sqlbox_cfg));
cfg.msg.func_short = warnx;
cfg.srcs.srcs = srcs;
cfg.srcs.srcsz = 1;
if ((p = sqlbox_alloc(&cfg)) == NULL)
errx(EXIT_FAILURE, "sqlbox_alloc");
if (pledge("stdio", NULL) == -1)
err(EXIT_FAILURE, "pledge");
/* Do work. */
sqlbox_free(p);