ORT_AUDIT(3)

NAME
ort_audit - audit role operations in a configuration

LIBRARY
libort

SYNOPSIS
#include <sys/queue.h>
#include <stdio.h>
#include <ort.h>
struct auditq *
ort_audit(const struct role *r, const struct config *cfg);

DESCRIPTION
Audits the configuration cfg and returns all operations and access possible by r.

The audit results are returned as a queue of operations and components that describe what the role may do.

The result should be freed by ort_auditq_free(3) after use.

The cfg must be fully linked as driven by ort_parse_close(3).

The type of audit target is defined in enum audidt, which may be any of the following:

AUDIT_INSERT
    For insert operations.

AUDIT_UPDATE
    For delete and update operations.

AUDIT_QUERY
    For count, iterate, list, and search operations.

AUDIT_REACHABLE
    For structures that may be accessed or exported through queries and the export interface.

The returned structure is a queue of struct audit, which consists of the following:

enum auditt type
    The audit target type. This affects which of the following union fields will be set.

<anon union>
    This is a union consisting of the following:

    const struct strct *st
        Set by AUDIT_INSERT.

    const struct update *up
        Set by AUDIT_UPDATE.

    const struct search *sr
        Set by AUDIT_QUERY.

    struct auditreach ar
        Set by AUDIT_REACHABLE.

Reachable structures are described by struct auditreach, which consists of the following:

const struct strct *st
    The structure that is readable and possible exportable.

struct auditpaths *srs
    An array consisting of all origin queries sr, dot-separated (or NULL) path from the origin structure to the target, and whether the target is exported or not.

size_t srsz
    The number of elements in srs.

struct auditfield *fds
    An array consisting of all fields that may be accessed. The structure contains fd, the field that may be accessed, and exported, which is non-zero if the field may be exported. Whether these fields are actually exported depends upon how the structure is being accessed in the srs search paths.

int exported
    Whether it is exportable through any source in srs.

RETURN VALUES
Returns the audit report or NULL on memory allocation failure.

EXAMPLES
The following audits the user role in a configuration db.ort.

    struct config *cfg;
    struct auditq *aq;
    const struct role *r;
    if ((cfg = ort_config_alloc()) == NULL)
      err(1, NULL);
    if (!ort_parse_file(cfg, stdin, "<stdin>"))
      errx(1, "failed parsing");
    if (!ort_parse_close(cfg))
      errx(1, "failed linking");
    TAILQ_FOREACH(r, &cfg->arq, allentries)
      if (strcasecmp(r->name, "user") == 0)
        break;
    if (r == NULL)
      errx(1, "user: role not found");
    if ((aq = ort_audit(r, cfg)) == NULL)
      err(1, NULL);
    /* Do something with aq. */
    ort_auditq_free(aq);
    ort_config_free(cfg);