qcbor_main_decode.h

Go to the documentation of this file.

/* ===========================================================================
 * qcbor_main_decode.h -- The main CBOR decoder.
 *
 * Copyright (c) 2016-2018, The Linux Foundation.
 * Copyright (c) 2018-2024, Laurence Lundblade.
 * Copyright (c) 2021, Arm Limited.
 * All rights reserved.
 *
 * Redistribution and use in source and binary forms, with or without
 * modification, are permitted provided that the following conditions are
 * met:
 *     * Redistributions of source code must retain the above copyright
 *       notice, this list of conditions and the following disclaimer.
 *     * Redistributions in binary form must reproduce the above
 *       copyright notice, this list of conditions and the following
 *       disclaimer in the documentation and/or other materials provided
 *       with the distribution.
 *     * Neither the name of The Linux Foundation nor the names of its
 *       contributors, nor the name "Laurence Lundblade" may be used to
 *       endorse or promote products derived from this software without
 *       specific prior written permission.
 *
 * THIS SOFTWARE IS PROVIDED "AS IS" AND ANY EXPRESS OR IMPLIED
 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
 * MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NON-INFRINGEMENT
 * ARE DISCLAIMED.  IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS
 * BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
 * CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
 * SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR
 * BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
 * WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE
 * OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN
 * IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * ========================================================================= */
 
#ifndef qcbor_main_decode_h
#define qcbor_main_decode_h
 
 
#include "qcbor/qcbor_common.h"
#include "qcbor/qcbor_private.h"
#include <stdbool.h>
 
 
#ifdef __cplusplus
extern "C" {
#if 0
} /* Keep editor indention formatting happy */
#endif
#endif
 
 
typedef enum {
   QCBOR_DECODE_MODE_NORMAL = 0,
 
   QCBOR_DECODE_MODE_MAP_STRINGS_ONLY = 0x01,
 
   QCBOR_DECODE_MODE_MAP_AS_ARRAY = 0x02,
 
   QCBOR_DECODE_ALLOW_UNPROCESSED_TAG_NUMBERS = 0x04,
 
   QCBOR_DECODE_NO_INDEF_LENGTH = 0x08,
 
   QCBOR_DECODE_ONLY_PREFERRED_NUMBERS = 0x10,
 
   QCBOR_DECODE_ONLY_PREFERRED_BIG_NUMBERS = 0x20,
 
   QCBOR_DECODE_ONLY_SORTED_MAPS = 0x40,
 
   QCBOR_DECODE_ONLY_REDUCED_FLOATS = 0x80,
 
   QCBOR_DECODE_DISALLOW_DCBOR_SIMPLES = 0x100,
 
   QCBOR_DECODE_MODE_PREFERRED = QCBOR_DECODE_NO_INDEF_LENGTH |
                                 QCBOR_DECODE_ONLY_PREFERRED_NUMBERS |
                                 QCBOR_DECODE_ONLY_PREFERRED_BIG_NUMBERS,
 
   QCBOR_DECODE_MODE_CDE = QCBOR_DECODE_MODE_PREFERRED |
                           QCBOR_DECODE_ONLY_SORTED_MAPS,
 
   QCBOR_DECODE_MODE_DCBOR = QCBOR_DECODE_MODE_CDE |
                             QCBOR_DECODE_ONLY_REDUCED_FLOATS |
                             QCBOR_DECODE_DISALLOW_DCBOR_SIMPLES,
 
} QCBORDecodeMode;
 
 
 
#define QCBOR_MAX_DECODE_INPUT_SIZE (UINT32_MAX - 2)
 
#define QCBOR_MAX_TAGS_PER_ITEM QCBOR_MAX_TAGS_PER_ITEM1
 
 
 
/* Do not renumber these. Code depends on some of these values. */
#define QCBOR_TYPE_NONE           0
 
#define QCBOR_TYPE_ANY            1
 
#define QCBOR_TYPE_INT64          2
 
#define QCBOR_TYPE_UINT64         3
 
#define QCBOR_TYPE_ARRAY          4
 
#define QCBOR_TYPE_MAP            5
 
#define QCBOR_TYPE_BYTE_STRING    6
 
#define QCBOR_TYPE_TEXT_STRING    7
 
#define QCBOR_TYPE_POSBIGNUM      9
 
#define QCBOR_TYPE_NEGBIGNUM     10
 
#define QCBOR_TYPE_DATE_STRING   11
 
#define QCBOR_TYPE_DATE_EPOCH    12
 
