idnits 2.17.1 draft-birrane-dtn-amp-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 15, 2020) is 1465 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'TYPE 1' is mentioned on line 256, but not defined == Missing Reference: 'TYPE 2' is mentioned on line 256, but not defined == Missing Reference: 'ARRAY' is mentioned on line 1766, but not defined == Missing Reference: 'BYTE' is mentioned on line 1612, but not defined == Missing Reference: 'TXT STR' is mentioned on line 590, but not defined == Missing Reference: 'Varies' is mentioned on line 590, but not defined == Missing Reference: 'OCTETS' is mentioned on line 1505, but not defined == Missing Reference: 'UINT' is mentioned on line 1462, but not defined == Missing Reference: 'ARI' is mentioned on line 1513, but not defined == Missing Reference: 'AC' is mentioned on line 1740, but not defined == Missing Reference: 'VARIES' is mentioned on line 1612, but not defined == Missing Reference: 'UVAST' is mentioned on line 938, but not defined == Missing Reference: 'BYTESTR' is mentioned on line 1689, but not defined == Missing Reference: 'TNVC' is mentioned on line 1408, but not defined == Missing Reference: 'TS' is mentioned on line 1584, but not defined == Missing Reference: 'TV' is mentioned on line 1740, but not defined == Missing Reference: 'EXPR' is mentioned on line 1325, but not defined == Missing Reference: 'TNV' is mentioned on line 1513, but not defined == Outdated reference: A later version (-06) exists of draft-birrane-dtn-adm-02 ** Obsolete normative reference: RFC 7049 (Obsoleted by RFC 8949) Summary: 1 error (**), 0 flaws (~~), 20 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Delay-Tolerant Networking E. Birrane 3 Internet-Draft Johns Hopkins Applied Physics Laboratory 4 Intended status: Standards Track April 15, 2020 5 Expires: October 17, 2020 7 Asynchronous Management Protocol 8 draft-birrane-dtn-amp-08 10 Abstract 12 This document describes a binary encoding of the Asynchronous 13 Management Model (AMM) and a protocol for the exchange of these 14 encoded items over a network. This Asynchronous Management Protocol 15 (AMP) does not require transport-layer sessions, operates over 16 unidirectional links, and seeks to reduce the energy and compute 17 power necessary for performing network management on resource 18 constrained devices. 20 Status of This Memo 22 This Internet-Draft is submitted in full conformance with the 23 provisions of BCP 78 and BCP 79. 25 Internet-Drafts are working documents of the Internet Engineering 26 Task Force (IETF). Note that other groups may also distribute 27 working documents as Internet-Drafts. The list of current Internet- 28 Drafts is at https://datatracker.ietf.org/drafts/current/. 30 Internet-Drafts are draft documents valid for a maximum of six months 31 and may be updated, replaced, or obsoleted by other documents at any 32 time. It is inappropriate to use Internet-Drafts as reference 33 material or to cite them other than as "work in progress." 35 This Internet-Draft will expire on October 17, 2020. 37 Copyright Notice 39 Copyright (c) 2020 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents 44 (https://trustee.ietf.org/license-info) in effect on the date of 45 publication of this document. Please review these documents 46 carefully, as they describe your rights and restrictions with respect 47 to this document. Code Components extracted from this document must 48 include Simplified BSD License text as described in Section 4.e of 49 the Trust Legal Provisions and are provided without warranty as 50 described in the Simplified BSD License. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 3 55 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 3 56 3. Scope . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3 57 3.1. Protocol Scope . . . . . . . . . . . . . . . . . . . . . 3 58 3.2. Specification Scope . . . . . . . . . . . . . . . . . . . 4 59 4. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 5. Constraints and Assumptions . . . . . . . . . . . . . . . . . 4 61 6. Technical Notes . . . . . . . . . . . . . . . . . . . . . . . 5 62 7. AMP-Specific Concepts . . . . . . . . . . . . . . . . . . . . 6 63 7.1. Nicknames (NN) . . . . . . . . . . . . . . . . . . . . . 6 64 7.1.1. Motivation for Compression . . . . . . . . . . . . . 6 65 7.1.2. ADM Enumeration . . . . . . . . . . . . . . . . . . . 7 66 7.1.3. ADM Template Collection Enumeration . . . . . . . . . 8 67 7.1.4. Nickname Definition . . . . . . . . . . . . . . . . . 9 68 7.1.5. ADM Enumeration Considerations . . . . . . . . . . . 9 69 8. Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . 10 70 8.1. CBOR Considerations . . . . . . . . . . . . . . . . . . . 10 71 8.2. AMM Type Encodings . . . . . . . . . . . . . . . . . . . 10 72 8.2.1. Primitive Types . . . . . . . . . . . . . . . . . . . 10 73 8.2.2. Derived Types . . . . . . . . . . . . . . . . . . . . 11 74 8.2.3. Collections . . . . . . . . . . . . . . . . . . . . . 14 75 8.3. AMM Resource Identifier (ARI) . . . . . . . . . . . . . . 19 76 8.3.1. Encoding ARIs of Type LITERAL . . . . . . . . . . . . 19 77 8.3.2. Encoding Non-Literal ARIs . . . . . . . . . . . . . . 20 78 8.4. ADM Object Encodings . . . . . . . . . . . . . . . . . . 23 79 8.4.1. Externally Defined Data (EDD) . . . . . . . . . . . . 23 80 8.4.2. Constants (CONST) . . . . . . . . . . . . . . . . . . 24 81 8.4.3. Controls (CTRL) . . . . . . . . . . . . . . . . . . . 24 82 8.4.4. Macros (MAC) . . . . . . . . . . . . . . . . . . . . 25 83 8.4.5. Operators (OPER) . . . . . . . . . . . . . . . . . . 26 84 8.4.6. Report Templates (RPTT) . . . . . . . . . . . . . . . 26 85 8.4.7. Report (RPT) . . . . . . . . . . . . . . . . . . . . 27 86 8.4.8. State-Based Rules (SBR) . . . . . . . . . . . . . . . 28 87 8.4.9. Table Templates (TBLT) . . . . . . . . . . . . . . . 30 88 8.4.10. Tables (TBL) . . . . . . . . . . . . . . . . . . . . 30 89 8.4.11. Time-Based Rules (TBR) . . . . . . . . . . . . . . . 31 90 8.4.12. Variables (VAR) . . . . . . . . . . . . . . . . . . . 33 91 9. Functional Specification . . . . . . . . . . . . . . . . . . 33 92 9.1. AMP Message Summary . . . . . . . . . . . . . . . . . . . 33 93 9.2. Message Group Format . . . . . . . . . . . . . . . . . . 34 94 9.3. Message Format . . . . . . . . . . . . . . . . . . . . . 35 95 9.4. Register Agent . . . . . . . . . . . . . . . . . . . . . 37 96 9.5. Report Set . . . . . . . . . . . . . . . . . . . . . . . 37 97 9.6. Perform Control . . . . . . . . . . . . . . . . . . . . . 38 98 9.7. Table Set . . . . . . . . . . . . . . . . . . . . . . . . 38 99 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 39 100 11. Security Considerations . . . . . . . . . . . . . . . . . . . 39 101 12. Implementation Notes . . . . . . . . . . . . . . . . . . . . 39 102 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 40 103 13.1. Informative References . . . . . . . . . . . . . . . . . 40 104 13.2. Normative References . . . . . . . . . . . . . . . . . . 40 105 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 40 106 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 40 108 1. Introduction 110 Network management in challenged and resource constrained networks 111 must be accomplished differently than the network management methods 112 in high-rate, high-availability networks. The Asynchronous 113 Management Architecture (AMA) [I-D.birrane-dtn-ama] provides an 114 overview and justification of an alternative to "synchronous" 115 management services such as those provided by NETCONF. In 116 particular, the AMA defines the need for a flexible, robust, and 117 efficient autonomy engine to handle decisions when operators cannot 118 be active in the network. The logical description of that autonomous 119 model and its major components is given in the AMA Data Model (ADM) 120 [I-D.birrane-dtn-adm]. 122 The ADM presents an efficient and expressive autonomy model for the 123 asynchronous management of a network node, but does not specify any 124 particular encoding. This document, the Asynchronous Management 125 Protocol (AMP), provides a binary encoding of AMM objects and 126 specifies a protocol for the exchange of these encoded objects. 128 2. Requirements Language 130 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 131 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 132 document are to be interpreted as described in [RFC2119]. 134 3. Scope 136 3.1. Protocol Scope 138 The AMP provides data monitoring, administration, and configuration 139 for applications operating above the data link layer of the OSI 140 networking model. While the AMP may be configured to support the 141 management of network layer protocols, it also uses these protocol 142 stacks to encapsulate and communicate its own messages. 144 It is assumed that the protocols used to carry AMP messages provide 145 addressing, confidentiality, integrity, security, fragmentation/ 146 reassembly, and other network functions. Therefore, these items are 147 outside of the scope of this document. 149 3.2. Specification Scope 151 This document describes the format of messages used to exchange data 152 models between managing and managed devices in a network. The 153 rationale for this type of exchange is outside of the scope of this 154 document and is covered in [I-D.birrane-dtn-ama]. The description 155 and explanation of the data models exchanged is also outside of the 156 scope of this document and is covered in [I-D.birrane-dtn-adm]. 158 This document does not address specific configurations of AMP-enabled 159 devices, nor does it discuss the interface between AMP and other 160 management protocols. 162 4. Terminology 164 Note: The terms "Actor", "Agent", "Application Data Model", 165 "Externally Defined Data", "Variable", "Control", "Literal", "Macro", 166 "Manager", "Report Template", "Report", "Table", "Constant", 167 "Operator", "Time-Based Rule" and "State-Based Rule" are used without 168 modification from the definitions provided in [I-D.birrane-dtn-ama]. 170 5. Constraints and Assumptions 172 The desirable properties of an asynchronous management protocol, as 173 specified in the AMA, are summarized here to represent design 174 constraints on the AMP specification. 176 o Intelligent Push of Information - Nodes in a challenged network 177 cannot guarantee concurrent, bi-directional communications. Some 178 links between nodes may be strictly unidirectional. AMP Agents 179 "push" data to Managers rather than Managers "pulling" data from 180 Agents. 182 o Small Message Sizes - Smaller messages require smaller periods of 183 viable transmission for communication, incur less retransmission 184 cost, and consume fewer resources when persistently stored en 185 route in the network. AMP minimizes message size wherever 186 practical, to include binary data representations and predefined 187 data definitions and templates. 189 o Absolute and Custom Data Identification - All data in the system 190 must be uniquely addressable, to include operator-specified 191 information. AMP provides a compact encoding for identifiers. 193 o Autonomous, Stateless Operation - There is no reliable concept of 194 session establishment or round-trip data exchange in asynchronous 195 networks. AMP is designed to be stateless. Where helpful, AMP 196 provides mechanisms for transactional ordering of commands within 197 a single AMP protocol data unit, but otherwise degrades gracefully 198 when nodes in the network diver in their configuration. 200 6. Technical Notes 202 o Unless otherwise specified, multi-byte values in this 203 specification are expected to be transmitted in network byte order 204 (Big Endian). 206 o Character encodings for all text-based data types will use UTF-8 207 encodings. 209 o All AMP encodings are self-terminating. This means that, given an 210 indefinite-length octet stream, each encoding can be unambiguously 211 decoded from the stream without requiring additional information 212 such as a length field separate from the data type definition. 214 o This specification uses the term OCTETS to refer to a sequence of 215 one or more related BYTE values. There is no implied structure 216 associated with OCTETS, meaning they do not encode a length value 217 or utilize a terminator character. While OCTETS may contain CBOR- 218 encoded values, the OCTETS sequence itself is not encoded as a 219 CBOR structure. 221 o If an OCTETS sequence is included as an element of a CBOR array 222 then the sequence MUST be considered as a single array element 223 when determining the size of the array. 225 o Bit-fields in this document are specified with bit position 0 226 holding the least-significant bit (LSB). When illustrated in this 227 document, the LSB appears on the right. 229 o In order to describe the encoding of data models specified in 230 [I-D.birrane-dtn-adm], this specification must refer to both the 231 data object being encoded and to the encoding of that data object. 232 When discussing the encoded version of a data object, this 233 specification uses the notation "E(data_object)" where E() refers 234 to a conceptual encoding function. This notation is only provided 235 as a means of clarifying the text and imposes no changes to the 236 actual wire coding. For example, this specification will refer to 237 the "macro" data object as "Macro" and to the encoding of a Macro 238 as "E(Macro)". 240 o Illustrations of fields in this specification consist of the name 241 of the field, the type of the field between []'s, and if the field 242 is optional, the text "(opt)". 243 Field order is deterministic and, therefore, fields MUST be 244 transmitted in the order in which they are specified. In cases 245 where an optional field is not present, then the next field will 246 be considered for transmission. 247 An example is shown in Figure 1 below. In this illustration two 248 fields (Field 1 and Field 2) are shown, with Field 1 of Type 1 and 249 Field 2 of Type 2. Field 2 is also listed as being optional. 250 Byte fields are shown in order of receipt, from left-to-right. 251 Therefore, when transmitted on the wire, Field 1 will be received 252 first, followed by Field 2 (if present). 254 +----------+----------+ 255 | Field 1 | Field 2 | 256 | [TYPE 1] | [TYPE 2] | 257 | | (opt) | 258 +----------+----------+ 260 Figure 1: Byte Field Formatting Example 262 When types are documented in this way, the type always refers to 263 the encoding of that type. The E() notation is not used as it is 264 to be inferred from the context of the illustration. 266 7. AMP-Specific Concepts 268 The AMP specification provides an encoding of objects comprising the 269 AMM. As such, AMP defines very few structures of its own. This 270 section identifies those data structures that are unique to the AMP 271 and required for it to perform appropriate and efficient encodings of 272 AMM objects. 274 7.1. Nicknames (NN) 276 In the AMP, a "Nickname" (NN) is used to reduce the overall size of 277 the encoding of ARIs that are defined in the context of an ADM. A NN 278 is calculated as a function of an ADM Moderated Namespace and the 279 type of object being identified. 281 7.1.1. Motivation for Compression 283 As identifiers, ARIs are used heavily in AMM object definitions, 284 particularly in those that define collections of objects. This makes 285 encoding ARIs an important consideration when trying to optimize the 286 size of AMP message. 288 Additionally, the majority of ARIs are defined in the context of an 289 ADM. Certain AMM objects types (EDDs, OPs, CTRLs, TBLTs) can only be 290 defined in the context of an ADM. Other object types (VARs, CONSTs, 291 RPTTs) may have common, useful objects defined in an ADM as well. 292 The structure of an ADM, to include its use of a Moderated Namespace 293 and collections by object type, provide a regular structure that can 294 be exploited for creating a compact representation. 296 In particular, as specified in [I-D.birrane-dtn-adm], ARIs can be 297 grouped by (1) their namespace and (2) the type of AMM object being 298 identified. For example, consider the following ARIs of type EDD 299 defined in ADM1 with a Moderated Namespace of "/DTN/ADM1/". 301 ari:/DTN/ADM1/Edd.item_1 ari:/DTN/ADM1/Edd.item_2 ... ari:/DTN/ADM1/ 302 Edd.item_1974 304 In this case, the namespace (/DTN/ADM1/) and the object type (Edd) 305 are good candidates for enumeration because their string encoding is 306 very verbose and their information follows a regular structure shared 307 across multiple ARIs. Separately, the string representation of 308 object names (item_1, item_2, etc...) may be very verbose and they 309 are also candidates for enumeration as they occupy a particular ADM 310 object type in a particular order as published in the ADM. 312 7.1.2. ADM Enumeration 314 Any ARI defined in an ADM exists in the context of a Moderated 315 Namespace. These namespaces provide a unique string name for the 316 ADM. However, ADMs can also be assigned a unique enumeration by the 317 same moderating entities that ensure namespace uniqueness. 319 An ADM enumeration is an unsigned integer in the range of 0 to 320 (2^64)/20. This range provides effective support for thousands of 321 trillions of ADMs. 323 The formal set of ADMs, similar to SNMP MIBs and NETCONF YANG models, 324 will be moderated and published. Additionally, a set of informal 325 ADMs may be developed on a network-by-network or on an organization- 326 by-organization bases. 328 Since informal ADMs exist within a predefined context (a network, an 329 organization, or some other entity) they do not have individual ADM 330 enumerations and are assigned the special enumeration "0". ARIs that 331 are not defined in formal ADMs rely on other context information to 332 help with their encoding (see Section 8.3). 334 7.1.3. ADM Template Collection Enumeration 336 The ADM template presented in [I-D.birrane-dtn-adm] defines a series 337 of object collections for the specification of various AMM objects. 338 Enumerating these collections in a standard way allows for their 339 compressed representation in the context of nicknames for objects 340 stored in these collections. 342 The enumeration of ADM Template collections is provided in Table 1 343 below. 345 +-----------------+-------------+ 346 | AMM Object Type | Enumeration | 347 +-----------------+-------------+ 348 | CONST | 0 | 349 | | | 350 | CTRL | 1 | 351 | | | 352 | EDD | 2 | 353 | | | 354 | MAC | 3 | 355 | | | 356 | OPER | 4 | 357 | | | 358 | RPTT | 5 | 359 | | | 360 | SBR | 6 | 361 | | | 362 | TBLT | 7 | 363 | | | 364 | TBR | 8 | 365 | | | 366 | VAR | 9 | 367 | | | 368 | metadata | 10 | 369 | | | 370 | reserved | 11-19 | 371 +-----------------+-------------+ 373 Table 1: ADM Type Enumerations 375 NOTE: Collection enumerations are different from AMM object types. 376 For example, the enumeration for the VAR collection (9) in an ADM is 377 different from the VAR object type (12). 379 7.1.4. Nickname Definition 381 As an enumeration, a Nickname is captured as a 64-bit unsigned 382 integer (UVAST) calculated as a function of the ADM enumeration and 383 the ADM type enumeration, as follows. 385 NN = ((ADM Enumeration) * 20) + (ADM Object Type Enumeration) 387 Considering the example set of ARIs from Section 7.1.1, assuming that 388 ADM1 has ADM enumeration 9 and given that objects in the example were 389 of type EDD, the NN for each of the 1974 items would be: (9 * 20) + 2 390 = 182. In this particular example, the ARI "/DTN/ADM1/Edd.item_1974" 391 can be encoded in 5 bytes: two bytes to CBOR encode the nickname 392 (182) and 3 bytes to CBOR encode the item's offset in the Edd 393 collection (1974). 395 7.1.5. ADM Enumeration Considerations 397 The assignment of formal ADM enumerations SHOULD take into 398 consideration the nature of the applications and protocols to which 399 the ADM applies. Those ADMs that are likely to be used in challenged 400 networks SHOULD be allocated low enumeration numbers (e.g. those that 401 will fit into 1-2 bytes) while ADMs that are likely to only be used 402 in well resourced networks SHOULD be allocated higher enumeration 403 numbers. It SHOULD NOT be the case that ADM enumerations are 404 allocated on a first-come, first-served basis. It is recommended 405 that ADM enumerations should be labeled based on the number of bytes 406 of the Nickname as a function of the size of the ADM enumeration. 407 These labels are shown in Table 2. 409 +-------------+--------+--------------+-----------------------------+ 410 | ADM Enum | NN | Label | Comment | 411 | | Size | | | 412 +-------------+--------+--------------+-----------------------------+ 413 | 0x1 - 0xCCC | 1-2 | Challenged | Constraints imposed by | 414 | | Bytes | Networks | physical layer and power. | 415 | | | | | 416 | 0xCCD - | 3-4 | Congested | Constraints imposed by | 417 | 0xCCCCCCC | Bytes | Networks | network traffic. | 418 | | | | | 419 | >=0xCCCCCCD | 5-8 | Resourced | Generally unconstrained | 420 | | Bytes | Networks | networks. | 421 +-------------+--------+--------------+-----------------------------+ 423 Table 2: ADM Enumerations Labels 425 8. Encodings 427 This section describes the binary encoding of logical data constructs 428 using the Concise Binary Object Representation (CBOR) defined in 429 [RFC7049]. 431 8.1. CBOR Considerations 433 The following considerations act as guidance for CBOR encoders and 434 decoders implementing the AMP. 436 o All AMP encodings are of definite length and, therefore, 437 indefinite encodings MUST NOT be used. 439 o AMP encodings MUST NOT use CBOR tags. Identification mechanisms 440 in the AMP capture structure and other information such that tags 441 are not necessary. 443 o Canonical CBOR MUST be used for all encoding. All AMP CBOR 444 decoders MUST run in strict mode. 446 o Because AMA objects are self-delineating they can be serialized 447 into, or deserialized from, OCTETS. CBOR containers such as 448 BYTESTR and TXTSTR that encode length fields are only useful for 449 data that is not self-delineating, such as name fields. Encoding 450 self-delineating objects into CBOR containers reduced efficiency 451 as length fields would then be added to data that does not reqire 452 a length field for processing. 454 o Encodings MUST result in smallest data representations. There are 455 several cases where the AMM defines types with less granularity 456 than CBOR. For example, AMM defines the UINT type to represent 457 unsigned integers up to 32 bits in length. CBOR supports separate 458 definitions of unsigned integers of 8, 16, or 32 bits in length. 459 In cases where an AMM type MAY be encoded in multiple ways in 460 CBOR, the smallest data representation MUST be used. For example, 461 UINT values of 0-255 MUST be encoded as a uint8_t, and so on. 463 8.2. AMM Type Encodings 465 8.2.1. Primitive Types 467 The AMP encodes AMM primitive types as outlined in Table 3. 469 +--------+-------------+--------------------------------------------+ 470 | AMM | CBOR Major | Comments | 471 | Type | Type | | 472 +--------+-------------+--------------------------------------------+ 473 | BYTE | unsigned | BYTEs are individually encoded as unsigned | 474 | | int or byte | integers unless the are defined as part of | 475 | | string | a byte string, in which case they are | 476 | | | encoded as a single byte in the byte | 477 | | | string. | 478 | | | | 479 | INT | unsigned | INTs are encoded as positive or negative | 480 | | integer or | integers from (u)int8_t up to (u)int32_t. | 481 | | negative | | 482 | | integer | | 483 | | | | 484 | UINT | unsigned | UINTs are unsigned integers from uint8_t | 485 | | integer | up to uint32_t. | 486 | | | | 487 | VAST | unsigned | VASTs are encoding as positive or negative | 488 | | integer or | integers up to (u)int64_t. | 489 | | negative | | 490 | | integer | | 491 | | | | 492 | UVAST | unsigned | VASTs are unsigned integers up to | 493 | | integer | uint64_t. | 494 | | | | 495 | REAL32 | floating | Up to an IEEE-754 Single Precision Float. | 496 | | point | | 497 | | | | 498 | REAL64 | floating | Up to an IEEE-754 Double Precision Float. | 499 | | point | | 500 | | | | 501 | STRING | text string | Uses CBOR encoding unmodified. | 502 | | | | 503 | BOOL | Simple | 0 is considered FALSE. Any other value is | 504 | | Value | considered TRUE. | 505 +--------+-------------+--------------------------------------------+ 507 Table 3: Standard Numeric Types 509 8.2.2. Derived Types 511 This section provides the CBOR encodings for AMM derived types. 513 8.2.2.1. Byte String Encoding 515 The AMM derived type Byte String (BYTESTR) is encoded as a CBOR byte 516 string. 518 8.2.2.2. Time Values (TV) and Timestamps (TS) 520 An TV is encoded as a UVAST. Similarly, a TS is also encoded as a 521 UVAST since a TS is simply an absolute TV. 523 Rather than define two separate encodings for TVs (one for absolute 524 TVs and one for relative TVs) a single, unambiguous encoding can be 525 generated by defining a Relative Time Epoch (RTE) and interpreting 526 the type of TV in relation to that epoch. Time values less than the 527 RTE MUST be interpreted as relative times. Time values greater than 528 or equal to the RTE MUST be interpreted as absolute time values. 530 A relative TV is encoded as the number of seconds after an initiating 531 event. An absolute TV (and TS) is encoded as the number of seconds 532 that have elapsed since 1 Jan 2000 00:00:00 (Unix Time 946684800). 534 The RTE is defined as the timestamp value for September 9th, 2017 535 (Unix time 1504915200). Since TS values are the number of seconds 536 since 1 Jan 2000 00:00:00, the RTE as a TS value is 1504915200 - 537 946684800 = 558230400. 539 The potential values of TV, and how they should be interpreted as 540 relative or absolute is illustrated below. 542 Potential Time values 543 ________________________/\________________________ 544 / \ 545 Relative Times Absolute Times 546 <------------------------><------------------------> 547 0 - 558,230,400 558,230,401 - 2^64 549 |------------------------|-------------------------| 550 | | 551 00:00:00 1 Jan 2000 00:00:00 9 Sep 2017 552 Unix Time 946684800 Unix Time 1504915200 554 For example, a time value of "10" is a relative time representing 10 555 seconds after an initiating event. A time value of "600,000,000" 556 refers to Saturday, 5 Jan, 2019 10:40:00. 558 NOTE: Absolute and relative times are interchangeable. An absolute 559 time can be converted into a relative time by subtracting the current 560 time from the absolute time. A relative time can be converted into 561 an absolute time by adding to the relative time the timestamp of its 562 relative event. A pseudo-code example of converting a relative time 563 to an absolute time is as follows, assuming that current-time is 564 expressed in Unix Epoch time. 566 IF (time_value <= 558230400) THEN 567 absolute_time = (event_time - 946684800) + time_value 568 ELSE 569 absolute_time = time_value 571 8.2.2.3. Type-Name-Value (TNV) 573 TNV values are encoded as a CBOR array that comprises four distinct 574 pieces of information: a set of flags, a type, an optional name, and 575 an optional value. In the E(TNV) the flag and type information are 576 compressed into a single value. The CBOR array MUST have length 1, 577 2, or 3 depending on the number of optional fields appearing in the 578 encoding. The E(TNV) format is illustrated in Figure 2. 580 +---------+ 581 | TNV | 582 | [ARRAY] | 583 +----++---+ 584 || 585 || 586 _______________/ \________________ 587 / \ 588 +------------+-----------+----------+ 589 | Flags/Type | Name | Value | 590 | [BYTE] | [TXT STR] | [Varies] | 591 | | (opt) | (opt) | 592 +------------+-----------+----------+ 594 Figure 2: E(TNV) Format 596 The E(TNV) fields are defined as follows. 598 Flags/Type 599 The first byte of the E(TNV) describes the type associated 600 with the TNV and which optional components are present. The 601 layout of this byte is illustrated in Figure 3. 603 E(TNV) Flag/Type Byte Format 605 +------+---------------+ 606 | Name | Struct | 607 | Flag | Type | 608 +------+---------------+ 609 | 7 | 6 5 4 3 2 1 0 | 610 +------+---------------+ 611 MSB LSB 613 Figure 3 615 Name Flag 616 This flag indicates that the TNV contains a name 617 field. When set to 1 the Name field MUST be present 618 in the E(TNV). When set to 0 the Name field MUST NOT 619 be present in the E(TNV). 621 Struct Type 622 This field lists the type associated with this TNV 623 and MUST contain one of the types defined in 624 [I-D.birrane-dtn-adm] with the exception that the 625 type of a TNV MUST NOT be a TNV. 627 Name 628 This optional field captures the human-readable name for the 629 TNV encoded as a CBOR text string. If there are 3 elements 630 in the TNV array OR there are 2 elements in the array and the 631 Name Flag is set, then this field MUST be present. 632 Otherwise, this field MUST NOT be present. 634 Value 635 This optional field captures the encoded value associated 636 with this TNV. The value is encoded in accordance with AMP 637 rules for encoding of items of the type of this TNV. If 638 there are 3 elements in the TNV array OR there are 2 elements 639 in the array and the Name Flag is not set, then this field 640 MUST be present. Otherwise, this field MUST NOT be present. 642 8.2.3. Collections 644 8.2.3.1. Type-Name-Value Collection (TNVC) 646 A TNV Collection (TNVC) is an ordered set of TNVs with special 647 semantics for more efficiently encoding sets of TNVs with identical 648 attributes. 650 A TNV, defined in Section 8.2.2.3, consists of three distinct 651 components: a type, a name, and a value. When all of the TNVs in the 652 TNVC have the same format (such as they all include type information) 653 then the encoding of the TNVC can use this information to save 654 encoding space and make processing more efficient. In cases when all 655 TNVs have the same format, the types (if present), names (if 656 present), and values (if present) are separated into their own arrays 657 for individual processing with type information (if present) always 658 appearing first. 660 Extracting type information to the "front" of the collection 661 optimizes the performance of type validators. A validator can 662 inspect the first array to ensure that element values match type 663 expectations. If type information were distributed throughout the 664 collection, as in the case with the TNVC, a type validator would need 665 to scan through the entire set of data to validate each type in the 666 collection. 668 A TNVC is encoded as a sequence of at least 1 octet, where the single 669 required octet includes the flag BYTE representing the optional 670 portions of the collection that are present. If the flag BYTE 671 indicates an empty collection there will be no following octets.The 672 format of a TNVC is illustrated in Figure 4. 674 +----------+ 675 | TNVC | 676 | [OCTETS] | 677 +----++----+ 678 || 679 || 680 ____________________________/ \_____________________________ 681 / \ 682 +--------+---------+----------+----------+----------+----------+ 683 | Flags | # Items | Types | Names | Values | Mixed | 684 | [BYTE] | [UINT] | [OCTETS] | [OCTETS] | [OCTETS] | [OCTETS] | 685 | | (Opt) | (Opt) | (Opt) | (Opt) | (Opt) | 686 +--------+---------+----------+----------+----------+----------+ 688 Figure 4: E(TNVC) Format 690 The E(TNVC) fields are defined as follows. 692 Flags 693 The first byte of the E(TNVC) describes which optional 694 portions of a TNV will be present for each TNV in the 695 collection. 697 If all non-reserved flags have the value 0 then the TNVC 698 represents an empty collection, in which case no other 699 information is provided for the E(TNVC). 700 The layout of this byte is illustrated in Figure 5. 702 E(TNV) Flag Byte Format 704 +----------+------+------+------+------+ 705 | Reserved | Mix | Type | Name | Val | 706 | Flags | Flag | Flag | Flag | Flag | 707 +----------+------+------+------+------+ 708 | 7-4 | 3 | 2 | 1 | 0 | 709 +----------+------+------+------+------+ 710 MSB LSB 712 Figure 5 714 Mixed Flag 715 This flag indicates that the set of TNVs in the 716 collection do not all share the same properties and, 717 therefore, the collection is a mix of different types 718 of TNV. When set to 1 the E(TNVC) MUST contain the 719 Mixed Values field and all other flags in this byte 720 MUST be set to 0. When set to 0 the E(TNVC) MUST NOT 721 contain the Mixed Values field. 723 Type Flag 724 This flag indicates whether each TNV in the 725 collection has type information associated with it. 726 When set to 1 the E(TNVC) MUST contain type 727 information for each TNV. When set to 0, type 728 information MUST NOT be present. 730 Name Flag 731 This flag indicates whether each TNV in the 732 collection has name information associated with it. 733 When set to 1 the E(TNVC) MUST contain name 734 information for each TNV. When set to 0, name 735 information MUST NOT be present. 737 Value Flag 738 This flag indicates whether each TNV in the 739 collection has value information associated with it. 740 When set to 1 the E(TNVC) MUST contain value 741 information for each TNV. When set to 0, value 742 information MUST NOT be present. 744 # Items 745 The number of items field lists the number of items that are 746 contained in the TNVC. Each of the types, names, and values 747 sequences (if present) MUST have exactly this number of 748 entries in them. This field MUST be present in the E(TNVC) 749 when any one of the non-reserved bits of the Flag Byte are 750 set to 1. 752 Types 753 The types field is encoded as an OCTETS sequence where the 754 Nth byte in the sequence represents the type for the Nth TNV 755 in the collection. This field MUST be present in the E(TNVC) 756 when the Type Flag is set to 1 and MUST NOT be present 757 otherwise. If present, this field MUST contain exactly the 758 same number of types as number of items in the TNVC. 760 Names 761 The names field is encoded as an OCTETS sequence containing 762 the names of the TNVs in the collection. Each name is 763 encoded as a CBOR string, with the Nth CBOR string 764 representing the name of the Nth TNV in the collection. This 765 field MUST be present in the E(TNVC) when the Names Flag is 766 set to 1 and MUST NOT be present otherwise. If present, this 767 field MUST contain exactly the same number of CBOR strings as 768 number of items in the TNVC. 770 Values 771 The values field is encoded as an OCTETS sequence containing 772 the values of TNVs in the collection. 773 If the Type Flag is set to 1 then each entry will be encoded 774 in accordance with the corresponding index in the type field. 775 For example, the 1st value will be encoded using the encoding 776 rules for the first byte in the type OCTETS sequence. 777 If the Type Flag is set to 0 then the values will be encoded 778 as native CBOR types. CBOR types do not have a one-to-one 779 mapping with AMP types and it is the responsibility of the 780 transmitting AMP actor and the receiving AMP actor to 781 determine how to map these to AMP types. This field MUST be 782 present in the E(TNVC) when the Value Flag is set to 1 and 783 MUST NOT be present otherwise. If present, this field MUST 784 contain exactly the same number of values as number of items 785 in the TNVC. 787 Mixed 788 The mixed field is encoded as an OCTETS sequence containing a 789 series of E(TNV) objects. This field MUST be present when 790 the Mixed Flag is set to 1 and MUST NOT be present otherwise. 791 If present, this field MUST contain exactly the same number 792 of E(TNV) objects as numnber of items in the TNVC. 794 8.2.3.2. ARI Collections (AC) 796 An ARI collection is an ordered collection of ARI values. It is 797 encoded as a CBOR array with each element being an encoded ARI, as 798 illustrated in Figure 6. 800 E(AC) Format 802 +---------+ 803 | AC | 804 | [ARRAY] | 805 +----++---+ 806 || 807 || 808 ________/ \_________ 809 / \ 810 +-------+ +-------+ 811 | ARI 1 | ... | ARI N | 812 | [ARI] | | [ARI] | 813 +-------+ +-------+ 815 Figure 6 817 8.2.3.3. Expressions (EXPR) 819 The Expression object encapsulates a typed postfix expression in 820 which each operator MUST be of type OPER and each operand MUST be the 821 typed result of an operator or one of EDD, VAR, LIT, or CONST. 823 The Expression object is encoded as an OCTETS sequence whose format 824 is illustrated in Figure 7. 826 E(EXPR) Format 828 +----------+ 829 | EXPR | 830 | [OCTETS] | 831 +-----++---+ 832 || 833 || 834 _________/ \_________ 835 / \ 836 +---------+------------+ 837 | Type | Expression | 838 | [BYTE] | [AC] | 839 +---------+------------+ 841 Figure 7 843 Type 844 The enumeration representing the type of the result of the 845 evaluated expression. This type MUST be defined in 846 [I-D.birrane-dtn-adm] as a "Primitive Type". 848 Expression 849 An expression is represented in the AMP as an ARI collection, 850 where each ARI in the ordered collection represents either an 851 operand or operator in postfix form. 853 8.3. AMM Resource Identifier (ARI) 855 The ARI, as defined in [I-D.birrane-dtn-adm], identifies an AMM 856 object. There are two kinds of objects that can be identified in 857 this scheme: literal objects (of type LIT) and all other objects. 859 8.3.1. Encoding ARIs of Type LITERAL 861 A literal identifier is one that is literally defined by its value, 862 such as numbers (0, 3.14) and strings ("example"). ARIs of type 863 LITERAL do not have issuers or nicknames or parameters. They are 864 simply typed basic values. 866 The E(ARI) of a LIT object is encoded as an OCTETS sequence and 867 consists of a mandatory flag BYTE and the value of the LIT. 869 The E(ARI) structure for LIT types is illustrated in Figure 8. 871 E(ARI) Literal Format 873 +--------+----------+ 874 | Flags | Value | 875 | [BYTE] | [VARIES] | 876 +--------+----------+ 878 Figure 8 880 These fields are defined as follows. 882 Flags 883 The Flags byte identifies the object as being of type LIT and 884 also captures the primitive type of the following value. The 885 layout of this byte is illustrated in Figure 9. 887 E(ARI) Literal Flag Byte Format 889 +-------------------+-------------+ 890 | VALUE TYPE OFFSET | STRUCT TYPE | 891 +-------------------+-------------| 892 | 7 6 5 4 | 3 2 1 0 | 893 +-------------------+-------------+ 894 MSB LSB 896 Figure 9 898 Value Type Offset 899 The high nibble of the flag byte contains the offset 900 into the Primitive Types enumeration defined in 901 [I-D.birrane-dtn-adm]. An offset of 0 represents the 902 first defined Primitive Type. An offset of 1 903 represents the second defined Primitive Type, and so 904 on. An offset into the data types field is used to 905 ensure that the type value fits into a nibble. 907 Structure Type 908 The lower nibble of the flag byte identifies the type 909 of AMM Object being identified by the ARI. In this 910 instance, this value MUST be LIT, as defined in 911 [I-D.birrane-dtn-adm]. 913 Value 914 This field captures the CBOR encoding of the value. Values 915 are encoded according to their Value Type as specified in the 916 flag byte in accordance with the encoding rules provided in 917 Section 8.2.1. 919 8.3.2. Encoding Non-Literal ARIs 921 All other ARIs are defined in the context of AMM objects and may 922 contain parameters and other meta-data. The AMP, as a machine-to- 923 machine binary encoding of this information removes human-readable 924 information such as Name and Description from the E(ARI). 925 Additionally, this encoding adds other information to improve the 926 efficiency of the encoding, such as the concept of Nicknames, defined 927 in Section 7.1. 929 The E(ARI) is encoded as an OCTETS sequence and consists of a 930 mandatory flag byte, an encoded object name, and optional annotations 931 to assist with filtering, access control, and parameterization. The 932 E(ARI) structure is illustrated in Figure 10. 934 E(ARI) General Format 936 +--------+---------+-----------+---------+-----------+-----------+ 937 | Flags | NN | Name | Parms | Issuer | Tag | 938 | [BYTE] | [UVAST] | [BYTESTR] | [TNVC] | [BYTESTR] | [BYTESTR] | 939 | | (opt) | | (opt) | (opt) | opt) | 940 +--------+---------+-----------+---------+-----------+-----------+ 942 Figure 10 944 These fields are defined as follows. 946 Flags 947 Flags describe the type of structure and which optional 948 fields are present in the encoding. The layout of the flag 949 byte is illustrated in Figure 11. 951 E(ARI) General Flag Byte Format 953 +----+------+-----+-----+-------------+ 954 | NN | PARM | ISS | TAG | STRUCT TYPE | 955 +----+------+-----+-----+-------------+ 956 | 7 | 6 | 5 | 4 | 3 2 1 0 | 957 +----+------+-----+-----+-------------+ 958 MSB LSB 960 Figure 11 962 Nickname (NN) 963 This flag indicates that ADM compression is used for 964 this E(ARI). When set to 1 the Nickname field MUST 965 be present in the E(ARI). When set to 0 the Nickname 966 field MUST NOT be present in the E(ARI). When an ARI 967 is user-defined, there are no semantics for Nicknames 968 and, therefore, this field MUST be 0 when the Issuer 969 flag is set to 1. Implementations SHOULD use 970 Nicknames whenever possible to reduce the size of the 971 E(ARI). 973 Parameters Present (PARM) 974 This flag indicates that this ARI can be 975 parameterized and that parameter information is 976 included in the E(ARI). When set to 1 the Parms 977 field MUST be present in the E(ARI). When set to 0 978 the Parms field MUST NOT be present in the E(ARI). 980 Issuer Present (ISS) 981 This flag indicates that this ARI is defined in the 982 context of a specific issuing entity. When set to 1 983 the Issuer field MUST be present in the E(ARI). When 984 set to 0 the Issuer field MUST NOT be present in the 985 E(ARI). 987 Tag Present (TAG) 988 This flag indicates that the ARI is defined in the 989 context of a specific issuing entity and that issuing 990 entity adds additional information in the form of a 991 tag. When set to 1 the Tag field MUST be present in 992 the E(ARI). When set to 0 the Tag field MUST NOT be 993 present in the E(ARI). This flag MUST be set to 0 if 994 the Issuer Present flag is set to 0. 996 Structure Type (STRUCT TYPE) 997 The lower nibble of the E(ARI) flag byte identifies 998 the kind of structure being identified. This field 999 MUST contain one of the AMM object types defined in 1000 [I-D.birrane-dtn-adm]. 1002 Nickname (NN) 1003 This optional field contains the Nickname as calculated 1004 according to Section 7.1. 1006 Object Name 1007 This mandatory field contains an encoding of the ADM object. 1008 For elements defined in an ADM Template (e.g., where the 1009 Issuer Flag is set to 0) this is the 0-based index into the 1010 ADM collection holding this element. For all user-defined 1011 ADM objects, (e.g., where the Issuer Flag is set to 1) this 1012 value is as defined by the Issuing organization. 1014 Parameters 1015 The parameters field is represented as a Type Name Value 1016 Collection (TNVC) as defined in Section 8.2.3.1. The overall 1017 number of items in the collection represents the number of 1018 parameters. The types of the TNVC represent the types of 1019 each parameter, with the first listed type associated with 1020 the first parameter, and so on. The values, if present, 1021 represent the values of the parameters, with the first listed 1022 value being the value of the first parameter, and so on. 1024 Issuer 1025 This is a binary identifier representing a predetermined 1026 issuer name. The AMP protocol does not parse or validate 1027 this identifier, using it only as a distinguishing bit 1028 pattern to ensure uniqueness. This value, for example, may 1029 come from a global registry of organizations, an issuing node 1030 address, or some other network-unique marking. The issuer 1031 field MUST NOT be present for any ARI defined in an ADM. 1033 Tag 1034 A value used to disambiguate multiple ARIs with the same 1035 Issuer. The definition of the tag is left to the discretion 1036 of the Issuer. The Tag field MUST be present if the Tag Flag 1037 is set in the flag byte and MUST NOT be present otherwise. 1039 8.4. ADM Object Encodings 1041 The autonomy model codified in [I-D.birrane-dtn-adm] comprises 1042 multiple individual objects. This section describes the CBOR 1043 encoding of these objects. 1045 Note: The encoding of an object refers to the way in which the 1046 complete object can be encoded such that the object as it exists on a 1047 Manager may be re-created on an Agent, and vice-versa. In cases 1048 where both a Manager and an Agent already have the definition of an 1049 object, then only the encoded ARI of the object needs to be 1050 communicated. This is the case for all objects defined in a 1051 published ADM and any user-defined object that has been synchronized 1052 between an Agent and Manager. 1054 8.4.1. Externally Defined Data (EDD) 1056 Externally defined data (EDD) are solely defined in the ADMs for 1057 various applications and protocols. EDDs represent values that are 1058 calculated external to an AMA Agent, such as values measured by 1059 firmware. 1061 The representation of these data is simply their identifying ARIs. 1062 The representation of an EDD is illustrated in Figure 12. 1064 E(EDD) Format 1066 +-------+ 1067 | ID | 1068 | [ARI] | 1069 +-------+ 1071 Figure 12 1073 ID 1074 This is the ARI identifying the EDD. Since EDDs are always 1075 defined solely in the context of an ADM, this ARI MUST NOT 1076 have an ISSUER field and MUST NOT have a TAG field. This ARI 1077 may be defined with parameters. 1079 8.4.2. Constants (CONST) 1081 Unlike Literals, a Constant is an immutable, typed, named value. 1082 Examples of constants include PI to some number of digits or the UNIX 1083 Epoch. 1085 Since ADM definitions are preconfigured on Agents and Managers in an 1086 AMA, the type information for a given Constant is known by all actors 1087 in the system and the encoding of the Constant needs to only be the 1088 name of the constant as the Manager and Agent can derive the type and 1089 value from the unique Constant name. 1091 The format of a Constant is illustrated in Figure 13. 1093 E(CONST) Format 1095 +-------+ 1096 | ID | 1097 | [ARI] | 1098 +-------+ 1100 Figure 13 1102 ID 1103 This is the ARI identifying the Constant. Since Constant 1104 definitions are always provided in an ADM, this ARI MUST NOT 1105 have an ISSUER field and MUST NOT have a TAG field. The ARI 1106 MUST NOT have parameters. 1108 8.4.3. Controls (CTRL) 1110 A Control represents a pre-defined and optionally parameterized 1111 opcode that can be run on an Agent. Controls in the AMP are always 1112 defined in the context of an AMA; there is no concept of an operator- 1113 defined Control. Since Controls are pre-configured in Agents and 1114 Managers as part of ADM support, their representation is the ARI that 1115 identifies them, similar to EDDs. 1117 The format of a Control is illustrated in Figure 14. 1119 E(CTRL) Format 1121 +-------+ 1122 | ID | 1123 | [ARI] | 1124 +-------+ 1126 Figure 14 1128 ID 1129 This is the ARI identifying the Control. This ARI MUST NOT 1130 have an ISSUER field and MUST NOT have a TAG field. This ARI 1131 may have parameters. 1133 8.4.4. Macros (MAC) 1135 Macros in the AMP are ordered collections of ARIs (an AC) that 1136 contain Controls or other Macros. When run by an Agent, each ARI in 1137 the AC MUST be run in order. 1139 Any AMP implementation MUST allow at least 4 levels of Macro nesting. 1140 Implementations MUST prevent recursive nesting of Macros. 1142 The ARI associated with a Macro MAY contain parameters. Each 1143 parameter present in a Macro ARI MUST contain type, name, and value 1144 information. Any Control or Macro encapsulated within a 1145 parameterized Macro MAY also contain parameters. If an encapsulated 1146 object parameter contains only name information, then the parameter 1147 value MUST be taken from the named parameter provided by the 1148 encapsulating Macro. Otherwise, the value provided to the object 1149 MUST be used instead. 1151 The format of a Macro is illustrated in Figure 15. 1153 E(MAC) Format 1155 +-------+------------+ 1156 | ID | Definition | 1157 | [ARI] | [AC] | 1158 +-------+------------+ 1160 Figure 15 1162 ID 1163 This is the ARI identifying the Macro. When a Macro is 1164 defined in an ADM this ARI MUST NOT have an ISSUER field and 1165 MUST NOT have a TAG field. When the Macro is defined outside 1166 of an ADM, the ARI MUST have an ISSUER field and MAY have a 1167 TAG field. 1169 Definition 1170 This is the ordered collection of ARIs that identify the 1171 Controls and other Macros that should be run as part of 1172 running this Macro. 1174 8.4.5. Operators (OPER) 1176 Operators are always defined in the context of an ADM. There is no 1177 concept of a user-defined operator, as operators represent 1178 mathematical functions implemented by the firmware on an Agent. 1179 Since Operators are preconfigured in Agents and Managers as part of 1180 ADM support, their representation is simply the ARI that identifies 1181 them. 1183 The ADM definition of an Operator MUST specify how many parameters 1184 are expected and the expected type of each parameter. For example, 1185 the unary NOT Operator ("!") would accept one parameter. The binary 1186 PLUS Operator ("+") would accept two parameters. A custom function 1187 to calculate the average of the last 10 samples of a data item should 1188 accept 10 parameters. 1190 Operators are always evaluated in the context of an Expression. The 1191 encoding of an Operator is illustrated in Figure 16. 1193 E(OP) Format 1195 +-------+ 1196 | ID | 1197 | [ARI] | 1198 +-------+ 1200 Figure 16 1202 ID 1203 This is the ARI identifying the Operator. Since Operators 1204 are always defined solely in the context of an ADM, this ARI 1205 MUST NOT have an ISSUER field and MUST NOT have a TAG field. 1207 8.4.6. Report Templates (RPTT) 1209 A Report Template is an ordered collection of identifiers that 1210 describe the order and format of data in any Report built in 1211 compliance with the template. A template is a schema for a class of 1212 reports. It contains no actual values and may be defined in a formal 1213 ADM or configured by users in the context of a network deployment. 1215 The encoding of a RPTT is illustrated in Figure 17. 1217 E(RPTT) Format 1219 +-------+----------+ 1220 | ID | Contents | 1221 | [ARI] | [AC] | 1222 +-------+----------+ 1224 Figure 17 1226 ID 1227 This is the ARI identifying the report template. 1229 Contents 1230 This is the ordered collection of ARIs that define the 1231 template. 1233 8.4.7. Report (RPT) 1235 A Report is a set of data values populated using a given Report 1236 Template. While Reports do not contain name information, they MAY 1237 contain type information in cases where recipients wish to perform 1238 type validation prior to interpreting the Report contents in the 1239 context of a Report Template. Reports are "anonymous" in the sense 1240 that any individual Report does not contain a unique identifier. 1241 Reports can be differentiated by examining the combination of (1) the 1242 Report Template being populated, (2) the time at which the Report was 1243 populated, and (3) the Agent producing the report. 1245 A Report object is comprised of the identifier of the template used 1246 to populate the report, an optional timestamp, and the contents of 1247 the report. A Report is encoded as a CBOR array with either 2 or 3 1248 elements. If the array has 2 elements then the optional Timestamp 1249 MUST NOT be in the Report encoding. If the array has 3 elements then 1250 the optional timestamp MUST be included in the Report encoding. The 1251 Report encoding is illustrated in Figure 18. 1253 E(RPT) Format 1255 +---------+ 1256 | RPT | 1257 | [ARRAY] | 1258 +---++----+ 1259 || 1260 || 1261 _____________/ \______________ 1262 / \ 1263 +----------+-----------+----------+ 1264 | Template | Timestamp | Entries | 1265 | [OCTETS: | [TS] | [OCTETS: | 1266 | ARI] | (opt) | TNVC] | 1267 +----------+-----------+----------+ 1269 Figure 18 1271 Template 1272 This is the ARI identifying the template used to interpret 1273 the data in this report. 1275 This ARI may be parameterized and, if so, the parameters MUST 1276 include a name field and have been passed-by-name to the 1277 template contents when constructing the report. 1279 Timestamp 1280 The timestamp marks the time at which the report was created. 1281 This timestamp may be omitted in cases where the time of the 1282 report generation can be inferred from other information. 1283 For example, if a report is included in a message group such 1284 that the timestamp of the message group is equivalent to the 1285 timestamp of the report, the report timestamp may be omitted 1286 and the timestamp of the included message group used instead. 1288 Entries 1289 This is the collection of data values that comprise the 1290 report contents in accordance with the associated Report 1291 Template. 1293 8.4.8. State-Based Rules (SBR) 1295 A State-Based Rule (SBR) specifies that a particular action should be 1296 taken by an Agent based on some evaluation of the internal state of 1297 the Agent. A SBR specifies that starting at a particular START time 1298 an ACTION should be run by the Agent if some CONDITION evaluates to 1299 true, until the ACTION has been run COUNT times. When the SBR is no 1300 longer valid it may be discarded by the agent. 1302 Examples of SBRs include: 1304 Starting 2 hours from receipt, whenever V1 > 10, produce a Report 1305 for Report Template R1 no more than 20 times. 1307 Starting at some future absolute time, whenever V2 != V4, run 1308 Macro M1 no more than 36 times. 1310 An SBR object is encoded as an OCTETS sequence as illustrated in 1311 Figure 19. 1313 E(SBR) Format 1315 +----------+ 1316 | SBR | 1317 | [OCTETS] | 1318 +----++----+ 1319 || 1320 || 1321 _______________________/ \_______________________ 1322 / \ 1323 +-------+-------+--------+--------+--------+--------+ 1324 | ID | START | COND | EVALS | FIRES | ACTION | 1325 | [ARI] | [TV] | [EXPR] | [UINT] | [UINT] | [AC] | 1326 +-------+-------+--------+--------+--------+--------+ 1328 Figure 19 1330 ID 1331 This is the ARI identifying the SBR. If this ARI contains 1332 parameters they MUST include a name in support of pass-by- 1333 name to each element of the Action AC. 1335 START 1336 The time at which the SBR condition should start to be 1337 evaluated. This will mark the first evaluation of the 1338 condition associated with the SBR. 1340 CONDITION 1341 The Expression which, if true, results in the SBR running the 1342 associated action. An EXPR is considered true if it 1343 evaluates to a non-zero value. 1345 EVALS 1346 The number of times the SBR condition can be evaluated. The 1347 special value of 0 indicates there is no limit on how many 1348 times the condition can be evaluated. 1350 FIRES 1351 The number of times the SBR action can be run. The special 1352 value of 0 indicates there is no limit on how many times the 1353 action can be run. 1355 ACTION 1356 The collection of Controls and/or Macros to run as part of 1357 the action. This is encoded as an AC in accordance with 1358 Section 8.2.3.2 with the stipulation that every ARI in this 1359 collection MUST be of type CTRL or MAC. 1361 8.4.9. Table Templates (TBLT) 1363 A Table Template (TBLT) describes the types, and optionally names, of 1364 the columns that define a Table. 1366 Because TBLTs are only defined in the context of an ADM, their 1367 definition cannot change operationally. Therefore, a TBLT is encoded 1368 simply as the ARI for the template. The format of the TBLT Object 1369 Array is illustrated in Figure 20. 1371 E(TBLT) Format 1373 +-------+ 1374 | ID | 1375 | [ARI] | 1376 +-------+ 1378 Figure 20 1380 The elements of the TBLT array are defined as follows. 1382 ID 1383 This is the ARI of the table template encoded in accordance 1384 with Section 8.3. 1386 8.4.10. Tables (TBL) 1388 A Table object describes the series of values associated with a 1389 Table Template. 1391 A Table object is encoded as a CBOR array, with the first element of 1392 the array identifying the Table Template and each subsequent element 1393 identifying a row in the table. The format of the TBL Object Array 1394 is illustrated in Figure 21. 1396 E(TBL) Format 1398 +---------+ 1399 | TBL | 1400 | [ARRAY] | 1401 +---++----+ 1402 || 1403 || 1404 ______________/ \_______________ 1405 / \ 1406 +---------+--------+ +--------+ 1407 | TBLT ID | Row 1 | | Row N | 1408 | [ARI] | [TNVC] | ... | [TNVC] | 1409 +---------+--------+ +--------+ 1411 Figure 21 1413 The TBL fields are defined as follows. 1415 Template ID (TBLT ID) 1416 This is the ARI of the table template describing the format 1417 of the table and is encoded in accordance with Section 8.3. 1419 Row 1420 Each row of the table is represented as a series of values 1421 with optional type information to aid in type checking table 1422 contents to column types. Each row is encoded as a TNVC and 1423 MAY include type information. AMP implementations should 1424 consider the impact of including type information for every 1425 row on the overall size of the encoded table. 1426 Each TNVC representing a row MUST contain the same number of 1427 elements as there are columns in the referenced 1428 Table Template. 1430 8.4.11. Time-Based Rules (TBR) 1432 A Time-Based Rule (TBR) specifies that a particular action should be 1433 taken by an Agent based on some time interval. A TBR specifies that 1434 starting at a particular START time, and for every PERIOD seconds 1435 thereafter, an ACTION should be run by the Agent until the ACTION has 1436 been run for COUNT times. When the TBR is no longer valid it MAY BE 1437 discarded by the Agent. 1439 Examples of TBRs include: 1441 Starting 2 hours from receipt, produce a Report for Report 1442 Template R1 every 10 hours ending after 20 times. 1444 Starting at the given absolute time, run Macro M1 every 24 hours 1445 ending after 365 times. 1447 The TBR object is encoded as an OCTETS sequence as illustrated in 1448 Figure 22. 1450 E(TBR) Format 1452 +----------+ 1453 | TBR | 1454 | [OCTETS] | 1455 +----++----+ 1456 || 1457 || 1458 ___________________/ \___________________ 1459 / \ 1460 +-------+-------+--------+--------+--------+ 1461 | ID | START | PERIOD | COUNT | ACTION | 1462 | [ARI] | [TV] | [UINT] | [UINT] | [AC] | 1463 +-------+-------+--------+--------+--------+ 1465 Figure 22 1467 ID 1468 This is the ARI identifying the TBR and is encoded in 1469 accordance with Section 8.3. If this ARI contains parameters 1470 they MUST include a name in support of pass-by-name to each 1471 element of the Action AC. 1473 START 1474 The time at which the TBR condition should start to be 1475 evaluated. 1477 PERIOD 1478 The number of seconds to wait between running the action 1479 associated with the TBR. 1481 COUNT 1482 The number of times the TBR action can be run. The special 1483 value of 0 indicates there is no limit on how many times the 1484 action can be run. 1486 ACTION 1487 The collection of Controls and/or Macros to run as part of 1488 the action. This is encoded as an ARI Collection in 1489 accordance with Section 8.2.3.2 with the stipulation that 1490 every ARI in this collection MUST represent either a Control 1491 or a Macro. 1493 8.4.12. Variables (VAR) 1495 Variable objects are transmitted in the AMP without the human- 1496 readable description. 1498 Variable objects are encoded as an OCTETS sequence whose format is 1499 illustrated in Figure 23. 1501 E(VAR) Format 1503 +-----------+ 1504 | Variable | 1505 | [OCTETS] | 1506 +-----++----+ 1507 || 1508 || 1509 ______/ \_____ 1510 / \ 1511 +-------+-------+ 1512 | ID | Value | 1513 | [ARI] | [TNV] | 1514 +-------+-------+ 1516 Figure 23 1518 ID 1519 This is the ARI identifying the VAR and is encoded in 1520 accordance with Section 8.3. This ARI MUST NOT include 1521 parameters. 1523 Value 1524 This field captures the value (and optionally the type and 1525 name) of the variable, encoded as a TNV. 1527 9. Functional Specification 1529 This section describes the format of the messages that comprise the 1530 AMP protocol. 1532 9.1. AMP Message Summary 1534 The AMP message specification is limited to three basic 1535 communications: 1537 +------------+-------------+----------------------------------------+ 1538 | Message | Enumeration | Description | 1539 +------------+-------------+----------------------------------------+ 1540 | Register | 0 | Add Agents to the list of managed | 1541 | Agent | | devices known to a Manager. | 1542 | | | | 1543 | Report Set | 1 | Receiving a Report of one or more | 1544 | | | Report Entries from an Agent. | 1545 | | | | 1546 | Perform | 2 | Sending a Macro of one or more | 1547 | Control | | Controls to an Agent. | 1548 | | | | 1549 | Table Set | 3 | Receiving one or more tables from an | 1550 | | | Agent. | 1551 +------------+-------------+----------------------------------------+ 1553 Table 4: ADM Message Type Enumerations 1555 The entire management of a network can be performed using these three 1556 messages and the configurations from associated ADMs. 1558 9.2. Message Group Format 1560 Individual messages within the AMP are combined into a single group 1561 for communication with another AMP Actor. Messages within a group 1562 MUST be received and applied as an atomic unit. The format of a 1563 message group is illustrated in Figure 24. These message groups are 1564 assumed communicated amongst Agents and Managers as the payloads of 1565 encapsulating protocols which should provide additional security and 1566 data integrity features as needed. 1568 A message group is encoded as a CBOR array with at least 2 elements, 1569 the first being the time the group was created followed by 1 or more 1570 messages that comprise the group. The format of the message group is 1571 illustrated in Figure 24. 1573 AMP Message Group Format 1575 +---------------+ 1576 | Message Group | 1577 | [ARRAY] | 1578 +------++-------+ 1579 || 1580 ____________________||___________________ 1581 / \ 1582 +-----------+-----------+ +-----------+ 1583 | Timestamp | Message 1 | ... | Message N | 1584 | [TS] | [BYTESTR] | | [BYTESTR] | 1585 +-----------+-----------+ +-----------+ 1587 Figure 24 1589 Timestamp 1590 The creation time for this messaging group. Individual 1591 messages may have their own creation timestamps based on 1592 their type, but the group timestamp also serves as the 1593 default creation timestamp for every message in the group. 1594 This is encoded in accordance with Table 3. 1596 Message N 1597 The Nth message in the group. 1599 9.3. Message Format 1601 Each message identified in the AMP specification adheres to a common 1602 message format, illustrated in Figure 25, consisting of a message 1603 header, a message body, and an optional trailer. 1605 Each message in the AMP is encode as an OCTETS sequence formatted in 1606 accordance with Figure 25. 1608 AMP Message Format 1610 +--------+----------+----------+ 1611 | Header | Body | Trailer | 1612 | [BYTE] | [VARIES] | [VARIES] | 1613 | | | (opt.) | 1614 +--------+----------+----------+ 1616 Figure 25 1618 Header 1619 The message header BYTE is shown in Figure 26. The header 1620 identifies a message context and opcode as well as flags that 1621 control whether a Report should be generated on message 1622 success (Ack) and whether a Report should be generated on 1623 message failure (Nack). 1625 AMP Common Message Header 1627 +----------+-----+------+-----+----------+ 1628 | Reserved | ACL | Nack | Ack | Opcode | 1629 +----------+-----+------+-----+----------+ 1630 | 7 6 | 5 | 4 | 3 | 2 1 0 | 1631 +----------+-----+------+-----+----------+ 1632 MSB LSB 1634 Figure 26 1636 Opcode 1637 The opcode field identifies which AMP message is 1638 being represented. 1640 ACK Flag 1641 The ACK flag describes whether successful application 1642 of the message must generate an acknowledgment back 1643 to the message sender. If this flag is set (1) then 1644 the receiving actor MUST generate a Report 1645 communicating this status. Otherwise, the actor MAY 1646 generate such a Report based on other criteria. 1648 NACK Flag 1649 The NACK flag describes whether a failure applying 1650 the message must generate an error notice back to the 1651 message sender. If this flag is set (1) then the 1652 receiving Actor MUST generate a Report communicating 1653 this status. Otherwise, the Actor MAY generate such 1654 a Report based on other criteria. 1656 ACL Used Flag 1657 The ACL used flag indicates whether the message has a 1658 trailer associated with it that specifies the list of 1659 AMP actors that may participate in the Actions or 1660 definitions associated with the message. This area 1661 is still under development. 1663 Body 1664 The message body contains the information associated with the 1665 given message. 1667 Trailer 1668 An OPTIONAL access control list (ACL) may be appended as a 1669 trailer to a message. When present, the ACL for a message 1670 identifiers the agents and managers that can be affected by 1671 the definitions and actions contained within the message. 1672 The explicit impact of an ACL is described in the context of 1673 each message below. When an ACL trailer is not present, the 1674 message results may be visible to any AMP Actor in the 1675 network, pursuant to other security protocol implementations. 1677 9.4. Register Agent 1679 The Register Agent message is used to inform an AMP Manager of the 1680 presence of another Agent in the network. 1682 The body of this message is the name of the new agent, encoded as 1683 illustrated in Figure 27. 1685 Register Agent Message Body 1687 +-----------+ 1688 | Agent ID | 1689 | [BYTESTR] | 1690 +-----------+ 1692 Figure 27 1694 Agent ID 1695 The Agent ID MUST represent the unique address of the Agent 1696 in whatever protocol is used to communicate with the Agent. 1698 9.5. Report Set 1700 The Report Set message contains a set of 1 or more Reports produced 1701 by an AMP Agent and sent to an AMP Manager. 1703 The body of this message contains information on the recipient of the 1704 reports followed by one or more Reports. The body is encoded as 1705 illustrated in Figure 28. 1707 Report Set Message Body 1709 +----------+----------+ 1710 | RX Names | Reports | 1711 | [ARRAY] | [ARRAY] | 1712 +----------+----------+ 1714 Figure 28 1716 RX Names 1717 This field captures the set of Managers that have been sent 1718 this report set. This is encoded as a CBOR array that MUST 1719 have at least one entry. Each entry in this array is encoded 1720 as a CBOR text string. 1722 Reports 1723 This field captures the set of reports being sent. This is 1724 encoded as a CBOR array that MUST have at least one entry. 1725 Each entry in this array is encoded as a RPT in accordance 1726 with Section 8.4.7. 1728 9.6. Perform Control 1730 The perform control message causes the receiving AMP Actor to run one 1731 or more preconfigured Controls provided in the message. 1733 The body of this message is the start time for the controls followed 1734 by the controls themselves, as illustrated in Figure 29. 1736 Perform Control Message Body 1738 +-------+-----------+ 1739 | Start | Controls | 1740 | [TV] | [AC] | 1741 +-------+-----------+ 1743 Figure 29 1745 Start 1746 The time at which the Controls/Macros should be run. 1748 Controls 1749 The collection of ARIs that represent the Controls and/or 1750 Macros to be run by the AMP Actor. Every ARI in this 1751 collection MUST be either a Control or a Macro. 1753 9.7. Table Set 1755 The Table Set message contains a set of 1 or more TBLs produced by an 1756 AMP Agent and sent to an AMP Manager. 1758 The body of this message contains information on the recipient of the 1759 tables followed by one or more TBLs. The body is encoded as 1760 illustrated in Figure 30. 1762 Table Set Message Body 1764 +----------+----------+ 1765 | RX Names | Tables | 1766 | [ARRAY] | [ARRAY] | 1767 +----------+----------+ 1769 Figure 30 1771 RX Names 1772 This field captures the set of Managers that have been sent 1773 this table set. This is encoded as a CBOR array that MUST 1774 have at least one entry. Each entry in this array is encoded 1775 as a CBOR text string. 1777 Tables 1778 This field captures the set of tables being sent. This is 1779 encoded as a CBOR array that MUST have at least one entry. 1780 Each entry in this array is encoded as a TBL in accordance 1781 with Section 8.4.10. 1783 10. IANA Considerations 1785 A Nickname registry needs to be established. 1787 11. Security Considerations 1789 Security within the AMP exists in two layers: transport layer 1790 security and access control. 1792 Transport-layer security addresses the questions of authentication, 1793 integrity, and confidentiality associated with the transport of 1794 messages between and amongst Managers and Agents. This security is 1795 applied before any particular Actor in the system receives data and, 1796 therefore, is outside of the scope of this document. 1798 Finer grain application security is done via ACLs provided in the AMP 1799 message headers. 1801 12. Implementation Notes 1803 A reference implementation of this version of the AMP specification 1804 is available in the 3.6.2 release of the ION open source code base 1805 available from sourceforge at https://sourceforge.net/projects/ion- 1806 dtn/. 1808 13. References 1810 13.1. Informative References 1812 [I-D.birrane-dtn-ama] 1813 Birrane, E., "Asynchronous Management Architecture", 1814 draft-birrane-dtn-ama-07 (work in progress), June 2018. 1816 13.2. Normative References 1818 [I-D.birrane-dtn-adm] 1819 Birrane, E., DiPietro, E., and D. Linko, "AMA Application 1820 Data Model", draft-birrane-dtn-adm-02 (work in progress), 1821 June 2018. 1823 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1824 Requirement Levels", BCP 14, RFC 2119, 1825 DOI 10.17487/RFC2119, March 1997, 1826 . 1828 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1829 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1830 October 2013, . 1832 Appendix A. Acknowledgements 1834 The following participants contributed technical material, use cases, 1835 and useful thoughts on the overall approach to this protocol 1836 specification: Jeremy Pierce-Mayer of INSYEN AG contributed the 1837 concept of the typed data collection and early type checking in the 1838 protocol. David Linko and Evana DiPietro of the Johns Hopkins 1839 University Applied Physics Laboratory contributed appreciated review 1840 and type checking of various elements of this specification. 1842 Author's Address 1844 Edward J. Birrane 1845 Johns Hopkins Applied Physics Laboratory 1847 Email: Edward.Birrane@jhuapl.edu