Delay-Tolerant Networking Working Group S. Burleigh Internet Draft JPL, Calif. Inst. Of Technology Intended status: Standards Track April 29, 2016 Expires: October 2016 Bundle Protocol CBOR Representation Specification draft-burleigh-dtn-rs-cbor-01.txt Status of this Memo This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. This document may contain material from IETF Documents or IETF Contributions published or made publicly available before November 10, 2008. The person(s) controlling the copyright in some of this material may not have granted the IETF Trust the right to allow modifications of such material outside the IETF Standards Process. Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English. 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 October 31, 2016. Copyright Notice Copyright (c) 2016 IETF Trust and the persons identified as the document authors. All rights reserved. Burleigh Expires October 2016 [Page 1] Internet-Draft Proposed Revised Bundle Protocol April 2016 This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://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 Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Abstract This Internet Draft presents a specification for the use of Concise Binary Object Representation (CBOR) in the representation of transmitted Bundle Protocol (BP) bundles. Table of Contents 1. Introduction...................................................3 2. Conventions used in this document..............................3 3. BP Data Structure Representations in CBOR......................3 3.1. DTN Time..................................................3 3.2. Creation Timestamp........................................4 3.3. Endpoint ID...............................................4 3.4. Bundle Processing Control Flags...........................4 3.5. Fragment ID...............................................5 3.6. CRC.......................................................5 3.7. Block Processing Control Flags............................5 3.8. Block-type-specific Data..................................6 4. Bundle Representation in CBOR..................................6 4.1. Bundle....................................................6 4.2. Primary Block.............................................6 4.3. Canonical Block...........................................7 5. Block-type-specific Data Representations in CBOR...............8 5.1. Payload Block (block type 1)..............................8 5.2. Block Integrity Block (block type 2)......................8 5.3. Block Confidentiality Block (block type 3)................8 5.4. Manifest Block (block type 4).............................8 5.5. Current Custodian Block (block type 5)....................9 5.6. Flow Label Block (block type 6)...........................9 5.7. Previous Node Block (block type 7)........................9 5.8. Bundle Age Block (block type 8)...........................9 5.9. Hop Count Block (block type 9)............................9 6. Administrative Records.........................................9 6.1. Bundle Status Report (record type 1).....................10 6.2. Custody Signal (record type 2)...........................11 Burleigh Expires October 2016 [Page 2] Internet-Draft Proposed Revised Bundle Protocol April 2016 7. Security Considerations.......................................11 8. IANA Considerations...........................................11 9. References....................................................12 9.1. Normative References.....................................12 9.2. Informative References...................................12 10. Acknowledgments..............................................12 Appendix A. For More Information.................................13 1. Introduction The Bundle Protocol specification [BPBIS] states that it defines only the abstract structures of the "blocks" of which bundles are composed: "The specific bitstream that is emitted when a CLA sends a bundle will be dictated by the applicable bundle representation specification to which the sending and receiving nodes conform, an implementation matter....Bundle representation specifications are beyond the scope of this document." One bundle representation approach that has been suggested is to utilize Concise Binary Object Representation (CBOR [RFC7049]) for this purpose. The design goals of CBOR appear to meet the operational requirements of a wide range of BP use cases. Accordingly, this document proposes specific rules for encoding and decoding bundles in CBOR representation. 2. Conventions used in this document The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in RFC-2119 [RFC2119]. In this document, these words will appear with that interpretation only when in ALL CAPS. Lower case uses of these words are not to be interpreted as carrying RFC-2119 significance. 3. BP Data Structure Representations in CBOR 3.1. DTN Time A DTN time is an unsigned integer indicating a count of seconds since the start of the year 2000 on the Coordinated Universal Time (UTC) scale [UTC]. Each DTN time SHALL be represented as a CBOR unsigned integer item; the unsigned integer following the item type byte SHALL contain the time value. Burleigh Expires October 2016 [Page 3] Internet-Draft Proposed Revised Bundle Protocol April 2016 3.2. Creation Timestamp Each creation timestamp SHALL be represented as a CBOR array item with additional info 2, indicating that the item is a 2-tuple. The first item of the array SHALL be a DTN time. The second item of the array SHALL be the creation timestamp's sequence number, represented as a CBOR unsigned integer. 3.3. Endpoint ID Each BP endpoint ID (EID) SHALL be represented as a CBOR array with additional info 2, indicating that the item is a 2-tuple. The first item of the array SHALL be the code number identifying the endpoint's URI scheme [URI], as defined in the registry of URI scheme code numbers maintained by IANA as described in Section 7. [URIREG]. Each URI scheme code number SHALL be represented as a CBOR unsigned integer. The second item of the array SHALL be the applicable CBOR representation of the scheme-specific part (SSP) of the EID, defined as follows: . If the EID's URI scheme is "dtn" then the SSP SHALL be represented as a CBOR text string. . If the EID's URI scheme is "ipn" then the SSP SHALL be represented as a CBOR array with additional info 2, indicating that the item is a 2-tuple. The first item of this array SHALL be the EID's node number represented as a CBOR unsigned integer. The second item of this array SHALL be the EID's service number represented as a CBOR unsigned integer. . Definitions of the CBOR representations of the SSPs of EIDs encoded in other URI schemes are included in the specifications defining those schemes. 3.4. Bundle Processing Control Flags The bundle processing control flags SHALL be represented as a CBOR unsigned integer item with additional info 25; the 16-bit unsigned integer following the item type byte SHALL be a bit field indicating the control flag values as follows: . Bit 0 (the high-order bit, 0x8000): reserved. . Bit 1 (0x4000): reserved. . Bit 2(0x2000): reserved. Burleigh Expires October 2016 [Page 4] Internet-Draft Proposed Revised Bundle Protocol April 2016 . Bit 3(0x1000): bundle deletion status reports are requested. . Bit 4(0x0800): bundle delivery status reports are requested. . Bit 5(0x0400): bundle forwarding status reports are requested. . Bit 6(0x0200): custody acceptance status reports are requested. . Bit 7(0x0100): bundle reception status reports are requested. . Bit 8(0x0080): bundle contains a Manifest block. . Bit 9(0x0040): status time is requested in all status reports. . Bit 10(0x0020): user application acknowledgement is requested. . Bit 11(0x0010): destination is a singleton endpoint. . Bit 12(0x0008): custody transfer is requested. . Bit 13(0x0004): bundle must not be fragmented. . Bit 14(0x0002): payload is an administrative record. . Bit 15 (the low-order bit, 0x0001: bundle is a fragment. 3.5. Fragment ID Fragment ID SHALL be omitted from the primary block if and only if the value of the "bundle is a fragment" flag in the bundle processing control flags is zero. Otherwise, the bundle's fragment ID SHALL be represented as a CBOR array with additional info 2, indicating that the item is a 2-tuple. The first item of this array SHALL be the fragment offset of the bundle's payload, represented as a CBOR unsigned integer. The second item of this array SHALL be the total (original) application data unit length, represented as a CBOR unsigned integer. 3.6. CRC CRC SHALL be omitted from a block if and only if the block's CRC type code is zero. When not omitted, the CRC SHALL be represented as a CBOR unsigned integer. 3.7. Block Processing Control Flags The block processing control flags SHALL be represented as a CBOR unsigned integer item with additional info 24; the 8-bit unsigned integer following the item type byte SHALL be a bit field indicating the control flag values as follows: . Bit 0 (the high-order bit, 0x80): reserved. . Bit 1 (0x40): reserved. . Bit 2(0x20): reserved. . Bit 3(0x10): reserved. Burleigh Expires October 2016 [Page 5] Internet-Draft Proposed Revised Bundle Protocol April 2016 . Bit 4(0x08): bundle must be deleted if block can't be processed. . Bit 5(0x04): status report must be transmitted if block can't be processed. . Bit 6(0x02): block must be removed from bundle if it can't be processed. . Bit 7(the low-order bit, 0x01): block must be replicated in every fragment. 3.8. Block-type-specific Data Block-type-specific data in each block (other than the primary block) SHALL be the applicable CBOR representation of the content of the block. Details of this representation are included in the specification defining the block type. 4. Bundle Representation in CBOR 4.1. Bundle Each bundle SHALL be represented as a CBOR indefinite-length array (major type 4 with additional info 31). The first item of this array SHALL be the CBOR representation of a Primary Block. Every other item of the array except the last SHALL be the CBOR representation of a Canonical Block. The last item of the array SHALL be a CBOR "break" stop code (major type 7 with additional information 31). 4.2. Primary Block Each primary block SHALL be represented as a CBOR array with additional info either 8 (if the bundle is not a fragment and CRC type is zero) or 9 (if the bundle is a fragment or CRC type is non- zero, but not both) or 10 (if the bundle is a fragment and CRC-type is non-zero). The items of this array SHALL be as indicated in Table 1, appearing in the order shown in this table. +-------------+-----------------+---------------------------------+ | | Item Type Byte | Content Bytes | | | | | | | Major | | | | Item | Add'l | | | | Type | Info | | | Item | 3 bits | 5 bits | Size | Value | +=============+========+========+======+==========================+ | version | 4 | 7 | n/a | n/a | +-------------+--------+--------+------+--------------------------+ Burleigh Expires October 2016 [Page 6] Internet-Draft Proposed Revised Bundle Protocol April 2016 | bundle | See 3.4. above | | processing | | | | | | control | | | | | | flags | | | | | +-------------+--------+--------+------+--------------------------+ | CRC type | 4 | type | n/a | n/a | | | | code | | | +-------------+--------+--------+------+--------------------------+ | destination | See 3.3. above | | EID | | | | | +-------------+--------+--------+------+--------------------------+ | source node | See 3.3. above | | ID | | | | | +-------------+--------+--------+------+--------------------------+ | report-to | See 3.3. above | | EID | | | | | +-------------+--------+--------+------+--------------------------+ | creation | See 3.2. above | | timestamp | | | | | +-------------+--------+--------+------+--------------------------+ | lifetime | 4 | as required to contain value | +-------------+--------+--------+------+--------------------------+ | fragment ID | See 3.5. above | +-------------+--------+--------+------+--------------------------+ | CRC | See 3.6. above | +-------------+--------+--------+------+--------------------------+ Table 1: Primary Block Data Items 4.3. Canonical Block Each block other than the primary block SHALL be represented as a CBOR array with additional info either 5 (if CRC type is zero) or 6 (otherwise). The items of this array SHALL be as indicated in Table 2, appearing in the order shown in this table. +-------------+-----------------+---------------------------------+ | | Item Type Byte | Content Bytes | | | | | | | Major | | | | Item | Add'l | | | | Type | Info | | | Item | 3 bits | 5 bits | Size | Value | +=============+========+========+======+==========================+ | block type | 4 | as required to contain value | | code | | | | | +-------------+--------+--------+------+--------------------------+ Burleigh Expires October 2016 [Page 7] Internet-Draft Proposed Revised Bundle Protocol April 2016 | block number| 4 | as required to contain value | +-------------+--------+--------+------+--------------------------+ | block | See 3.7. above | | processing | | | | | | control | | | | | | flags | | | | | +-------------+--------+--------+------+--------------------------+ | CRC type | 4 | type | n/a | n/a | | | | code | | | +-------------+--------+--------+------+--------------------------+ | CRC | See 3.6. above | +-------------+--------+--------+------+--------------------------+ | block-type- | See 3.8. above | | specific | | | | | | data | | | | | +-------------+--------+--------+------+--------------------------+ Table 2: Canonical Block Data Items 5. Block-type-specific Data Representations in CBOR 5.1. Payload Block (block type 1) The block-type-specific data in a payload block is an application data unit, or some contiguous extent thereof, which SHALL be represented as a CBOR byte string. 5.2. Block Integrity Block (block type 2) The representation of the block-type-specific data in a block integrity block is provided in the Bundle Security Protocol specification, a work in progress. 5.3. Block Confidentiality Block (block type 3) The representation of the block-type-specific data in a block confidentiality block is provided in the Bundle Security Protocol specification, a work in progress. 5.4. Manifest Block (block type 4) The representation of the block-type-specific data in a manifest block is provided in the Manifest Extension Block specification, TBD. Burleigh Expires October 2016 [Page 8] Internet-Draft Proposed Revised Bundle Protocol April 2016 5.5. Current Custodian Block (block type 5) The block-type-specific data in a current custodian block is a node ID, which takes the form of an endpoint ID represented as described in Section 3.3. above. 5.6. Flow Label Block (block type 6) The representation of the block-type-specific data in a flow label block is provided in the Flow Label Extension Block specification, TBD. 5.7. Previous Node Block (block type 7) The block-type-specific data in a previous node block is a node ID, which takes the form of an endpoint ID represented as described in Section 3.3. above. 5.8. Bundle Age Block (block type 8) The block-type-specific data in a bundle age block is the age of the bundle in seconds, which SHALL be represented as a CBOR unsigned integer. 5.9. Hop Count Block (block type 9) The block-type-specific data in a hop count block SHALL be represented as a CBOR array (major type 4) with additional info 2, indicating that the item is a 2-tuple. The first item of this array SHALL be the bundle's hop limit, represented as a CBOR unsigned integer. The second item of this array SHALL be the bundle's hop count, represented as a CBOR unsigned integer. 6. Administrative Records Each BP administrative record SHALL be represented as a CBOR array (major type 4) with additional info 2 indicating that the item is a 2-tuple. The first item of the array SHALL be a record type code, which SHALL be represented as a CBOR unsigned integer. The second element of this array SHALL be the applicable CBOR representation of the content of the record. Details of the CBOR representations of administrative record types 1 and 2 are provided below. Details of the CBOR representations of other types of Burleigh Expires October 2016 [Page 9] Internet-Draft Proposed Revised Bundle Protocol April 2016 administrative record type are included in the specifications defining those records. 6.1. Bundle Status Report (record type 1) Each bundle status report SHALL be represented as a CBOR array (major type 4) with additional info either 5 (if the subject bundle is a fragment) or 4 (otherwise). The first item of the bundle status report array SHALL be bundle status information represented as a CBOR array (major type 4) with additional info 5. The five items of the bundle status information array shall provide information on the following five status assertions, in this order: . Reporting node received bundle. . Reporting node accepted custody of bundle. . Reporting node forwarded the bundle. . Reporting node delivered the bundle. . Reporting node deleted the bundle. Each item of the bundle status information array SHALL be a bundle status item represented as a CBOR array (major type 4) with additional info either 2 (if the value of the first item of this bundle status item is 1) or 1 (otherwise). The first item of the bundle status item array SHALL be a Boolean value, indicating whether or not the corresponding bundle status is asserted, represented as a CBOR unsigned integer (major type 0). The second item of the bundle status item array, if present, SHALL be a DTN time as described in Section 3.1. above. The second item of the bundle status report array SHALL be the bundle status report reason code, represented as a CBOR unsigned integer. The third item of the bundle status report array SHALL be the source node ID of the subject bundle, taking the form of an endpoint ID and represented as described in Section 3.3. above. The fourth item of the bundle status report array SHALL be the creation timestamp of the subject bundle, represented as described in Section 3.2. above. The fifth item of the bundle status report array, if present, SHALL be the subject bundle's fragment reference represented as a CBOR array (major type 4) with additional info 2 indicating that the item is a 2-tuple. The first item of this array SHALL be the fragment Burleigh Expires October 2016 [Page 10] Internet-Draft Proposed Revised Bundle Protocol April 2016 offset of the subject bundle's payload, represented as a CBOR unsigned integer. The second item of this array SHALL be the length of the payload of the subject bundle, represented as a CBOR unsigned integer. 6.2. Custody Signal (record type 2) Each custody signal SHALL be represented as a CBOR array (major type 4) with additional info either 5 (if the subject bundle is a fragment) or 4 (otherwise). The first item of the custody signal array SHALL be a Boolean value, indicating whether or not custody was accepted, represented as a CBOR unsigned integer. The second item of the custody signal array SHALL be the bundle status report reason code, represented as a CBOR unsigned integer. The third item of the custody signal array SHALL be the source node ID of the subject bundle, taking the form of an endpoint ID and represented as described in Section 3.3. above. The fourth item of the custody signal array SHALL be the creation timestamp of the subject bundle, represented as described in Section 3.2. above. The fifth item of the custody signal array, if present, SHALL be the subject bundle's fragment reference represented as a CBOR array (major type 4) with additional info 2 indicating that the item is a 2-tuple. The first item of this array SHALL be the fragment offset of the subject bundle's payload, represented as a CBOR unsigned integer. The second item of this array SHALL be the length of the payload of the subject bundle, represented as a CBOR unsigned integer. 7. Security Considerations Representation of DTN bundles in CBOR introduces no security considerations beyond those introduced by the Bundle Protocol. 8. IANA Considerations A registry of URI scheme type numbers will be required. Burleigh Expires October 2016 [Page 11] Internet-Draft Proposed Revised Bundle Protocol April 2016 9. References 9.1. Normative References [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate Requirement Levels", BCP 14, RFC 2119, March 1997. [RFC7049] Borman, C. and P. Hoffman, "Concise Binary Object Representation (CBOR)", RFC 7049, October 2013. [URI] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform Resource Identifier (URI): Generic Syntax", RFC 3986, STD 66, January 2005. [URIREG] Thaler, D., Hansen, T., and T. Hardie, "Guidelines and Registration Procedures for URI Schemes", RFC 7595, BCP 35, June 2015. 9.2. Informative References [BPBIS] Burleigh, S., Fall, K., and E. Birrane, "Bundle Protocol", Work In Progress, March 2016. [UTC] Arias, E. and B. Guinot, "Coordinated universal time UTC: historical background and perspectives" in "Journees systemes de reference spatio-temporels", 2004. 10. Acknowledgments This document was prepared using 2-Word-v2.0.template.dot. Burleigh Expires October 2016 [Page 12] Internet-Draft Proposed Revised Bundle Protocol April 2016 Appendix A. For More Information Please refer comments to dtn@ietf.org. The Delay Tolerant Networking Research Group (DTNRG) Web site is located at http://www.dtnrg.org. Copyright (c) 2016 IETF Trust and the persons identified as authors of the code. All rights reserved. Redistribution and use in source and binary forms, with or without modification, is permitted pursuant to, and subject to the license terms contained in, the Simplified BSD License set forth in Section 4.c of the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info). Authors' Addresses Scott Burleigh Jet Propulsion Laboratory, California Institute of Technology 4800 Oak Grove Dr. Pasadena, CA 91109-8099 US Phone: +1 818 393 3353 Email: Scott.Burleigh@jpl.nasa.gov Burleigh Expires October 2016 [Page 13]