NAME
sqlbox_role —
change role of sqlbox
context
LIBRARY
library “sqlbox”
SYNOPSIS
#include
<stdint.h>
#include <sqlbox.h>
void
sqlbox_role(struct sqlbox *box,
size_t role);
DESCRIPTION
Change the active role of box to role. Changing to the current role has no effect.
Roles are defined in struct sqlbox_roles as passed to sqlbox_alloc(3). It has the following fields:
- roles
- An array of roles, each role being identified by its index. For example, if rolesz is 2, the first role (index 0) is role 0, the second role (index 1) is role 1.
- rolesz
- The number of roles. If zero, there are no roles and defrole is ignored.
- defrole
- The default role if and only if rolesz is non-zero, in which case it must be less than rolesz.
The resources available to each role are defined in struct sqlbox_role, which has the following fields:
- roles
- Which roles the given role may transition into. For example, an array of size 2 with values 0 and 1 would mean that the current role may transition into roles 0 and 1. The value for self-transition is ignored: self-transition is always allowed.
- rolesz
- Number of elements in roles.
- stmts
- Which statement indices the given role may execute or prepare with sqlbox_exec(3) and sqlbox_prepare_bind(3), respectively.
- stmtsz
- Number of elements in stmts.
- srcs
- Which source indices the given role may open or close with sqlbox_open(3) and sqlbox_close(3), respectively.
- srcsz
- Number of elements in srcs.
RETURN VALUES
Returns zero if communication with box fails. Otherwise, returns non-zero.
If role is not a valid role, no roles have been configured, or the current role does not have permission to transition to it, subsequent box access will fail. Use sqlbox_ping(3) to check explicitly.
If sqlbox_role() fails,
box is no longer accessible beyond
sqlbox_ping(3) and
sqlbox_free(3).
EXAMPLES
To transition from one "privileged" role into another "unprivileged" role (which cannot further transition nor open a database):
struct sqlbox *p;
struct sqlbox_cfg cfg;
struct sqlbox_src srcs[] = {
{ .fname = (char *)":memory:",
.mode = SQLBOX_SRC_RWC },
};
struct sqlbox_role roles[] = {
{ .rolesz = 2,
.roles = (size_t[]){ 1, 0 },
.stmtsz = 0,
.srcsz = 1,
.srcs = (size_t[]){ 0 } },
{ .rolesz = 0,
.stmtsz = 0,
.srcsz = 0 }
};
memset(&cfg, 0, sizeof(struct sqlbox_cfg));
cfg.msg.func_short = warnx;
cfg.roles.rolesz = 2;
cfg.roles.roles = roles;
cfg.roles.rolesz = 1;
cfg.roles.roles = srcs;
cfg.roles.defrole = 0;
if ((p = sqlbox_alloc(&cfg)) == NULL)
errx(EXIT_FAILURE, "sqlbox_alloc");
if (!(id = sqlbox_open(p, 0)))
errx(EXIT_FAILURE, "sqlbox_open");
if (!sqlbox_role(p, 1))
errx(EXIT_FAILURE, "sqlbox_role");
/* Now operate as the "unprivileged" role. */
/* The database will be closed out automatically. */
sqlbox_free(p);