SQLBOX(3) Library Functions Manual SQLBOX(3)

sqlbox
database access library

library “sqlbox”

#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

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:

  1. allocate a context with sqlbox_alloc(3),
  2. open a database connection in that context with sqlbox_open(3),
  3. execute statements with sqlbox_prepare_bind(3) or sqlbox_exec(3),
  4. explicitly close databases with sqlbox_close(3),
  5. 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.

Applications must additionally link to -lsqlite3 and -lm. In some platforms such as OpenBSD, they must also link to -lpthread. Compiling sqlbox applications typically looks as follows on OpenBSD, assuming main.c is the source file and ports are installed into /usr/local:
% cc -I/usr/local/include -o main main.c \
> -L/usr/local/lib -lsqlbox -lsqlite3 -lm -lpthread

On Linux systems with libraries installed into the system path, this usually amounts to:

% cc -o main main.c -lsqlbox -lsqlite3 -lm

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);
November 8, 2019 OpenBSD 6.5