ota_base64.c File Reference

Implements a Base64 decoding routine. More...

#include "ota_base64_private.h"
#include <assert.h>

Macros
#define	NEWLINE   64U
	Number to represent both line feed and carriage return symbols in the pBase64SymbolToIndexMap table.
#define	WHITESPACE   65U
	Number to represent the whitespace character in the pBase64SymbolToIndexMap table.
#define	PADDING_SYMBOL   66U
	Number to represent the Base64 padding symbol in the pBase64SymbolToIndexMap table.
#define	NON_BASE64_INDEX   67U
	Number to represent values that are invalid in the pBase64SymbolToIndexMap table.
#define	VALID_BASE64_SYMBOL_INDEX_RANGE_MAX   63U
	Maximum value for a Base64 index that represents a valid, non-formatting Base64 symbol.
#define	SEXTET_SIZE   6
	Number of bits in a sextet.
#define	MAX_NUM_BASE64_DATA   4U
	Maximum number of Base64 symbols to store in a buffer before decoding them.
#define	MAX_EXPECTED_NUM_PADDING   2
	Maximum number of padding symbols in a string of encoded data that is considered valid.
#define	MIN_VALID_ENCODED_DATA_SIZE   2U
	Smallest amount of data that can be Base64 encoded is a byte. Encoding a single byte of data results in 2 bytes of encoded data. Therefore if the encoded data is smaller than 2 bytes, there is an error with the data.
#define	SIZE_OF_ONE_OCTET   8U
	The number of bits in a single octet.
#define	SIZE_OF_TWO_OCTETS   16U
	The number of bits in two octets.
#define	SIZE_OF_PADDING_WITH_TWO_SEXTETS   4
	The number of padding bits that are present when there are two sextets of encoded data.
#define	SIZE_OF_PADDING_WITH_THREE_SEXTETS   2
	The number of padding bits that are present when there are three sextets of encoded data.
#define	SYMBOL_TO_INDEX_MAP_VALUE_UPPER_BOUND   67U
	Inclusive upper bound for valid values that can be contained in pBase64SymbolToIndexMap.
#define	BASE64_INDEX_VALUE_UPPER_BOUND   63U
	Inclusive upper bound for the range of valid Base64 index values.

Functions
static Base64Status_t	preprocessBase64Index (uint8_t base64Index, int64_t *pNumPadding, int64_t *pNumWhitespace)
	Validates the input Base64 index based on the context of what has been decoded so far and the value of the index. Updates the input counters that are used to keep track of the number of whitespace and padding symbols that have been parsed so far. More...
static void	updateBase64DecodingBuffer (const uint8_t base64Index, uint32_t *pBase64IndexBuffer, uint32_t *pNumDataInBuffer)
	Add a Base64 index to a Base64 index buffer. The buffer will only be updated if the index represents a Base64 digit. More...
static Base64Status_t	decodeBase64IndexBuffer (uint32_t *pBase64IndexBuffer, uint32_t *pNumDataInBuffer, uint8_t *pDest, const size_t destLen, size_t *pOutputLen)
	Decode a buffer containing two, three, or four Base64 indices. More...
Base64Status_t	base64Decode (uint8_t *pDest, const size_t destLen, size_t *pResultLen, const uint8_t *pEncodedData, const size_t encodedLen)
	Decode Base64 encoded data. More...

Variables
static const uint8_t	pBase64SymbolToIndexMap []
	This table takes is indexed by an Ascii character and returns the respective Base64 index. The Ascii character used to index into this table is assumed to represent a symbol in a string of Base64 encoded data. There are three kinds of possible ascii characters: 1) Base64 Symbols. These are the digits of a Base 64 number system. 2) Formatting characters. These are newline, whitespace, and padding. 3) Symbols that are impossible to have inside of correctly Base64 encoded data. More...

Detailed Description

Implements a Base64 decoding routine.

Function Documentation

preprocessBase64Index()

static Base64Status_t preprocessBase64Index ( uint8_t  base64Index, int64_t *  pNumPadding, int64_t *  pNumWhitespace  )

static

Validates the input Base64 index based on the context of what has been decoded so far and the value of the index. Updates the input counters that are used to keep track of the number of whitespace and padding symbols that have been parsed so far.

Parameters

[in]	base64Index	Base64 index that can have on of the values listed in pBase64SymbolToIndexMap. This index represents the value of a valid Base64 symbol, a number to identify it as a formatting symbol, or a number to identify it as an invalid symbol.
[in,out]	pNumPadding	Pointer to the number of padding symbols that are present before the input Base64 index in the encoded data. This number is incremented if the input symbol is a padding symbol.
[in,out]	pNumWhitespace	Pointer to the number of whitespace symbols that are present before the input Base64 index in the encoded data. This number is incremented if the input symbol is a whitespace symbol.

Returns

One of the following:

