carb::extras::Base64

class Base64

Encoder and decoder helper for Base64 data.

This allows for processing Base64 data in multiple different standard and non-standard variants of the algorithm, plus custom encodings. Padding bytes are always optional but will be generated by default by all non-custom variants. A custom variant without padding bytes can be specified by setting the padding byte to 0. No data verification is done on decoded data - that is left up to the caller. Any invalid input data is simply ignored.

Public Types

enum class Variant

Various variants of the Base64 algorithm.

The only differences these cause in the generated encoded data are in the bytes used for the values 62 and 63, as well as the padding byte. All other encoded values will always use A-Z, a-z, and 0-9. The correct variant must also be known ahead of time when decoding data. No auto-detection on the input data will be done. For most applications, the Variant::eDefault and Variant::eFilenameSafe variants should be the most useful.

Values:

enumerator eDefault: Default encoding set.

enumerator ePem: Encoding set for privacy-enhanced mail (RFC 1421, deprecated).

enumerator eMime: Encoding set for standard MIME Base64 (RFC 2045).

enumerator eRfc4648: Encoding set for RFC 4648.

enumerator eFilenameSafe: Encoding set for URL and filename safe Base64 (RFC 4648, section 5).

enumerator eOpenPgp: Encoding set for OpenPGP (RFC 4880).

enumerator eUtf7: Encoding set for UTF-7 (RFC 2152).

enumerator eImap: Encoding set for IMAP mailbox names (RFC 3501).

enumerator eYui: Encoding set for Y64 URL-sage Base64 from the YUI library.

enumerator eProgramId1: Encoding set for Program identifier Base64 variant 1 (non-standard).

enumerator eProgramId2: Encoding set for Program identifier Base64 variant 2 (non-standard).

enumerator eFreenetUrl: Encoding set for Freenet URL-safe Base64 (non-standard).

Public Functions

inline Base64(): Constructor: creates a new object supporting the default Base64 encoding.

inline Base64(Variant variant)

Constructor: creates a new object supporting a specific known Base64 encoding.

Parameters: variant – [in] The algorithm variant to use. This controls which additional two encoding bytes and which padding byte will be used. The variant specifics about line lengths, checksums, and optional versus mandatory padding will be ignored.

inline Base64(uint8_t byte62, uint8_t byte63, uint8_t padding = 0)

Constructor: creates a new object supporting a custom Base64 encoding.

Parameters

byte62 – [in] The byte that will be used to represent the encoding for the value 62 (0x3e). This may be any non-zero byte outside of the ranges [A-Z, a-z, 0-9]. This may not be equal to byte63 or padding.
byte63 – [in] The byte that will be used to represent the encoding for the value 63 (0x3f). This may be any non-zero byte outside of the ranges [A-Z, a-z, 0-9]. This may not be equal to byte62 or padding.
padding – [in] The padding byte to use at the end of an encoded block to identify an unaligned block. This may be 0 to indicate that no specific padding byte is used. This may not be equal to byte62 or byte63 and must not be in the range [A-Z, a-z, 0-9]. The usual padding byte for this value in most variants is ‘=’. This defaults to 0.

inline size_t encode(const void *buffer, size_t size, char *output, size_t maxOut)

Encodes a block of binary data into Base64.

Note

If the encoded data block is expected to be transmitted to a generic destination (ie: one not controlled by this process or something related to it), the caller is responsible for ensuring that the data can be properly interpreted by the receiver regardless of endianness. Since base64 encoding simply sees the block of data as a simple string of bytes, it has no knowledge of any internal structure and can therefore not properly do an kind of network byte order swapping. The caller would be the one with the knowledge of internal structure and should byte swap the incoming data as needed before attempting to encode it.

Parameters

buffer – [in] The input buffer to be encoded. This may not be nullptr.
size – [in] The size of the input buffer in bytes. This may not be 0. This may be kNullTerminated to indicate that the input data is a null terminated C string. The actual length of the input will be calculated by finding the length of the string.
output – [out] Receives the encoded output as long as it is large enough to contain the entire encoded output. No work will be done if the output buffer is not large enough. Encoding into the same buffer as buffer is not safe since the input data will be overwritten as it is processed resulting in a corrupted encoding. This output buffer will always be null terminated so that the output data can be processed as a standard C string.
maxOut – [in] The size of the output buffer in bytes. This may be larger than is strictly required by the encoding operation. This must be large enough to hold the entire encoded result.

Returns

The number of bytes of encoded data written to the output buffer, not including the null terminator. Note that this byte count may not be aligned to a multiple of 4 if padding is ignored (ie: this object was initialized to use a padding byte of 0).

Returns

0 if the output buffer is not large enough to hold the full encoded output.

inline size_t decode(const char *buffer, size_t size, void *output, size_t maxOut)

Decodes a block of binary data from Base64.

Note

This will decode the block exactly as it was encoded and assuming a little endian byte ordering. Since base64 always treats the data block as a simple string of bytes, the caller is responsible for doing any kind of endianness checks and byte swapping as necessary after decoding.

Parameters

buffer – [in] The input buffer to be decoded. This may not be nullptr. This buffer may be optionally null terminated.
size – [in] The size of the input buffer in bytes. This may not be 0. This may be kNullTerminated to indicate that the input buffer is a null terminated C string. In this case, the length of the input buffer will be calculated as the length of the string.
output – [out] Receives the decoded data as long as it is large enough to contain the entire decoded output. No work will be done if the output buffer is not large enough. Decoding into the same buffer as buffer is safe since the input data will be always be longer than the output. No null terminator or extra data will ever be written to the decoded data buffer.
maxOut – [in] The size of the output buffer in bytes. This may be larger than is strictly required by the decoding operation. This must be large enough to hold the entire decoded result.

Returns

The number of bytes of decoded data written to the output buffer. Note that this byte count will not have a particular alignment and will always match that of the original encoded data exactly.

Returns

0 if the output buffer is not large enough to hold the full decoded output.

Public Static Functions

static inline size_t getEncodeOutputSize(size_t inputSize)

Calculates the required output size for encoding a given number of bytes.

Parameters: inputSize – [in] The size of the input buffer in bytes. This may not be 0.
Returns: The number of bytes required to store the encoded data for the given input size. This will always include space for a null terminator byte so that the encoded data can always be treated as a C string for further processing. The actual size of the encoded data should always come from the value returned by encode().

static inline size_t getEncodeInputSize(size_t outputSize)

Calculates the require input buffer size for a given output buffer length.

Parameters: outputSize – [in] The size of the output to write.
Returns: The number of bytes that needs to be input to produce a given output size without padding. This is useful if you want to split up a base64 encode across multiple buffers. Breaking up the input into a series of chunks of this size will allow the output base64 chunks to be concatenated together without creating an invalid base64 string.

static inline size_t getDecodeOutputSize(size_t inputSize)

Calculates the required output size for decoding a given number of bytes.

Parameters: inputSize – [in] The size of the input buffer in bytes. This may not be 0.
Returns: The number of bytes required to store the decoded data for the given input size. This may include some extra space depending on whether the input buffer is null terminated or not. The actual size of the decoded data should always come from the value returned by decode().

Public Static Attributes

static constexpr size_t kNullTerminated = ~0ull

Special value for the size parameters to encode() and decode() to indicate that the input data buffer is a null terminated string.

This is only safe on encode() if the input to be encoded is known to be a standard C string. If binary data is provided to be encoded, an explicit size must always be given. On decode(), this value should only be used if the encoded data being passed as input is known to be null terminated. encoded data produced by this object will always be null terminated.