CBOR W. McNally, Ed. Internet-Draft Blockchain Commons Intended status: Standards Track 4 November 2025 Expires: 8 May 2026 A CBOR Tag for Lossless Transport of IEEE-754 NaN Bit Patterns draft-mcnally-cbor-nan-bstr-01 Abstract IEEE-754 NaN formations are not numbers and have no equivalence class. They are not comparable to anything, including reflexively, and therefore each attribute - sign bit, signaling/quiet bit, payload bits, and representation width (binary16, binary32, binary64, binary128) - can carry meaning for an implementation. CBOR permits encoding NaNs as floating-point values, but generic processing, preferred serialization, and deterministic profiles may canonicalize or otherwise alter NaN encodings, losing information. This document defines a CBOR tag, colloquially "nan-bstr", whose content is a byte string carrying the exact IEEE-754 NaN bit pattern so that all attributes are preserved across encode/decode, enabling use cases like NaN boxing, platform-specific error signaling, diagnostics, and forensics. About This Document This note is to be removed before publishing as an RFC. Status information for this document may be found at https://datatracker.ietf.org/doc/draft-mcnally-cbor-nan-bstr/. Discussion of this document takes place on the CBOR Working Group mailing list (mailto:cbor@ietf.org), which is archived at https://mailarchive.ietf.org/arch/browse/cbor/. Subscribe at https://www.ietf.org/mailman/listinfo/cbor/. Source for this draft and an issue tracker can be found at https://github.com/BlockchainCommons/draft-mcnally-cbor-nan-bstr. Status of This Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. McNally Expires 8 May 2026 [Page 1] Internet-Draft nan-bstr November 2025 Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at https://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." This Internet-Draft will expire on 8 May 2026. Copyright Notice Copyright (c) 2025 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/ license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Revised BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Revised BSD License. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Conventions and Definitions . . . . . . . . . . . . . . . . . 3 3. Motivation and Rationale . . . . . . . . . . . . . . . . . . 3 4. The nan-bstr Tag . . . . . . . . . . . . . . . . . . . . . . 4 4.1. Semantics . . . . . . . . . . . . . . . . . . . . . . . . 4 4.2. Validity . . . . . . . . . . . . . . . . . . . . . . . . 4 4.3. Deterministic Encoding and Preferred Serialization . . . 4 4.4. Interoperability with Deterministic Rules and dCBOR . . . 4 5. Examples and Diagnostic Notation . . . . . . . . . . . . . . 5 6. CDDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6 7. Security Considerations . . . . . . . . . . . . . . . . . . . 6 8. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 6 9. Implementation Notes . . . . . . . . . . . . . . . . . . . . 6 10. Alternatives Considered . . . . . . . . . . . . . . . . . . . 7 11. References . . . . . . . . . . . . . . . . . . . . . . . . . 7 11.1. Normative References . . . . . . . . . . . . . . . . . . 7 11.2. Informative References . . . . . . . . . . . . . . . . . 7 Appendix A. Implementation Status . . . . . . . . . . . . . . . 8 A.1. Rust Implementation . . . . . . . . . . . . . . . . . . . 8 Appendix B. Acknowledgments . . . . . . . . . . . . . . . . . . 9 McNally Expires 8 May 2026 [Page 2] Internet-Draft nan-bstr November 2025 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 9 1. Introduction CBOR defines an extensible binary format with semantic tags (major type 6) that can ascribe additional meaning to enclosed data items ([RFC8949]). While CBOR's floating-point types can encode NaN values, encoders and application profiles commonly canonicalize NaNs or collapse them to a single preferred representation. For applications that rely on specific NaN formations, this behavior is unacceptable. This specification defines a single CBOR tag that wraps a CBOR byte string (bstr) containing 2, 4, 8, or 16 octets representing the big-endian bit pattern of a single IEEE-754 NaN (binary16/32/64/128). The tag enables exact round-tripping of NaN attributes independent of the policies that an ecosystem applies to floating-point numbers. 2. Conventions and Definitions The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all capitals, as shown here. 3. Motivation and Rationale IEEE-754 purposefully leaves NaNs incomparable and allows implementations to use sign, signaling/quiet, and payload bits for implementation-defined purposes ([IEEE754]). When CBOR encoders perform preferred serialization or when deterministic profiles constrain encodings for predictability (see [RFC8949], Section 4.2), the precise NaN formation can be lost. A narrowly scoped tag that treats a NaN as an opaque bit pattern avoids interfering with numeric semantics while providing an explicit, interoperable mechanism to preserve all attributes. This mechanism addresses concrete needs: (1) NaN boxing schemes use NaN payload space to embed tagged values and pointers; preserving those bits across transports is essential ([JSC-NaNBox]). (2) Some profiles, such as dCBOR, intentionally allow only a single canonical NaN and reject others to maximize determinism; those ecosystems still benefit from an explicit escape hatch when a precise NaN must be preserved ([I-D.mcnally-deterministic-cbor]). (3) Other communities canonicalize NaNs for determinism (for example, WebAssembly discussions), illustrating the tension between reproducibility and information retention ([WASM-NaN]). See also prior CBOR WG threads that discussed NaN handling and determinism ([CBOR-WG-NaN-Threads]). A tag solves the transport problem without weakening profile policies McNally Expires 8 May 2026 [Page 3] Internet-Draft nan-bstr November 2025 for ordinary numeric values. 4. The nan-bstr Tag 4.1. Semantics The nan-bstr tag denotes that its content is a CBOR byte string whose bytes are, in network byte order (big-endian), the bit pattern of a single IEEE-754 NaN in one of the three interchange widths: 2 bytes (binary16), 4 bytes (binary32), 8 bytes (binary64), or 16 bytes (binary128). The tag does not change IEEE-754 NaN semantics: it does not define equality or ordering for NaNs. A tagged NaN is not a CBOR floating-point number; it is an opaque bit pattern that an application MAY convert to a native NaN when desired, acknowledging that the conversion could lose information if the platform cannot represent signaling NaNs or payload bits. 4.2. Validity A decoder that understands this tag MUST enforce all of the following: (1) The enclosed bstr length is exactly 2, 4, 8, or 16. (2) The bytes are interpreted in network byte order, consistent with CBOR's encoding of multi-byte values ([RFC8949]). (3) The bit pattern is a NaN for the indicated width (that is, exponent is all ones and the significand/fraction field is non-zero per [IEEE754]). (4) No normalization or canonicalization of the payload, sign bit, signaling/quiet bit, or width is performed by the tag processing itself. If any check fails, the decoder MUST treat the tagged value as invalid for this tag and handle it per application error policy. 4.3. Deterministic Encoding and Preferred Serialization CBOR's preferred serialization and deterministically encoded CBOR rules ([RFC8949], Section 4.2) apply to the tag and to the bstr's container (for example, definite length), not to the content bytes themselves. The content of the bstr is application-defined and MUST be preserved exactly. When an application needs exact preservation of a NaN, the sender SHOULD use this tag in place of a floating-point NaN literal. 4.4. Interoperability with Deterministic Rules and dCBOR Deterministic rules often restrict or canonicalize floating-point representations to ensure byte-for-byte stability. For example, the dCBOR rules allows only a single canonical NaN formation (half-width value with CBOR representation 0xf97e00) and rejects others ([I-D.mcnally-deterministic-cbor]). The output of deterministic rule sets can still carry non-canonical NaNs by allowing this tag: McNally Expires 8 May 2026 [Page 4] Internet-Draft nan-bstr November 2025 encoders emit nan-bstr when exact NaN preservation is required and emit the canonical NaN otherwise. This keeps deterministic rules for numbers intact while providing a precise transport for exceptional cases. 5. Examples and Diagnostic Notation The requested tag number for this specification is 102. Diagnostic notation shows tags in decimal by default. The following table presents examples for each supported width: +===========+================================+============+=========+ | Width | Description | Diagnostic |CBOR | | | | Notation |Encoding | | | | |(hex) | +===========+================================+============+=========+ | binary16 | Half-precision quiet NaN | 102( |D866 42 | | | (0x7E00) | h'7E00' ) |7E00 | +-----------+--------------------------------+------------+---------+ | binary32 | Single-precision quiet NaN | 102( |D866 44 | | | with payload 0x000001 | h'7FC0 |7FC0 | | | | 0001' ) |0001 | +-----------+--------------------------------+------------+---------+ | binary64 | Double-precision signaling NaN | 102( |D866 48 | | | with payload 0x00000000000001 | h'FFF0 |FFF0 | | | and sign bit set | 0000 0000 |0000 | | | | 0001' ) |0000 | | | | |0001 | +-----------+--------------------------------+------------+---------+ | binary128 | Quad-precision quiet NaN with | 102( |D866 50 | | | payload | h'7FFF |7FFF | | | 0x0000000000000000000000000001 | 8000 0000 |8000 | | | | 0000 0000 |0000 | | | | 0000 0000 |0000 | | | | 0001' ) |0000 | | | | |0000 | | | | |0000 | | | | |0001 | +-----------+--------------------------------+------------+---------+ Table 1 In all cases, the content preserves sign, signaling/quiet, payload bits, and width exactly; applications that cannot natively represent a formation still retain the bit pattern for pass-through or later analysis. McNally Expires 8 May 2026 [Page 5] Internet-Draft nan-bstr November 2025 6. CDDL The following CDDL ([RFC8610]) defines the tagged value. nan-bstr = #6.102 (bstr .size (2 / 4 / 8 / 16)) 7. Security Considerations Treat the bstr as untrusted input. A decoder MUST validate NaN well- formedness for the indicated width. Implementations MUST avoid triggering floating-point exceptions when merely transporting the bit pattern. Because payload bits can carry platform-specific metadata, applications should consider confidentiality and integrity requirements when transporting tagged NaNs. The tag restricts size to 2/4/8 bytes and introduces no variable-length resource concerns beyond those of CBOR bstr handling ([RFC8949]). 8. IANA Considerations IANA is requested to register one new entry in the CBOR Tags registry ([IANA-CBOR-TAGS]) using the template of [RFC8949], Section 9.2. * Tag: 102 (Specification Required range). * Data item: byte string. * Semantics: IEEE-754 NaN encoded as a 2, 4, 8, or 16 octet byte string (nan-bstr). * Reference: This document. 9. Implementation Notes This section is non-normative. * Encoders SHOULD use definite-length bstrs. * Decoders SHOULD expose APIs that surface width, sign, signaling/ quiet, and payload without mutating bits. * Implementations SHOULD avoid using nan-bstr values as map keys because NaN equivalence is undefined; generic CBOR guidance on key equivalence applies ([RFC8949]). * Rules that otherwise canonicalize floating-point NaNs can retain those rules and treat nan-bstr as the explicit mechanism for exact preservation when needed. McNally Expires 8 May 2026 [Page 6] Internet-Draft nan-bstr November 2025 10. Alternatives Considered This section is non-normative. The CBOR Tags registry defines tags 80-87 for various permutations of "IEEE 754 binary, , Typed Array" ([IANA-CBOR-TAGS]). These tags may be used to preserve exact bit patterns of floating-point values, including NaNs. However, they do not connote the special semantics of NaNs, such as incomparability and payload significance. Using those tags for NaNs could mislead implementers into treating tagged values as ordinary numbers, risking unintended comparisons or arithmetic. A dedicated nan-bstr tag clarifies intent and avoids semantic confusion. 11. References 11.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, DOI 10.17487/RFC2119, March 1997, . [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, May 2017, . [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data Definition Language (CDDL): A Notational Convention to Express Concise Binary Object Representation (CBOR) and JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, June 2019, . [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", STD 94, RFC 8949, DOI 10.17487/RFC8949, December 2020, . 11.2. Informative References [CBOR-WG-NaN-Threads] "CBOR WG mailing list threads on NaN and determinism", n.d., . [I-D.mcnally-deterministic-cbor] McNally, W., Allen, C., Bormann, C., and L. Lundblade, "dCBOR: Deterministic CBOR", Work in Progress, Internet- McNally Expires 8 May 2026 [Page 7] Internet-Draft nan-bstr November 2025 Draft, draft-mcnally-deterministic-cbor-14, 1 November 2025, . [IANA-CBOR-TAGS] "Concise Binary Object Representation (CBOR) Tags Registry", n.d., . [IEEE754] "IEEE Standard for Floating-Point Arithmetic", IEEE Std 754-2019, n.d., . [JSC-NaNBox] "JavaScriptCore NaN Boxing exercise", n.d., . [RFC7942] Sheffer, Y. and A. Farrel, "Improving Awareness of Running Code: The Implementation Status Section", BCP 205, RFC 7942, DOI 10.17487/RFC7942, July 2016, . [WASM-NaN] "WebAssembly issue", n.d., . Appendix A. Implementation Status This section records the status of known implementations of the protocol defined by this specification at the time of publication, and is based on a proposal described in [RFC7942]. The description of implementations in this section is intended to assist the IETF in its decision processes in progressing drafts to RFCs. Please note that the listing of any individual implementation here does not imply endorsement by the IETF. Furthermore, no effort has been spent to verify the information presented here that was supplied by IETF contributors. This is not intended as, and must not be construed to be, a catalog of available implementations or their features. Readers are advised to note that other implementations may exist. A.1. Rust Implementation Organization: Blockchain Commons Name: cbor-nan-bstr-rust McNally Expires 8 May 2026 [Page 8] Internet-Draft nan-bstr November 2025 Description: A Rust implementation providing encoding and decoding support for CBOR tag 102 (nan-bstr). The implementation includes functions to encode IEEE-754 NaN bit patterns as CBOR byte strings and decode them back, preserving all NaN attributes including sign, signaling/quiet bit, payload bits, and width. Level of Maturity: Development Coverage: The implementation covers encoding and decoding of all four supported widths (binary16, binary32, binary64, binary128) with full validation of NaN bit patterns. Version Compatibility: This implementation is compatible with the current draft specification. Licensing: BSD-2-Clause-Patent Implementation Experience: No issues have been encountered during development. The implementation demonstrates that the tag provides a practical mechanism for exact NaN preservation across CBOR encode/ decode cycles. Contact: Wolf McNally (wolf@wolfmcnally.com) URL: https://github.com/BlockchainCommons/cbor-nan-bstr-rust Appendix B. Acknowledgments Thanks to CBOR WG participants for discussion of determinism and floating-point edge cases, and to implementers who documented NaN canonicalization and processing behavior across platforms. Author's Address Wolf McNally (editor) Blockchain Commons Email: wolf@wolfmcnally.com McNally Expires 8 May 2026 [Page 9]