Skip to content
NOQTIS

nqersput(3)

nqersreq, nqersput — RFC 4998 evidence records for a sealed capsule

libnoqtis, -lnoqtis

#include <noqtis.h>

int
nqersreq(const char *dir, nqhalg h, const uint8_t *nonce, size_t noncelen, uint8_t *req, size_t reqlen, size_t *outlen, const char **why);

int
nqersput(const char *dir, nqhalg h, const uint8_t *rsp, size_t rsplen, const uint8_t *nonce, size_t noncelen, const uint8_t *const *anc, const size_t *anclen, size_t nanc, int64_t *gt, int *how, const char **why);

An evidence record (noqtis.ers), beside the seal of the capsule in dir, is an RFC 4998 EvidenceRecord whose one data object is the seal file noqtis.sig, byte for byte. It keeps the seal provably in existence at the time of its first archive timestamp for as long as its timestamps are renewed. As with nqtsput(3), the library makes no network request: the caller sends the request to a TSA and passes back its reply.

() writes to req (reqlen bytes; 128 are enough) the RFC 3161 TimeStampReq for the next archive timestamp, with hash h (NQS256, NQS384 or NQS512); 0 takes the record's last hash, or SHA-256 for a new record), the nonce when not NULL (at most 32 bytes) and certReq TRUE; *outlen gets its size. The next timestamp covers: without a record, the hash of the seal file; with h the record's last hash, the last timestamp (timestamp renewal); with another, the hash of the seal file and of the record's ArchiveTimeStampSequence, in binary ascending order (hash-tree renewal, a new chain).

() checks the record already there, as nqchkt(3) does under the nanc anchors anc (DER certificates of anclen bytes, at most 32), or each token alone without anchors; then the reply rsp, a TimeStampResp or a bare token: granted, its imprint the hash nqersreq() asked for, its nonce the given one, its genTime not before the record's last, and its signature valid (under an anchor when given). It then writes the record with the new archive timestamp. *how (when not NULL) gets 0 for a new record, 1 for a timestamp renewal and 2 for a hash-tree renewal; *gt the new timestamp's genTime, in seconds since 1970.

While a record is there, nqtsput(3) and nqseal(3) return NQESTATE: either would change the seal the record proves. nqchkt(3) and () check the record in an “ers” row.

noqtis writes archive timestamps that hold only their token, and reads also the digestAlgorithm, attributes, reducedHashtree and cryptoInfos fields; a record of encrypted data (encryptionInfo) is NQENOSUP.

The request, or the record, was written.
[NQEARG]
A required pointer is NULL, a nonce is longer than 32 bytes, or an anchor is not a certificate.
[NQEBUF]
reqlen is too small.
[NQEVRFY]
The reply does not check, or the record there does not; nothing is written.
[NQEDEC]
The record there is not a DER EvidenceRecord in the form noqtis reads.
[NQENOSUP]
h is not one of the three hashes, or the record there uses another or is of encrypted data.
[NQEIO]
The seal, the record, or the new record could not be read or written.

*why (when not NULL) gets a sentence on what failed, or NULL.

noqtis-ers(1), noqtis(3), nqchkt(3), nqtsput(3), noqtis-capsule(5)

Evidence Record Syntax (ERS), RFC 4998.