-iter.* contains helpers that may pass over the iterables.
-items.* contains a non-streamable parser.
+C99 implementation of the YAC codec.
+Look at doc/ for more information.
/build/
+/cyac.info
/docstringer.log
redo-ifchange docstringer.pl *.texi ../lib/*.h ../lib/pki/*.h
rm -rf build
-./docstringer.pl -v build ../lib .
+./docstringer.pl -v build ../lib:../lib/pki .
@include atom.texi
@include tai64.texi
@include items.texi
+@include pki.texi
@node Indices
@unnumbered Indices
@section Programs Index
@printindex pg
+@node Functions Index
+@section Functions Index
+@printindex fn
+
@node Variables Index
@section Variables Index
@printindex vr
--- /dev/null
+@node PKI
+@cindex PKI
+@unnumbered PKI
+
+@file{lib/pki} contains PKI-related code. It is not directly related to
+the YAC codec, so it is placed isolated nearby. Currently there are
+functions to deal with certificate verification:
+
+@anchor{YACCer}
+@DOCSTRING YACCer@
+
+@DOCSTRING YACCerParse@
+
+@DOCSTRING YACCerVerify@
+
+@DOCSTRING YACCerVerifyOpts@
+
+@anchor{YACCerSigVerifier}
+@DOCSTRING YACCerSigVerifier@
};
// TEXINFO: YACAtomDecode
-// @deftypefun {enum YACErr} YACAtomDecode( @
+// @deftypefun {enum YACErr} YACAtomDecode ( @
// size_t *got, @
// struct YACAtom *atom, @
// const unsigned char *buf, @
#include "err.h"
// TEXINFO: YACTAI64ToTimespec
-// @deftypefun {enum YACErr} YACTAI64ToTimespec( @
-// struct timespec *tv, const unsigned char *buf, const size_t len)
+// @deftypefun {enum YACErr} YACTAI64ToTimespec @
+// (struct timespec *tv, const unsigned char *buf, const size_t len)
// Convert TAI64* value from @var{buf} to @var{ts} structure.
// @code{YACErrTAI64InPast} error is returned if value represents time
// before 1970. Some systems support those dates, but not guaranteed to.
YACTAI64ToTimespec(struct timespec *ts, const unsigned char *buf, const size_t len);
// TEXINFO: YACTimespecToUTC
-// @deftypefun {enum YACErr} YACTimespecToUTC(struct timespec *ts)
+// @deftypefun {enum YACErr} YACTimespecToUTC (struct timespec *ts)
// Convert TAI stored in @var{ts} structure to UTC. @code{YACErrTAI64InPast}
// error is returned if value represents time before 1970.
// @end deftypefun
#include <stdint.h>
// TEXINFO: YACAtomEOCEncode
-// @deftypefun bool YACAtomEOCEncode( @
-// size_t *len, unsigned char *buf, const size_t cap)
+// @deftypefun bool YACAtomEOCEncode @
+// (size_t *len, unsigned char *buf, const size_t cap)
// Encode EOC atom in provided @var{buf} with capacity of @var{cap}.
// In case of success, true is returned and @var{len} will hold how many
// bytes were written to buffer.
YACAtomEOCEncode(size_t *len, unsigned char *buf, const size_t cap);
// TEXINFO: YACAtomNILEncode
-// @deftypefun bool YACAtomNILEncode( @
-// size_t *len, unsigned char *buf, const size_t cap)
+// @deftypefun bool YACAtomNILEncode @
+// (size_t *len, unsigned char *buf, const size_t cap)
// Encode NUL atom in provided @var{buf} with capacity of @var{cap}.
// In case of success, true is returned and @var{len} will hold how many
// bytes were written to buffer.
YACAtomNILEncode(size_t *len, unsigned char *buf, const size_t cap);
// TEXINFO: YACAtomBoolEncode
-// @deftypefun bool YACAtomBoolEncode( @
-// size_t *len, unsigned char *buf, const size_t cap, const bool v)
+// @deftypefun bool YACAtomBoolEncode @
+// (size_t *len, unsigned char *buf, const size_t cap, const bool v)
// Encode boolean atom in provided @var{buf} with capacity of @var{cap}.
// In case of success, true is returned and @var{len} will hold how many
// bytes were written to buffer.
YACAtomBoolEncode(size_t *len, unsigned char *buf, const size_t cap, const bool v);
// TEXINFO: YACAtomUUIDEncode
-// @deftypefun bool YACAtomUUIDEncode( @
-// size_t *len, unsigned char *buf, const size_t cap, const unsigned char v[16])
+// @deftypefun bool YACAtomUUIDEncode @
+// (size_t *len, unsigned char *buf, const size_t cap, const unsigned char v[16])
// Encode UUID atom in provided @var{buf} with capacity of @var{cap}.
// In case of success, true is returned and @var{len} will hold how many
// bytes were written to buffer.
const unsigned char v[16]);
// TEXINFO: YACAtomUintEncode
-// @deftypefun bool YACAtomUintEncode( @
-// size_t *len, unsigned char *buf, const size_t cap, const uint64_t v)
+// @deftypefun bool YACAtomUintEncode @
+// (size_t *len, unsigned char *buf, const size_t cap, const uint64_t v)
// Encode positive integer atom in provided @var{buf} with capacity of
// @var{cap}.
// In case of success, true is returned and @var{len} will hold how many
YACAtomUintEncode(size_t *len, unsigned char *buf, const size_t cap, const uint64_t v);
// TEXINFO: YACAtomSintEncode
-// @deftypefun bool YACAtomSintEncode( @
-// size_t *len, unsigned char *buf, const size_t cap, const int64_t v)
+// @deftypefun bool YACAtomSintEncode @
+// (size_t *len, unsigned char *buf, const size_t cap, const int64_t v)
// Encode signed integer atom in provided @var{buf} with capacity of
// @var{cap}. If it is zero or positive, then it encodes unsigned one.
// Negative one otherwise.
YACAtomSintEncode(size_t *len, unsigned char *buf, const size_t cap, const int64_t v);
// TEXINFO: YACAtomListEncode
-// @deftypefun bool YACAtomListEncode( @
-// size_t *len, unsigned char *buf, const size_t cap)
+// @deftypefun bool YACAtomListEncode @
+// (size_t *len, unsigned char *buf, const size_t cap)
// Encode LIST atom in provided @var{buf} with capacity of @var{cap}.
// In case of success, true is returned and @var{len} will hold how many
// bytes were written to buffer. Do not forget to add EOC atom at the end.
YACAtomListEncode(size_t *len, unsigned char *buf, const size_t cap);
// TEXINFO: YACAtomMapEncode
-// @deftypefun bool YACAtomMapEncode( @
-// size_t *len, unsigned char *buf, const size_t cap)
+// @deftypefun bool YACAtomMapEncode @
+// (size_t *len, unsigned char *buf, const size_t cap)
// Encode MAP atom in provided @var{buf} with capacity of @var{cap}.
// In case of success, true is returned and @var{len} will hold how many
// bytes were written to buffer. Do not forget to add EOC atom at the end.
YACAtomMapEncode(size_t *len, unsigned char *buf, const size_t cap);
// TEXINFO: YACAtomBlobEncode
-// @deftypefun bool YACAtomBlobEncode( @
-// size_t *len, unsigned char *buf, const size_t cap, const size_t chunkLen)
+// @deftypefun bool YACAtomBlobEncode @
+// (size_t *len, unsigned char *buf, const size_t cap, const size_t chunkLen)
// Encode BLOB atom in provided @var{buf} with capacity of @var{cap}.
// In case of success, true is returned and @var{len} will hold how many
// bytes were written to buffer. You must call @ref{YACAtomChunkEncode}
const size_t chunkLen);
// TEXINFO: YACAtomStrEncode
-// @deftypefun bool YACAtomStrEncode( @
-// size_t *len, unsigned char *buf, const size_t cap, @
+// @deftypefun bool YACAtomStrEncode @
+// (size_t *len, unsigned char *buf, const size_t cap, @
// const unsigned char *src, const size_t srcLen)
// Encode STR atom in provided @var{buf} with capacity of @var{cap}.
// In case of success, true is returned and @var{len} will hold how many
const size_t srcLen);
// TEXINFO: YACAtomBinEncode
-// @deftypefun bool YACAtomBinEncode( @
-// size_t *len, unsigned char *buf, const size_t cap, @
+// @deftypefun bool YACAtomBinEncode @
+// (size_t *len, unsigned char *buf, const size_t cap, @
// const unsigned char *src, const size_t srcLen)
// Encode BIN atom in provided @var{buf} with capacity of @var{cap}.
// In case of success, true is returned and @var{len} will hold how many
const size_t srcLen);
// TEXINFO: YACAtomChunkEncode
-// @deftypefun bool YACAtomChunkEncode( @
-// size_t *len, unsigned char *buf, const size_t cap, @
+// @deftypefun bool YACAtomChunkEncode @
+// (size_t *len, unsigned char *buf, const size_t cap, @
// const unsigned char *src, const size_t srcLen)
// Encode the chunk in provided @var{buf} with capacity of @var{cap}.
// In case of success, true is returned and @var{len} will hold how many
const size_t srcLen);
// TEXINFO: YACAtomTAI64Encode
-// @deftypefun bool YACAtomTAI64Encode( @
-// size_t *len, unsigned char *buf, const size_t cap, @
+// @deftypefun bool YACAtomTAI64Encode @
+// (size_t *len, unsigned char *buf, const size_t cap, @
// const unsigned char *src, const size_t srcLen)
// Encode the TAI64* atom in provided @var{buf} with capacity of @var{cap}.
// In case of success, true is returned and @var{len} will hold how many
const size_t srcLen);
// TEXINFO: YACAtomRawEncode
-// @deftypefun bool YACAtomRawEncode( @
-// size_t *len, unsigned char *buf, const size_t cap, @
+// @deftypefun bool YACAtomRawEncode @
+// (size_t *len, unsigned char *buf, const size_t cap, @
// const unsigned char typ, const unsigned char *src, const size_t srcLen)
// Encode raw atom in provided @var{buf} with capacity of @var{cap}.
// In case of success, true is returned and @var{len} will hold how many
#include <time.h>
// TEXINFO: YACTimespecToTAI64
-// @deftypefun bool YACTimespecToTAI64( @
-// unsigned char *buf, const struct timespec *ts)
+// @deftypefun bool YACTimespecToTAI64 @
+// (unsigned char *buf, const struct timespec *ts)
// Convert @var{ts} structure to TAI64/TAI64N in the @var{buf}.
// If @var{ts} contains non zero nanoseconds count, then be sure that
// @var{buf} has enough capacity for 12-byte TAI64N value.
YACTimespecToTAI64(unsigned char *buf, const struct timespec *ts);
// TEXINFO: YACTimespecToTAI
-// @deftypefun bool YACTimespecToTAI(struct timespec *ts)
+// @deftypefun bool YACTimespecToTAI (struct timespec *ts)
// Convert UTC stored in @var{ts} structure to TAI.
// False is returned if represented time is out of allowable bounds.
// @end deftypefun
};
// TEXINFO: YACErr2Str
-// @deftypefun {const char *} YACErr2Str(const enum YACErr)
+// @deftypefun {const char *} YACErr2Str (const enum YACErr)
// Get human-readable string of the error.
// @end deftypefun
const char *
};
// TEXINFO: YACItemsInit
-// @deftypefun {enum YACErr} YACItemsInit(struct YACItems *items)
+// @deftypefun {enum YACErr} YACItemsInit (struct YACItems *items)
// Initialise the @ref{YACItems} structure by allocating an initial
// capacity for the underlying storage.
//
YACItemsInit(struct YACItems *);
// TEXINFO: YACItemsGrow
-// @deftypefun {enum YACErr} YACItemsGrow(struct YACItems *items)
+// @deftypefun {enum YACErr} YACItemsGrow (struct YACItems *items)
// Enlarge underlying storage of items, increasing its capacity. If
// @code{.cap} equals to -1, then nothing will happen and
// @code{YACErrNoMem} error will be returned. You can use that -1 value
YACItemsGrow(struct YACItems *);
// TEXINFO: YACItemsParse
-// @deftypefun {enum YACErr} YACItemsParse( @
+// @deftypefun {enum YACErr} YACItemsParse ( @
// struct YACItems *items, @
// size_t *off, @
// const unsigned char *buf, @
const size_t len);
// TEXINFO: YACItemsEncode
-// @deftypefun bool YACItemsEncode( @
+// @deftypefun bool YACItemsEncode ( @
// const struct YACItems *items, @
// size_t idx, @
// size_t *off, @
const size_t cap);
// TEXINFO: YACItemsGetByKeyLen
-// @deftypefun size_t YACItemsGetByKeyLen( @
+// @deftypefun size_t YACItemsGetByKeyLen ( @
// const struct YACItems *items, @
// const size_t itemIdx, @
// const char *key, @
const size_t keyLen);
// TEXINFO: YACItemsGetByKey
-// @deftypefun size_t YACItemsGetByKey( @
+// @deftypefun size_t YACItemsGetByKey ( @
// const struct YACItems *items, @
// const size_t itemIdx, @
// const char *key)
YACItemsGetByKey(const struct YACItems *, const size_t itemIdx, const char *key);
// TEXINFO: YACItemsGetByKeyAndType
-// @deftypefun size_t YACItemsGetByKeyAndType( @
+// @deftypefun size_t YACItemsGetByKeyAndType ( @
// const struct YACItems *items, @
// const size_t itemIdx, @
// const char *key, @
const enum YACItemType typ);
// TEXINFO: YACStrEqual
-// @deftypefun bool YACStrEqual(const struct YACAtom *atom, const char *s)
+// @deftypefun bool YACStrEqual (const struct YACAtom *atom, const char *s)
// Returns true if string atom's value equal to null-terminated @var{s}.
// @end deftypefun
bool
YACStrEqual(const struct YACAtom *, const char *s);
// TEXINFO: YACListHasOnlyType
-// @deftypefun bool YACListHasOnlyType( @
+// @deftypefun bool YACListHasOnlyType ( @
// const struct YACItems *items, @
// const size_t idx, @
// const enum YACItemType typ)
YACListHasOnlyType(const struct YACItems *, size_t idx, const enum YACItemType typ);
// TEXINFO: YACMapHasOnlyType
-// @deftypefun bool YACMapHasOnlyType( @
+// @deftypefun bool YACMapHasOnlyType ( @
// const struct YACItems *items, @
// const size_t idx, @
// const enum YACItemType typ)
#include "../err.h"
#include "../items.h"
+// TEXINFO: YACCer
+// @deftp {Data type} {struct YACCer}
+// Parsed certificate structure.
+// @table @code
+// @item .items
+// Holds parsed @ref{YACItems} items.
+// @item .load
+// Items index of the @code{/load/v}, certificate body.
+// @item .pub
+// Items index of the first @code{/load/v/pub}, certificate's public key.
+// @item .sub
+// Items index of the @code{/load/v/sub}, certificate's subject.
+// @item .sig
+// Items index of the first @code{/sigs}, certificate's signature.
+// @item .cid
+// Pointer to the start of if @code{cid} UUID, certificate's id.
+// @item .pkid
+// Pointer to the start of if @code{pkid} UUID, certificate's
+// first public key id.
+// @item .sid
+// Pointer to the start of if @code{sid} UUID, certificate's signature id.
+// @item .since
+// Parsed "since" datetime.
+// @item .till
+// Parsed un"till" datetime.
+// @end table
+// @end deftp
struct YACCer {
struct YACItems items;
size_t load;
struct timespec till;
};
+// TEXINFO: YACCerParse
+// @deftypefun {enum YACErr} YACCerParse ( @
+// struct YACCer *cer, @
+// size_t *off, @
+// char **failReason, @
+// const unsigned char *buf, @
+// const size_t len)
+// Parse represented YAC certificate from @var{buf} of @var{len} length,
+// to the @var{cer}, starting with @var{off} offset in the buffer.
+// Offset will be updated to show where parsing stopped. If parsing,
+// made by @ref{YACItemsParse}, finished successfully, then
+// @code{YACErrUnsatisfiedSchema} may be returned after that, setting
+// the @var{failReason} to the string describing the error.
+// @end deftypefun
enum YACErr
YACCerParse(
struct YACCer *,
const unsigned char *data,
const size_t dataLen);
+// TEXINFO: YACCerSigVerifier
+// @deftp {Data type} {struct YACCerSigVerifier}
+// Cryptographic signature verifier. That structure's @code{.algo} holds
+// the string identifier of the algorithm met in the YAC structures.
+// @code{.func} holds the pointer to the verifier function itself, that
+// accepts the algorithm identifier, signature, raw public key, the data
+// to be verified.
+// @end deftp
struct YACCerSigVerifier {
char *algo;
yacSigVerifier func;
};
+// TEXINFO: YACCerVerifyOpts
+// @deftp {Data type} {struct YACCerVerifyOpts}
+// Certificate verification options:
+// @table @code
+// @item .t
+// Validity time to check against.
+// @item .sigVerifiers
+// List of @ref{YACCerSigVerifier}.
+// Its last dummy element must have NULL @code{.algo}.
+// @end table
+// @end deftp
struct YACCerVerifyOpts {
struct timespec t;
struct YACCerSigVerifier *sigVerifiers;
};
+// TEXINFO: YACCerVerify
+// @deftypefun bool YACCerVerify ( @
+// char **failReason, @
+// struct YACCer **verifier, @
+// struct YACCer *cer, @
+// struct YACCer *pool, @
+// const size_t poolLen, @
+// const struct YACCerVerifyOpts opts)
+// Verify @var{cer} certificate. @var{pool} is a list of certificates of
+// @var{poolLen} length, which is searched for verifier certificates. If
+// verifier is found (certificate with @code{pkid} equals to @code{sid}),
+// then @var{verifier} points to it. @var{opts} options affect
+// verification process.
+// @end deftypefun
bool
YACCerVerify(
char **failReason,