From: Sergey Matveev Date: Mon, 21 Oct 2024 11:11:00 +0000 (+0300) Subject: More docstrings X-Git-Url: http://www.git.cypherpunks.su/?a=commitdiff_plain;h=b83151cb2483c3faa928f4110b800a43b4ff9de0a139b3714f6adf11244272bf;p=keks.git More docstrings --- diff --git a/cyac/README b/cyac/README index 555f049..f18c2cb 100644 --- a/cyac/README +++ b/cyac/README @@ -1,2 +1,2 @@ -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. diff --git a/cyac/doc/.gitignore b/cyac/doc/.gitignore index d86ddd4..68365ba 100644 --- a/cyac/doc/.gitignore +++ b/cyac/doc/.gitignore @@ -1,2 +1,3 @@ /build/ +/cyac.info /docstringer.log diff --git a/cyac/doc/docstringer.log.do b/cyac/doc/docstringer.log.do index 148fbe9..ed1b0e0 100644 --- a/cyac/doc/docstringer.log.do +++ b/cyac/doc/docstringer.log.do @@ -1,3 +1,3 @@ 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 . diff --git a/cyac/doc/index.texi b/cyac/doc/index.texi index 32bd88d..fa8d8ca 100644 --- a/cyac/doc/index.texi +++ b/cyac/doc/index.texi @@ -32,6 +32,7 @@ licenced under @url{https://www.gnu.org/licenses/lgpl-3.0.html, GNU LGPLv3}. @include atom.texi @include tai64.texi @include items.texi +@include pki.texi @node Indices @unnumbered Indices @@ -44,6 +45,10 @@ licenced under @url{https://www.gnu.org/licenses/lgpl-3.0.html, GNU LGPLv3}. @section Programs Index @printindex pg +@node Functions Index +@section Functions Index +@printindex fn + @node Variables Index @section Variables Index @printindex vr diff --git a/cyac/doc/pki.texi b/cyac/doc/pki.texi new file mode 100644 index 0000000..745fa9b --- /dev/null +++ b/cyac/doc/pki.texi @@ -0,0 +1,19 @@ +@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@ diff --git a/cyac/lib/dec.h b/cyac/lib/dec.h index c01ad30..c06d8ab 100644 --- a/cyac/lib/dec.h +++ b/cyac/lib/dec.h @@ -102,7 +102,7 @@ struct YACAtom { }; // TEXINFO: YACAtomDecode -// @deftypefun {enum YACErr} YACAtomDecode( @ +// @deftypefun {enum YACErr} YACAtomDecode ( @ // size_t *got, @ // struct YACAtom *atom, @ // const unsigned char *buf, @ diff --git a/cyac/lib/dectai.h b/cyac/lib/dectai.h index 4070121..401bb14 100644 --- a/cyac/lib/dectai.h +++ b/cyac/lib/dectai.h @@ -7,8 +7,8 @@ #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. @@ -21,7 +21,7 @@ enum YACErr 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 diff --git a/cyac/lib/enc.h b/cyac/lib/enc.h index 0282f88..1055c72 100644 --- a/cyac/lib/enc.h +++ b/cyac/lib/enc.h @@ -6,8 +6,8 @@ #include // 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. @@ -16,8 +16,8 @@ bool 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. @@ -26,8 +26,8 @@ bool 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. @@ -36,8 +36,8 @@ bool 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. @@ -50,8 +50,8 @@ YACAtomUUIDEncode( 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 @@ -61,8 +61,8 @@ bool 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. @@ -73,8 +73,8 @@ bool 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. @@ -83,8 +83,8 @@ bool 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. @@ -93,8 +93,8 @@ bool 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} @@ -109,8 +109,8 @@ YACAtomBlobEncode( 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 @@ -125,8 +125,8 @@ YACAtomStrEncode( 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 @@ -141,8 +141,8 @@ YACAtomBinEncode( 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 @@ -158,8 +158,8 @@ YACAtomChunkEncode( 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 @@ -175,8 +175,8 @@ YACAtomTAI64Encode( 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 diff --git a/cyac/lib/enctai.h b/cyac/lib/enctai.h index b7c25bb..a790bb9 100644 --- a/cyac/lib/enctai.h +++ b/cyac/lib/enctai.h @@ -5,8 +5,8 @@ #include // 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. @@ -16,7 +16,7 @@ bool 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 diff --git a/cyac/lib/err.h b/cyac/lib/err.h index 67d98e3..7ee9570 100644 --- a/cyac/lib/err.h +++ b/cyac/lib/err.h @@ -63,7 +63,7 @@ enum YACErr { }; // 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 * diff --git a/cyac/lib/items.h b/cyac/lib/items.h index b0bba8f..fce7856 100644 --- a/cyac/lib/items.h +++ b/cyac/lib/items.h @@ -56,7 +56,7 @@ struct YACItems { }; // 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. // @@ -72,7 +72,7 @@ enum YACErr 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 @@ -82,7 +82,7 @@ enum YACErr YACItemsGrow(struct YACItems *); // TEXINFO: YACItemsParse -// @deftypefun {enum YACErr} YACItemsParse( @ +// @deftypefun {enum YACErr} YACItemsParse ( @ // struct YACItems *items, @ // size_t *off, @ // const unsigned char *buf, @ @@ -103,7 +103,7 @@ YACItemsParse( const size_t len); // TEXINFO: YACItemsEncode -// @deftypefun bool YACItemsEncode( @ +// @deftypefun bool YACItemsEncode ( @ // const struct YACItems *items, @ // size_t idx, @ // size_t *off, @ @@ -123,7 +123,7 @@ YACItemsEncode( 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, @ @@ -139,7 +139,7 @@ YACItemsGetByKeyLen( 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) @@ -150,7 +150,7 @@ size_t 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, @ @@ -165,14 +165,14 @@ YACItemsGetByKeyAndType( 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) @@ -183,7 +183,7 @@ bool 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) diff --git a/cyac/lib/pki/cer.h b/cyac/lib/pki/cer.h index e8ba251..9314d27 100644 --- a/cyac/lib/pki/cer.h +++ b/cyac/lib/pki/cer.h @@ -8,6 +8,33 @@ #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; @@ -21,6 +48,20 @@ struct YACCer { 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 *, @@ -40,16 +81,49 @@ typedef bool (*yacSigVerifier)( 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,