From 24cd62a415161c2851327e96a023b47bb0897e64 Mon Sep 17 00:00:00 2001 From: Laurence Lundblade Date: Wed, 6 Nov 2024 11:02:19 -0800 Subject: [PATCH] Small big number documentation fixes (#269) Co-authored-by: Laurence Lundblade --- inc/qcbor/qcbor_common.h | 5 ++--- inc/qcbor/qcbor_encode.h | 32 +++++++++++++++++++++++--------- inc/qcbor/qcbor_spiffy_decode.h | 9 +++++++-- 3 files changed, 32 insertions(+), 14 deletions(-) diff --git a/inc/qcbor/qcbor_common.h b/inc/qcbor/qcbor_common.h index 1b9a843e..0027cf95 100644 --- a/inc/qcbor/qcbor_common.h +++ b/inc/qcbor/qcbor_common.h @@ -405,10 +405,9 @@ typedef enum { * this error is returned. This error is unrecoverable because the * built-in tag decoding doesn't try to consume the unexpected * type. In previous versions of QCBOR this was considered a - * recoverable error hence @ref QCBOR_ERR_BAD_TAG_CONTENT. Going + * recoverable error hence QCBOR_ERR_BAD_TAG_CONTENT. Going * back further, RFC 7049 use the name "optional tags". That name - * is no longer used because "optional" was causing confusion. See - * also @ref QCBOR_ERR_RECOVERABLE_BAD_TAG_CONTENT. */ + * is no longer used because "optional" was causing confusion. */ QCBOR_ERR_UNRECOVERABLE_TAG_CONTENT = 48, QCBOR_ERR_BAD_TAG_CONTENT = 48, QCBOR_ERR_BAD_OPT_TAG = 48, diff --git a/inc/qcbor/qcbor_encode.h b/inc/qcbor/qcbor_encode.h index f7252171..cf88754f 100644 --- a/inc/qcbor/qcbor_encode.h +++ b/inc/qcbor/qcbor_encode.h @@ -369,6 +369,8 @@ extern "C" { * - The maximum tag nesting is @c QCBOR_MAX_TAGS_PER_ITEM (typically 4). * - Works only on 32- and 64-bit CPUs. * - QCBORDecode_EnterBstrWrapped() doesn't work on indefinite-length strings. + * - Numeric reduction of big numbers to integers for preferred + * serialization is not performed. * * The public interface uses @c size_t for all lengths. Internally the * implementation uses 32-bit lengths by design to use less memory and @@ -987,9 +989,9 @@ QCBOREncode_AddTBinaryUUIDToMapN(QCBOREncodeContext *pCtx, * (https://www.rfc-editor.org/rfc/rfc8949.html#section-3.4.3). No * processing, such as removal of leading zeros, is perfomed. * - * Sometimes big numbers are used to represent parts of cryptographic - * keys, however, COSE which defines representations for keys does, - * not use this particular type. + * RFC 8949 preferred serialization requires big numbers that + * will fit in integers be encoded as integers. That is NOT + * performed. */ static void QCBOREncode_AddTPositiveBignum(QCBOREncodeContext *pCtx, @@ -1026,6 +1028,10 @@ QCBOREncode_AddTPositiveBignumToMapN(QCBOREncodeContext *pCtx, * (https://www.rfc-editor.org/rfc/rfc8949.html#section-3.4.3). No * processing, such as removal of leading zeros or the required offset * of 1 for negative values, is perfomed. + * + * RFC 8949 preferred serialization requires big numbers that + * will fit in integers be encoded as integers. That is NOT + * performed. */ static void QCBOREncode_AddTNegativeBignum(QCBOREncodeContext *pCtx, @@ -1055,7 +1061,7 @@ QCBOREncode_AddTNegativeBignumToMapN(QCBOREncodeContext *pCtx, * @param[in] nMantissa The mantissa. * @param[in] nBase10Exponent The exponent. * - * The value is nMantissa * 10 ^ nBase10Exponent. + * The value is @c nMantissa * 10 ^ @c nBase10Exponent. * * A decimal fraction is good for exact representation of some values * that can't be represented exactly with standard C (IEEE 754) @@ -1074,8 +1080,8 @@ QCBOREncode_AddTNegativeBignumToMapN(QCBOREncodeContext *pCtx, * support this range to reduce code size and interface complexity a * little). * - * CBOR Preferred serialization of the integers is used, thus they - * will be encoded in the smallest number of bytes possible. + * Preferred serialization is used when the mantissa or exponent are + * integers, thus they will be encoded in the smallest number of bytes. * * See also QCBOREncode_AddTDecimalFractionBigNum() for a decimal * fraction with arbitrarily large precision and @@ -1121,6 +1127,10 @@ QCBOREncode_AddTDecimalFractionToMapN(QCBOREncodeContext *pCtx, * mantissa is a big number (See QCBOREncode_AddTPositiveBignum()) * allowing for arbitrarily large precision. * + * RFC 8949 preferred serialization requires reduction of big numbers + * that can fit into integers be encoded as integers, not big numbers. + * This implementation does NOT do that. + * * See @ref expAndMantissa for decoded representation. */ static void @@ -1155,7 +1165,7 @@ QCBOREncode_AddTDecimalFractionBigNumToMapN(QCBOREncodeContext *pCtx, * @param[in] nMantissa The mantissa. * @param[in] nBase2Exponent The exponent. * - * The value is nMantissa * 2 ^ nBase2Exponent. + * The value is @c nMantissa * 2 ^ @c nBase2Exponent. * * "Bigfloats", as CBOR terms them, are similar to IEEE floating-point * numbers in having a mantissa and base-2 exponent, but they are not @@ -1175,8 +1185,8 @@ QCBOREncode_AddTDecimalFractionBigNumToMapN(QCBOREncodeContext *pCtx, * support this range to reduce code size and interface complexity a * little). * - * CBOR preferred serialization of the integers is used, thus they will - * be encoded in the smallest number of bytes possible. + * Preferred serialization is used when the mantissa or exponent are + * integers, thus they will be encoded in the smallest number of bytes. * * This can also be used to represent floating-point numbers in * environments that don't support IEEE 754. @@ -1219,6 +1229,10 @@ QCBOREncode_AddTBigFloatToMapN(QCBOREncodeContext *pCtx, * is a big number (See QCBOREncode_AddTPositiveBignum()) allowing for * arbitrary precision. * + * RFC 8949 preferred serialization requires reduction of big numbers + * that can fit into integers be encoded as integers, not big numbers. + * This implementation does NOT do that. + * * See @ref expAndMantissa for decoded representation. */ static void diff --git a/inc/qcbor/qcbor_spiffy_decode.h b/inc/qcbor/qcbor_spiffy_decode.h index dcb03f39..48e3bbd2 100644 --- a/inc/qcbor/qcbor_spiffy_decode.h +++ b/inc/qcbor/qcbor_spiffy_decode.h @@ -1421,6 +1421,12 @@ QCBORDecode_GetEpochDaysInMapSZ(QCBORDecodeContext *pCtx, * leaves it up to the caller to apply this computation for negative * big numbers. * + * RFC 8949 preferred serialization requires that big numbers + * that fit into integers be encoded as integers. This function + * will error if the input CBOR is a type 0 or 1 integers. A + * future version of QCBOR fixes this, but in the mean time + * the application must handle this manually. + * * See @ref Tag-Usage for discussion on tag requirements. * * Determination of the sign of the big number depends on the tag @@ -1438,7 +1444,6 @@ QCBORDecode_GetEpochDaysInMapSZ(QCBORDecodeContext *pCtx, * QCBOREncode_AddTPositiveBignum(), QCBOREncode_AddTNegativeBignum(), * @ref QCBOR_TYPE_POSBIGNUM and @ref QCBOR_TYPE_NEGBIGNUM. */ -// Improvement: Add function that converts integers and other to big nums void QCBORDecode_GetBignum(QCBORDecodeContext *pCtx, uint8_t uTagRequirement, @@ -1558,7 +1563,7 @@ QCBORDecode_GetDecimalFractionInMapSZ(QCBORDecodeContext *pMe, * For QCBOR before v1.5, this function had a bug where * by the negative mantissa sometimes had the offset of * one applied, making this function somewhat usless for - * negative mantissas. Specifically if the to-be-decode CBOR + * negative mantissas. Specifically if the to-be-decoded CBOR * was a type 1 integer the offset was applied and when it * was a tag 3, the offset was not applied. It is possible * that a tag 3 could contain a value in the range of a type 1