From acffd82b481bcac5e06434f4a27420928a2c5c03 Mon Sep 17 00:00:00 2001 From: Jordan Bancino Date: Tue, 27 Sep 2022 16:13:59 -0400 Subject: [PATCH] Move Base64 documentation to man page. --- docs/Array.3 | 6 ++- docs/Base64.3 | 81 ++++++++++++++++++++++++++++++++ docs/telodendria.7 | 8 ++-- src/include/Base64.h | 107 ------------------------------------------- 4 files changed, 88 insertions(+), 114 deletions(-) create mode 100644 docs/Base64.3 diff --git a/docs/Array.3 b/docs/Array.3 index f2443c4..c9262ce 100644 --- a/docs/Array.3 +++ b/docs/Array.3 @@ -1,4 +1,4 @@ -.Dd $Mdocdate: September 25 2022 $ +.Dd $Mdocdate: September 27 2022 $ .Dt ARRAY 3 .Os Telodendria Project .Sh NAME @@ -87,7 +87,9 @@ the opposite: the second element should appear after the first in the array. is used to get the element at the specified index. .Sh RETURN VALUES .Fn ArrayCreate -returns a pointer on the heap to a newly allocated array structure. +returns a pointer on the heap to a newly allocated array structure, or +.Dv NULL +if the allocation fails. .Pp .Fn ArrayGet and diff --git a/docs/Base64.3 b/docs/Base64.3 new file mode 100644 index 0000000..986bd45 --- /dev/null +++ b/docs/Base64.3 @@ -0,0 +1,81 @@ +.Dd $Mdocdate: September 27 2022 $ +.Dt BASE64 3 +.Os Telodendria Project +.Sh NAME +.Nm Base64 +.Nd A simple base64 encoder/decoder with "unpadded base64" support. +.Sh SYNOPSIS +.In Base64.h +.Ft size_t +.Fn Base64EncodedSize "size_t" +.Ft size_t +.Fn Base64DecodedSize "const char *" "size_t" +.Ft char * +.Fn Base64Encode "const char *" "size_t" +.Ft char * +.Fn Base64Decode "const char *" "size_t" +.Ft void +.Fn Base64Unpad "char *" "size_t" +.Ft int +.Fn Base64Pad "char **" "size_t" +.Sh DESCRIPTION +This is an efficient yet simple base64 encoding and decoding +library that supports regular base64, as well as the Matrix +specification's extension to base64, called "unpadded base64." +.Nm provides the ability to convert between the two, instead of +just implementing "unpadded base64." +.Pp +.Fn Base64EncodedSize +and +.Fn Base64DecodedSize +compute the amount of characters needed to store an encoded or +decoded message, respectively. Both functions take the size of +the message being encoded or decoded, but +.Fn Base64DecodedSize +also takes a pointer to an encoded string, because a few bytes of +the string need to be read in order to compute the size. +.Pp +.Fn Base64Encode +and +.Fn Base64Decode +do the actual work of encoding and decoding base64 data. They both +take a string and its length. +.Pp +.Fn Base64Unpad +and +.Fn Base64Pad +are used to implement Matrix unpadded base64. +.Fn Base64Unpad +takes a valid base64 string and strips off the trailing equal signs, +as per the specification. +.Fn Base64Pad +does the opposite; it takes an unpadded base64 input string, and pads +it with equal signs as necessary, so that it can be properly decoded +with +.Fn Base64Decode +if necessary. However, the Matrix specification envisons unpadded base64 +as opaque; that is, once it's encoded, it never needs to be decoded. +In practice, a homeserver might need to decode an unpadded base64 string. +.Sh RETURN VALUES +.Fn Base64EncodedSize +and +.Fn Base64DecodedSize +simply return unsigned integers representing a number of bytes generated +from a simple computation. +.Pp +.Fn Base64Encode +and +.Fn Base64Decode +return pointers to new strings, allocated on the heap, or +.Dv NULL +if a heap allocation fails. These pointers must be +.Xr free 3 -ed +at some point when they are no longer needed. +.Pp +.Fn Base64Unpad +modifies the passed string in-place. It thus has no return value, because +it cannot fail. If the passed pointer is invalid, the behavior is undefined. +.Fn Base64Pad +returns a boolean value indicating whether the pad operation was successful. +In practice, this function will only fail if a bigger string is necessary, but +could not be automatically allocated on the heap. diff --git a/docs/telodendria.7 b/docs/telodendria.7 index 35a85a4..b48042b 100644 --- a/docs/telodendria.7 +++ b/docs/telodendria.7 @@ -1,4 +1,4 @@ -.Dd $Mdocdate: September 23 2022 $ +.Dd $Mdocdate: September 27 2022 $ .Dt TELODENDRIA 7 .Os Telodendria Project .Sh NAME @@ -88,10 +88,8 @@ up the data directory and you're good to go. .Sh PROJECT GOALS The goals of this project are generally divided into user goals and developer goals, depending on who they impact the most. This isn't an exaustive list -of -.Nm 's -goals, but it is a list of things that I want to prioritize, because other -server implementations lack them. +of the project's goals, but it is a list of things that I want to prioritize, +because other server implementations lack them. .sp The user goals are as follows: .Bl -bullet diff --git a/src/include/Base64.h b/src/include/Base64.h index 5f21263..428506e 100644 --- a/src/include/Base64.h +++ b/src/include/Base64.h @@ -22,133 +22,26 @@ * SOFTWARE. */ -/* - * Base64.h: An efficient base64 encoder and decoder that supports - * both regular base64, and the Matrix spec's "unpadded base64." - */ #ifndef TELODENDRIA_BASE64_H #define TELODENDRIA_BASE64_H #include -/* - * Compute the encoded size, including padding, of an input with the - * provided size. - * - * Params: - * - * (size_t) The size of the input data to be encoded. - * - * Return: The size of the string needed to hold the data in its - * encoded form. Note that base64 is not compression; base64 strings - * are actually 25% larger than the unencoded input. - */ extern size_t Base64EncodedSize(size_t); -/* - * Compute the decoded size of the provide base64 input and length. - * - * Note that both the size and the actual base64 string itself is - * needed for this computation, unlike Base64EncodedSize(). This is - * because base64 strings are padded, and that padding is used in the - * calculations. - * - * Params: - * - * (const char *) A padded base64 string. If you are dealing with - * potentially user-provided base64, you should call - * Base64Pad() on it to normalize it before computing - * the decoded size. - * (size_t) The length of the base64 string. Instead of scanning the - * string for a null terminator, and then working backwards, - * the length of the string must be passed here. - * - * Return: The number of bytes that can be decoded from this base64 - * string. Note that this will be smaller than the length of the base64 - * string because base64 is larger than the unencoded form. - */ extern size_t Base64DecodedSize(const char *, size_t); -/* - * Copy the given input string to a new string, base64 encoding it in - * the process. This function will produce standard padded base64. If - * you want unpadded base64, call Base64Unpad() on the return value - * of this function. - * - * Params: - * - * (const char *) The raw, unencoded input to be encoded as base64. - * (size_t) The length of the unencoded input string. - * - * Return: A new string, allocated on the heap, that holds the base64 - * representation of the input. This string must be free()-ed when it - * is no longer needed. If the allocation of the proper size fails, - * or the input is inaccessible, then this function will return NULL. - */ extern char * Base64Encode(const char *, size_t); -/* - * Decode a standard padded base64 string. This function expects that - * the input will be padded, so if you are recieving untrusted input, - * you should run Base64Pad() on it before attempting to decode it. - * - * Params: - * - * (const char *) The base64 string to decode. - * (size_t) The length of the base64 string to decode. - * - * Return: A new string, allocated on the heap, that contains the - * decoded string, or NULL if a decoding error occurred. - */ extern char * Base64Decode(const char *, size_t); -/* - * Remove the padding from a base64 string. This is to implement the - * Matrix spec's "unpadded base64" functionality. When base64 strings - * are sent to other servers and clients, their padding must be - * stripped. - * - * Params: - * - * (char *) The base64 string to remove padding from. Note that - * this string is modified in place. - * (size_t) The length of the provided base64 string. - * - */ extern void Base64Unpad(char *, size_t); -/* - * Pad a base64 string in place. This is to implement the Matrix spec's - * "unpadded base64." As we will most likely be getting unpadded base64 - * from clients and other servers, we should pad it before attempting - * to decode it. - * - * I technically could have just had the decoder accept unpadded as - * well as padded strings, but Matrix is the only thing I know of that - * actually makes "unpadded" base64 a thing, so I thought it best to - * make it clear in this library that unpadded base64 is an extension, - * not the norm. - * - * Params: - * - * (char **) A pointer to a base64 string pointer. The reason we - * take a pointer pointer is because the string may need - * to be reallocated, as characters may be added to the - * end of it. If the string is reallocated, then the - * passed pointer must be updated. If the string is not - * reallocated, the original pointer is not touched. - * (size_t) The length of the given base64 string. - * - * Return: Whether or not the pad operation was successful. This - * function will fail if a larger string cannot be allocated when it - * is needed. Note that not all cases require the string to be - * reallocated. - */ extern int Base64Pad(char **, size_t);