Base64 encoding/decoding

Modules
	Base64 format specifiers

Functions
bool	c4::base64_valid (const char *encoded, size_t encoded_sz)
	check that the given buffer is a valid base64 encoding More...
size_t	c4::base64_encode (char *encoded, size_t encoded_sz, void const *data, size_t data_sz)
	base64-encode binary data. More...
bool	c4::base64_decode (char const *encoded, size_t encoded_sz, void *data, size_t data_sz, size_t *data_sz_required)
	decode the base64 encoding in the given buffer. More...

Detailed Description

See also

https://en.wikipedia.org/wiki/Base64

https://www.base64encode.org/

Function Documentation

bool c4::base64_valid	(	const char *	encoded,
		size_t	encoded_sz
	)

check that the given buffer is a valid base64 encoding

See also

https://en.wikipedia.org/wiki/Base64

Definition at line 332 of file base64.cpp.

{
    if(!encoded_sz)
        return true;
    if((encoded_sz & size_t(3u))) // is it not a multiple of 4?
        return false;
    const char *C4_RESTRICT encoded = encoded_;
    size_t i = 0;
    #if C4_WORDSIZE >= 8
    for( ; i + 8 < encoded_sz; i += 8)
        if(!is_valid_encoded_group8_(encoded + i))
            return false;
    #endif
    for( ; i + 4 < encoded_sz; i += 4)
        if(!is_valid_encoded_group4_(encoded + i))
            return false;
    if(!is_valid_encoded_char_(encoded[i])
       || !is_valid_encoded_char_(encoded[i + 1]))
        return false;
    if(!is_valid_encoded_char_(encoded[i + 2]))
        return (encoded[i + 2] == '=' && encoded[i + 3] == '=');
    if(!is_valid_encoded_char_(encoded[i + 3]))
        return (encoded[i + 3] == '=');
    return true;
}

size_t c4::base64_encode	(	char *	encoded,
		size_t	encoded_sz,
		void const *	data,
		size_t	data_sz
	)

base64-encode binary data.

This is a plain implementation with a focus on simplicity and small footprint, such that it runs reasonably well in constrained platforms. On larger platforms it is reasonably fast (reaching 3GB/s and over), but it is not the fastest. If ultimate base64 speed in x64 platforms is your objective, there are faster implementations available. One recommendation is https://github.com/aklomp/base64, which uses a larger Look-Up Table (4096B as compared with 64B in c4core), making it between 1.5x~2x faster than c4core for larger payloads (but also slower for small payloads), and much faster when using AVX2 or AVX512 processing. But this speed comes at a cost in constrained platforms: eg c4core encodes ~2.5x faster in armv4 and armv5.

Parameters

encoded	[out] output buffer for encoded data
encoded_sz	[in] size of the output buffer for encoded data
data	[in] the input buffer with the binary data
data_sz	[in] size of the input buffer with the binary data

Returns

the number of bytes required for the output buffer. No writes occur beyond the end of the output buffer, so it is safe to do a speculative call where the encoded buffer is empty, or maybe too small. The caller should ensure that the returned size is smaller than the size of the encoded buffer.

Note

the result depends on endianness. If transfer between little/big endian systems is desired, the caller should normalize data before encoding.

See also

https://en.wikipedia.org/wiki/Base64

Referenced by c4::to_chars().

bool c4::base64_decode	(	char const *	encoded,
		size_t	encoded_sz,
		void *	data,
		size_t	data_sz,
		size_t *	data_sz_required
	)

decode the base64 encoding in the given buffer.

This is a plain implementation with a focus on simplicity and small footprint, such that it runs reasonably well in constrained platforms. On larger platforms it is reasonably fast, but it is not the fastest. If ultimate base64 speed in x64 platforms is your objective, there are faster implementations available. One recommendation is https://github.com/aklomp/base64, which uses up to 16x larger Look-Up Tables, making it between 1.5x~2x faster than c4core (but also slower for small payloads), and much faster when using AVX2 or AVX512 processing. But this x64 speed comes at a cost in constrained platforms: eg c4core decodes ~4x faster in armv4 and armv5.

