nqrep(3)

NAME

nqrepn, nqrepi, nqrepfree — read and free a capsule check report

LIBRARY

libnoqtis, -lnoqtis

SYNOPSIS

#include <noqtis.h>

size_t
nqrepn(const nqrep *r);

int
nqrepi(const nqrep *r, size_t i, const char **check, int *ok, const char **detail);

void
nqrepfree(nqrep *r);

DESCRIPTION

A nqrep, made by nqchk(3) or nqchkt(3), holds one row per check, in the order the checks ran. Its layout is private.

nqrepn() returns the number of rows, or 0 when r is NULL.

nqrepi() gives row i: *check the check's name, a stable string listed below; *ok 1 when the check passed, 0 when it failed; *detail a UTF-8 text for people (a file's path, what differs). Any of the three output pointers may be NULL. The strings belong to the report and stay valid until nqrepfree().

nqrepfree() frees the report and wipes its memory; NULL is allowed.

Check names

seal.read: noqtis.sig read
seal.parse: it is a JSON object
seal.canonical: in canonical form
seal.fields: exactly the seal's fields, with their types
seal.format: ‘noqtis-seal-1’
seal.alg: a known signature algorithm
seal.context: the context ‘noqtis-capsule-1’
seal.key: the public key's size
seal.signature: the signature's size
manifest.read: noqtis.json read within the limit
manifest.digest: its SHA-256 is the seal's
key: pinned or not, and whether it matches
signature: the signature over the manifest
timestamp: the RFC 3161 token
folder: the folder listed
file: one per listed file
manifest.parse: the manifest is a JSON object
manifest.canonical: in canonical form
manifest.fields: exactly the manifest's fields
manifest.format: ‘noqtis-capsule-1’ or ‘noqtis-capsule-2’
manifest.created: RFC 3339 UTC
manifest.order: sorted by path, no repeats
manifest.merkle: format 2: the tree over the entries has the signed root
lineage: one per input, with nqchkx(3) lineage folders
partial: what a partial check or a proof left out; never a failure
keys, key.time: key statements, and a rotated or revoked key's time (nqkstmt(3))
proof.parse, proof.canonical, proof.fields, proof.entry: a proof's form and each entry's audit path (nqprove(3))
path: one per refused, non-normal, duplicate or case-colliding path
extra: one per regular file not listed
unsafe: one per link, special file or refused name

Rows after a failure that makes later checks meaningless are left out (for example, no seal.alg row when seal.format failed). A report never has zero rows.

RETURN VALUES

nqrepi() returns NQOK, or NQEARG when r is NULL or i is not below nqrepn(r).

EXAMPLES

size_t i;
for (i = 0; i < nqrepn(rep); i++) {
  const char *check, *detail;
  int ok;
  if (nqrepi(rep, i, &check, &ok, &detail) == NQOK)
    printf("%-4s %s: %s\n", ok ? "ok" : "FAIL", check, detail);
}
nqrepfree(rep);