• Base64Success if the Base64 encoded data was valid and successfully decoded.
• An error code defined in ota_base64_private.h if the encoded data or input parameters are invalid.

updateBase64DecodingBuffer()

static void updateBase64DecodingBuffer ( const uint8_t  base64Index, uint32_t *  pBase64IndexBuffer, uint32_t *  pNumDataInBuffer  )

static

Add a Base64 index to a Base64 index buffer. The buffer will only be updated if the index represents a Base64 digit.

Parameters

[in]	base64Index	Base64 index that can have one of the values listed in pBase64SymbolToIndexMap.
[in,out]	pBase64IndexBuffer	Pointer to a 32 bit variable that contains Base64 indexes that will be decoded.
[in,out]	pNumDataInBuffer	Pointer to the number of sextets that are stored in pBase64IndexBuffer. This will be incremented if base64Index is stored in pBase64IndexBuffer.

decodeBase64IndexBuffer()

static Base64Status_t decodeBase64IndexBuffer ( uint32_t *  pBase64IndexBuffer, uint32_t *  pNumDataInBuffer, uint8_t *  pDest, const size_t  destLen, size_t *  pOutputLen  )

static

Decode a buffer containing two, three, or four Base64 indices.

Parameters

[in,out]	pBase64IndexBuffer	Pointer to a 32 bit variable that contains Base64 indexes that will be decoded. Each index is represented by a sextet in the buffer.
[in,out]	pNumDataInBuffer	Pointer to the number of sextets (indexes) that are concatenated and stored in pBase64IndexBuffer. This will be set to zero before this function returns.
[out]	pDest	Pointer to a buffer used for storing the decoded data.
[in]	destLen	Length of the pDest buffer.
[in,out]	pOutputLen	Pointer to the index of pDest where the output should be written.

Returns

One of the following:

• Base64Success if the Base64 encoded data was valid and successfully decoded.
• An error code defined in ota_base64_private.h if the encoded data or input parameters are invalid.

base64Decode()

Base64Status_t base64Decode	(	uint8_t *	pDest,
		const size_t	destLen,
		size_t *	pResultLen,
		const uint8_t *	pEncodedData,
		const size_t	encodedLen
	)

Decode Base64 encoded data.

Parameters

[out]	pDest	Pointer to a buffer for storing the decoded result.
[in]	destLen	Length of the pDest buffer.
[out]	pResultLen	Pointer to the length of the decoded result.
[in]	pEncodedData	Pointer to a buffer containing the Base64 encoded data that is intended to be decoded.
[in]	encodedLen	Length of the pEncodedData buffer.

Returns

One of the following:

• Base64Success if the Base64 encoded data was valid and successfully decoded.
• An error code defined in ota_base64_private.h if the encoded data or input parameters are invalid.

Variable Documentation

pBase64SymbolToIndexMap

const uint8_t pBase64SymbolToIndexMap[]

static

Initial value:

=
{
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    64, 67, 67, 64, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 65, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 62, 67, 67, 67, 63, 52, 53,
    54, 55, 56, 57, 58, 59, 60, 61, 67, 67,
    67, 66, 67, 67, 67, 0,  1,  2,  3,  4,
    5,  6,  7,  8,  9,  10, 11, 12, 13, 14,
    15, 16, 17, 18, 19, 20, 21, 22, 23, 24,
    25, 67, 67, 67, 67, 67, 67, 26, 27, 28,
    29, 30, 31, 32, 33, 34, 35, 36, 37, 38,
    39, 40, 41, 42, 43, 44, 45, 46, 47, 48,
    49, 50, 51, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67, 67, 67, 67, 67,
    67, 67, 67, 67, 67, 67
}

This table takes is indexed by an Ascii character and returns the respective Base64 index. The Ascii character used to index into this table is assumed to represent a symbol in a string of Base64 encoded data. There are three kinds of possible ascii characters: 1) Base64 Symbols. These are the digits of a Base 64 number system. 2) Formatting characters. These are newline, whitespace, and padding. 3) Symbols that are impossible to have inside of correctly Base64 encoded data.

This table assumes that the padding symbol is the Ascii character '='

Valid Base64 symbols will have an index ranging from 0-63. The Base64 digits being used are "ABCDEFGHIJKLMNOPQRSTUVWXYabcdefghijklmnopqrstuvwxyz0123456789+/" where 'A' is the 0th index of the Base64 symbols and '/' is the 63rd index.

Outside of the numbers 0-63, there are magic numbers in this table:

• The 11th entry in this table has the number 64. This is to identify the ascii character '
  ' as a newline character.
• The 14th entry in this table has the number 64. This is to identify the ascii character '\r' as a newline character.
• The 33rd entry in this table has the number 65. This is to identify the ascii character ' ' as a whitespace character.
• The 62nd entry in this table has the number 66. This is to identify the ascii character '=' as the padding character.
• All positions in the ascii table that are invalid symbols are identified with the number 67 (other than '
  ','\r',' ','=').