SQLBOX(3)

NAME
sqlbox - database access 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:

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.

  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);