#define QCBOR_TYPE_UKNOWN_SIMPLE 13
 
#define QCBOR_TYPE_DECIMAL_FRACTION            14
 
#define QCBOR_TYPE_DECIMAL_FRACTION_POS_BIGNUM 15
 
#define QCBOR_TYPE_DECIMAL_FRACTION_NEG_BIGNUM 16
 
#define QCBOR_TYPE_DECIMAL_FRACTION_POS_U64    79
 
#define QCBOR_TYPE_DECIMAL_FRACTION_NEG_U64    80
 
#define QCBOR_TYPE_BIGFLOAT                    17
 
#define QCBOR_TYPE_BIGFLOAT_POS_BIGMANTISSA    18
#define QCBOR_TYPE_BIGFLOAT_POS_BIGNUM         18
 
#define QCBOR_TYPE_BIGFLOAT_NEG_BIGMANTISSA    19
#define QCBOR_TYPE_BIGFLOAT_NEG_BIGNUM         19
 
#define QCBOR_TYPE_BIGFLOAT_POS_U64MANTISSA    82
 
#define QCBOR_TYPE_BIGFLOAT_NEG_U64MANTISSA    83
 
#define QCBOR_TYPE_FALSE         20
 
#define QCBOR_TYPE_TRUE          21
 
#define QCBOR_TYPE_NULL          22
 
#define QCBOR_TYPE_UNDEF         23
 
#define QCBOR_TYPE_FLOAT         26
 
#define QCBOR_TYPE_DOUBLE        27
 
#define QCBOR_TYPE_65BIT_NEG_INT 28
 
#define QCBOR_TYPE_BREAK         31
 
#define QCBOR_TYPE_MAP_AS_ARRAY  32
 
#define QBCOR_TYPE_WRAPPED_CBOR  36
 
#define QCBOR_TYPE_URI           44
 
#define QCBOR_TYPE_BASE64URL     45
 
#define QCBOR_TYPE_BASE64        46
 
#define QCBOR_TYPE_REGEX         47
 
#define QCBOR_TYPE_MIME          48
 
#define QCBOR_TYPE_UUID          49
 
#define QBCOR_TYPE_WRAPPED_CBOR_SEQUENCE  75
 
#define QCBOR_TYPE_BINARY_MIME   76
 
#define QCBOR_TYPE_DAYS_STRING   77
 
#define QCBOR_TYPE_DAYS_EPOCH    78
 
/* 79, 80, 82, 83 is used above for decimal fraction and big float */
 
 
#define QCBOR_TYPE_TAG_NUMBER 127
 
#define QCBOR_TYPE_START_USER_DEFINED 128
 
#define QCBOR_TYPE_END_USER_DEFINED 255
 
 
#define QCBOR_LAST_UNMAPPED_TAG (CBOR_TAG_INVALID16 - QCBOR_NUM_MAPPED_TAGS - 1)
 
 
typedef struct  {
   int64_t nExponent;
   union {
      int64_t    nInt;
      uint64_t   uInt;
      UsefulBufC bigNum;
   } Mantissa;
} QCBORExpAndMantissa;
 
 
 
typedef struct _QCBORItem {
   uint8_t  uDataType;
 
   uint8_t  uLabelType;
 
   uint8_t  uNestingLevel;
 
   uint8_t  uNextNestLevel;
 
   uint8_t  uDataAlloc;
 
   uint8_t  uLabelAlloc;
 
   union {
      int64_t     int64;
      uint64_t    uint64;
      UsefulBufC  string;
      uint16_t    uCount;
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
      double      dfnum;
      float       fnum;
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
      struct {
         int64_t  nSeconds;
#ifndef USEFULBUF_DISABLE_ALL_FLOAT
         double   fSecondsFraction;
#endif /* USEFULBUF_DISABLE_ALL_FLOAT */
      } epochDate;
 
      int64_t     epochDays;
 
      UsefulBufC  bigNum;
 
      uint8_t     uSimple;
 
#ifndef QCBOR_DISABLE_EXP_AND_MANTISSA
      QCBORExpAndMantissa expAndMantissa;
#endif /* ! QCBOR_DISABLE_EXP_AND_MANTISSA */
 
      uint64_t    uTagNumber; /* Used internally during decoding */
 
      /* For use by user-defined tag content handlers */
      uint8_t     userDefined[24];
   } val;
 
   union {
      int64_t     int64;
#ifndef QCBOR_DISABLE_NON_INTEGER_LABELS
      uint64_t    uint64;
      UsefulBufC  string;
#endif /* ! QCBOR_DISABLE_NON_INTEGER_LABELS */
   } label;
 
#ifndef QCBOR_DISABLE_TAGS
   QCBORMappedTagNumbers auTagNumbers;
#endif
} QCBORItem;
 
