From 5771e615d7c20db9edffa5cc24ebc85d37856245 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Wed, 30 Nov 2022 18:23:25 +0000 Subject: [PATCH] Document CanonicalJson --- TODO.txt | 2 +- man/man3/CanonicalJson.3 | 69 +++++++++++++++++++++++++++++++++++++ site/index.html | 6 ++++ src/include/CanonicalJson.h | 49 -------------------------- 4 files changed, 76 insertions(+), 50 deletions(-) create mode 100644 man/man3/CanonicalJson.3 diff --git a/TODO.txt b/TODO.txt index 6ae1e11..62ffce7 100644 --- a/TODO.txt +++ b/TODO.txt @@ -27,7 +27,7 @@ Due: January 1, 2023 [~] Internal API docs [x] Array [x] Base64 - [ ] CanonicalJson + [x] CanonicalJson [ ] Config [ ] API (Config.3) [ ] File format (Config.5) diff --git a/man/man3/CanonicalJson.3 b/man/man3/CanonicalJson.3 new file mode 100644 index 0000000..91fc44f --- /dev/null +++ b/man/man3/CanonicalJson.3 @@ -0,0 +1,69 @@ +.Dd $Mdocdate: November 30 2022 $ +.Dt CANONICALJSON 3 +.Os Telodendria Project +.Sh NAME +.Nm CanonicalJson +.Nd An extension of JSON that produces the Matrix spec's "canonical" JSON. +.Sh SYNOPSIS +.In CanonicalJson.h +.Ft int +.Fn CanonicalJsonEncode "HashMap *" "FILE *" +.Ft char * +.Fn CanonicalJsonEncodeToString "HashMap *" +.Sh DESCRIPTION +.Pp +.Nm +is an extension of +.Xr Json 3 +that is specifically designed to produce the Matrix specification's +"canonical" JSON. +.Pp +Canonical JSON is defined as JSON that: +.Bl -bullet -offset indent +.It +Does not have any unecessary whitespace. +.It +Has all object keys lexicographically sorted. +.It +Does not contain any floating point numerical values. +.El +.Pp +The regular JSON encoder has no such rules, because normally they are +not needed. However, Canonical JSON is needed to consistently sign JSON +objects. +.Pp +.Fn CanonicalJsonEncode +encodes a JSON object following the rules of Canonical Json. See the +documentation for +.Fn JsonEncode , +documented in +.Xr Json 3 +for more details on how JSON encoding operates. This function exists +as an alternative to +.Fn JsonEncode , +but should not be preferred to it in most circumstances. It is a lot +more costly, as it must lexicographically sort all keys and strip out +float values. If at all possible, use +.Fn JsonEncode +because it is much cheaper both in terms of memory and CPU time. +.Pp +.Fn CanonicalJsonEncodeToString +encodes a JSON object to a string. +.Xr Json 3 +doesn't have any way to send JSON to a string, because there's +absolutely no reason to handle JSON strings in most cases. However, +the sole reason Canonical JSON exists is so that JSON objects can +be signed in a consistent way. Thus, you need a string to pass to +the signing function. +.Sh RETURN VALUES +.Pp +.Fn CanonicalJsonEncode +returns whether or not the JSON encoding operation was sucessful. +This function will fail only if NULL was given for any parameter. +Otherwise, if an invalid pointer is given, undefined behavior results. +.Pp +.Fn CanonicalJsonEncodeToString +returns a C string containing the canonical JSON representation of +the given object, or NULL if the encoding failed. +.Sh SEE ALSO +.Xr Json 3 diff --git a/site/index.html b/site/index.html index 820a655..a80ca98 100644 --- a/site/index.html +++ b/site/index.html @@ -235,6 +235,12 @@ Smart memory management API. A feature-complete API for reading and writing JSON. + +CanonicalJson(3) + +An extension to the Json API that implements Matrix's canonical JSON. + +

Resources