forked from lda/telodendria
Move Base64 documentation to man page.
This commit is contained in:
parent
5ecb810a88
commit
acffd82b48
4 changed files with 88 additions and 114 deletions
|
|
@ -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
|
||||
|
|
|
|||
81
docs/Base64.3
Normal file
81
docs/Base64.3
Normal file
|
|
@ -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.
|
||||
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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 <stddef.h>
|
||||
|
||||
/*
|
||||
* 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);
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue