idnits 2.17.1 draft-birrane-dtn-amp-07.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 (July 7, 2019) is 1753 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 252, but not defined == Missing Reference: 'TYPE 2' is mentioned on line 252, but not defined == Missing Reference: 'ARRAY' is mentioned on line 1751, but not defined == Missing Reference: 'BYTE' is mentioned on line 1600, but not defined == Missing Reference: 'TXT STR' is mentioned on line 578, but not defined == Missing Reference: 'Varies' is mentioned on line 578, but not defined == Missing Reference: 'OCTETS' is mentioned on line 1572, but not defined == Missing Reference: 'UINT' is mentioned on line 1450, but not defined == Missing Reference: 'ARI' is mentioned on line 1501, but not defined == Missing Reference: 'AC' is mentioned on line 1725, but not defined == Missing Reference: 'VARIES' is mentioned on line 1600, but not defined == Missing Reference: 'UVAST' is mentioned on line 926, but not defined == Missing Reference: 'BYTESTR' is mentioned on line 1677, but not defined == Missing Reference: 'TNVC' is mentioned on line 1396, but not defined == Missing Reference: 'TS' is mentioned on line 1572, but not defined == Missing Reference: 'TV' is mentioned on line 1725, but not defined == Missing Reference: 'EXPR' is mentioned on line 1313, but not defined == Missing Reference: 'TNV' is mentioned on line 1501, but not defined == Missing Reference: 'RPT' is mentioned on line 1699, but not defined == Missing Reference: 'TBL' is mentioned on line 1751, 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 (~~), 22 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 July 7, 2019 5 Expires: January 8, 2020 7 Asynchronous Management Protocol 8 draft-birrane-dtn-amp-07 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 January 8, 2020. 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 . . . . . . . . . . . . . . . . . . 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 . . . . . . . . . . . . . . . . . . . . . . . . . 39 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 BYTE values. There is no implied structure associated 216 with OCTETS, meaning they do not encode a length value or utilize 217 a terminator character. While OCTETS may contain CBOR-encoded 218 values, the OCTETS sequence itself is not encoded as a CBOR 219 structure. 221 o Bit-fields in this document are specified with bit position 0 222 holding the least-significant bit (LSB). When illustrated in this 223 document, the LSB appears on the right. 225 o In order to describe the encoding of data models specified in 226 [I-D.birrane-dtn-adm], this specification must refer to both the 227 data object being encoded and to the encoding of that data object. 228 When discussing the encoded version of a data object, this 229 specification uses the notation "E(data_object)" where E() refers 230 to a conceptual encoding function. This notation is only provided 231 as a means of clarifying the text and imposes no changes to the 232 actual wire coding. For example, this specification will refer to 233 the "macro" data object as "Macro" and to the encoding of a Macro 234 as "E(Macro)". 236 o Illustrations of fields in this specification consist of the name 237 of the field, the type of the field between []'s, and if the field 238 is optional, the text "(opt)". 239 Field order is deterministic and, therefore, fields MUST be 240 transmitted in the order in which they are specified. In cases 241 where an optional field is not present, then the next field will 242 be considered for transmission. 243 An example is shown in Figure 1 below. In this illustration two 244 fields (Field 1 and Field 2) are shown, with Field 1 of Type 1 and 245 Field 2 of Type 2. Field 2 is also listed as being optional. 246 Byte fields are shown in order of receipt, from left-to-right. 247 Therefore, when transmitted on the wire, Field 1 will be received 248 first, followed by Field 2 (if present). 250 +----------+----------+ 251 | Field 1 | Field 2 | 252 | [TYPE 1] | [TYPE 2] | 253 | | (opt) | 254 +----------+----------+ 256 Figure 1: Byte Field Formatting Example 258 When types are documented in this way, the type always refers to 259 the encoding of that type. The E() notation is not used as it is 260 to be inferred from the context of the illustration. 262 7. AMP-Specific Concepts 264 The AMP specification provides an encoding of objects comprising the 265 AMM. As such, AMP defines very few structures of its own. This 266 section identifies those data structures that are unique to the AMP 267 and required for it to perform appropriate and efficient encodings of 268 AMM objects. 270 7.1. Nicknames (NN) 272 In the AMP, a "Nickname" (NN) is used to reduce the overall size of 273 the encoding of ARIs that are defined in the context of an ADM. A NN 274 is calculated as a function of an ADM Moderated Namespace and the 275 type of object being identified. 277 7.1.1. Motivation for Compression 279 As identifiers, ARIs are used heavily in AMM object definitions, 280 particularly in those that define collections of objects. This makes 281 encoding ARIs an important consideration when trying to optimize the 282 size of AMP message. 284 Additionally, the majority of ARIs are defined in the context of an 285 ADM. Certain AMM objects types (EDDs, OPs, CTRLs, TBLTs) can only be 286 defined in the context of an ADM. Other object types (VARs, CONSTs, 287 RPTTs) may have common, useful objects defined in an ADM as well. 288 The structure of an ADM, to include its use of a Moderated Namespace 289 and collections by object type, provide a regular structure that can 290 be exploited for creating a compact representation. 292 In particular, as specified in [I-D.birrane-dtn-adm], ARIs can be 293 grouped by (1) their namespace and (2) the type of AMM object being 294 identified. For example, consider the following ARIs of type EDD 295 defined in ADM1 with a Moderated Namespace of "/DTN/ADM1/". 297 ari:/DTN/ADM1/Edd.item_1 ari:/DTN/ADM1/Edd.item_2 ... ari:/DTN/ADM1/ 298 Edd.item_1974 300 In this case, the namespace (/DTN/ADM1/) and the object type (Edd) 301 are good candidates for enumeration because their string encoding is 302 very verbose and their information follows a regular structure shared 303 across multiple ARIs. Separately, the string representation of 304 object names (item_1, item_2, etc...) may be very verbose and they 305 are also candidates for enumeration as they occupy a particular ADM 306 object type in a particular order as published in the ADM. 308 7.1.2. ADM Enumeration 310 Any ARI defined in an ADM exists in the context of a Moderated 311 Namespace. These namespaces provide a unique string name for the 312 ADM. However, ADMs can also be assigned a unique enumeration by the 313 same moderating entities that ensure namespace uniqueness. 315 An ADM enumeration is an unsigned integer in the range of 0 to 316 (2^64)/20. This range provides effective support for thousands of 317 trillions of ADMs. 319 The formal set of ADMs, similar to SNMP MIBs and NETCONF YANG models, 320 will be moderated and published. Additionally, a set of informal 321 ADMs may be developed on a network-by-network or on an organization- 322 by-organization bases. 324 Since informal ADMs exist within a predefined context (a network, an 325 organization, or some other entity) they do not have individual ADM 326 enumerations and are assigned the special enumeration "0". ARIs that 327 are not defined in formal ADMs rely on other context information to 328 help with their encoding (see Section 8.3). 330 7.1.3. ADM Object Type Enumeration 332 An ADM Object Type Enumeration is an unsigned integer in the range of 333 0 - 19. This covers all of the standard areas for the ADM Template 334 as defined in [I-D.birrane-dtn-adm]. Each of these types are 335 enumerated in Table 1. 337 +-----------------+-------------+ 338 | AMM Object Type | Enumeration | 339 +-----------------+-------------+ 340 | CONST | 0 | 341 | | | 342 | CTRL | 1 | 343 | | | 344 | EDD | 2 | 345 | | | 346 | MAC | 3 | 347 | | | 348 | OPER | 4 | 349 | | | 350 | RPTT | 5 | 351 | | | 352 | SBR | 6 | 353 | | | 354 | TBLT | 7 | 355 | | | 356 | TBR | 8 | 357 | | | 358 | VAR | 9 | 359 | | | 360 | metadata | 10 | 361 | | | 362 | reserved | 11-19 | 363 +-----------------+-------------+ 365 Table 1: ADM Type Enumerations 367 7.1.4. Nickname Definition 369 As an enumeration, a Nickname is captured as a 64-bit unsigned 370 integer (UVAST) calculated as a function of the ADM enumeration and 371 the ADM type enumeration, as follows. 373 NN = ((ADM Enumeration) * 20) + (ADM Object Type Enumeration) 375 Considering the example set of ARIs from Section 7.1.1, assuming that 376 ADM1 has ADM enumeration 9 and given that objects in the example were 377 of type EDD, the NN for each of the 1974 items would be: (9 * 20) + 2 378 = 182. In this particular example, the ARI "/DTN/ADM1/Edd.item_1974" 379 can be encoded in 5 bytes: two bytes to CBOR encode the nickname 380 (182) and 3 bytes to CBOR encode the item's offset in the Edd 381 collection (1974). 383 7.1.5. ADM Enumeration Considerations 385 The assignment of formal ADM enumerations SHOULD take into 386 consideration the nature of the applications and protocols to which 387 the ADM applies. Those ADMs that are likely to be used in challenged 388 networks SHOULD be allocated low enumeration numbers (e.g. those that 389 will fit into 1-2 bytes) while ADMs that are likely to only be used 390 in well resourced networks SHOULD be allocated higher enumeration 391 numbers. It SHOULD NOT be the case that ADM enumerations are 392 allocated on a first-come, first-served basis. It is recommended 393 that ADM enumerations should be labeled based on the number of bytes 394 of the Nickname as a function of the size of the ADM enumeration. 395 These labels are shown in Table 2. 397 +-------------+--------+--------------+-----------------------------+ 398 | ADM Enum | NN | Label | Comment | 399 | | Size | | | 400 +-------------+--------+--------------+-----------------------------+ 401 | 0x1 - 0xCCC | 1-2 | Challenged | Constraints imposed by | 402 | | Bytes | Networks | physical layer and power. | 403 | | | | | 404 | 0xCCD - | 3-4 | Congested | Constraints imposed by | 405 | 0xCCCCCCC | Bytes | Networks | network traffic. | 406 | | | | | 407 | >=0xCCCCCCD | 5-8 | Resourced | Generally unconstrained | 408 | | Bytes | Networks | networks. | 409 +-------------+--------+--------------+-----------------------------+ 411 Table 2: ADM Enumerations Labels 413 8. Encodings 415 This section describes the binary encoding of logical data constructs 416 using the Concise Binary Object Representation (CBOR) defined in 417 [RFC7049]. 419 8.1. CBOR Considerations 421 The following considerations act as guidance for CBOR encoders and 422 decoders implementing the AMP. 424 o All AMP encodings are of definite length and, therefore, 425 indefinite encodings MUST NOT be used. 427 o AMP encodings MUST NOT use CBOR tags. Identification mechanisms 428 in the AMP capture structure and other information such that tags 429 are not necessary. 431 o Canonical CBOR MUST be used for all encoding. All AMP CBOR 432 decoders MUST run in strict mode. 434 o Because AMA objects are self-delineating they can be serialized 435 into, or deserialized from, OCTETS. CBOR containers such as 436 BYTESTR and TXTSTR that encode length fields are only useful for 437 data that is not self-delineating, such as name fields. Encoding 438 self-delineating objects into CBOR containers reduced efficiency 439 as length fields would then be added to data that does not reqire 440 a length field for processing. 442 o Encodings MUST result in smallest data representations. There are 443 several cases where the AMM defines types with less granularity 444 than CBOR. For example, AMM defines the UINT type to represent 445 unsigned integers up to 32 bits in length. CBOR supports separate 446 definitions of unsigned integers of 8, 16, or 32 bits in length. 447 In cases where an AMM type MAY be encoded in multiple ways in 448 CBOR, the smallest data representation MUST be used. For example, 449 UINT values of 0-255 MUST be encoded as a uint8_t, and so on. 451 8.2. AMM Type Encodings 453 8.2.1. Primitive Types 455 The AMP encodes AMM primitive types as outlined in Table 3. 457 +--------+-------------+--------------------------------------------+ 458 | AMM | CBOR Major | Comments | 459 | Type | Type | | 460 +--------+-------------+--------------------------------------------+ 461 | BYTE | unsigned | BYTEs are individually encoded as unsigned | 462 | | int or byte | integers unless the are defined as part of | 463 | | string | a byte string, in which case they are | 464 | | | encoded as a single byte in the byte | 465 | | | string. | 466 | | | | 467 | INT | unsigned | INTs are encoded as positive or negative | 468 | | integer or | integers from (u)int8_t up to (u)int32_t. | 469 | | negative | | 470 | | integer | | 471 | | | | 472 | UINT | unsigned | UINTs are unsigned integers from uint8_t | 473 | | integer | up to uint32_t. | 474 | | | | 475 | VAST | unsigned | VASTs are encoding as positive or negative | 476 | | integer or | integers up to (u)int64_t. | 477 | | negative | | 478 | | integer | | 479 | | | | 480 | UVAST | unsigned | VASTs are unsigned integers up to | 481 | | integer | uint64_t. | 482 | | | | 483 | REAL32 | floating | Up to an IEEE-754 Single Precision Float. | 484 | | point | | 485 | | | | 486 | REAL64 | floating | Up to an IEEE-754 Double Precision Float. | 487 | | point | | 488 | | | | 489 | STRING | text string | Uses CBOR encoding unmodified. | 490 | | | | 491 | BOOL | Simple | 0 is considered FALSE. 1 is considered | 492 | | Value | TRUE. | 493 +--------+-------------+--------------------------------------------+ 495 Table 3: Standard Numeric Types 497 8.2.2. Derived Types 499 This section provides the CBOR encodings for AMM derived types. 501 8.2.2.1. Byte String Encoding 503 The AMM derived type Byte String (BYTESTR) is encoded as a CBOR byte 504 string. 506 8.2.2.2. Time Values (TV) and Timestamps (TS) 508 An TV is encoded as a UVAST. Similarly, a TS is also encoded as a 509 UVAST since a TS is simply an absolute TV. 511 Rather than define two separate encodings for TVs (one for absolute 512 TVs and one for relative TVs) a single, unambiguous encoding can be 513 generated by defining a Relative Time Epoch (RTE) and interpreting 514 the type of TV in relation to that epoch. Time values less than the 515 RTE MUST be interpreted as relative times. Time values greater than 516 or equal to the RTE MUST be interpreted as absolute time values. 518 A relative TV is encoded as the number of seconds after an initiating 519 event. An absolute TV (and TS) is encoded as the number of seconds 520 that have elapsed since 1 Jan 2000 00:00:00 (Unix Time 946684800). 522 The RTE is defined as the timestamp value for September 9th, 2017 523 (Unix time 1504915200). Since TS values are the number of seconds 524 since 1 Jan 2000 00:00:00, the RTE as a TS value is 1504915200 - 525 946684800 = 558230400. 527 The potential values of TV, and how they should be interpreted as 528 relative or absolute is illustrated below. 530 Potential Time values 531 ________________________/\________________________ 532 / \ 533 Relative Times Absolute Times 534 <------------------------><------------------------> 535 0 - 558,230,400 558,230,401 - 2^64 537 |------------------------|-------------------------| 538 | | 539 00:00:00 1 Jan 2000 00:00:00 9 Sep 2017 540 Unix Time 946684800 Unix Time 1504915200 542 For example, a time value of "10" is a relative time representing 10 543 seconds after an initiating event. A time value of "600,000,000" 544 refers to Saturday, 5 Jan, 2019 10:40:00. 546 NOTE: Absolute and relative times are interchangeable. An absolute 547 time can be converted into a relative time by subtracting the current 548 time from the absolute time. A relative time can be converted into 549 an absolute time by adding to the relative time the timestamp of its 550 relative event. A pseudo-code example of converting a relative time 551 to an absolute time is as follows, assuming that current-time is 552 expressed in Unix Epoch time. 554 IF (time_value <= 558230400) THEN 555 absolute_time = (event_time - 946684800) + time_value 556 ELSE 557 absolute_time = time_value 559 8.2.2.3. Type-Name-Value (TNV) 561 TNV values are encoded as a CBOR array that comprises four distinct 562 pieces of information: a set of flags, a type, an optional name, and 563 an optional value. In the E(TNV) the flag and type information are 564 compressed into a single value. The CBOR array MUST have length 1, 565 2, or 3 depending on the number of optional fields appearing in the 566 encoding. The E(TNV) format is illustrated in Figure 2. 568 +---------+ 569 | TNV | 570 | [ARRAY] | 571 +----++---+ 572 || 573 || 574 _______________/ \________________ 575 / \ 576 +------------+-----------+----------+ 577 | Flags/Type | Name | Value | 578 | [BYTE] | [TXT STR] | [Varies] | 579 | | (opt) | (opt) | 580 +------------+-----------+----------+ 582 Figure 2: E(TNV) Format 584 The E(TNV) fields are defined as follows. 586 Flags/Type 587 The first byte of the E(TNV) describes the type associated 588 with the TNV and which optional components are present. The 589 layout of this byte is illustrated in Figure 3. 591 E(TNV) Flag/Type Byte Format 593 +------+---------------+ 594 | Name | Struct | 595 | Flag | Type | 596 +------+---------------+ 597 | 7 | 6 5 4 3 2 1 0 | 598 +------+---------------+ 599 MSB LSB 601 Figure 3 603 Name Flag 604 This flag indicates that the TNV contains a name 605 field. When set to 1 the Name field MUST be present 606 in the E(TNV). When set to 0 the Name field MUST NOT 607 be present in the E(TNV). 609 Struct Type 610 This field lists the type associated with this TNV 611 and MUST contain one of the types defined in 612 [I-D.birrane-dtn-adm] with the exception that the 613 type of a TNV MUST NOT be a TNV. 615 Name 616 This optional field captures the human-readable name for the 617 TNV encoded as a CBOR text string. If there are 3 elements 618 in the TNV array OR there are 2 elements in the array and the 619 Name Flag is set, then this field MUST be present. 620 Otherwise, this field MUST NOT be present. 622 Value 623 This optional field captures the encoded value associated 624 with this TNV. The value is encoded in accordance with AMP 625 rules for encoding of items of the type of this TNV. If 626 there are 3 elements in the TNV array OR there are 2 elements 627 in the array and the Name Flag is not set, then this field 628 MUST be present. Otherwise, this field MUST NOT be present. 630 8.2.3. Collections 632 8.2.3.1. Type-Name-Value Collection (TNVC) 634 A TNV Collection (TNVC) is an ordered set of TNVs with special 635 semantics for more efficiently encoding sets of TNVs with identical 636 attributes. 638 A TNV, defined in Section 8.2.2.3, consists of three distinct 639 components: a type, a name, and a value. When all of the TNVs in the 640 TNVC have the same format (such as they all include type information) 641 then the encoding of the TNVC can use this information to save 642 encoding space and make processing more efficient. In cases when all 643 TNVs have the same format, the types (if present), names (if 644 present), and values (if present) are separated into their own arrays 645 for individual processing with type information (if present) always 646 appearing first. 648 Extracting type information to the "front" of the collection 649 optimizes the performance of type validators. A validator can 650 inspect the first array to ensure that element values match type 651 expectations. If type information were distributed throughout the 652 collection, as in the case with the TNVC, a type validator would need 653 to scan through the entire set of data to validate each type in the 654 collection. 656 A TNVC is encoded as a sequence of at least 1 octet, where the single 657 required octet includes the flag BYTE representing the optional 658 portions of the collection that are present. If the flag BYTE 659 indicates an empty collection there will be no following octets.The 660 format of a TNVC is illustrated in Figure 4. 662 +----------+ 663 | TNVC | 664 | [OCTETS] | 665 +----++----+ 666 || 667 || 668 ____________________________/ \_____________________________ 669 / \ 670 +--------+---------+----------+----------+----------+----------+ 671 | Flags | # Items | Types | Names | Values | Mixed | 672 | [BYTE] | [UINT] | [OCTETS] | [OCTETS] | [OCTETS] | [OCTETS] | 673 | | (Opt) | (Opt) | (Opt) | (Opt) | (Opt) | 674 +--------+---------+----------+----------+----------+----------+ 676 Figure 4: E(TNVC) Format 678 The E(TNVC) fields are defined as follows. 680 Flags 681 The first byte of the E(TNVC) describes which optional 682 portions of a TNV will be present for each TNV in the 683 collection. 685 If all non-reserved flags have the value 0 then the TNVC 686 represents an empty collection, in which case no other 687 information is provided for the E(TNVC). 688 The layout of this byte is illustrated in Figure 5. 690 E(TNV) Flag Byte Format 692 +----------+------+------+------+------+ 693 | Reserved | Mix | Type | Name | Val | 694 | Flags | Flag | Flag | Flag | Flag | 695 +----------+------+------+------+------+ 696 | 7-4 | 3 | 2 | 1 | 0 | 697 +----------+------+------+------+------+ 698 MSB LSB 700 Figure 5 702 Mixed Flag 703 This flag indicates that the set of TNVs in the 704 collection do not all share the same properties and, 705 therefore, the collection is a mix of different types 706 of TNV. When set to 1 the E(TNVC) MUST contain the 707 Mixed Values field and all other flags in this byte 708 MUST be set to 0. When set to 0 the E(TNVC) MUST NOT 709 contain the Mixed Values field. 711 Type Flag 712 This flag indicates whether each TNV in the 713 collection has type information associated with it. 714 When set to 1 the E(TNVC) MUST contain type 715 information for each TNV. When set to 0, type 716 information MUST NOT be present. 718 Name Flag 719 This flag indicates whether each TNV in the 720 collection has name information associated with it. 721 When set to 1 the E(TNVC) MUST contain name 722 information for each TNV. When set to 0, name 723 information MUST NOT be present. 725 Value Flag 726 This flag indicates whether each TNV in the 727 collection has value information associated with it. 728 When set to 1 the E(TNVC) MUST contain value 729 information for each TNV. When set to 0, value 730 information MUST NOT be present. 732 # Items 733 The number of items field lists the number of items that are 734 contained in the TNVC. Each of the types, names, and values 735 sequences (if present) MUST have exactly this number of 736 entries in them. This field MUST be present in the E(TNVC) 737 when any one of the non-reserved bits of the Flag Byte are 738 set to 1. 740 Types 741 The types field is encoded as an OCTETS sequence where the 742 Nth byte in the sequence represents the type for the Nth TNV 743 in the collection. This field MUST be present in the E(TNVC) 744 when the Type Flag is set to 1 and MUST NOT be present 745 otherwise. If present, this field MUST contain exactly the 746 same number of types as number of items in the TNVX. 748 Names 749 The names field is encoded as an OCTETS sequence containing 750 the names of the TNVs in the collection. Each name is 751 encoded as a CBOR string, with the Nth CBOR string 752 representing the name of the Nth TNV in the collection. This 753 field MUST be present in the E(TNVC) when the Names Flag is 754 set to 1 and MUST NOT be present otherwise. If present, this 755 field MUST contain exactly the same number of CBOR strings as 756 number of items in the TNVC. 758 Values 759 The values field is encoded as an OCTETS sequence containing 760 the values of TNVs in the collection. 761 If the Type Flag is set to 1 then each entry will be encoded 762 in accordance with the corresponding index in the type field. 763 For example, the 1st value will be encoded using the encoding 764 rules for the first byte in the type OCTETS sequence. 765 If the Type Flag is set to 0 then the values will be encoded 766 as native CBOR types. CBOR types do not have a one-to-one 767 mapping with AMP types and it is the responsibility of the 768 transmitting AMP actor and the receiving AMP actor to 769 determine how to map these to AMP types. This field MUST be 770 present in the E(TNVC) when the Value Flag is set to 1 and 771 MUST NOT be present otherwise. If present, this field MUST 772 contain exactly the same number of values as number of items 773 in the TNVC. 775 Mixed 776 The mixed field is encoded as an OCTETS sequence containing a 777 series of E(TNV) objects. This field MUST be present when 778 the Mixed Flag is set to 1 and MUST NOT be present otherwise. 779 If present, this field MUST contain exactly the same number 780 of E(TNV) objects as numnber of items in the TNVC. 782 8.2.3.2. ARI Collections (AC) 784 An ARI collection is an ordered collection of ARI values. It is 785 encoded as a CBOR array with each element being an encoded ARI, as 786 illustrated in Figure 6. 788 E(AC) Format 790 +---------+ 791 | AC | 792 | [ARRAY] | 793 +----++---+ 794 || 795 || 796 ________/ \_________ 797 / \ 798 +-------+ +-------+ 799 | ARI 1 | ... | ARI N | 800 | [ARI] | | [ARI] | 801 +-------+ +-------+ 803 Figure 6 805 8.2.3.3. Expressions (EXPR) 807 The Expression object encapsulates a typed postfix expression in 808 which each operator MUST be of type OPER and each operand MUST be the 809 typed result of an operator or one of EDD, VAR, LIT, or CONST. 811 The Expression object is encoded as an OCTETS sequence whose format 812 is illustrated in Figure 7. 814 E(EXPR) Format 816 +----------+ 817 | EXPR | 818 | [OCTETS] | 819 +-----++---+ 820 || 821 || 822 _________/ \_________ 823 / \ 824 +---------+------------+ 825 | Type | Expression | 826 | [BYTE] | [AC] | 827 +---------+------------+ 829 Figure 7 831 Type 832 The enumeration representing the type of the result of the 833 evaluated expression. This type MUST be defined in 834 [I-D.birrane-dtn-adm] as a "Primitive Type". 836 Expression 837 An expression is represented in the AMP as an ARI collection, 838 where each ARI in the ordered collection represents either an 839 operand or operator in postfix form. 841 8.3. AMM Resource Identifier (ARI) 843 The ARI, as defined in [I-D.birrane-dtn-adm], identifies an AMM 844 object. There are two kinds of objects that can be identified in 845 this scheme: literal objects (of type LIT) and all other objects. 847 8.3.1. Encoding ARIs of Type LITERAL 849 A literal identifier is one that is literally defined by its value, 850 such as numbers (0, 3.14) and strings ("example"). ARIs of type 851 LITERAL do not have issuers or nicknames or parameters. They are 852 simply typed basic values. 854 The E(ARI) of a LIT object is encoded as an OCTETS sequence and 855 consists of a mandatory flag BYTE and the value of the LIT. 857 The E(ARI) structure for LIT types is illustrated in Figure 8. 859 E(ARI) Literal Format 861 +--------+----------+ 862 | Flags | Value | 863 | [BYTE] | [VARIES] | 864 +--------+----------+ 866 Figure 8 868 These fields are defined as follows. 870 Flags 871 The Flags byte identifies the object as being of type LIT and 872 also captures the primitive type of the following value. The 873 layout of this byte is illustrated in Figure 9. 875 E(ARI) Literal Flag Byte Format 877 +-------------------+-------------+ 878 | VALUE TYPE OFFSET | STRUCT TYPE | 879 +-------------------+-------------| 880 | 7 6 5 4 | 3 2 1 0 | 881 +-------------------+-------------+ 882 MSB LSB 884 Figure 9 886 Value Type Offset 887 The high nibble of the flag byte contains the offset 888 into the Primitive Types enumeration defined in 889 [I-D.birrane-dtn-adm]. An offset of 0 represents the 890 first defined Primitive Type. An offset of 1 891 represents the second defined Primitive Type, and so 892 on. An offset into the data types field is used to 893 ensure that they type value fits into a nibble. 895 Structure Type 896 The lower nibble of the flag byte identifies the type 897 of AMM Object being identified by the ARI. In this 898 instance, this value MUST be LIT, as defined in 899 [I-D.birrane-dtn-adm]. 901 Value 902 This field captures the CBOR encoding of the value. Values 903 are encoded according to their Value Type as specified in the 904 flag byte in accordance with the encoding rules provided in 905 Section 8.2.1. 907 8.3.2. Encoding Non-Literal ARIs 909 All other ARIs are defined in the context of AMM objects and may 910 contain parameters and other meta-data. The AMP, as a machine-to- 911 machine binary encoding of this information removes human-readable 912 information such as Name and Description from the E(ARI). 913 Additionally, this encoding adds other information to improve the 914 efficiency of the encoding, such as the concept of Nicknames, defined 915 in Section 7.1. 917 The E(ARI) is encoded as an OCTETS sequence and consists of a 918 mandatory flag byte, an encoded object name, and optional annotations 919 to assist with filtering, access control, and parameterization. The 920 E(ARI) structure is illustrated in Figure 10. 922 E(ARI) General Format 924 +--------+---------+-----------+---------+---------+-----------+ 925 | Flags | NN | Name | Parms | Issuer | Tag | 926 | [BYTE] | [UVAST] | [BYTESTR] | [TNVC] | [UVAST] | [BYTESTR] | 927 | | (opt) | | (opt) | (opt) | opt) | 928 +--------+---------+-----------+---------+---------+-----------+ 930 Figure 10 932 These fields are defined as follows. 934 Flags 935 Flags describe the type of structure and which optional 936 fields are present in the encoding. The layout of the flag 937 byte is illustrated in Figure 11. 939 E(ARI) General Flag Byte Format 941 +----+------+-----+-----+-------------+ 942 | NN | PARM | ISS | TAG | STRUCT TYPE | 943 +----+------+-----+-----+-------------+ 944 | 7 | 6 | 5 | 4 | 3 2 1 0 | 945 +----+------+-----+-----+-------------+ 946 MSB LSB 948 Figure 11 950 Nickname (NN) 951 This flag indicates that ADM compression is used for 952 this E(ARI). When set to 1 the Nickname field MUST 953 be present in the E(ARI). When set to 0 the Nickname 954 field MUST NOT be present in the E(ARI). When an ARI 955 is user-defined, there are no semantics for Nicknames 956 and, therefore, this field MUST be 0 when the Issuer 957 flag is set to 1. Implementations SHOULD use 958 Nicknames whenever possible to reduce the size of the 959 E(ARI). 961 Parameters Present (PARM) 962 This flag indicates that this ARI can be 963 parameterized and that parameter information is 964 included in the E(ARI). When set to 1 the Parms 965 field MUST be present in the E(ARI). When set to 0 966 the Parms field MUST NOT be present in the E(ARI). 968 Issuer Present (ISS) 969 This flag indicates that this ARI is defined in the 970 context of a specific issuing entity. When set to 1 971 the Issuer field MUST be present in the E(ARI). When 972 set to 0 the Issuer field MUST NOT be present in the 973 E(ARI). 975 Tag Present (TAG) 976 This flag indicates that the ARI is defined in the 977 context of a specific issuing entity and that issuing 978 entity adds additional information in the form of a 979 tag. When set to 1 the Tag field MUST be present in 980 the E(ARI). When set to 0 the Tag field MUST NOT be 981 present in the E(ARI). This flag MUST be set to 0 if 982 the Issuer Present flag is set to 0. 984 Structure Type (STRUCT TYPE) 985 The lower nibble of the E(ARI) flag byte identifies 986 the kind of structure being identified. This field 987 MUST contain one of the AMM object types defined in 988 [I-D.birrane-dtn-adm]. 990 Nickname (NN) 991 This optional field contains the Nickname as calculated 992 according to Section 7.1. 994 Object Name 995 This mandatory field contains an encoding of the ADM object. 996 For elements defined in an ADM Template (e.g., where the 997 Issuer Flag is set to 0) this is the 0-based index into the 998 ADM collection holding this element. For all user-defined 999 ADM objects, (e.g., where the Issuer Flag is set to 1) this 1000 value is as defined by the Issuing organization. 1002 Parameters 1003 The parameters field is represented as a Type Name Value 1004 Collection (TNVC) as defined in Section 8.2.3.1. The overall 1005 number of items in the collection represents the number of 1006 parameters. The types of the TNVC represent the types of 1007 each parameter, with the first listed type associated with 1008 the first parameter, and so on. The values, if present, 1009 represent the values of the parameters, with the first listed 1010 value being the value of the first parameter, and so on. 1012 Issuer 1013 This is a binary identifier representing a predetermined 1014 issuer name. The AMP protocol does not parse or validate 1015 this identifier, using it only as a distinguishing bit 1016 pattern to ensure uniqueness. This value, for example, may 1017 come from a global registry of organizations, an issuing node 1018 address, or some other network-unique marking. The issuer 1019 field MUST NOT be present for any ARI defined in an ADM. 1021 Tag 1022 A value used to disambiguate multiple ARIs with the same 1023 Issuer. The definition of the tag is left to the discretion 1024 of the Issuer. The Tag field MUST be present if the Tag Flag 1025 is set in the flag byte and MUST NOT be present otherwise. 1027 8.4. ADM Object Encodings 1029 The autonomy model codified in [I-D.birrane-dtn-adm] comprises 1030 multiple individual objects. This section describes the CBOR 1031 encoding of these objects. 1033 Note: The encoding of an object refers to the way in which the 1034 complete object can be encoded such that the object as it exists on a 1035 Manager may be re-created on an Agent, and vice-versa. In cases 1036 where both a Manager and an Agent already have the definition of an 1037 object, then only the encoded ARI of the object needs to be 1038 communicated. This is the case for all objects defined in a 1039 published ADM and any user-defined object that has been synchronized 1040 between an Agent and Manager. 1042 8.4.1. Externally Defined Data (EDD) 1044 Externally defined data (EDD) are solely defined in the ADMs for 1045 various applications and protocols. EDDs represent values that are 1046 calculated external to an AMA Agent, such as values measured by 1047 firmware. 1049 The representation of these data is simply their identifying ARIs. 1050 The representation of an EDD is illustrated in Figure 12. 1052 E(EDD) Format 1054 +-------+ 1055 | ID | 1056 | [ARI] | 1057 +-------+ 1059 Figure 12 1061 ID 1062 This is the ARI identifying the EDD. Since EDDs are always 1063 defined solely in the context of an ADM, this ARI MUST NOT 1064 have an ISSUER field and MUST NOT have a TAG field. This ARI 1065 may be defined with parameters. 1067 8.4.2. Constants (CONST) 1069 Unlike Literals, a Constant is an immutable, typed, named value. 1070 Examples of constants include PI to some number of digits or the UNIX 1071 Epoch. 1073 Since ADM definitions are preconfigured on Agents and Managers in an 1074 AMA, the type information for a given Constant is known by all actors 1075 in the system and the encoding of the Constant needs to only be the 1076 name of the constant as the Manager and Agent can derive the type and 1077 value from the unique Constant name. 1079 The format of a Constant is illustrated in Figure 13. 1081 E(CONST) Format 1083 +-------+ 1084 | ID | 1085 | [ARI] | 1086 +-------+ 1088 Figure 13 1090 ID 1091 This is the ARI identifying the Constant. Since Constant 1092 definitions are always provided in an ADM, this ARI MUST NOT 1093 have an ISSUER field and MUST NOT have a TAG field. The ARI 1094 MUST NOT have parameters. 1096 8.4.3. Controls (CTRL) 1098 A Control represents a pre-defined and optionally parameterized 1099 opcode that can be run on an Agent. Controls in the AMP are always 1100 defined in the context of an AMA; there is no concept of an operator- 1101 defined Control. Since Controls are pre-configured in Agents and 1102 Managers as part of ADM support, their representation is the ARI that 1103 identifies them, similar to EDDs. 1105 The format of a Control is illustrated in Figure 14. 1107 E(CTRL) Format 1109 +-------+ 1110 | ID | 1111 | [ARI] | 1112 +-------+ 1114 Figure 14 1116 ID 1117 This is the ARI identifying the Control. This ARI MUST NOT 1118 have an ISSUER field and MUST NOT have a TAG field. This ARI 1119 may have parameters. 1121 8.4.4. Macros (MAC) 1123 Macros in the AMP are ordered collections of ARIs (an AC) that 1124 contain Controls or other Macros. When run by an Agent, each ARI in 1125 the AC MUST be run in order. 1127 Any AMP implementation MUST allow at least 4 levels of Macro nesting. 1128 Implementations MUST prevent recursive nesting of Macros. 1130 The ARI associated with a Macro MAY contain parameters. Each 1131 parameter present in a Macro ARI MUST contain type, name, and value 1132 information. Any Control or Macro encapsulated within a 1133 parameterized Macro MAY also contain parameters. If an encapsulated 1134 object parameter contains only name information, then the parameter 1135 value MUST be taken from the named parameter provided by the 1136 encapsulating Macro. Otherwise, the value provided to the object 1137 MUST be used instead. 1139 The format of a Macro is illustrated in Figure 15. 1141 E(MAC) Format 1143 +-------+------------+ 1144 | ID | Definition | 1145 | [ARI] | [AC] | 1146 +-------+------------+ 1148 Figure 15 1150 ID 1151 This is the ARI identifying the Macro. When a Macro is 1152 defined in an ADM this ARI MUST NOT have an ISSUER field and 1153 MUST NOT have a TAG field. When the Macro is defined outside 1154 of an ADM, the ARI MUST have an ISSUER field and MAY have a 1155 TAG field. 1157 Definition 1158 This is the ordered collection of ARIs that identify the 1159 Controls and other Macros that should be run as part of 1160 running this Macro. 1162 8.4.5. Operators (OPER) 1164 Operators are always defined in the context of an ADM. There is no 1165 concept of a user-defined operator, as operators represent 1166 mathematical functions implemented by the firmware on an Agent. 1167 Since Operators are preconfigured in Agents and Managers as part of 1168 ADM support, their representation is simply the ARI that identifies 1169 them. 1171 The ADM definition of an Operator MUST specify how many parameters 1172 are expected and the expected type of each parameter. For example, 1173 the unary NOT Operator ("!") would accept one parameter. The binary 1174 PLUS Operator ("+") would accept two parameters. A custom function 1175 to calculate the average of the last 10 samples of a data item should 1176 accept 10 parameters. 1178 Operators are always evaluated in the context of an Expression. The 1179 encoding of an Operator is illustrated in Figure 16. 1181 E(OP) Format 1183 +-------+ 1184 | ID | 1185 | [ARI] | 1186 +-------+ 1188 Figure 16 1190 ID 1191 This is the ARI identifying the Operator. Since Operators 1192 are always defined solely in the context of an ADM, this ARI 1193 MUST NOT have an ISSUER field and MUST NOT have a TAG field. 1195 8.4.6. Report Templates (RPTT) 1197 A Report Template is an ordered collection of identifiers that 1198 describe the order and format of data in any Report built in 1199 compliance with the template. A template is a schema for a class of 1200 reports. It contains no actual values and may be defined in a formal 1201 ADM or configured by users in the context of a network deployment. 1203 The encoding of a RPTT is illustrated in Figure 17. 1205 E(RPTT) Format 1207 +-------+----------+ 1208 | ID | Contents | 1209 | [ARI] | [AC] | 1210 +-------+----------+ 1212 Figure 17 1214 ID 1215 This is the ARI identifying the report template. 1217 Contents 1218 This is the ordered collection of ARIs that define the 1219 template. 1221 8.4.7. Report (RPT) 1223 A Report is a set of data values populated using a given Report 1224 Template. While Reports do not contain name information, they MAY 1225 contain type information in cases where recipients wish to perform 1226 type validation prior to interpreting the Report contents in the 1227 context of a Report Template. Reports are "anonymous" in the sense 1228 that any individual Report does not contain a unique identifier. 1229 Reports can be differentiated by examining the combination of (1) the 1230 Report Template being populated, (2) the time at which the Report was 1231 populated, and (3) the Agent producing the report. 1233 A Report object is comprised of the identifier of the template used 1234 to populate the report, an optional timestamp, and the contents of 1235 the report. A Report is encoded as a CBOR array with either 2 or 3 1236 elements. If the array has 2 elements then the optional Timestamp 1237 MUST NOT be in the Report encoding. If the array has 3 elements then 1238 the optional timestamp MUST be included in the Report encoding. The 1239 Report encoding is illustrated in Figure 18. 1241 E(RPT) Format 1243 +---------+ 1244 | RPT | 1245 | [ARRAY] | 1246 +---++----+ 1247 || 1248 || 1249 _____________/ \_____________ 1250 / \ 1251 +----------+-----------+---------+ 1252 | Template | Timestamp | Entries | 1253 | [ARI] | [TS] | [TNVC] | 1254 | | (opt) | | 1255 +----------+-----------+---------+ 1257 Figure 18 1259 Template 1260 This is the ARI identifying the template used to interpret 1261 the data in this report. 1263 This ARI may be parameterized and, if so, the parameters MUST 1264 include a name field and have been passed-by-name to the 1265 template contents when constructing the report. 1267 Timestamp 1268 The timestamp marks the time at which the report was created. 1269 This timestamp may be omitted in cases where the time of the 1270 report generation can be inferred from other information. 1271 For example, if a report is included in a message group such 1272 that the timestamp of the message group is equivalent to the 1273 timestamp of the report, the report timestamp may be omitted 1274 and the timestamp of the included message group used instead. 1276 Entries 1277 This is the collection of data values that comprise the 1278 report contents in accordance with the associated Report 1279 Template. 1281 8.4.8. State-Based Rules (SBR) 1283 A State-Based Rule (SBR) specifies that a particular action should be 1284 taken by an Agent based on some evaluation of the internal state of 1285 the Agent. A SBR specifies that starting at a particular START time 1286 an ACTION should be run by the Agent if some CONDITION evaluates to 1287 true, until the ACTION has been run COUNT times. When the SBR is no 1288 longer valid it may be discarded by the agent. 1290 Examples of SBRs include: 1292 Starting 2 hours from receipt, whenever V1 > 10, produce a Report 1293 for Report Template R1 no more than 20 times. 1295 Starting at some future absolute time, whenever V2 != V4, run 1296 Macro M1 no more than 36 times. 1298 An SBR object is encoded as an OCTETS sequence as illustrated in 1299 Figure 19. 1301 E(SBR) Format 1303 +----------+ 1304 | SBR | 1305 | [OCTETS] | 1306 +----++----+ 1307 || 1308 || 1309 _______________________/ \_______________________ 1310 / \ 1311 +-------+-------+--------+--------+--------+--------+ 1312 | ID | START | COND | EVALS | FIRES | ACTION | 1313 | [ARI] | [TV] | [EXPR] | [UINT] | [UINT] | [AC] | 1314 +-------+-------+--------+--------+--------+--------+ 1316 Figure 19 1318 ID 1319 This is the ARI identifying the SBR. If this ARI contains 1320 parameters they MUST include a name in support of pass-by- 1321 name to each element of the Action AC. 1323 START 1324 The time at which the SBR condition should start to be 1325 evaluated. This will mark the first evaluation of the 1326 condition associated with the SBR. 1328 CONDITION 1329 The Expression which, if true, results in the SBR running the 1330 associated action. An EXPR is considered true if it 1331 evaluates to a non-zero value. 1333 EVALS 1334 The number of times the SBR condition can be evaluated. The 1335 special value of 0 indicates there is no limit on how many 1336 times the condition can be evaluated. 1338 FIRES 1339 The number of times the SBR action can be run. The special 1340 value of 0 indicates there is no limit on how many times the 1341 action can be run. 1343 ACTION 1344 The collection of Controls and/or Macros to run as part of 1345 the action. This is encoded as an AC in accordance with 1346 Section 8.2.3.2 with the stipulation that every ARI in this 1347 collection MUST be of type CTRL or MAC. 1349 8.4.9. Table Templates (TBLT) 1351 A Table Template (TBLT) describes the types, and optionally names, of 1352 the columns that define a Table. 1354 Because TBLTs are only defined in the context of an ADM, their 1355 definition cannot change operationally. Therefore, a TBLT is encoded 1356 simply as the ARI for the template. The format of the TBLT Object 1357 Array is illustrated in Figure 20. 1359 E(TBLT) Format 1361 +-------+ 1362 | ID | 1363 | [ARI] | 1364 +-------+ 1366 Figure 20 1368 The elements of the TBLT array are defined as follows. 1370 ID 1371 This is the ARI of the table template encoded in accordance 1372 with Section 8.3. 1374 8.4.10. Tables (TBL) 1376 A Table object describes the series of values associated with a 1377 Table Template. 1379 A Table object is encoded as a CBOR array, with the first element of 1380 the array identifying the Table Template and each subsequent element 1381 identifying a row in the table. The format of the TBL Object Array 1382 is illustrated in Figure 21. 1384 E(TBL) Format 1386 +---------+ 1387 | TBL | 1388 | [ARRAY] | 1389 +---++----+ 1390 || 1391 || 1392 ______________/ \_______________ 1393 / \ 1394 +---------+--------+ +--------+ 1395 | TBLT ID | Row 1 | | Row N | 1396 | [ARI] | [TNVC] | ... | [TNVC] | 1397 +---------+--------+ +--------+ 1399 Figure 21 1401 The TBL fields are defined as follows. 1403 Template ID (TBLT ID) 1404 This is the ARI of the table template describing the format 1405 of the table and is encoded in accordance with Section 8.3. 1407 Row 1408 Each row of the table is represented as a series of values 1409 with optional type information to aid in type checking table 1410 contents to column types. Each row is encoded as a TNVC and 1411 MAY include type information. AMP implementations should 1412 consider the impact of including type information for every 1413 row on the overall size of the encoded table. 1414 Each TNVC representing a row MUST contain the same number of 1415 elements as there are columns in the referenced 1416 Table Template. 1418 8.4.11. Time-Based Rules (TBR) 1420 A Time-Based Rule (TBR) specifies that a particular action should be 1421 taken by an Agent based on some time interval. A TBR specifies that 1422 starting at a particular START time, and for every PERIOD seconds 1423 thereafter, an ACTION should be run by the Agent until the ACTION has 1424 been run for COUNT times. When the TBR is no longer valid it MAY BE 1425 discarded by the Agent. 1427 Examples of TBRs include: 1429 Starting 2 hours from receipt, produce a Report for Report 1430 Template R1 every 10 hours ending after 20 times. 1432 Starting at the given absolute time, run Macro M1 every 24 hours 1433 ending after 365 times. 1435 The TBR object is encoded as an OCTETS sequence as illustrated in 1436 Figure 22. 1438 E(TBR) Format 1440 +----------+ 1441 | TBR | 1442 | [OCTETS] | 1443 +----++----+ 1444 || 1445 || 1446 ___________________/ \___________________ 1447 / \ 1448 +-------+-------+--------+--------+--------+ 1449 | ID | START | PERIOD | COUNT | ACTION | 1450 | [ARI] | [TV] | [UINT] | [UINT] | [AC] | 1451 +-------+-------+--------+--------+--------+ 1453 Figure 22 1455 ID 1456 This is the ARI identifying the TBR and is encoded in 1457 accordance with Section 8.3. If this ARI contains parameters 1458 they MUST include a name in support of pass-by-name to each 1459 element of the Action AC. 1461 START 1462 The time at which the TBR condition should start to be 1463 evaluated. 1465 PERIOD 1466 The number of seconds to wait between running the action 1467 associated with the TBR. 1469 COUNT 1470 The number of times the TBR action can be run. The special 1471 value of 0 indicates there is no limit on how many times the 1472 action can be run. 1474 ACTION 1475 The collection of Controls and/or Macros to run as part of 1476 the action. This is encoded as an ARI Collection in 1477 accordance with Section 8.2.3.2 with the stipulation that 1478 every ARI in this collection MUST represent either a Control 1479 or a Macro. 1481 8.4.12. Variables (VAR) 1483 Variable objects are transmitted in the AMP without the human- 1484 readable description. 1486 Variable objects are encoded as an OCTETS sequence whose format is 1487 illustrated in Figure 23. 1489 E(VAR) Format 1491 +-----------+ 1492 | Variable | 1493 | [OCTETS] | 1494 +-----++----+ 1495 || 1496 || 1497 ______/ \_____ 1498 / \ 1499 +-------+-------+ 1500 | ID | Value | 1501 | [ARI] | [TNV] | 1502 +-------+-------+ 1504 Figure 23 1506 ID 1507 This is the ARI identifying the VAR and is encoded in 1508 accordance with Section 8.3. This ARI MUST NOT include 1509 parameters. 1511 Value 1512 This field captures the value (and optionally the type and 1513 name) of the variable, encoded as a TNV. 1515 9. Functional Specification 1517 This section describes the format of the messages that comprise the 1518 AMP protocol. 1520 9.1. AMP Message Summary 1522 The AMP message specification is limited to three basic 1523 communications: 1525 +------------+-------------+----------------------------------------+ 1526 | Message | Enumeration | Description | 1527 +------------+-------------+----------------------------------------+ 1528 | Register | 0 | Add Agents to the list of managed | 1529 | Agent | | devices known to a Manager. | 1530 | | | | 1531 | Report Set | 1 | Receiving a Report of one or more | 1532 | | | Report Entries from an Agent. | 1533 | | | | 1534 | Perform | 2 | Sending a Macro of one or more | 1535 | Control | | Controls to an Agent. | 1536 | | | | 1537 | Table Set | 3 | Receiving one or more tables from an | 1538 | | | Agent. | 1539 +------------+-------------+----------------------------------------+ 1541 Table 4: ADM Message Type Enumerations 1543 The entire management of a network can be performed using these three 1544 messages and the configurations from associated ADMs. 1546 9.2. Message Group Format 1548 Individual messages within the AMP are combined into a single group 1549 for communication with another AMP Actor. Messages within a group 1550 MUST be received and applied as an atomic unit. The format of a 1551 message group is illustrated in Figure 24. These message groups are 1552 assumed communicated amongst Agents and Managers as the payloads of 1553 encapsulating protocols which should provide additional security and 1554 data integrity features as needed. 1556 A message group is encoded as a CBOR array with at least 2 elements, 1557 the first being the time the group was created followed by 1 or more 1558 messages that comprise the group. The format of the message group is 1559 illustrated in Figure 24. 1561 AMP Message Group Format 1563 +---------------+ 1564 | Message Group | 1565 | [ARRAY] | 1566 +------++-------+ 1567 || 1568 ____________________||___________________ 1569 / \ 1570 +-----------+-----------+ +-----------+ 1571 | Timestamp | Message 1 | ... | Message N | 1572 | [TS] | [OCTETS] | | [OCTETS] | 1573 +-----------+-----------+ +-----------+ 1575 Figure 24 1577 Timestamp 1578 The creation time for this messaging group. Individual 1579 messages may have their own creation timestamps based on 1580 their type, but the group timestamp also serves as the 1581 default creation timestamp for every message in the group. 1582 This is encoded in accordance with Table 3. 1584 Message N 1585 The Nth message in the group. 1587 9.3. Message Format 1589 Each message identified in the AMP specification adheres to a common 1590 message format, illustrated in Figure 25, consisting of a message 1591 header, a message body, and an optional trailer. 1593 Each message in the AMP is encode as an OCTETS sequence formatted in 1594 accordance with Figure 25. 1596 AMP Message Format 1598 +--------+----------+----------+ 1599 | Header | Body | Trailer | 1600 | [BYTE] | [VARIES] | [VARIES] | 1601 | | | (opt.) | 1602 +--------+----------+----------+ 1604 Figure 25 1606 Header 1607 The message header BYTE is shown in Figure 26. The header 1608 identifies a message context and opcode as well as flags that 1609 control whether a Report should be generated on message 1610 success (Ack) and whether a Report should be generated on 1611 message failure (Nack). 1613 AMP Common Message Header 1615 +----------+-----+------+-----+----------+ 1616 | Reserved | ACL | Nack | Ack | Opcode | 1617 +----------+-----+------+-----+----------+ 1618 | 7 6 | 5 | 4 | 3 | 2 1 0 | 1619 +----------+-----+------+-----+----------+ 1620 MSB LSB 1622 Figure 26 1624 Opcode 1625 The opcode field identifies which AMP message is 1626 being represented. 1628 ACK Flag 1629 The ACK flag describes whether successful application 1630 of the message must generate an acknowledgment back 1631 to the message sender. If this flag is set (1) then 1632 the receiving actor MUST generate a Report 1633 communicating this status. Otherwise, the actor MAY 1634 generate such a Report based on other criteria. 1636 NACK Flag 1637 The NACK flag describes whether a failure applying 1638 the message must generate an error notice back to the 1639 message sender. If this flag is set (1) then the 1640 receiving Actor MUST generate a Report communicating 1641 this status. Otherwise, the Actor MAY generate such 1642 a Report based on other criteria. 1644 ACL Used Flag 1645 The ACL used flag indicates whether the message has a 1646 trailer associated with it that specifies the list of 1647 AMP actors that may participate in the Actions or 1648 definitions associated with the message. This area 1649 is still under development. 1651 Body 1652 The message body contains the information associated with the 1653 given message. 1655 Trailer 1656 An OPTIONAL access control list (ACL) may be appended as a 1657 trailer to a message. When present, the ACL for a message 1658 identifiers the agents and managers that can be affected by 1659 the definitions and actions contained within the message. 1660 The explicit impact of an ACL is described in the context of 1661 each message below. When an ACL trailer is not present, the 1662 message results may be visible to any AMP Actor in the 1663 network, pursuant to other security protocol implementations. 1665 9.4. Register Agent 1667 The Register Agent message is used to inform an AMP Manager of the 1668 presence of another Agent in the network. 1670 The body of this message is the name of the new agent, encoded as 1671 illustrated in Figure 27. 1673 Register Agent Message Body 1675 +-----------+ 1676 | Agent ID | 1677 | [BYTESTR] | 1678 +-----------+ 1680 Figure 27 1682 Agent ID 1683 The Agent ID MUST represent the unique address of the Agent 1684 in whatever protocol is used to communicate with the Agent. 1686 9.5. Report Set 1688 The Report Set message contains a set of 1 or more Reports produced 1689 by an AMP Agent and sent to an AMP Manager. 1691 The body of this message contains information on the recipient of the 1692 reports followed by one or more Reports. The body is encoded as 1693 illustrated in Figure 28. 1695 Report Set Message Body 1697 +----------+--------+ +--------+ 1698 | RX Names | RPT 1 | | RPT N | 1699 | [ARRAY] | [RPT] | ... | [RPT] | 1700 +----------+--------+ +--------+ 1702 Figure 28 1704 RX Names 1705 This field captures the set of Managers that have been sent 1706 this report set. This is encoded as a CBOR array that MUST 1707 have at least one entry. Each entry in this array is 1708 encdoded as a CBOR text string. 1710 RPT N 1711 The Nth Report encoded in accordance with Section 8.4.7. 1713 9.6. Perform Control 1715 The perform control message causes the receiving AMP Actor to run one 1716 or more preconfigured Controls provided in the message. 1718 The body of this message is the start time for the controls followed 1719 by the controls themselves, as illustrated in Figure 29. 1721 Perform Control Message Body 1723 +-------+-----------+ 1724 | Start | Controls | 1725 | [TV] | [AC] | 1726 +-------+-----------+ 1728 Figure 29 1730 Start 1731 The time at which the Controls/Macros should be run. 1733 Controls 1734 The collection of ARIs that represent the Controls and/or 1735 Macros to be run by the AMP Actor. Every ARI in this 1736 collection MUST be either a Control or a Macro. 1738 9.7. Table Set 1740 The Table Set message contains a set of 1 or more TBLs produced by an 1741 AMP Agent and sent to an AMP Manager. 1743 The body of this message contains information on the recipient of the 1744 tables followed by one or more TBLs. The body is encoded as 1745 illustrated in Figure 30. 1747 Table Set Message Body 1749 +----------+--------+ +--------+ 1750 | RX Names | TBL 1 | | TBL N | 1751 | [ARRAY] | [TBL] | ... | [TBL] | 1752 +----------+--------+ +--------+ 1754 Figure 30 1756 RX Names 1757 This field captures the set of Managers that have been sent 1758 this table set. This is encoded as a CBOR array that MUST 1759 have at least one entry. Each entry in this array is 1760 encdoded as a CBOR text string. 1762 TBL N 1763 The Nth Table encoded in accordance with Section 8.4.10. 1765 10. IANA Considerations 1767 A Nickname registry needs to be established. 1769 11. Security Considerations 1771 Security within the AMP exists in two layers: transport layer 1772 security and access control. 1774 Transport-layer security addresses the questions of authentication, 1775 integrity, and confidentiality associated with the transport of 1776 messages between and amongst Managers and Agents. This security is 1777 applied before any particular Actor in the system receives data and, 1778 therefore, is outside of the scope of this document. 1780 Finer grain application security is done via ACLs provided in the AMP 1781 message headers. 1783 12. Implementation Notes 1785 A reference implementation of this version of the AMP specification 1786 is available in the 3.6.2 release of the ION open source code base 1787 available from sourceforge at https://sourceforge.net/projects/ion- 1788 dtn/. 1790 13. References 1791 13.1. Informative References 1793 [I-D.birrane-dtn-ama] 1794 Birrane, E., "Asynchronous Management Architecture", 1795 draft-birrane-dtn-ama-07 (work in progress), June 2018. 1797 13.2. Normative References 1799 [I-D.birrane-dtn-adm] 1800 Birrane, E., DiPietro, E., and D. Linko, "AMA Application 1801 Data Model", draft-birrane-dtn-adm-02 (work in progress), 1802 June 2018. 1804 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1805 Requirement Levels", BCP 14, RFC 2119, 1806 DOI 10.17487/RFC2119, March 1997, 1807 . 1809 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1810 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1811 October 2013, . 1813 Appendix A. Acknowledgements 1815 The following participants contributed technical material, use cases, 1816 and useful thoughts on the overall approach to this protocol 1817 specification: Jeremy Pierce-Mayer of INSYEN AG contributed the 1818 concept of the typed data collection and early type checking in the 1819 protocol. David Linko and Evana DiPietro of the Johns Hopkins 1820 University Applied Physics Laboratory contributed appreciated review 1821 and type checking of various elements of this specification. 1823 Author's Address 1825 Edward J. Birrane 1826 Johns Hopkins Applied Physics Laboratory 1828 Email: Edward.Birrane@jhuapl.edu