AWS IoT Over-the-air Update  v2.0.0 (Release Candidate)
Client library for AWS IoT OTA
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]base64IndexBase64 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]pNumPaddingPointer 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]pNumWhitespacePointer 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]base64IndexBase64 index that can have one of the values listed in pBase64SymbolToIndexMap.
[in,out]pBase64IndexBufferPointer to a 32 bit variable that contains Base64 indexes that will be decoded.
[in,out]pNumDataInBufferPointer 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]pBase64IndexBufferPointer 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]pNumDataInBufferPointer to the number of sextets (indexes) that are concatenated and stored in pBase64IndexBuffer. This will be set to zero before this function returns.
[out]pDestPointer to a buffer used for storing the decoded data.
[in]destLenLength of the pDest buffer.
[in,out]pOutputLenPointer 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]pDestPointer to a buffer for storing the decoded result.
[in]destLenLength of the pDest buffer.
[out]pResultLenPointer to the length of the decoded result.
[in]pEncodedDataPointer to a buffer containing the Base64 encoded data that is intended to be decoded.
[in]encodedLenLength 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',' ','=').