Network Working Group M. Uruena Internet-Draft D. Larrabeiti Expires: March 12, 2008 UC3M September 09, 2007 eXtensible Binary Encoding (XBE32) Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that other groups may also distribute working documents as Internet- Drafts. 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." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. This Internet-Draft will expire on March 12, 2008. Copyright Notice Copyright (C) The IETF Trust (2007). Uruena & Larrabeiti Expires March 12, 2008 [Page 1] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 Abstract This document defines the eXtensible Binary Encoding (XBE32). It has been designed to serialize hierarchical data with a compact and extensible format. XBE32 elements are binary-encoded inside Type- Length-Value (TLV) structures, that are aligned to 32-bit words in order to be easily processed by computers. XBE32 is NOT a binary encoding for XML documents, but a serialization format for small, lightweight network protocols. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1.1. Notation Conventions . . . . . . . . . . . . . . . . . . . 3 2. Common TLV Format . . . . . . . . . . . . . . . . . . . . . . 4 2.1. Unspecified Length . . . . . . . . . . . . . . . . . . . . 6 3. XBE32 TLVs . . . . . . . . . . . . . . . . . . . . . . . . . . 7 3.1. Complex TLVs with inner TLVs . . . . . . . . . . . . . . . 7 3.2. Simple TLV with one variable-length Value . . . . . . . . 8 3.3. Simple TLVs with 1-Octet Values . . . . . . . . . . . . . 8 3.4. Simple TLV with 2-Octets Values . . . . . . . . . . . . . 9 3.5. Simple TLVs with 4-Octets Values . . . . . . . . . . . . . 9 3.6. Simple TLVs with 8-Octets Values . . . . . . . . . . . . . 10 3.7. Simple TLVs with 12-Octets Values . . . . . . . . . . . . 10 3.8. Simple TLVs with 16-Octets Values . . . . . . . . . . . . 11 3.9. Opaque TLV Values . . . . . . . . . . . . . . . . . . . . 12 3.10. String TLV Value . . . . . . . . . . . . . . . . . . . . . 12 3.11. Boolean TLV Values . . . . . . . . . . . . . . . . . . . . 12 3.12. Integer TLV Values . . . . . . . . . . . . . . . . . . . . 13 3.13. Floating point TLV Values . . . . . . . . . . . . . . . . 13 4. XBE32 Elements . . . . . . . . . . . . . . . . . . . . . . . . 14 4.1. Compact Elements . . . . . . . . . . . . . . . . . . . . . 14 4.2. Extensible Elements: Extensible Names and Identifiers . . 15 4.3. Extensible Complex Elements . . . . . . . . . . . . . . . 16 4.4. Extensible Attribute Elements . . . . . . . . . . . . . . 16 5. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 18 6. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 Appendix A. XBE32 Example . . . . . . . . . . . . . . . . . . . . 19 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 20 Intellectual Property and Copyright Statements . . . . . . . . . . 21 Uruena & Larrabeiti Expires March 12, 2008 [Page 2] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 1. Introduction Nowadays, the most popular format to represent hierarchical structured information is the eXtensible Markup Language (XML), and it has been employed by multiple network protocols and applications. Although its textual representation allows protocols to be extensible, and eases development and debugging, it could require more bandwidth and processing than a binary counterpart. This document defines the eXtensible Binary Encoding (XBE32), a simple binary encoding for network protocols that carry hierarchical data. XBE32 Elements are serialized inside TLV structures which are 32-bit aligned to ease the parsing process. As data is clearly delimited, XBE32 does not require to escape characters as XML does, thus it also eases message creation. XBE32 TLVs have a 2-octets long Type and Length fields. Therefore, XBE32 is well suited for simple protocols with short messages and a small set of identifiers. However, in order to be extensible, XBE32 Elements may also have variable-length names or longer binary identifiers. Moreover, XBE32 may support TLVs with an "unspecified" length in order to encode big messages, and to start sending a message before its total length is known. There are two kinds of XBE32 Elements: "Attribute Elements" which carry primitive data values, and "Complex Elements" which are not able to carry data by themselves but contain other Attributes and/or other Complex Elements. In order to be employed by modern programming languages, XBE32 employs common primitive data types for its Attribute Elements, such as Strings, Booleans, Integers, Floats, as well as Arrays. Other data types can be encoded using the different binary Opaque value types defined by XBE32. 1.1. Notation Conventions The keywords MUST, MUST NOT, REQUIRED, SHALL, SHALL NOT, SHOULD, SHOULD NOT, RECOMMENDED, NOT RECOMMENDED, MAY, and OPTIONAL, when they appear in this document, are to be interpreted as described in RFC2119 [1]. Uruena & Larrabeiti Expires March 12, 2008 [Page 3] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 2. Common TLV Format XBE32 Elements are encoded inside Type-Length-Value (TLV) structures, that MUST be aligned to 4-octet words. XBE32 TLVs could be: "Simple" TLVs if they carry primitive data values, or "Complex" ones if they contain other TLVs. In any case, all XBE32 TLVs MUST have the following format: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type | Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : Values : : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : | [ Padding ] | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Type (16 bits): This field describes the processing rules, TLV structure and what kind of data is carried inside the Values field. The Type field has the following internal structure: 0 1 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |C|E| Meta | Subtype | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ C and E bits (1 bit each): These two bits specify the measures that must be taken if the XBE32 processing entity does not recognize this Type value: C - Continue Processing: 0 - Discard this mandatory TLV and stop processing TLVs left 1 - Skip this optional TLV and continue processing next TLV E - Notify Error: 0 - Do not report to the sender that this Type is unknown. 1 - Report to the sender that this Type is unknown. Uruena & Larrabeiti Expires March 12, 2008 [Page 4] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 Meta (6 bits): This subfield describes the internal structure of the TLV's Values field, as well as the type of the primitive data it contains: Type.Meta TLV Values structure --------- ------------------------------------ 0x00-0x1F Multiple variable-length TLVs 0x20 Single variable-length opaque Value 0x21 Single variable-length string Value 0x24 Multiple opaque1 Values 0x25 Multiple int8 Values 0x26 Multiple boolean Values 0x28 Multiple opaque2 Values 0x29 Multiple int16 Values 0x2C Multiple opaque4 Values 0x2D Multiple int32 Values 0x2E Multiple float32 Values 0x30 Multiple opaque8 Values 0x31 Multiple int64 Values 0x32 Multiple float64 Values 0x34 Multiple opaque12 Values 0x38 Multiple opaque16 Values The unlisted values are reserved by XBE32 and SHOULD NOT be employed. Subtype (8 bits): This subfield identifies the semantic meaning of this TLV and/or the data carried inside its Values field. Therefore, Subtype values should be defined by the upper application/protocol that is employing a XBE32 encoding. However, Subtype values 0x00 and 0xFF are reserved for XBE32 use and SHOULD NOT be employed for other purposes. Length (16 bits): This field MUST be encoded as an unsigned binary number in network byte order (a.k.a. Big Endian, i.e, the most significant byte first). It specifies the size in octets of the whole TLV structure, excluding padding. Length SHOULD be always equal or greater than 4 octets, that is, the length of the Type and Length fields. The only exception to this rule is a Complex TLV with a zero (0x0000) length value, whose meaning is explained in the next subsection. Uruena & Larrabeiti Expires March 12, 2008 [Page 5] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 Values and Padding (variable length): The Values field may contain a single variable-length value, multiple fixed-length values, or other TLVs, as defined by the Type and Length fields. The Values field may be empty, that is, have zero octets. In that case, the Length field SHOULD be set to 4. In order to properly align a non-empty Values field to 4-octet words, up to 3 octets of padding space MUST be added and filled with zeros (0x00) in transmission, and they MUST be ignored in reception. 2.1. Unspecified Length In some circumstances a message can not be delayed/stored and it must start being sent before all the data to be encoded is available. However, as a TLV header defines the total length of the structure, a TLV-encoded message should not be sent until all its data becomes available, or the total length can be inferred somehow. For that reason, XBE32 parsers MAY allow a Complex TLV (i.e. containing other TLVs) to have an "unspecified" length. In that case, the last of the inner TLVs MUST be an End-of-data TLV to mark its ending. This "unspecified" length is indicated by setting the Length field of a Complex TLV to zero (0x0000). End-of-data TLVs have the Type field set to zero (0x0000) and a fixed Length of 4 octets, thus they MUST NOT include a Values field: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type = 0x0000 | Length = 4 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ This optional mechanism allows XBE32 to encode Complex TLVs of arbitrary length. However, only Complex TLVs may have an "unspecified" length. The Values field of a Simple TLV containing primitive data Values MUST NOT be longer than 65532 octets. Uruena & Larrabeiti Expires March 12, 2008 [Page 6] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 3. XBE32 TLVs This section specifies all the possible TLV structures and data types allowed in XBE32. All TLVs share the common format for the Type and Length fields defined in the previous section. Therefore, the only difference between XBE32 TLVs is the inner structure of their Values fields and the type of the primitive data they contain, as defined by the Meta part of the TLV's Type field. 3.1. Complex TLVs with inner TLVs This figure represents a Complex TLV containing multiple inner TLVs. If the Length is "unspecified" (i.e. zero), the Complex TLV MUST end with a 4-octet End-of-data TLV. Otherwise, if the Length of a Complex TLV is non-zero, it MUST NOT contain any End-of-data TLVs. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type.Meta = 0x00-0x1F | Length = 0 or 4 + length TLVs | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type #1 | Length #1 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : Values #1 : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type #N | Length #N | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : Values #N : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | [ End-of-data TLV ] | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ As XBE32 TLVs must be aligned to 4-octet words, all Complex TLV will be also aligned to 4-octet words. Therefore, padding MUST NOT be added, and the Length field SHOULD specify the size of the whole Complex TLV, including the length of all the inner TLVs it contains. However, as some of the inner TLVs Values may be padded, the Length of a Complex TLV SHOULD NOT be calculated as 4 plus the sum of the Length fields of all its inner TLVs, as these fields may not include their padding octets. Uruena & Larrabeiti Expires March 12, 2008 [Page 7] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 3.2. Simple TLV with one variable-length Value This figure represents a Simple TLV containing a single variable- length Value: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type.Meta = 0x20-0x21 | Length = 4 + Value.length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : Value : : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : | [ 0x00 ] | [ 0x00 ] | [ 0x00 ] | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The Length field MUST specify the size of the Type and Length fields, plus the length of the encoded Value measured in octets. If the Value is not aligned to 4-octet words, padding MUST be added. In that case, the Length field does not define the size of the whole TLV structure, but its total length without the padding octets. 3.3. Simple TLVs with 1-Octet Values This figure represents a Simple TLV containing N, 1-octet Values: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type.Meta = 0x24-0x26 | Length = 4 + N | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Value #1 | Value #2 | Value #3 | Value #4 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Value #N | [ 0x00 ] | [ 0x00 ] | [ 0x00 ] | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The Length field MUST specify the size of the Type and Length fields, plus the number of 1-octet Values, if any. If the number of Values is not a multiple of 4, up to 3 padding octets MUST be added. In that case, the Length field does not define the size of the whole TLV structure, but its total length without the padding octets. Uruena & Larrabeiti Expires March 12, 2008 [Page 8] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 3.4. Simple TLV with 2-Octets Values This figure represents a Simple TLV containing N, 2-octets Values: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type.Meta = 0x28-0x29 | Length = 4 + N*2 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Value #1 | Value #2 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Value #N | [ 0x0000 ] | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The Length field MUST specify the size of the Type and Length fields, plus the number of 2-octet values, if any, multiplied by two. If the number of Values is not a multiple of 2, two padding octets MUST be added. In that case, the Length field does not define the size of the whole TLV structure, but its total length without the padding octets. 3.5. Simple TLVs with 4-Octets Values This figure represents a Simple TLV containing N, 4-octets Values: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type.Meta = 0x2C-0x2E | Length = 4 + N*4 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Value #1 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Value #N | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ As these TLVs are always aligned to 4-octet words, the Length field MUST specify the size of the whole TLV, and padding octets MUST NOT be added. Uruena & Larrabeiti Expires March 12, 2008 [Page 9] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 3.6. Simple TLVs with 8-Octets Values This figure represents a Simple TLV containing N, 8-octets Values: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type.Meta = 0x30-0x32 | Length = 4 + N*8 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | + Value #1 + | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | + Value #N + | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ As these TLVs are always aligned to 4-octet words, the Length field MUST specify the size of the whole TLV, and padding octets MUST NOT be added. 3.7. Simple TLVs with 12-Octets Values This figure represents a Simple TLV containing N, 12-octet Values: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type.Meta = 0x34 | Length = 4 + N*12 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | + + | Value #1 | + + | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | + + | Value #N | + + | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Uruena & Larrabeiti Expires March 12, 2008 [Page 10] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 As these TLVs are always aligned to 4-octet words, the Length field MUST specify the size of the whole TLV, and padding octets MUST NOT be added. 3.8. Simple TLVs with 16-Octets Values This figure represents a Simple TLV containing N, 16-octet Values: 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type.Meta = 0x38 | Length = 4 + N*16 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | + + | | + Value #1 + | | + + | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | + + | | + Value #N + | | + + | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ As these TLVs are always aligned to 4-octet words, the Length field MUST specify the size of the whole TLV, and padding octets MUST NOT be added. Uruena & Larrabeiti Expires March 12, 2008 [Page 11] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 3.9. Opaque TLV Values An Opaque Value is a sequence of octets that SHOULD NOT be processed by a XBE32 parsing entity, but just be delivered to the upper layer. The Meta values reserved for Simple XBE32 TLVs carrying Opaque Values are: Meta TLV Value Description ---- ------------------------------------ 0x20 Single variable-length opaque Value 0x24 Multiple opaque1 Values 0x28 Multiple opaque2 Values 0x2C Multiple opaque4 Values 0x30 Multiple opaque8 Values 0x34 Multiple opaque12 Values 0x38 Multiple opaque16 Values 3.10. String TLV Value String Values MUST be encoded using UTF-8 as specified in [2]. The Meta value reserved for Simple XBE32 TLVs carrying a single String Value is: Meta TLV Value Description ---- ------------------------------------ 0x21 Single variable-length string Value 3.11. Boolean TLV Values Each Boolean Value is encoded with a single octet. A "False" Value is serialized as 0x00, while "True" is encoded as 0xFF. Other values than 0x00 or 0xFF MUST NOT appear as boolean-encoded values. The Meta value reserved for Simple XBE32 TLVs carrying multiple Boolean Values is: Meta TLV Value Description ---- ------------------------------------ 0x26 Multiple boolean Values Uruena & Larrabeiti Expires March 12, 2008 [Page 12] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 3.12. Integer TLV Values Integer Values are signed and MUST be encoded as a two's complement binary number in network byte order (a.k.a. Big Endian, i.e., the most significant byte first). The Meta values reserved for Simple XBE32 TLVs carrying multiple Integer Values are: Meta TLV Value Description ---- ------------------------------------ 0x25 Multiple int8 Values 0x29 Multiple int16 Values 0x2D Multiple int32 Values 0x31 Multiple int64 Values 3.13. Floating point TLV Values Floating point Values MUST be encoded as specified in [3]. The Meta values reserved for Simple XBE32 TLVs carrying multiple Floating Point Values are: Meta TLV Value Description ---- ------------------------------------ 0x2E Multiple float32 Values 0x32 Multiple float64 Values Uruena & Larrabeiti Expires March 12, 2008 [Page 13] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 4. XBE32 Elements Hierarchical data can be represented as a tree, where each node has an identifier. The "leaf" nodes of the tree are the only ones which are able to carry primitive data values. In XBE32 the nodes of the tree are known as "Elements". Each XBE32 Element has an identifier, that could be a binary one or a human-readable name. There are two kinds of Elements in XBE32, depending on whether they carry primitive data or not: "Attribute Elements" are the leafs of the tree and carry zero or more Values of a given data type."Complex Elements" on the other hand, cannot carry primitive data, but they are the parents of other XBE32 Elements, that could be Attribute Elements or other Complex Elements themselves. Furthermore, the so-called "Compact Elements" are encoded inside a single XBE32 TLV, while the optional "Extensible Elements" require two or more TLVs in order to carry their Extensible Names or Identifiers. Moreover, Complex Elements are encoded using Complex XBE32 TLVs, whereas Attribute Elements employ Simple XBE32 TLVs. 4.1. Compact Elements As most network protocols only employ a small set of elements to build their messages, they could be easily encoded with XBE32 by just using Compact Elements, that are encoded with a single TLV and are identified by its binary 16-bit Type field. Each application/protocol using XBE32 may define its own set of Type values, unless they have been reserved in the base specification of XBE32. Therefore Compact Elements SHOULD employ only the following TLV Meta and Subtype values (with any combination of C and E bits): Meta Subtype TLV Description --------- --------- ------------------------------ 0x00-0x1F 0x01-0xFE Compact Complex Element 0x20-0x38 0x01-0xFE Compact Attribute Element Compact Attribute Elements MUST employ an appropriate Meta value according to the type of the primitive data carried in their TLV Values field, as defined in the previous section of this document. For example, an Attribute Element carrying zero or more 32-bit Integer Values may be encoded with one Simple TLV whose Type value is in the 0x2D01-0x2DFE range, with the C and E bits set accordingly to the desired processing rules. Uruena & Larrabeiti Expires March 12, 2008 [Page 14] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 4.2. Extensible Elements: Extensible Names and Identifiers The above mechanism allows a compact representation of binary data and is suitable for the initial definition of the mandatory operations and optional parameters of a simple network protocol. However, a 2-octet Type field may not be enough for truly extensible protocols, as it could be a namespace too small for vendor extensions, experimental operations, or future versions of the protocol. In order to cope with this limitation, XBE32 implementations MAY also support Extensible Elements. These optional XBE32 Elements are encoded employing multiple TLVs, that are stored inside a XBE32 Complex TLV with a reserved Type value depending on whether the Extensible Element is an Attribute or a Complex one: Meta Subtype TLV Description ---- ------- --------------------------------- 0x1F 0xFF Extensible Complex TLV 0x1F 0x00 Extensible Attribute TLV Note that C and E bits may have any value, thus, four different Extensible Complex Element TLVs, and other four Extensible Attribute Element TLVs are defined. For instance, an optional Extensible Attribute Element, that should be notified if unknown, must be encoded inside an Extensible TLV with a 0xDF00 Type value. Each XBE32 Extensible Element MUST have an identifier, that can be a single 4-octet opaque value called Extensible Identifier, or a non- empty UTF-8 string called Extensible Name. The identifier of an Extensible Element MUST be included inside the first inner TLV of the Complex TLV which encodes the Extensible Element. XBE32 has reserved two Simple TLVs to carry Extensible Names and Identifiers: Type TLV Description ------ --------------------------------- 0x21FF Extensible Name TLV 0x2CFF Extensible Identifier TLV Although the Type field of the upper Extensible TLV does not identify the Extensible Element by itself, its C and E bits are fully meaningful, and MUST specify what measures must be taken if a XBE32 processing entity does not recognize the Extensible Name or Identifier of this Extensible Element, or it just does not support Extensible Elements at all. Uruena & Larrabeiti Expires March 12, 2008 [Page 15] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 4.3. Extensible Complex Elements An Extensible Complex Element is encoded inside an Extensible Complex TLV (Meta=0x1F Subtype=0xFF), that MUST contain a single Extensible Name TLV (Type=0x21FF) or Extensible Identifier TLV (Type=0x2CFF) first, followed by zero or more TLV-encoded XBE32 Elements, that could be Compact or Extensible ones, Attributes or Complex ones, or any combination of them. 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |C|E| Type = 0x1FFF | ExtElem Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type = 0x21FF/0x2CFF | ExtName/Id Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : ExtName/ExtId : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type #1 | Length #1 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : Values #1 : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type #N | Length #N | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : Values #N : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ The optional "unspecified" length mechanism, when applied to an Extensible Complex TLV, may allow XBE32 processing entities to start encoding and sending partial Extensible Complex Elements before all their sub-elements are known or their data is fully available. 4.4. Extensible Attribute Elements The structure of an Extensible Attribute Element is quite similar to an Extensible Complex Element, as it is encoded inside a Extensible Attribute TLV (Meta=0x1F Subtype=0x00), that MUST include at least two TLVs: a single Extensible Name TLV (Type=0x21FF) or Extensible Identifier TLV (Type=0x2CFF) first, followed by one or more TLVs which carry the Values of that Extensible Attribute. Uruena & Larrabeiti Expires March 12, 2008 [Page 16] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ |C|E| Type = 0x1F00 | ExtAttr Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type = 0x21FF/0x2CFF | ExtName/Id Length | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : ExtName/ExtId : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | ExtVals Type | ExtVals Length #1 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : ExtValues #1 : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | ExtVals Type | ExtVals Length #N | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ : : : ExtValues #N : : : +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ XBE32 has reserved the following Type values for the Extensible Values TLVs: Type TLV Description ------ ------------------------------------------------- 0x2000 Extensible variable-length opaque Value TLV 0x2100 Extensible variable-length string Value TLV 0x2400 Extensible opaque1 Values TLV 0x2500 Extensible int8 Values TLV 0x2600 Extensible boolean Values TLV 0x2800 Extensible opaque2 Values TLV 0x2900 Extensible int16 Values TLV 0x2C00 Extensible opaque4 Values TLV 0x2D00 Extensible int32 Values TLV 0x2E00 Extensible float32 Values TLV 0x3000 Extensible opaque8 Values TLV 0x3100 Extensible int64 Values TLV 0x3200 Extensible float64 Values TLV 0x3400 Extensible opaque12 Values TLV 0x3800 Extensible opaque16 Values TLV Uruena & Larrabeiti Expires March 12, 2008 [Page 17] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 If several Extensible Values TLVs are present, all of them MUST have the same Type value, depending on the data type of the Extensible Attribute Element. It is RECOMMENDED to encode all the Values of an Extensible Attribute in a single Extensible Values TLV, whenever it is possible. Nevertheless, a XBE32 processing entity SHOULD concatenate, keeping the received order, all the Values fields of all the Extensible Values TLVs forming an Extensible Attribute Element. For instance, multiple Extensible string Value TLVs should be appended to form a single variable-length String Value, whereas several Extensible int32 Values TLVs would generate a single array of Integer Values. The encoding of Extensible Attributes with multiple Extensible Values TLVs, paired with the optional "unspecified" length mechanism, may allow XBE32 Extensible Attributes to carry a single Value or a list of Values longer than the 65532 octets limit of Compact Attributes. 5. Acknowledgements We would like to thank Roy T. Fielding, Miguel Fernandez, and Raul Garcia for their valuable comments. 6. References [1] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [2] Yergeau, F., "UTF-8, a transformation format of ISO 10646", STD 63, RFC 3629, November 2003. [3] Institute of Electrical and Electronics Engineers, "Standard for Binary Floating-Point Arithmetic", IEEE Standard 754, August 1985. Uruena & Larrabeiti Expires March 12, 2008 [Page 18] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 Appendix A. XBE32 Example true -32768, 0, 32767 4.9E-324 0 1 2 3 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | TYPE = 0xDFFF | LENGTH = 0x0000 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type = 0x2CFF | Length = 0x0008 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x11111111 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type = 0xA602 | Length = 0x0005 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0xFF | 0x00 | 0x00 | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | TYPE = 0x1F00 | LENGTH = 0x001C | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type = 0x21FF | Length = 0x0007 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0xC2 | 0x81 | 0x62 | 0x00 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type = 0x2900 | Length = 0x0008 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x8000 | 0x0000 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type = 0x2900 | Length = 0x0006 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | 0x7FFF | 0x0000 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | Type = 0x7204 | Length = 0x000C | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | | + 0x0000000000000001 + | | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ | TYPE = 0x0000 | LENGTH = 0x0004 | +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ Uruena & Larrabeiti Expires March 12, 2008 [Page 19] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 Authors' Addresses Manuel Uruena Universidad Carlos III de Madrid Av. Universidad 30 Leganes, Madrid 28911 ES Phone: +34 91 624 62 35 Email: muruenya@it.uc3m.es David Larrabeiti Universidad Carlos III de Madrid Av. Universidad 30 Leganes, Madrid 28911 ES Phone: +34 91 624 99 53 Email: dlarra@it.uc3m.es Uruena & Larrabeiti Expires March 12, 2008 [Page 20] Internet-Draft eXtensible Binary Encoding (XBE32) September 2007 Full Copyright Statement Copyright (C) The IETF Trust (2007). This document is subject to the rights, licenses and restrictions contained in BCP 78, and except as set forth therein, the authors retain all their rights. This document and the information contained herein are provided on an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. Intellectual Property The IETF takes no position regarding the validity or scope of any Intellectual Property Rights or other rights that might be claimed to pertain to the implementation or use of the technology described in this document or the extent to which any license under such rights might or might not be available; nor does it represent that it has made any independent effort to identify any such rights. Information on the procedures with respect to rights in RFC documents can be found in BCP 78 and BCP 79. Copies of IPR disclosures made to the IETF Secretariat and any assurances of licenses to be made available, or the result of an attempt made to obtain a general license or permission for the use of such proprietary rights by implementers or users of this specification can be obtained from the IETF on-line IPR repository at http://www.ietf.org/ipr. The IETF invites any interested party to bring to its attention any copyrights, patents or patent applications, or other proprietary rights that may cover technology that may be required to implement this standard. Please address the information to the IETF at ietf-ipr@ietf.org. Acknowledgment Funding for the RFC Editor function is provided by the IETF Administrative Support Activity (IASA). Uruena & Larrabeiti Expires March 12, 2008 [Page 21]