le_base64.h

    1 /**
    2  * @page c_base64 Base64 encoding/decoding API
    3  *
    4  * @subpage le_base64.h "API Reference"
    5  *
    6  * <HR>
    7  *
    8  * This module implements encoding binary data into base64-encoded string, which contains only
    9  * the characters that belong to the base64 alphabet:
   10  * ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/=
   11  *
   12  * This allows to convert the binary data into a form that is suitable for serialization
   13  * into a text file (without conflicting with special characters and markup elements),
   14  * and for sending through the channels that do not support arbitrary binary data.
   15  *
   16  * Encoded data is about 33% larger in size than the original binary data. Padding characters '='
   17  * are added to the end of the encoded string, to make the string length multiple of 4.
   18  *
   19  * The following sample performs base64 encoding and decoding:
   20  *
   21  * @code
   22  *
   23  * void Base64EncodeDecodeExample
   24  * (
   25  *     void
   26  * )
   27  * {
   28  *     // allocate 4-byte array and fill it with some data
   29  *     uint8_t binBuf[4] = {1, 2, 3, 4};
   30  *     // use macro to calculate the encoded size, add 1 byte for terminating 0
   31  *     char encodedBuf[LE_BASE64_ENCODED_SIZE(sizeof(binBuf)) + 1];
   32  *     uint8_t decodedBuf[4] = {0};
   33  *
   34  *     // perform encoding
   35  *     size_t len = sizeof(encodedBuf);
   36  *     le_result_t result = le_base64_Encode(binBuf,
   37  *                                           sizeof(binBuf),
   38  *                                           encodedBuf,
   39  *                                           &len);
   40  *     if (LE_OK != result)
   41  *     {
   42  *         LE_ERROR("Error %d encoding data!", result);
   43  *     }
   44  *     LE_INFO("Encoded string [%s] size %zd", encodedBuf, len);
   45  *
   46  *     // perform decoding
   47  *     len = sizeof(decodedBuf);
   48  *     result = le_base64_Decode(encodedBuf,
   49  *                               strlen(encodedBuf),
   50  *                               decodedBuf,
   51  *                               &len);
   52  *     if (LE_OK != result)
   53  *     {
   54  *         LE_ERROR("Error %d decoding data!", result);
   55  *     }
   56  *     LE_INFO("Decoded length: %zd", len);
   57  *     LE_INFO("Decoded data: %u %u %u %u",
   58  *              decodedBuf[0], decodedBuf[1],
   59  *              decodedBuf[2], decodedBuf[3]);
   60  * }
   61  * @endcode
   62  *
   63  * <HR>
   64  *
   65  * Copyright (C) Sierra Wireless Inc.
   66  *
   67  */
   68 
   69 //--------------------------------------------------------------------------------------------------
   70 /** @file le_base64.h
   71  *
   72  * Legato @ref c_base64 include file.
   73  *
   74  * Copyright (C) Sierra Wireless Inc.
   75  */
   76 //--------------------------------------------------------------------------------------------------
   77 
   78 #ifndef LEGATO_BASE64_INCLUDE_GUARD
   79 #define LEGATO_BASE64_INCLUDE_GUARD
   80 
   81 //--------------------------------------------------------------------------------------------------
   82 /**
   83  * Calculate the encoded string length (including padding, not including terminating zero)
   84  * for a given binary data size.
   85  */
   86 //--------------------------------------------------------------------------------------------------
   87 #define LE_BASE64_ENCODED_SIZE(x) (4 * ((x + 2) / 3))
   88 
   89 //--------------------------------------------------------------------------------------------------
   90 /**
   91  * Perform base64 data encoding.
   92  *
   93  * @return
   94  *      - LE_OK if succeeds
   95  *      - LE_BAD_PARAMETER if NULL pointer provided
   96  *      - LE_OVERFLOW if provided buffer is not large enough
   97  */
   98 //--------------------------------------------------------------------------------------------------
   99 le_result_t le_base64_Encode
  100 (
  101     const uint8_t *dataPtr,     ///< [IN] Data to be encoded
  102     size_t dataLength,          ///< [IN] Data length
  103     char *resultPtr,            ///< [OUT] Base64-encoded string buffer
  104     size_t *resultSizePtr       ///< [INOUT] Length of the base64-encoded string buffer
  105 );
  106 
  107 //--------------------------------------------------------------------------------------------------
  108 /**
  109  * Decode base64-encoded data.
  110  *
  111  * @return
  112  *      - LE_OK if succeeds
  113  *      - LE_BAD_PARAMETER if NULL pointer provided
  114  *      - LE_FORMAT_ERROR if data contains invalid (non-base64) characters
  115  *      - LE_OVERFLOW if provided buffer is not large enough
  116  */
  117 //--------------------------------------------------------------------------------------------------
  118 le_result_t le_base64_Decode
  119 (
  120     const char *srcPtr, ///< [IN] Encoded string
  121     size_t srcLen,      ///< [IN] Encoded string length
  122     uint8_t *dstPtr,    ///< [OUT] Binary data buffer
  123     size_t *dstLenPtr   ///< [INOUT] Binary data buffer size / decoded data size
  124 );
  125 
  126 #endif // LEGATO_BASE64_INCLUDE_GUARD
le_result_t
le_result_t
Definition: le_basics.h:46
le_base64_Encode
le_result_t le_base64_Encode(const uint8_t *dataPtr, size_t dataLength, char *resultPtr, size_t *resultSizePtr)
le_base64_Decode
le_result_t le_base64_Decode(const char *srcPtr, size_t srcLen, uint8_t *dstPtr, size_t *dstLenPtr)