Parameters

encoded	[in] the encoded base64
encoded_sz	[in] the size of the encoded buffer
data	[out] the output decoded buffer
data_sz	[in] the size of the output decoded buffer
data_sz_required	[out] the size required for the output decoded buffer, ie, the number of bytes needed to return the output (ie the required size for data). No writes occur beyond the end of the output buffer, so it is safe to do a speculative call where the data buffer is empty, or maybe too small. The caller should ensure that this value is smaller than data_sz.

Returns

false if the encoding was invalid or the data size was too small, and true otherwise.

Note

the result depends on endianness. If transfer between little/big endian systems is desired, the caller should normalize data after decoding.

See also

https://en.wikipedia.org/wiki/Base64

Definition at line 412 of file base64.cpp.

Referenced by c4::from_chars().

{
    C4_ASSERT(encoded_ != nullptr || encoded_sz == 0);
    C4_ASSERT(data_ != nullptr || data_sz == 0);
    C4_ASSERT(data_sz_required != nullptr);
    if(!encoded_sz)
    {
        *data_sz_required = 0;
        return true;
    }
    else if(encoded_sz & 3u) // is encoded_sz not a multiple of 4?
    {
        return false;
    }
    // compute the required size for the decoded buffer:
    //                  ................ how many 4-byte groups of encoded data to decode
    //                                  .... each group results in 3 decoded bytes
    *data_sz_required = (encoded_sz / 4) * 3;
    const char *C4_RESTRICT encoded = encoded_;
    // account for padded bytes at the end
    C4_ASSERT(encoded_sz >= 4);
    if(encoded[encoded_sz - 1] == '=')
    {
        C4_ASSERT(*data_sz_required >= 3);
        if(encoded[encoded_sz - 2] == '=')
            *data_sz_required -= 2;
        else
            *data_sz_required -= 1;
    }
    if(data_sz < *data_sz_required)
        return false;
    // we have enough room
    size_t rem = *data_sz_required; // numbytes remaining to write
    dectype *C4_RESTRICT data = (dectype *)data_;
    C4_STATIC_ASSERT(sizeof(dectype) == 1);
#if (C4_WORDSIZE >= 8)
    for( ; rem >= 15; rem -= 12)
    {
        if C4_UNLIKELY(!is_valid_encoded_group16_(encoded, 16))
            return false;
        base64_decode_block64_(encoded, data); encoded += 8; data += 6;
        base64_decode_block64_(encoded, data); encoded += 8; data += 6;
    }
    for( ; rem >= 9; rem -= 6)
    {
        if C4_UNLIKELY(!is_valid_encoded_group8_(encoded))
            return false;
        base64_decode_block64_(encoded, data); encoded += 8; data += 6;
    }
#else
    for( ; rem >= 9; rem -= 6)
    {
        if C4_UNLIKELY(!is_valid_encoded_group8_(encoded))
            return false;
        base64_decode_block32_(encoded, data); encoded += 4; data += 3;
        base64_decode_block32_(encoded, data); encoded += 4; data += 3;
    }
#endif
    for( ; rem >= 3; rem -= 3)
    {
        if C4_UNLIKELY(!is_valid_encoded_group4_(encoded))
            return false;
        base64_decode_block32_(encoded, data); encoded += 4; data += 3;
    }
    C4_ASSERT(rem < 3);
    // the last quartet requires dealing with padded chars
    if(rem == 1) // 1 remaining byte, 2 padding chars
    {
        if(!is_valid_encoded_char_(encoded[0])
           || !is_valid_encoded_char_(encoded[1])
           || encoded[2] != '='
           || encoded[3] != '=')
            return false;
        base64_decode_block32_term1_(encoded, data);
    }
    else if(rem == 2) // 2 remaining bytes, 1 padding char
    {
        if(!is_valid_encoded_char_(encoded[0])
           || !is_valid_encoded_char_(encoded[1])
           || !is_valid_encoded_char_(encoded[2])
           || encoded[3] != '=')
            return false;
        base64_decode_block32_term2_(encoded, data);
    }
    return true;
}