#define QCBOR_COUNT_INDICATES_INDEFINITE_LENGTH UINT16_MAX
 
 
 
 
typedef UsefulBuf (* QCBORStringAllocate)(void   *pAllocateCxt,
                                          void   *pOldMem,
                                          size_t  uNewSize);
 
 
#define QCBOR_DECODE_MIN_MEM_POOL_SIZE 8
 
 
 
 
typedef struct _QCBORDecodeContext QCBORDecodeContext;
 
 
void
QCBORDecode_Init(QCBORDecodeContext *pCtx, UsefulBufC EncodedCBOR, QCBORDecodeMode uConfigFlags);
 
 
QCBORError
QCBORDecode_SetMemPool(QCBORDecodeContext *pCtx,
                       UsefulBuf           MemPool,
                       bool                bAllStrings);
 
 
#ifndef QCBOR_DISABLE_INDEFINITE_LENGTH_STRINGS
static void
QCBORDecode_SetUpAllocator(QCBORDecodeContext *pCtx,
                           QCBORStringAllocate pfAllocateFunction,
                           void               *pAllocateContext,
                           bool                bAllStrings);
 
#endif /* ! QCBOR_DISABLE_INDEFINITE_LENGTH_STRINGS */
 
void
QCBORDecode_VGetNext(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
 
 
QCBORError
QCBORDecode_GetNext(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
 
 
void
QCBORDecode_VGetNextConsume(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
 
 
void
QCBORDecode_VPeekNext(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
 
 
QCBORError
QCBORDecode_PeekNext(QCBORDecodeContext *pCtx, QCBORItem *pDecodedItem);
 
 
static uint32_t
QCBORDecode_Tell(QCBORDecodeContext *pCtx);
 
 
QCBORError
QCBORDecode_EndCheck(QCBORDecodeContext *pCtx);
 
 
 
QCBORError
QCBORDecode_Finish(QCBORDecodeContext *pCtx);
 
 
QCBORError
QCBORDecode_PartialFinish(QCBORDecodeContext *pCtx, size_t *puConsumed);
 
 
static UsefulBufC
QCBORDecode_RetrieveUndecodedInput(QCBORDecodeContext *pCtx);
 
 
static QCBORError
QCBORDecode_GetError(QCBORDecodeContext *pCtx);
 
 
static QCBORError
QCBORDecode_GetAndResetError(QCBORDecodeContext *pCtx);
 
 
static bool
QCBORDecode_IsNotWellFormedError(QCBORError uErr);
 
 
static bool
QCBORDecode_IsUnrecoverableError(QCBORError uErr);
 
 
static void
QCBORDecode_SetError(QCBORDecodeContext *pCtx, QCBORError uError);
 
 
 
 
/* ========================================================================= *
 *    BEGINNING OF DEPRECATED FUNCTIONS                                      *
 *                                                                           *
 *    There is no plan to remove these in future versions.                   *
 *    They just have been replaced by something better.                      *
 * ========================================================================= */
 
void
QCBORDecode_CompatibilityV1(QCBORDecodeContext *pCtx);
 
 
/* ========================================================================= *
 *    END OF DEPRECATED FUNCTIONS                                            *
 * ========================================================================= */
 
 
 
 
/* ========================================================================= *
 *    BEGINNING OF PRIVATE AND INLINE IMPLEMENTATION                         *
 * ========================================================================= */
 
QCBORError
QCBORDecode_Private_GetNextTagContent(QCBORDecodeContext *pMe,
                                      QCBORItem          *pDecodedItem);
 
 
uint64_t
QCBORDecode_Private_UnMapTagNumber(const QCBORDecodeContext *pMe,
                                   const uint16_t            uMappedTagNumber);
 
QCBORError
QCBORDecode_Private_ConsumeItem(QCBORDecodeContext *pMe,
                                const QCBORItem    *pItemToConsume,
                                bool               *pbBreak,
                                uint8_t            *puNextNestLevel);
 
QCBORError
QCBORDecode_Private_GetItemChecks(QCBORDecodeContext *pMe,
                                  QCBORError          uErr,
                                  const size_t        uOffset,
                                  QCBORItem          *pDecodedItem);
 
QCBORError
QCBORDecode_Private_NestLevelAscender(QCBORDecodeContext *pMe,
                                      bool                bMarkEnd,
                                      bool               *pbBreak);
 
#ifndef QCBOR_DISABLE_INDEFINITE_LENGTH_STRINGS
static inline void
QCBORDecode_SetUpAllocator(QCBORDecodeContext *pMe,
                           QCBORStringAllocate pfAllocateFunction,
                           void               *pAllocateContext,
                           bool                bAllStrings)
{
   pMe->StringAllocator.pfAllocator   = pfAllocateFunction;
   pMe->StringAllocator.pAllocateCxt  = pAllocateContext;
   pMe->bStringAllocateAll            = bAllStrings;
}
#endif /* ! QCBOR_DISABLE_INDEFINITE_LENGTH_STRINGS */
 
 
static inline uint32_t
QCBORDecode_Tell(QCBORDecodeContext *pMe)
{
   if(pMe->uLastError) {
      return UINT32_MAX;
   }
 
   /* Cast is safe because decoder input size is restricted. */
   return (uint32_t)UsefulInputBuf_Tell(&(pMe->InBuf));
}
 
static inline UsefulBufC
QCBORDecode_RetrieveUndecodedInput(QCBORDecodeContext *pMe)
{
   return UsefulInputBuf_RetrieveUndecodedInput(&(pMe->InBuf));
}
 
static inline QCBORError
QCBORDecode_GetError(QCBORDecodeContext *pMe)
{
    return (QCBORError)pMe->uLastError;
}
 
static inline QCBORError
QCBORDecode_GetAndResetError(QCBORDecodeContext *pMe)
{
    const QCBORError uReturn = (QCBORError)pMe->uLastError;
    pMe->uLastError = QCBOR_SUCCESS;
    return uReturn;
}
 
static inline bool
QCBORDecode_IsNotWellFormedError(const QCBORError uErr)
{
   if(uErr >= QCBOR_START_OF_NOT_WELL_FORMED_ERRORS &&
      uErr <= QCBOR_END_OF_NOT_WELL_FORMED_ERRORS) {
      return true;
   } else {
      return false;
   }
}
 
static inline bool
QCBORDecode_IsUnrecoverableError(const QCBORError uErr)
{
   if(uErr >= QCBOR_START_OF_UNRECOVERABLE_DECODE_ERRORS &&
      uErr <= QCBOR_END_OF_UNRECOVERABLE_DECODE_ERRORS) {
      return true;
   } else {
      return false;
   }
}
 
 
static inline void
QCBORDecode_SetError(QCBORDecodeContext *pMe, QCBORError uError)
{
   pMe->uLastError = (uint8_t)uError;
}
 
 
static inline void
QCBORDecode_Private_SaveTagNumbers(QCBORDecodeContext *pMe, const QCBORItem *pItem)
{
#ifndef QCBOR_DISABLE_TAGS
   memcpy(pMe->auLastTagNumbers,
          pItem->auTagNumbers,
          sizeof(pItem->auTagNumbers));
#else /* ! QCBOR_DISABLE_TAGS */
   (void)pMe;
   (void)pItem;
#endif /* ! QCBOR_DISABLE_TAGS */
}
 
static inline void
QCBORDecode_Private_GetAndTell(QCBORDecodeContext *pMe, QCBORItem *Item, size_t *uOffset)
{
#ifndef QCBOR_DISABLE_TAGS
   if(pMe->uLastError != QCBOR_SUCCESS) {
      return;
   }
 
   *uOffset = QCBORDecode_Tell(pMe);
#else /* ! QCBOR_DISABLE_TAGS */
   *uOffset = SIZE_MAX;
 
#endif /* ! QCBOR_DISABLE_TAGS */
   pMe->uLastError = (uint8_t)QCBORDecode_Private_GetNextTagContent(pMe, Item);
}
 
 
/* ======================================================================== *
 *    END OF PRIVATE INLINE IMPLEMENTATION                                  *
 * ======================================================================== */
 
 
 
 
/* A few cross checks on size constants and special value lengths */
#if  QCBOR_MAP_OFFSET_CACHE_INVALID < QCBOR_MAX_DECODE_INPUT_SIZE
#error QCBOR_MAP_OFFSET_CACHE_INVALID is too large
#endif
 
#if QCBOR_NON_BOUNDED_OFFSET < QCBOR_MAX_DECODE_INPUT_SIZE
#error QCBOR_NON_BOUNDED_OFFSET is too large
#endif
 
#ifdef __cplusplus
}
#endif
 
#endif /* qcbor_main_decode_h */