idnits 2.17.1 draft-birrane-dtn-amp-06.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 (March 11, 2019) is 1872 days in the past. Is this intentional? 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 245, but not defined == Missing Reference: 'TYPE 2' is mentioned on line 245, but not defined == Missing Reference: 'ARRAY' is mentioned on line 1653, but not defined == Missing Reference: 'BYTE' is mentioned on line 1554, but not defined == Missing Reference: 'TXT STR' is mentioned on line 563, but not defined == Missing Reference: 'Varies' is mentioned on line 563, but not defined == Missing Reference: 'BYTESTR' is mentioned on line 1631, but not defined == Missing Reference: 'ARI' is mentioned on line 1458, but not defined == Missing Reference: 'AC' is mentioned on line 1679, but not defined == Missing Reference: 'VARIES' is mentioned on line 1554, but not defined == Missing Reference: 'UVAST' is mentioned on line 883, but not defined == Missing Reference: 'TNVC' is mentioned on line 1353, but not defined == Missing Reference: 'TS' is mentioned on line 1526, but not defined == Missing Reference: 'TV' is mentioned on line 1679, but not defined == Missing Reference: 'EXPR' is mentioned on line 1270, but not defined == Missing Reference: 'UINT' is mentioned on line 1407, but not defined == Missing Reference: 'TNV' is mentioned on line 1458, but not defined == Missing Reference: 'RPT' is mentioned on line 1653, 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 (==), 1 comment (--). 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 March 11, 2019 5 Expires: September 12, 2019 7 Asynchronous Management Protocol 8 draft-birrane-dtn-amp-06 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 September 12, 2019. 37 Copyright Notice 39 Copyright (c) 2019 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 Object Type Enumeration . . . . . . . . . . . . . 7 67 7.1.4. Nickname Definition . . . . . . . . . . . . . . . . . 8 68 7.1.5. ADM Enumeration Considerations . . . . . . . . . . . 9 69 8. Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . 9 70 8.1. CBOR Considerations . . . . . . . . . . . . . . . . . . . 9 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 . . . . . . . . . . . . . . . . . . 22 79 8.4.1. Externally Defined Data (EDD) . . . . . . . . . . . . 23 80 8.4.2. Constants (CONST) . . . . . . . . . . . . . . . . . . 23 81 8.4.3. Controls (CTRL) . . . . . . . . . . . . . . . . . . . 24 82 8.4.4. Macros (MAC) . . . . . . . . . . . . . . . . . . . . 24 83 8.4.5. Operators (OPER) . . . . . . . . . . . . . . . . . . 25 84 8.4.6. Report Templates (RPTT) . . . . . . . . . . . . . . . 26 85 8.4.7. Report (RPT) . . . . . . . . . . . . . . . . . . . . 26 86 8.4.8. State-Based Rules (SBR) . . . . . . . . . . . . . . . 28 87 8.4.9. Table Templates (TBLT) . . . . . . . . . . . . . . . 29 88 8.4.10. Tables (TBL) . . . . . . . . . . . . . . . . . . . . 30 89 8.4.11. Time-Based Rules (TBR) . . . . . . . . . . . . . . . 31 90 8.4.12. Variables (VAR) . . . . . . . . . . . . . . . . . . . 32 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 . . . . . . . . . . . . . . . . . . . . . 36 96 9.5. Report Set . . . . . . . . . . . . . . . . . . . . . . . 37 97 9.6. Perform Control . . . . . . . . . . . . . . . . . . . . . 37 98 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38 99 11. Security Considerations . . . . . . . . . . . . . . . . . . . 38 100 12. Implementation Notes . . . . . . . . . . . . . . . . . . . . 38 101 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 102 13.1. Informative References . . . . . . . . . . . . . . . . . 39 103 13.2. Normative References . . . . . . . . . . . . . . . . . . 39 104 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 39 105 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 39 107 1. Introduction 109 Network management in challenged and resource constrained networks 110 must be accomplished differently than the network management methods 111 in high-rate, high-availability networks. The Asynchronous 112 Management Architecture (AMA) [I-D.birrane-dtn-ama] provides an 113 overview and justification of an alternative to "synchronous" 114 management services such as those provided by NETCONF. In 115 particular, the AMA defines the need for a flexible, robust, and 116 efficient autonomy engine to handle decisions when operators cannot 117 be active in the network. The logical description of that autonomous 118 model and its major components is given in the AMA Data Model (ADM) 119 [I-D.birrane-dtn-adm]. 121 The ADM presents an efficient and expressive autonomy model for the 122 asynchronous management of a network node, but does not specify any 123 particular encoding. This document, the Asynchronous Management 124 Protocol (AMP), provides a binary encoding of AMM objects and 125 specifies a protocol for the exchange of these encoded objects. 127 2. Requirements Language 129 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 130 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 131 document are to be interpreted as described in [RFC2119]. 133 3. Scope 135 3.1. Protocol Scope 137 The AMP provides data monitoring, administration, and configuration 138 for applications operating above the data link layer of the OSI 139 networking model. While the AMP may be configured to support the 140 management of network layer protocols, it also uses these protocol 141 stacks to encapsulate and communicate its own messages. 143 It is assumed that the protocols used to carry AMP messages provide 144 addressing, confidentiality, integrity, security, fragmentation/ 145 reassembly, and other network functions. Therefore, these items are 146 outside of the scope of this document. 148 3.2. Specification Scope 150 This document describes the format of messages used to exchange data 151 models between managing and managed devices in a network. The 152 rationale for this type of exchange is outside of the scope of this 153 document and is covered in [I-D.birrane-dtn-ama]. The description 154 and explanation of the data models exchanged is also outside of the 155 scope of this document and is covered in [I-D.birrane-dtn-adm]. 157 This document does not address specific configurations of AMP-enabled 158 devices, nor does it discuss the interface between AMP and other 159 management protocols. 161 4. Terminology 163 Note: The terms "Actor", "Agent", "Application Data Model", 164 "Externally Defined Data", "Variable", "Control", "Literal", "Macro", 165 "Manager", "Report Template", "Report", "Table", "Constant", 166 "Operator", "Time-Based Rule" and "State-Based Rule" are used without 167 modification from the definitions provided in [I-D.birrane-dtn-ama]. 169 5. Constraints and Assumptions 171 The desirable properties of an asynchronous management protocol, as 172 specified in the AMA, are summarized here to represent design 173 constraints on the AMP specification. 175 o Intelligent Push of Information - Nodes in a challenged network 176 cannot guarantee concurrent, bi-directional communications. Some 177 links between nodes may be strictly unidirectional. AMP Agents 178 "push" data to Managers rather than Managers "pulling" data from 179 Agents. 181 o Small Message Sizes - Smaller messages require smaller periods of 182 viable transmission for communication, incur less retransmission 183 cost, and consume fewer resources when persistently stored en 184 route in the network. AMP minimizes message size wherever 185 practical, to include binary data representations and predefined 186 data definitions and templates. 188 o Absolute and Custom Data Identification - All data in the system 189 must be uniquely addressable, to include operator-specified 190 information. AMP provides a compact encoding for identifiers. 192 o Autonomous, Stateless Operation - There is no reliable concept of 193 session establishment or round-trip data exchange in asynchronous 194 networks. AMP is designed to be stateless. Where helpful, AMP 195 provides mechanisms for transactional ordering of commands within 196 a single AMP protocol data unit, but otherwise degrades gracefully 197 when nodes in the network diver in their configuration. 199 6. Technical Notes 201 o Unless otherwise specified, multi-byte values in this 202 specification are expected to be transmitted in network byte order 203 (Big Endian). 205 o Character encodings for all text-based data types will use UTF-8 206 encodings. 208 o All AMP encodings are self-terminating. This means that, given an 209 indefinite-length octet stream, each encoding can be unambiguously 210 decoded from the stream without requiring additional information 211 such as a length field separate from the data type definition. 213 o Bit-fields in this document are specified with bit position 0 214 holding the least-significant bit (LSB). When illustrated in this 215 document, the LSB appears on the right. 217 o In order to describe the encoding of data models specified in 218 [I-D.birrane-dtn-adm], this specification must refer to both the 219 data object being encoded and to the encoding of that data object. 220 When discussing the encoded version of a data object, this 221 specification uses the notation "E(data_object)" where E() refers 222 to a conceptual encoding function. This notation is only provided 223 as a means of clarifying the text and imposes no changes to the 224 actual wire coding. For example, this specification will refer to 225 the "macro" data object as "Macro" and to the encoding of a Macro 226 as "E(Macro)". 228 o Illustrations of fields in this specification consist of the name 229 of the field, the type of the field between []'s, and if the field 230 is optional, the text "(opt)". 231 Field order is deterministic and, therefore, fields MUST be 232 transmitted in the order in which they are specified. In cases 233 where an optional field is not present, then the next field will 234 be considered for transmission. 235 An example is shown in Figure 1 below. In this illustration two 236 fields (Field 1 and Field 2) are shown, with Field 1 of Type 1 and 237 Field 2 of Type 2. Field 2 is also listed as being optional. 238 Byte fields are shown in order of receipt, from left-to-right. 240 Therefore, when transmitted on the wire, Field 1 will be received 241 first, followed by Field 2 (if present). 243 +----------+----------+ 244 | Field 1 | Field 2 | 245 | [TYPE 1] | [TYPE 2] | 246 | | (opt) | 247 +----------+----------+ 249 Figure 1: Byte Field Formatting Example 251 When types are documented in this way, the type always refers to 252 the encoding of that type. The E() notation is not used as it is 253 to be inferred from the context of the illustration. 255 7. AMP-Specific Concepts 257 The AMP specification provides an encoding of objects comprising the 258 AMM. As such, AMP defines very few structures of its own. This 259 section identifies those data structures that are unique to the AMP 260 and required for it to perform appropriate and efficient encodings of 261 AMM objects. 263 7.1. Nicknames (NN) 265 In the AMP, a "Nickname" (NN) is used to reduce the overall size of 266 the encoding of ARIs that are defined in the context of an ADM. A NN 267 is calculated as a function of an ADM Moderated Namespace and the 268 type of object being identified. 270 7.1.1. Motivation for Compression 272 As identifiers, ARIs are used heavily in AMM object definitions, 273 particularly in those that define collections of objects. This makes 274 encoding ARIs an important consideration when trying to optimize the 275 size of AMP message. 277 Additionally, the majority of ARIs are defined in the context of an 278 ADM. Certain AMM objects types (EDDs, OPs, CTRLs, TBLTs) can only be 279 defined in the context of an ADM. Other object types (VARs, CONSTs, 280 RPTTs) may have common, useful objects defined in an ADM as well. 281 The structure of an ADM, to include its use of a Moderated Namespace 282 and collections by object type, provide a regular structure that can 283 be exploited for creating a compact representation. 285 In particular, as specified in [I-D.birrane-dtn-adm], ARIs can be 286 grouped by (1) their namespace and (2) the type of AMM object being 287 identified. For example, consider the following ARIs of type EDD 288 defined in ADM1 with a Moderated Namespace of "/DTN/ADM1/". 290 ari:/DTN/ADM1/Edd.item_1 ari:/DTN/ADM1/Edd.item_2 ... ari:/DTN/ADM1/ 291 Edd.item_1974 293 In this case, the namespace (/DTN/ADM1/) and the object type (Edd) 294 are good candidates for enumeration because their string encoding is 295 very verbose and their information follows a regular structure shared 296 across multiple ARIs. Separately, the string representation of 297 object names (item_1, item_2, etc...) may be very verbose and they 298 are also candidates for enumeration as they occupy a particular ADM 299 object type in a particular order as published in the ADM. 301 7.1.2. ADM Enumeration 303 Any ARI defined in an ADM exists in the context of a Moderated 304 Namespace. These namespaces provide a unique string name for the 305 ADM. However, ADMs can also be assigned a unique enumeration by the 306 same moderating entities that ensure namespace uniqueness. 308 An ADM enumeration is an unsigned integer in the range of 0 to 309 (2^64)/20. This range provides effective support for thousands of 310 trillions of ADMs. 312 The formal set of ADMs, similar to SNMP MIBs and NETCONF YANG models, 313 will be moderated and published. Additionally, a set of informal 314 ADMs may be developed on a network-by-network or on an organization- 315 by-organization bases. 317 Since informal ADMs exist within a predefined context (a network, an 318 organization, or some other entity) they do not have individual ADM 319 enumerations and are assigned the special enumeration "0". ARIs that 320 are not defined in formal ADMs rely on other context information to 321 help with their encoding (see Section 8.3). 323 7.1.3. ADM Object Type Enumeration 325 An ADM Object Type Enumeration is an unsigned integer in the range of 326 0 - 19. This covers all of the standard areas for the ADM Template 327 as defined in [I-D.birrane-dtn-adm]. Each of these types are 328 enumerated in Table 1. 330 +-----------------+-------------+ 331 | AMM Object Type | Enumeration | 332 +-----------------+-------------+ 333 | CONST | 0 | 334 | | | 335 | CTRL | 1 | 336 | | | 337 | EDD | 2 | 338 | | | 339 | MAC | 3 | 340 | | | 341 | OPER | 4 | 342 | | | 343 | RPTT | 5 | 344 | | | 345 | SBR | 6 | 346 | | | 347 | TBLT | 7 | 348 | | | 349 | TBR | 8 | 350 | | | 351 | VAR | 9 | 352 | | | 353 | metadata | 10 | 354 | | | 355 | reserved | 11-19 | 356 +-----------------+-------------+ 358 Table 1: ADM Type Enumerations 360 7.1.4. Nickname Definition 362 As an enumeration, a Nickname is captured as a 64-bit unsigned 363 integer (UVAST) calculated as a function of the ADM enumeration and 364 the ADM type enumeration, as follows. 366 NN = ((ADM Enumeration) * 20) + (ADM Object Type Enumeration) 368 Considering the example set of ARIs from Section 7.1.1, assuming that 369 ADM1 has ADM enumeration 9 and given that objects in the example were 370 of type EDD, the NN for each of the 1974 items would be: (9 * 20) + 2 371 = 182. In this particular example, the ARI "/DTN/ADM1/Edd.item_1974" 372 can be encoded in 5 bytes: two bytes to CBOR encode the nickname 373 (182) and 3 bytes to CBOR encode the item's offset in the Edd 374 collection (1974). 376 7.1.5. ADM Enumeration Considerations 378 The assignment of formal ADM enumerations SHOULD take into 379 consideration the nature of the applications and protocols to which 380 the ADM applies. Those ADMs that are likely to be used in challenged 381 networks SHOULD be allocated low enumeration numbers (e.g. those that 382 will fit into 1-2 bytes) while ADMs that are likely to only be used 383 in well resourced networks SHOULD be allocated higher enumeration 384 numbers. It SHOULD NOT be the case that ADM enumerations are 385 allocated on a first-come, first-served basis. It is recommended 386 that ADM enumerations should be labeled based on the number of bytes 387 of the Nickname as a function of the size of the ADM enumeration. 388 These labels are shown in Table 2. 390 +-------------+--------+--------------+-----------------------------+ 391 | ADM Enum | NN | Label | Comment | 392 | | Size | | | 393 +-------------+--------+--------------+-----------------------------+ 394 | 0x1 - 0xCCC | 1-2 | Challenged | Constraints imposed by | 395 | | Bytes | Networks | physical layer and power. | 396 | | | | | 397 | 0xCCD - | 3-4 | Congested | Constraints imposed by | 398 | 0xCCCCCCC | Bytes | Networks | network traffic. | 399 | | | | | 400 | >=0xCCCCCCD | 5-8 | Resourced | Generally unconstrained | 401 | | Bytes | Networks | networks. | 402 +-------------+--------+--------------+-----------------------------+ 404 Table 2: ADM Enumerations Labels 406 8. Encodings 408 This section describes the binary encoding of logical data constructs 409 using the Concise Binary Object Representation (CBOR) defined in 410 [RFC7049]. 412 8.1. CBOR Considerations 414 The following considerations act as guidance for CBOR encoders and 415 decoders implementing the AMP. 417 o All AMP encodings are of definite length and, therefore, 418 indefinite encodings MUST NOT be used. 420 o AMP encodings MUST NOT use CBOR tags. Identification mechanisms 421 in the AMP capture structure and other information such that tags 422 are not necessary. 424 o Canonical CBOR MUST be used for all encoding. All AMP CBOR 425 decoders MUST run in strict mode. 427 o Encodings MUST result in smallest data representations. There are 428 several cases where the AMM defines types with less granularity 429 than CBOR. For example, AMM defines the UINT type to represent 430 unsigned integers up to 32 bits in length. CBOR supports separate 431 definitions of unsigned integers of 8, 16, or 32 bits in length. 432 In cases where an AMM type MAY be encoded in multiple ways in 433 CBOR, the smallest data representation MUST be used. For example, 434 UINT values of 0-255 MUST be encoded as a uint8_t, and so on. 436 8.2. AMM Type Encodings 438 8.2.1. Primitive Types 440 The AMP encodes AMM primitive types as outlined in Table 3. 442 +--------+-------------+--------------------------------------------+ 443 | AMM | CBOR Major | Comments | 444 | Type | Type | | 445 +--------+-------------+--------------------------------------------+ 446 | BYTE | unsigned | BYTEs are individually encoded as unsigned | 447 | | int or byte | integers unless the are defined as part of | 448 | | string | a byte string, in which case they are | 449 | | | encoded as a single byte in the byte | 450 | | | string. | 451 | | | | 452 | INT | unsigned | INTs are encoded as positive or negative | 453 | | integer or | integers from (u)int8_t up to (u)int32_t. | 454 | | negative | | 455 | | integer | | 456 | | | | 457 | UINT | unsigned | UINTs are unsigned integers from uint8_t | 458 | | integer | up to uint32_t. | 459 | | | | 460 | VAST | unsigned | VASTs are encoding as positive or negative | 461 | | integer or | integers up to (u)int64_t. | 462 | | negative | | 463 | | integer | | 464 | | | | 465 | UVAST | unsigned | VASTs are unsigned integers up to | 466 | | integer | uint64_t. | 467 | | | | 468 | REAL32 | floating | Up to an IEEE-754 Single Precision Float. | 469 | | point | | 470 | | | | 471 | REAL64 | floating | Up to an IEEE-754 Double Precision Float. | 472 | | point | | 473 | | | | 474 | STRING | text string | Uses CBOR encoding unmodified. | 475 | | | | 476 | BOOL | Simple | 0 is considered FALSE. 1 is considered | 477 | | Value | TRUE. | 478 +--------+-------------+--------------------------------------------+ 480 Table 3: Standard Numeric Types 482 8.2.2. Derived Types 484 This section provides the CBOR encodings for AMM derived types. 486 8.2.2.1. Byte String Encoding 488 The AMM derived type Byte String (BYTESTR) is encoded as a CBOR byte 489 string. 491 8.2.2.2. Time Values (TV) and Timestamps (TS) 493 An TV is encoded as a UVAST. Similarly, a TS is also encoded as a 494 UVAST since a TS is simply an absolute TV. 496 Rather than define two separate encodings for TVs (one for absolute 497 TVs and one for relative TVs) a single, unambiguous encoding can be 498 generated by defining a Relative Time Epoch (RTE) and interpreting 499 the type of TV in relation to that epoch. Time values less than the 500 RTE MUST be interpreted as relative times. Time values greater than 501 or equal to the RTE MUST be interpreted as absolute time values. 503 A relative TV is encoded as the number of seconds after an initiating 504 event. An absolute TV (and TS) is encoded as the number of seconds 505 that have elapsed since 1 Jan 2000 00:00:00 (Unix Time 946684800). 507 The RTE is defined as the timestamp value for September 9th, 2017 508 (Unix time 1504915200). Since TS values are the number of seconds 509 since 1 Jan 2000 00:00:00, the RTE as a TS value is 1504915200 - 510 946684800 = 558230400. 512 The potential values of TV, and how they should be interpreted as 513 relative or absolute is illustrated below. 515 Potential Time values 516 ________________________/\________________________ 517 / \ 518 Relative Times Absolute Times 519 <------------------------><------------------------> 520 0 - 558,230,400 558,230,401 - 2^64 522 |------------------------|-------------------------| 523 | | 524 00:00:00 1 Jan 2000 00:00:00 9 Sep 2017 525 Unix Time 946684800 Unix Time 1504915200 527 For example, a time value of "10" is a relative time representing 10 528 seconds after an initiating event. A time value of "600,000,000" 529 refers to Saturday, 5 Jan, 2019 10:40:00. 531 NOTE: Absolute and relative times are interchangeable. An absolute 532 time can be converted into a relative time by subtracting the current 533 time from the absolute time. A relative time can be converted into 534 an absolute time by adding to the relative time the timestamp of its 535 relative event. A pseudo-code example of converting a relative time 536 to an absolute time is as follows, assuming that current-time is 537 expressed in Unix Epoch time. 539 IF (time_value <= 558230400) THEN 540 absolute_time = (event_time - 946684800) + time_value 541 ELSE 542 absolute_time = time_value 544 8.2.2.3. Type-Name-Value (TNV) 546 TNV values are encoded as a CBOR array that comprises four distinct 547 pieces of information: a set of flags, a type, an optional name, and 548 an optional value. In the E(TNV) the flag and type information are 549 compressed into a single value. The CBOR array MUST have length 1, 550 2, or 3 depending on the number of optional fields appearing in the 551 encoding. The E(TNV) format is illustrated in Figure 2. 553 +---------+ 554 | TNV | 555 | [ARRAY] | 556 +----++---+ 557 || 558 || 559 _______________/ \________________ 560 / \ 561 +------------+-----------+----------+ 562 | Flags/Type | Name | Value | 563 | [BYTE] | [TXT STR] | [Varies] | 564 | | (opt) | (opt) | 565 +------------+-----------+----------+ 567 Figure 2: E(TNV) Format 569 The E(TNV) fields are defined as follows. 571 Flags/Type 572 The first byte of the E(TNV) describes the type associated 573 with the TNV and which optional components are present. The 574 layout of this byte is illustrated in Figure 3. 576 E(TNV) Flag/Type Byte Format 578 +------+---------------+ 579 | Name | Struct | 580 | Flag | Type | 581 +------+---------------+ 582 | 7 | 6 5 4 3 2 1 0 | 583 +------+---------------+ 584 MSB LSB 586 Figure 3 588 Name Flag 589 This flag indicates that the TNV contains a name 590 field. When set to 1 the Name field MUST be present 591 in the E(TNV). When set to 0 the Name field MUST NOT 592 be present in the E(TNV). 594 Struct Type 595 This field lists the type associated with this TNV 596 and MUST contain one of the types defined in 597 [I-D.birrane-dtn-adm] with the exception that the 598 type of a TNV MUST NOT be a TNV. 600 Name 601 This optional field captures the human-readable name for the 602 TNV encoded as a CBOR text string. If there are 3 elements 603 in the TNV array OR there are 2 elements in the array and the 604 Name Flag is set, then this field MUST be present. 605 Otherwise, this field MUST NOT be present. 607 Value 608 This optional field captures the encoded value associated 609 with this TNV. The value is encoded in accordance with AMP 610 rules for encoding of items of the type of this TNV. If 611 there are 3 elements in the TNV array OR there are 2 elements 612 in the array and the Name Flag is not set, then this field 613 MUST be present. Otherwise, this field MUST NOT be present. 615 8.2.3. Collections 617 8.2.3.1. Type-Name-Value Collection (TNVC) 619 A TNV Collection (TNVC) is an ordered set of TNVs with special 620 semantics for more efficiently encoding sets of TNVs with identical 621 attributes. 623 A TNV, defined in Section 8.2.2.3, consists of three distinct 624 components: a type, a name, and a value. When all of the TNVs in the 625 TNVC have the same format (such as they all include type information) 626 then the encoding of the TNVC can use this information to save 627 encoding space and make processing more efficient. In cases when all 628 TNVs have the same format, the types (if present), names (if 629 present), and values (if present) are separated into their own arrays 630 for individual processing with type information (if present) always 631 appearing first. 633 Extracting type information to the "front" of the collection 634 optimizes the performance of type validators. A validator can 635 inspect the first array to ensure that element values match type 636 expectations. If type information were distributed throughout the 637 collection, as in the case with the TNVC, a type validator would need 638 to scan through the entire set of data to validate each type in the 639 collection. 641 A TNVC is encoded as a CBOR array with at least one element, the 642 flags which represent the optional portions of the collection that 643 are present. If the TNVC represents an empty set, there will be no 644 additional entries. The format of a TNVC is illustrated in Figure 4. 646 +----------+ 647 | TNVC | 648 | [ARRAY] | 649 +----++----+ 650 || 651 || 652 ______________________/ \_______________________ 653 / \ 654 +--------+-----------+---------+---------+---------+ 655 | Flags | Types | Names | Values | Mixed | 656 | [BYTE] | [BYTESTR] | [ARRAY] | [ARRAY] | [ARRAY] | 657 | | (Opt) | (Opt) | (Opt) | (Opt) | 658 +--------+-----------+---------+---------+---------+ 660 Figure 4: E(TNVC) Format 662 The E(TNVC) fields are defined as follows. 664 Flags 665 The first byte of the E(TNVC) describes which optional 666 portions of a TNV will be present for each TNV in the 667 collection. The layout of this byte is illustrated in 668 Figure 5. 670 E(TNV) Flag Byte Format 672 +----------+------+------+------+------+ 673 | Reserved | Mix | Type | Name | Val | 674 | Flags | Flag | Flag | Flag | Flag | 675 +----------+------+------+------+------+ 676 | 7-4 | 3 | 2 | 1 | 0 | 677 +----------+------+------+------+------+ 678 MSB LSB 680 Figure 5 682 Type Flag 683 This flag indicates that the set of TNVs in the 684 collection do not all share the same properties and, 685 therefore, the collection is a mix of different types 686 of TNV. When set to 1 the E(TNVC) MUST contain the 687 Mixed Values field and all other flags in this byte 688 MUST be set to 0. When set to 0 the E(TNVC) MUST NOT 689 contain the Mixed Values field. 691 Type Flag 692 This flag indicates whether each TNV in the 693 collection has type information associated with it. 694 When set to 1 the E(TNVC) MUST contain type 695 information for each TNV. When set to 0, type 696 information MUST NOT be present. 698 Name Flag 699 This flag indicates whether each TNV in the 700 collection has name information associated with it. 701 When set to 1 the E(TNVC) MUST contain name 702 information for each TNV. When set to 0, name 703 information MUST NOT be present. 705 Value Flag 706 This flag indicates whether each TNV in the 707 collection has value information associated with it. 708 When set to 1 the E(TNVC) MUST contain value 709 information for each TNV. When set to 0, value 710 information MUST NOT be present. 712 Types 713 The types field is encoded as a CBOR byte string with length 714 equal to the number of items in the collection. The Nth byte 715 in the byte string represents the type for the Nth TNV in the 716 collection. This field MUST be present in the E(TNVC) when 717 the Type Flag is set to 1 and MUST NOT be present otherwise. 719 Names 720 The names field is encoded as a CBOR array with one entry for 721 each item in the collection. Each entry in the array is 722 encoded as a CBOR string and represents the name of a TNV in 723 the collection. The Nth string in the array represents the 724 name for the Nth TNV in the collection. This field MUST be 725 present in the E(TNVC) when the Name Flag is set to 1 and 726 MUST NOT be present otherwise. 728 Values 729 The values field is encoded as a CBOR array with one entry 730 for each item in the collection. Each entry in the array is 731 encoded as follows. If the Type Flag is set to 1 then each 732 entry will be encoded in accordance with the corresponding 733 index in the type field. For example, the 1st entry in the 734 value array will be encoded as the first entry in the type 735 bytestring. If the Type Flag is set to 0 then the entries in 736 the value array will be encoded as a native CBOR type. CBOR 737 types do not have a one-to-one mapping with AMP types and it 738 is the responsibility of the transmitting AMP actor and the 739 receiving AMP actor to determine how to map these to AMP 740 types. This field MUST be present in the E(TNVC) when the 741 Value Flag is set to 1 and MUST NOT be present otherwise. 743 Mixed 744 The mixed field is encoded as a CBOR array with one entry for 745 each item in the collection. Each entry in the array 746 contains a E(TNV). This field MUST be present in the E(TNVC) 747 when the Mix Flag is set to 1 and MUST NOT be present 748 otherwise. 750 8.2.3.2. ARI Collections (AC) 752 An ARI collection is an ordered collection of ARI values. It is 753 encoded as a CBOR array with each element being an encoded ARI, as 754 illustrated in Figure 6. 756 E(AC) Format 758 +---------+ 759 | AC | 760 | [ARRAY] | 761 +----++---+ 762 || 763 || 764 ________/ \_________ 765 / \ 766 +-------+ +-------+ 767 | ARI 1 | ... | ARI N | 768 | [ARI] | | [ARI] | 769 +-------+ +-------+ 771 Figure 6 773 8.2.3.3. Expressions (EXPR) 775 The Expression object encapsulates a typed postfix expression in 776 which each operator MUST be of type OPER and each operand MUST be the 777 typed result of an operator or one of EDD, VAR, LIT, or CONST. 779 The Expression object is encoded as a CBOR byte string whose format 780 is illustrated in Figure 7. 782 E(EXPR) Format 784 +--------+------------+ 785 | Type | Expression | 786 | [BYTE] | [AC] | 787 +--------+------------+ 789 Figure 7 791 Type 792 The enumeration representing the type of the result of the 793 evaluated expression. This type MUST be defined in 794 [I-D.birrane-dtn-adm] as a "Primitive Type". 796 Expression 797 An expression is represented in the AMP as an ARI collection, 798 where each ARI in the ordered collection represents either an 799 operand or operator in postfix form. 801 8.3. AMM Resource Identifier (ARI) 803 The ARI, as defined in [I-D.birrane-dtn-adm], identifies an AMM 804 object. There are two kinds of objects that can be identified in 805 this scheme: literal objects (of type LIT) and all other objects. 807 8.3.1. Encoding ARIs of Type LITERAL 809 A literal identifier is one that is literally defined by its value, 810 such as numbers (0, 3.14) and strings ("example"). ARIs of type 811 LITERAL do not have issuers or nicknames or parameters. They are 812 simply typed basic values. 814 The E(ARI) of a LIT object is encoded as a CBOR byte string and 815 consists of a mandatory flag BYTE and the value of the LIT. 817 The E(ARI) structure for LIT types is illustrated in Figure 8. 819 E(ARI) Literal Format 821 +--------+----------+ 822 | Flags | Value | 823 | [BYTE] | [VARIES] | 824 +--------+----------+ 826 Figure 8 828 These fields are defined as follows. 830 Flags 831 The Flags byte identifies the object as being of type LIT and 832 also captures the primitive type of the following value. The 833 layout of this byte is illustrated in Figure 9. 835 E(ARI) Literal Flag Byte Format 837 +------------+-------------+ 838 | VALUE TYPE | STRUCT TYPE | 839 +------------+-------------| 840 | 7 6 5 4 | 3 2 1 0 | 841 +------------+-------------+ 842 MSB LSB 844 Figure 9 846 Value Type 847 The high nibble of the flag byte describes the type 848 of the value of the ARI being encoded. This type 849 MUST be one of the AMM data types defined in 850 [I-D.birrane-dtn-adm] as a "Primitive Type". 852 Structure Type 853 The lower nibble of the flag byte identifies the type 854 of AMM Object being identified by the ARI. In this 855 instance, this value MUST be LIT, as defined in 856 [I-D.birrane-dtn-adm]. 858 Value 859 This field captures the CBOR encoding of the value. Values 860 are encoded according to their Value Type as specified in the 861 flag byte in accordance with the encoding rules provided in 862 Section 8.2.1. 864 8.3.2. Encoding Non-Literal ARIs 866 All other ARIs are defined in the context of AMM objects and may 867 contain parameters and other meta-data. The AMP, as a machine-to- 868 machine binary encoding of this information removes human-readable 869 information such as Name and Description from the E(ARI). 870 Additionally, this encoding adds other information to improve the 871 efficiency of the encoding, such as the concept of Nicknames, defined 872 in Section 7.1. 874 The E(ARI) is encoded as a CBOR byte string and consists of a 875 mandatory flag byte, an encoded object name, and optional annotations 876 to assist with filtering, access control, and parameterization. The 877 E(ARI) structure is illustrated in Figure 10. 879 E(ARI) General Format 881 +--------+---------+-----------+---------+---------+-----------+ 882 | Flags | NN | Name | Parms | Issuer | Tag | 883 | [BYTE] | [UVAST] | [BYTESTR] | [TNVC] | [UVAST] | [BYTESTR] | 884 | | (opt) | | (opt) | (opt) | opt) | 885 +--------+---------+-----------+---------+---------+-----------+ 887 Figure 10 889 These fields are defined as follows. 891 Flags 892 Flags describe the type of structure and which optional 893 fields are present in the encoding. The layout of the flag 894 byte is illustrated in Figure 11. 896 E(ARI) General Flag Byte Format 898 +----+------+-----+-----+-------------+ 899 | NN | PARM | ISS | TAG | STRUCT TYPE | 900 +----+------+-----+-----+-------------+ 901 | 7 | 6 | 5 | 4 | 3 2 1 0 | 902 +----+------+-----+-----+-------------+ 903 MSB LSB 905 Figure 11 907 Nickname (NN) 908 This flag indicates that ADM compression is used for 909 this E(ARI). When set to 1 the Nickname field MUST 910 be present in the E(ARI). When set to 0 the Nickname 911 field MUST NOT be present in the E(ARI). When an ARI 912 is user-defined, there are no semantics for Nicknames 913 and, therefore, this field MUST be 0 when the Issuer 914 flag is set to 1. Implementations SHOULD use 915 Nicknames whenever possible to reduce the size of the 916 E(ARI). 918 Parameters Present (PARM) 919 This flag indicates that this ARI can be 920 parameterized and that parameter information is 921 included in the E(ARI). When set to 1 the Parms 922 field MUST be present in the E(ARI). When set to 0 923 the Parms field MUST NOT be present in the E(ARI). 925 Issuer Present (ISS) 926 This flag indicates that this ARI is defined in the 927 context of a specific issuing entity. When set to 1 928 the Issuer field MUST be present in the E(ARI). When 929 set to 0 the Issuer field MUST NOT be present in the 930 E(ARI). 932 Tag Present (TAG) 933 This flag indicates that the ARI is defined in the 934 context of a specific issuing entity and that issuing 935 entity adds additional information in the form of a 936 tag. When set to 1 the Tag field MUST be present in 937 the E(ARI). When set to 0 the Tag field MUST NOT be 938 present in the E(ARI). This flag MUST be set to 0 if 939 the Issuer Present flag is set to 0. 941 Structure Type (STRUCT TYPE) 942 The lower nibble of the E(ARI) flag byte identifies 943 the kind of structure being identified. This field 944 MUST contain one of the AMM object types defined in 945 [I-D.birrane-dtn-adm]. 947 Nickname (NN) 948 This optional field contains the Nickname as calculated 949 according to Section 7.1. 951 Object Name 952 This mandatory field contains an encoding of the ADM object. 953 For elements defined in an ADM Template (e.g., where the 954 Issuer Flag is set to 0) this is the 0-based index into the 955 ADM collection holding this element. For all user-defined 956 ADM objects, (e.g., where the Issuer Flag is set to 1) this 957 value is as defined by the Issuing organization. 959 Parameters 960 The parameters field is represented as a Type Name Value 961 Collection (TNVC) as defined in Section 8.2.3.1. The overall 962 number of items in the collection represents the number of 963 parameters. The types of the TNVC represent the types of 964 each parameter, with the first listed type associated with 965 the first parameter, and so on. The values, if present, 966 represent the values of the parameters, with the first listed 967 value being the value of the first parameter, and so on. 969 Issuer 970 This is a binary identifier representing a predetermined 971 issuer name. The AMP protocol does not parse or validate 972 this identifier, using it only as a distinguishing bit 973 pattern to ensure uniqueness. This value, for example, may 974 come from a global registry of organizations, an issuing node 975 address, or some other network-unique marking. The issuer 976 field MUST NOT be present for any ARI defined in an ADM. 978 Tag 979 A value used to disambiguate multiple ARIs with the same 980 Issuer. The definition of the tag is left to the discretion 981 of the Issuer. The Tag field MUST be present if the Tag Flag 982 is set in the flag byte and MUST NOT be present otherwise. 984 8.4. ADM Object Encodings 986 The autonomy model codified in [I-D.birrane-dtn-adm] comprises 987 multiple individual objects. This section describes the CBOR 988 encoding of these objects. 990 Note: The encoding of an object refers to the way in which the 991 complete object can be encoded such that the object as it exists on a 992 Manager may be re-created on an Agent, and vice-versa. In cases 993 where both a Manager and an Agent already have the definition of an 994 object, then only the encoded ARI of the object needs to be 995 communicated. This is the case for all objects defined in a 996 published ADM and any user-defined object that has been synchronized 997 between an Agent and Manager. 999 8.4.1. Externally Defined Data (EDD) 1001 Externally defined data (EDD) are solely defined in the ADMs for 1002 various applications and protocols. EDDs represent values that are 1003 calculated external to an AMA Agent, such as values measured by 1004 firmware. 1006 The representation of these data is simply their identifying ARIs. 1007 The representation of an EDD is illustrated in Figure 12. 1009 E(EDD) Format 1011 +-------+ 1012 | ID | 1013 | [ARI] | 1014 +-------+ 1016 Figure 12 1018 ID 1019 This is the ARI identifying the EDD. Since EDDs are always 1020 defined solely in the context of an ADM, this ARI MUST NOT 1021 have an ISSUER field and MUST NOT have a TAG field. This ARI 1022 may be defined with parameters. 1024 8.4.2. Constants (CONST) 1026 Unlike Literals, a Constant is an immutable, typed, named value. 1027 Examples of constants include PI to some number of digits or the UNIX 1028 Epoch. 1030 Since ADM definitions are preconfigured on Agents and Managers in an 1031 AMA, the type information for a given Constant is known by all actors 1032 in the system and the encoding of the Constant needs to only be the 1033 name of the constant as the Manager and Agent can derive the type and 1034 value from the unique Constant name. 1036 The format of a Constant is illustrated in Figure 13. 1038 E(CONST) Format 1040 +-------+ 1041 | ID | 1042 | [ARI] | 1043 +-------+ 1045 Figure 13 1047 ID 1048 This is the ARI identifying the Constant. Since Constant 1049 definitions are always provided in an ADM, this ARI MUST NOT 1050 have an ISSUER field and MUST NOT have a TAG field. The ARI 1051 MUST NOT have parameters. 1053 8.4.3. Controls (CTRL) 1055 A Control represents a pre-defined and optionally parameterized 1056 opcode that can be run on an Agent. Controls in the AMP are always 1057 defined in the context of an AMA; there is no concept of an operator- 1058 defined Control. Since Controls are pre-configured in Agents and 1059 Managers as part of ADM support, their representation is the ARI that 1060 identifies them, similar to EDDs. 1062 The format of a Control is illustrated in Figure 14. 1064 E(CTRL) Format 1066 +-------+ 1067 | ID | 1068 | [ARI] | 1069 +-------+ 1071 Figure 14 1073 ID 1074 This is the ARI identifying the Control. This ARI MUST NOT 1075 have an ISSUER field and MUST NOT have a TAG field. This ARI 1076 may have parameters. 1078 8.4.4. Macros (MAC) 1080 Macros in the AMP are ordered collections of ARIs (an AC) that 1081 contain Controls or other Macros. When run by an Agent, each ARI in 1082 the AC MUST be run in order. 1084 Any AMP implementation MUST allow at least 4 levels of Macro nesting. 1085 Implementations MUST prevent recursive nesting of Macros. 1087 The ARI associated with a Macro MAY contain parameters. Each 1088 parameter present in a Macro ARI MUST contain type, name, and value 1089 information. Any Control or Macro encapsulated within a 1090 parameterized Macro MAY also contain parameters. If an encapsulated 1091 object parameter contains only name information, then the parameter 1092 value MUST be taken from the named parameter provided by the 1093 encapsulating Macro. Otherwise, the value provided to the object 1094 MUST be used instead. 1096 The format of a Macro is illustrated in Figure 15. 1098 E(MAC) Format 1100 +-------+------------+ 1101 | ID | Definition | 1102 | [ARI] | [AC] | 1103 +-------+------------+ 1105 Figure 15 1107 ID 1108 This is the ARI identifying the Macro. When a Macro is 1109 defined in an ADM this ARI MUST NOT have an ISSUER field and 1110 MUST NOT have a TAG field. When the Macro is defined outside 1111 of an ADM, the ARI MUST have an ISSUER field and MAY have a 1112 TAG field. 1114 Definition 1115 This is the ordered collection of ARIs that identify the 1116 Controls and other Macros that should be run as part of 1117 running this Macro. 1119 8.4.5. Operators (OPER) 1121 Operators are always defined in the context of an ADM. There is no 1122 concept of a user-defined operator, as operators represent 1123 mathematical functions implemented by the firmware on an Agent. 1124 Since Operators are preconfigured in Agents and Managers as part of 1125 ADM support, their representation is simply the ARI that identifies 1126 them. 1128 The ADM definition of an Operator MUST specify how many parameters 1129 are expected and the expected type of each parameter. For example, 1130 the unary NOT Operator ("!") would accept one parameter. The binary 1131 PLUS Operator ("+") would accept two parameters. A custom function 1132 to calculate the average of the last 10 samples of a data item should 1133 accept 10 parameters. 1135 Operators are always evaluated in the context of an Expression. The 1136 encoding of an Operator is illustrated in Figure 16. 1138 E(OP) Format 1140 +-------+ 1141 | ID | 1142 | [ARI] | 1143 +-------+ 1145 Figure 16 1147 ID 1148 This is the ARI identifying the Operator. Since Operators 1149 are always defined solely in the context of an ADM, this ARI 1150 MUST NOT have an ISSUER field and MUST NOT have a TAG field. 1152 8.4.6. Report Templates (RPTT) 1154 A Report Template is an ordered collection of identifiers that 1155 describe the order and format of data in any Report built in 1156 compliance with the template. A template is a schema for a class of 1157 reports. It contains no actual values and may be defined in a formal 1158 ADM or configured by users in the context of a network deployment. 1160 The encoding of a RPTT is illustrated in Figure 17. 1162 E(RPTT) Format 1164 +-------+----------+ 1165 | ID | Contents | 1166 | [ARI] | [AC] | 1167 +-------+----------+ 1169 Figure 17 1171 ID 1172 This is the ARI identifying the report template. 1174 Contents 1175 This is the ordered collection of ARIs that define the 1176 template. 1178 8.4.7. Report (RPT) 1180 A Report is a set of data values populated using a given Report 1181 Template. While Reports do not contain name information, they MAY 1182 contain type information in cases where recipients wish to perform 1183 type validation prior to interpreting the Report contents in the 1184 context of a Report Template. Reports are "anonymous" in the sense 1185 that any individual Report does not contain a unique identifier. 1186 Reports can be differentiated by examining the combination of (1) the 1187 Report Template being populated, (2) the time at which the Report was 1188 populated, and (3) the Agent producing the report. 1190 A Report object is comprised of the identifier of the template used 1191 to populate the report, an optional timestamp, and the contents of 1192 the report. A Report is encoded as a CBOR array with either 2 or 3 1193 elements. If the array has 2 elements then the optional Timestamp 1194 MUST NOT be in the Report encoding. If the array has 3 elements then 1195 the optional timestamp MUST be included in the Report encoding. The 1196 Report encoding is illustrated in Figure 18. 1198 E(RPT) Format 1200 +---------+ 1201 | RPT | 1202 | [ARRAY] | 1203 +---++----+ 1204 || 1205 || 1206 _____________/ \_____________ 1207 / \ 1208 +----------+-----------+---------+ 1209 | Template | Timestamp | Entries | 1210 | [ARI] | [TS] | [TNVC] | 1211 | | (opt) | | 1212 +----------+-----------+---------+ 1214 Figure 18 1216 Template 1217 This is the ARI identifying the template used to interpret 1218 the data in this report. 1220 This ARI may be parameterized and, if so, the parameters MUST 1221 include a name field and have been passed-by-name to the 1222 template contents when constructing the report. 1224 Timestamp 1225 The timestamp marks the time at which the report was created. 1226 This timestamp may be omitted in cases where the time of the 1227 report generation can be inferred from other information. 1228 For example, if a report is included in a message group such 1229 that the timestamp of the message group is equivalent to the 1230 timestamp of the report, the report timestamp may be omitted 1231 and the timestamp of the included message group used instead. 1233 Entries 1234 This is the collection of data values that comprise the 1235 report contents in accordance with the associated Report 1236 Template. 1238 8.4.8. State-Based Rules (SBR) 1240 A State-Based Rule (SBR) specifies that a particular action should be 1241 taken by an Agent based on some evaluation of the internal state of 1242 the Agent. A SBR specifies that starting at a particular START time 1243 an ACTION should be run by the Agent if some CONDITION evaluates to 1244 true, until the ACTION has been run COUNT times. When the SBR is no 1245 longer valid it may be discarded by the agent. 1247 Examples of SBRs include: 1249 Starting 2 hours from receipt, whenever V1 > 10, produce a Report 1250 for Report Template R1 no more than 20 times. 1252 Starting at some future absolute time, whenever V2 != V4, run 1253 Macro M1 no more than 36 times. 1255 An SBR object is encoded as a CBOR array with 5 elements as 1256 illustrated in Figure 19. 1258 E(SBR) Format 1260 +---------+ 1261 | SBR | 1262 | [ARRAY] | 1263 +---++----+ 1264 || 1265 || 1266 _______________________/ \_______________________ 1267 / \ 1268 +-------+-------+--------+--------+--------+--------+ 1269 | ID | START | COND | EVALS | FIRES | ACTION | 1270 | [ARI] | [TV] | [EXPR] | [UINT] | [UINT] | [AC] | 1271 +-------+-------+--------+--------+--------+--------+ 1273 Figure 19 1275 ID 1276 This is the ARI identifying the SBR. If this ARI contains 1277 parameters they MUST include a name in support of pass-by- 1278 name to each element of the Action AC. 1280 START 1281 The time at which the SBR condition should start to be 1282 evaluated. This will mark the first evaluation of the 1283 condition associated with the SBR. 1285 CONDITION 1286 The Expression which, if true, results in the SBR running the 1287 associated action. An EXPR is considered true if it 1288 evaluates to a non-zero value. 1290 EVALS 1291 The number of times the SBR condition can be evaluated. The 1292 special value of 0 indicates there is no limit on how many 1293 times the condition can be evaluated. 1295 FIRES 1296 The number of times the SBR action can be run. The special 1297 value of 0 indicates there is no limit on how many times the 1298 action can be run. 1300 ACTION 1301 The collection of Controls and/or Macros to run as part of 1302 the action. This is encoded as an AC in accordance with 1303 Section 8.2.3.2 with the stipulation that every ARI in this 1304 collection MUST be of type CTRL or MAC. 1306 8.4.9. Table Templates (TBLT) 1308 A Table Template (TBLT) describes the types, and optionally names, of 1309 the columns that define a Table. 1311 Because TBLTs are only defined in the context of an ADM, their 1312 definition cannot change operationally. Therefore, a TBLT is encoded 1313 simply as the ARI for the template. The format of the TBLT Object 1314 Array is illustrated in Figure 20. 1316 E(TBLT) Format 1318 +-------+ 1319 | ID | 1320 | [ARI] | 1321 +-------+ 1323 Figure 20 1325 The elements of the TBLT array are defined as follows. 1327 ID 1328 This is the ARI of the table template encoded in accordance 1329 with Section 8.3. 1331 8.4.10. Tables (TBL) 1333 A Table object describes the series of values associated with a 1334 Table Template. 1336 A Table object is encoded as a CBOR array, with the first element of 1337 the array identifying the Table Template and each subsequent element 1338 identifying a row in the table. The format of the TBL Object Array 1339 is illustrated in Figure 21. 1341 E(TBL) Format 1343 +---------+ 1344 | TBL | 1345 | [ARRAY] | 1346 +---++----+ 1347 || 1348 || 1349 ______________/ \_______________ 1350 / \ 1351 +---------+--------+ +--------+ 1352 | TBLT ID | Row 1 | | Row N | 1353 | [ARI] | [TNVC] | ... | [TNVC] | 1354 +---------+--------+ +--------+ 1356 Figure 21 1358 The TBL fields are defined as follows. 1360 Template ID (TBLT ID) 1361 This is the ARI of the table template describing the format 1362 of the table and is encoded in accordance with Section 8.3. 1364 Row 1365 Each row of the table is represented as a series of values 1366 with optional type information to aid in type checking table 1367 contents to column types. Each row is encoded as a TNVC and 1368 MAY include type information. AMP implementations should 1369 consider the impact of including type information for every 1370 row on the overall size of the encoded table. 1371 Each TNVC representing a row MUST contain the same number of 1372 elements as there are columns in the referenced 1373 Table Template. 1375 8.4.11. Time-Based Rules (TBR) 1377 A Time-Based Rule (TBR) specifies that a particular action should be 1378 taken by an Agent based on some time interval. A TBR specifies that 1379 starting at a particular START time, and for every PERIOD seconds 1380 thereafter, an ACTION should be run by the Agent until the ACTION has 1381 been run for COUNT times. When the TBR is no longer valid it MAY BE 1382 discarded by the Agent. 1384 Examples of TBRs include: 1386 Starting 2 hours from receipt, produce a Report for Report 1387 Template R1 every 10 hours ending after 20 times. 1389 Starting at the given absolute time, run Macro M1 every 24 hours 1390 ending after 365 times. 1392 The TBR object is encoded as a CBOR array with 5 elements as 1393 illustrated in Figure 22. 1395 E(TBR) Format 1397 +---------+ 1398 | TBR | 1399 | [ARRAY] | 1400 +---++----+ 1401 || 1402 || 1403 ___________________/ \___________________ 1404 / \ 1405 +-------+-------+--------+--------+--------+ 1406 | ID | START | PERIOD | COUNT | ACTION | 1407 | [ARI] | [TV] | [UINT] | [UINT] | [AC] | 1408 +-------+-------+--------+--------+--------+ 1410 Figure 22 1412 ID 1413 This is the ARI identifying the TBR and is encoded in 1414 accordance with Section 8.3. If this ARI contains parameters 1415 they MUST include a name in support of pass-by-name to each 1416 element of the Action AC. 1418 START 1419 The time at which the TBR condition should start to be 1420 evaluated. 1422 PERIOD 1423 The number of seconds to wait between running the action 1424 associated with the TBR. 1426 COUNT 1427 The number of times the TBR action can be run. The special 1428 value of 0 indicates there is no limit on how many times the 1429 action can be run. 1431 ACTION 1432 The collection of Controls and/or Macros to run as part of 1433 the action. This is encoded as an ARI Collection in 1434 accordance with Section 8.2.3.2 with the stipulation that 1435 every ARI in this collection MUST represent either a Control 1436 or a Macro. 1438 8.4.12. Variables (VAR) 1440 Variable objects are transmitted in the AMP without the human- 1441 readable description. 1443 Variable objects are encoded as a CBOR byte string whose format is 1444 illustrated in Figure 23. 1446 E(VAR) Format 1448 +------------+ 1449 | Variable | 1450 | [BYTESTR] | 1451 +-----++-----+ 1452 || 1453 || 1454 ______/ \_____ 1455 / \ 1456 +-------+-------+ 1457 | ID | Value | 1458 | [ARI] | [TNV] | 1459 +-------+-------+ 1461 Figure 23 1463 ID 1464 This is the ARI identifying the VAR and is encoded in 1465 accordance with Section 8.3. This ARI MUST NOT include 1466 parameters. 1468 Value 1469 This field captures the value (and optionally the type and 1470 name) of the variable, encoded as a TNV. 1472 9. Functional Specification 1474 This section describes the format of the messages that comprise the 1475 AMP protocol. 1477 9.1. AMP Message Summary 1479 The AMP message specification is limited to three basic 1480 communications: 1482 +------------+-------------+----------------------------------------+ 1483 | Message | Enumeration | Description | 1484 +------------+-------------+----------------------------------------+ 1485 | Register | 0 | Add Agents to the list of managed | 1486 | Agent | | devices known to a Manager. | 1487 | | | | 1488 | Report Set | 1 | Receiving a Report of one or more | 1489 | | | Report Entries from an Agent. | 1490 | | | | 1491 | Perform | 2 | Sending a Macro of one or more | 1492 | Control | | Controls to an Agent. | 1493 +------------+-------------+----------------------------------------+ 1495 Table 4: ADM Message Type Enumerations 1497 The entire management of a network can be performed using these three 1498 messages and the configurations from associated ADMs. 1500 9.2. Message Group Format 1502 Individual messages within the AMP are combined into a single group 1503 for communication with another AMP Actor. Messages within a group 1504 MUST be received and applied as an atomic unit. The format of a 1505 message group is illustrated in Figure 24. These message groups are 1506 assumed communicated amongst Agents and Managers as the payloads of 1507 encapsulating protocols which should provide additional security and 1508 data integrity features as needed. 1510 A message group is encoded as a CBOR array with at least 2 elements, 1511 the first being the time the group was created followed by 1 or more 1512 messages that comprise the group. The format of the message group is 1513 illustrated in Figure 24. 1515 AMP Message Group Format 1517 +---------------+ 1518 | Message Group | 1519 | [ARRAY] | 1520 +------++-------+ 1521 || 1522 ____________________||___________________ 1523 / \ 1524 +-----------+-----------+ +-----------+ 1525 | Timestamp | Message 1 | ... | Message N | 1526 | [TS] | [BYTESTR] | | [BYTESTR] | 1527 +-----------+-----------+ +-----------+ 1529 Figure 24 1531 Timestamp 1532 The creation time for this messaging group. Individual 1533 messages may have their own creation timestamps based on 1534 their type, but the group timestamp also serves as the 1535 default creation timestamp for every message in the group. 1536 This is encoded in accordance with Table 3. 1538 Message N 1539 The Nth message in the group. 1541 9.3. Message Format 1543 Each message identified in the AMP specification adheres to a common 1544 message format, illustrated in Figure 25, consisting of a message 1545 header, a message body, and an optional trailer. 1547 Each message in the AMP is encode as a CBOR byte string formatted in 1548 accordance with Figure 25. 1550 AMP Message Format 1552 +--------+----------+----------+ 1553 | Header | Body | Trailer | 1554 | [BYTE] | [VARIES] | [VARIES] | 1555 | | | (opt.) | 1556 +--------+----------+----------+ 1558 Figure 25 1560 Header 1561 The message header BYTE is shown in Figure 26. The header 1562 identifies a message context and opcode as well as flags that 1563 control whether a Report should be generated on message 1564 success (Ack) and whether a Report should be generated on 1565 message failure (Nack). 1567 AMP Common Message Header 1569 +----------+-----+------+-----+----------+ 1570 | Reserved | ACL | Nack | Ack | Opcode | 1571 +----------+-----+------+-----+----------+ 1572 | 7 6 | 5 | 4 | 3 | 2 1 0 | 1573 +----------+-----+------+-----+----------+ 1574 MSB LSB 1576 Figure 26 1578 Opcode 1579 The opcode field identifies which AMP message is 1580 being represented. 1582 ACK Flag 1583 The ACK flag describes whether successful application 1584 of the message must generate an acknowledgment back 1585 to the message sender. If this flag is set (1) then 1586 the receiving actor MUST generate a Report 1587 communicating this status. Otherwise, the actor MAY 1588 generate such a Report based on other criteria. 1590 NACK Flag 1591 The NACK flag describes whether a failure applying 1592 the message must generate an error notice back to the 1593 message sender. If this flag is set (1) then the 1594 receiving Actor MUST generate a Report communicating 1595 this status. Otherwise, the Actor MAY generate such 1596 a Report based on other criteria. 1598 ACL Used Flag 1599 The ACL used flag indicates whether the message has a 1600 trailer associated with it that specifies the list of 1601 AMP actors that may participate in the Actions or 1602 definitions associated with the message. This area 1603 is still under development. 1605 Body 1606 The message body contains the information associated with the 1607 given message. 1609 Trailer 1610 An OPTIONAL access control list (ACL) may be appended as a 1611 trailer to a message. When present, the ACL for a message 1612 identifiers the agents and managers that can be affected by 1613 the definitions and actions contained within the message. 1614 The explicit impact of an ACL is described in the context of 1615 each message below. When an ACL trailer is not present, the 1616 message results may be visible to any AMP Actor in the 1617 network, pursuant to other security protocol implementations. 1619 9.4. Register Agent 1621 The Register Agent message is used to inform an AMP Manager of the 1622 presence of another Agent in the network. 1624 The body of this message is the name of the new agent, encoded as 1625 illustrated in Figure 27. 1627 Register Agent Message Body 1629 +-----------+ 1630 | Agent ID | 1631 | [BYTESTR] | 1632 +-----------+ 1634 Figure 27 1636 Agent ID 1637 The Agent ID MUST represent the unique address of the Agent 1638 in whatever protocol is used to communicate with the Agent. 1640 9.5. Report Set 1642 The Report Set message contains a set of 1 or more Reports produced 1643 by an AMP Agent and sent to an AMP Manager. 1645 The body of this message contains information on the recipient of the 1646 reports followed by one or more Reports. The body is encoded as 1647 illustrated in Figure 28. 1649 Report Set Message Body 1651 +----------+--------+ +--------+ 1652 | RX Names | RPT 1 | | RPT N | 1653 | [ARRAY] | [RPT] | ... | [RPT] | 1654 +----------+--------+ +--------+ 1656 Figure 28 1658 RX Names 1659 This field captures the set of Managers that have been sent 1660 this report set. This is encoded as a CBOR array that MUST 1661 have at least one entry. Each entry in this array is 1662 encdoded as a CBOR text string. 1664 RPT N 1665 The Nth Report encoded in accordance with Section 8.4.7. 1667 9.6. Perform Control 1669 The perform control message causes the receiving AMP Actor to run one 1670 or more preconfigured Controls provided in the message. 1672 The body of this message is the start time for the controls followed 1673 by the controls themselves, as illustrated in Figure 29. 1675 Perform Control Message Body 1677 +-------+-----------+ 1678 | Start | Controls | 1679 | [TV] | [AC] | 1680 +-------+-----------+ 1682 Figure 29 1684 Start 1685 The time at which the Controls/Macros should be run. 1687 Controls 1688 The collection of ARIs that represent the Controls and/or 1689 Macros to be run by the AMP Actor. Every ARI in this 1690 collection MUST be either a Control or a Macro. 1692 10. IANA Considerations 1694 A Nickname registry needs to be established. 1696 11. Security Considerations 1698 Security within the AMP exists in two layers: transport layer 1699 security and access control. 1701 Transport-layer security addresses the questions of authentication, 1702 integrity, and confidentiality associated with the transport of 1703 messages between and amongst Managers and Agents. This security is 1704 applied before any particular Actor in the system receives data and, 1705 therefore, is outside of the scope of this document. 1707 Finer grain application security is done via ACLs provided in the AMP 1708 message headers. 1710 12. Implementation Notes 1712 A reference implementation of this version of the AMP specification 1713 is available in the 3.6.2 release of the ION open source code base 1714 available from sourceforge at https://sourceforge.net/projects/ion- 1715 dtn/. 1717 13. References 1718 13.1. Informative References 1720 [I-D.birrane-dtn-ama] 1721 Birrane, E., "Asynchronous Management Architecture", 1722 draft-birrane-dtn-ama-07 (work in progress), June 2018. 1724 13.2. Normative References 1726 [I-D.birrane-dtn-adm] 1727 Birrane, E., DiPietro, E., and D. Linko, "AMA Application 1728 Data Model", draft-birrane-dtn-adm-02 (work in progress), 1729 June 2018. 1731 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1732 Requirement Levels", BCP 14, RFC 2119, 1733 DOI 10.17487/RFC2119, March 1997, 1734 . 1736 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1737 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1738 October 2013, . 1740 Appendix A. Acknowledgements 1742 The following participants contributed technical material, use cases, 1743 and useful thoughts on the overall approach to this protocol 1744 specification: Jeremy Pierce-Mayer of INSYEN AG contributed the 1745 concept of the typed data collection and early type checking in the 1746 protocol. David Linko and Evana DiPietro of the Johns Hopkins 1747 University Applied Physics Laboratory contributed appreciated review 1748 and type checking of various elements of this specification. 1750 Author's Address 1752 Edward J. Birrane 1753 Johns Hopkins Applied Physics Laboratory 1755 Email: Edward.Birrane@jhuapl.edu