idnits 2.17.1 draft-birrane-dtn-amp-05.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 2, 2018) is 2122 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 244, but not defined == Missing Reference: 'TYPE 2' is mentioned on line 244, but not defined == Missing Reference: 'ARRAY' is mentioned on line 1617, but not defined == Missing Reference: 'UINT' is mentioned on line 1360, but not defined == Missing Reference: 'TXT STR' is mentioned on line 562, but not defined == Missing Reference: 'Varies' is mentioned on line 562, but not defined == Missing Reference: 'BYTESTR' is mentioned on line 1595, but not defined == Missing Reference: 'ARI' is mentioned on line 1411, but not defined == Missing Reference: 'BYTE' is mentioned on line 1518, but not defined == Missing Reference: 'AC' is mentioned on line 1643, but not defined == Missing Reference: 'VARIES' is mentioned on line 1518, but not defined == Missing Reference: 'UVAST' is mentioned on line 819, but not defined == Missing Reference: 'TTVC' is mentioned on line 1306, but not defined == Missing Reference: 'TS' is mentioned on line 1490, but not defined == Missing Reference: 'TV' is mentioned on line 1643, but not defined == Missing Reference: 'EXPR' is mentioned on line 1411, but not defined == Missing Reference: 'RPT' is mentioned on line 1617, 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 (~~), 19 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 July 2, 2018 5 Expires: January 3, 2019 7 Asynchronous Management Protocol 8 draft-birrane-dtn-amp-05 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 3, 2019. 37 Copyright Notice 39 Copyright (c) 2018 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) . . . . . . . . . . . . . . 18 76 8.3.1. Encoding ARIs of Type LITERAL . . . . . . . . . . . . 18 77 8.3.2. Encoding Non-Literal ARIs . . . . . . . . . . . . . . 19 78 8.4. ADM Object Encodings . . . . . . . . . . . . . . . . . . 21 79 8.4.1. Externally Defined Data (EDD) . . . . . . . . . . . . 22 80 8.4.2. Constants (CONST) . . . . . . . . . . . . . . . . . . 22 81 8.4.3. Controls (CTBR) . . . . . . . . . . . . . . . . . . . 23 82 8.4.4. Macros (MAC) . . . . . . . . . . . . . . . . . . . . 23 83 8.4.5. Operators (OPER) . . . . . . . . . . . . . . . . . . 24 84 8.4.6. Report Templates (RPTT) . . . . . . . . . . . . . . . 25 85 8.4.7. Report (RPT) . . . . . . . . . . . . . . . . . . . . 25 86 8.4.8. State-Based Rules (SBR) . . . . . . . . . . . . . . . 27 87 8.4.9. Table Templates (TBLT) . . . . . . . . . . . . . . . 28 88 8.4.10. Tables (TBL) . . . . . . . . . . . . . . . . . . . . 29 89 8.4.11. Time-Based Rules (TBR) . . . . . . . . . . . . . . . 30 90 8.4.12. Variables (VAR) . . . . . . . . . . . . . . . . . . . 31 91 9. Functional Specification . . . . . . . . . . . . . . . . . . 32 92 9.1. AMP Message Summary . . . . . . . . . . . . . . . . . . . 33 93 9.2. Message Group Format . . . . . . . . . . . . . . . . . . 33 94 9.3. Message Format . . . . . . . . . . . . . . . . . . . . . 34 95 9.4. Register Agent . . . . . . . . . . . . . . . . . . . . . 36 96 9.5. Report Set . . . . . . . . . . . . . . . . . . . . . . . 36 97 9.6. Perform Control . . . . . . . . . . . . . . . . . . . . . 37 98 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 99 11. Security Considerations . . . . . . . . . . . . . . . . . . . 37 100 12. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 101 12.1. Informative References . . . . . . . . . . . . . . . . . 38 102 12.2. Normative References . . . . . . . . . . . . . . . . . . 38 103 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 38 104 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 38 106 1. Introduction 108 Network management in challenged and resource constrained networks 109 must be accomplished differently than the network management methods 110 in high-rate, high-availability networks. The Asynchronous 111 Management Architecture (AMA) [I-D.birrane-dtn-ama] provides an 112 overview and justification of an alternative to "synchronous" 113 management services such as those provided by NETCONF. In 114 particular, the AMA defines the need for a flexible, robust, and 115 efficient autonomy engine to handle decisions when operators cannot 116 be active in the network. The logical description of that autonomous 117 model and its major components is given in the AMA Data Model (ADM) 118 [I-D.birrane-dtn-adm]. 120 The ADM presents an efficient and expressive autonomy model for the 121 asynchronous management of a network node, but does not specify any 122 particular encoding. This document, the Asynchronous Management 123 Protocol (AMP), provides a binary encoding of AMM objects and 124 specifies a protocol for the exchange of these encoded objects. 126 2. Requirements Language 128 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 129 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 130 document are to be interpreted as described in [RFC2119]. 132 3. Scope 134 3.1. Protocol Scope 136 The AMP provides data monitoring, administration, and configuration 137 for applications operating above the data link layer of the OSI 138 networking model. While the AMP may be configured to support the 139 management of network layer protocols, it also uses these protocol 140 stacks to encapsulate and communicate its own messages. 142 It is assumed that the protocols used to carry AMP messages provide 143 addressing, confidentiality, integrity, security, fragmentation/ 144 reassembly, and other network functions. Therefore, these items are 145 outside of the scope of this document. 147 3.2. Specification Scope 149 This document describes the format of messages used to exchange data 150 models between managing and managed devices in a network. The 151 rationale for this type of exchange is outside of the scope of this 152 document and is covered in [I-D.birrane-dtn-ama]. The description 153 and explanation of the data models exchanged is also outside of the 154 scope of this document and is covered in [I-D.birrane-dtn-adm]. 156 This document does not address specific configurations of AMP-enabled 157 devices, nor does it discuss the interface between AMP and other 158 management protocols. 160 4. Terminology 162 Note: The terms "Actor", "Agent", "Application Data Model", 163 "Externally Defined Data", "Variable", "Control", "Literal", "Macro", 164 "Manager", "Report Template", "Report", "Table", "Constant", 165 "Operator", "Time-Based Rule" and "State-Based Rule" are used without 166 modification from the definitions provided in [I-D.birrane-dtn-ama]. 168 5. Constraints and Assumptions 170 The desirable properties of an asynchronous management protocol, as 171 specified in the AMA, are summarized here to represent design 172 constraints on the AMP specification. 174 o Intelligent Push of Information - Nodes in a challenged network 175 cannot guarantee concurrent, bi-directional communications. Some 176 links between nodes may be strictly unidirectional. AMP Agents 177 "push" data to Managers rather than Managers "pulling" data from 178 Agents. 180 o Small Message Sizes - Smaller messages require smaller periods of 181 viable transmission for communication, incur less retransmission 182 cost, and consume fewer resources when persistently stored en 183 route in the network. AMP minimizes message size wherever 184 practical, to include binary data representations and predefined 185 data definitions and templates. 187 o Absolute and Custom Data Identification - All data in the system 188 must be uniquely addressable, to include operator-specified 189 information. AMP provides a compact encoding for identifiers. 191 o Autonomous, Stateless Operation - There is no reliable concept of 192 session establishment or round-trip data exchange in asynchronous 193 networks. AMP is designed to be stateless. Where helpful, AMP 194 provides mechanisms for transactional ordering of commands within 195 a single AMP protocol data unit, but otherwise degrades gracefully 196 when nodes in the network diver in their configuration. 198 6. Technical Notes 200 o Unless otherwise specified, multi-byte values in this 201 specification are expected to be transmitted in network byte order 202 (Big Endian). 204 o Character encodings for all text-based data types will use UTF-8 205 encodings. 207 o All AMP encodings are self-terminating. This means that, given an 208 indefinite-length octet stream, each encoding can be unambiguously 209 decoded from the stream without requiring additional information 210 such as a length field separate from the data type definition. 212 o Bit-fields in this document are specified with bit position 0 213 holding the least-significant bit (LSB). When illustrated in this 214 document, the LSB appears on the right. 216 o In order to describe the encoding of data models specified in 217 [I-D.birrane-dtn-adm], this specification must refer to both the 218 data object being encoded and to the encoding of that data object. 219 When discussing the encoded version of a data object, this 220 specification uses the notation "E(data_object)" where E() refers 221 to a conceptual encoding function. This notation is only provided 222 as a means of clarifying the text and imposes no changes to the 223 actual wire coding. For example, this specification will refer to 224 the "macro" data object as "Macro" and to the encoding of a Macro 225 as "E(Macro)". 227 o Illustrations of fields in this specification consist of the name 228 of the field, the type of the field between []'s, and if the field 229 is optional, the text "(opt)". 230 Field order is deterministic and, therefore, fields MUST be 231 transmitted in the order in which they are specified. In cases 232 where an optional field is not present, then the next field will 233 be considered for transmission. 234 An example is shown in Figure 1 below. In this illustration two 235 fields (Field 1 and Field 2) are shown, with Field 1 of Type 1 and 236 Field 2 of Type 2. Field 2 is also listed as being optional. 237 Byte fields are shown in order of receipt, from left-to-right. 239 Therefore, when transmitted on the wire, Field 1 will be received 240 first, followed by Field 2 (if present). 242 +----------+----------+ 243 | Field 1 | Field 2 | 244 | [TYPE 1] | [TYPE 2] | 245 | | (opt) | 246 +----------+----------+ 248 Figure 1: Byte Field Formatting Example 250 When types are documented in this way, the type always refers to 251 the encoding of that type. The E() notation is not used as it is 252 to be inferred from the context of the illustration. 254 7. AMP-Specific Concepts 256 The AMP specification provides an encoding of objects comprising the 257 AMM. As such, AMP defines very few structures of its own. This 258 section identifies those data structures that are unique to the AMP 259 and required for it to perform appropriate and efficient encodings of 260 AMM objects. 262 7.1. Nicknames (NN) 264 In the AMP, a "Nickname" (NN) is used to reduce the overall size of 265 the encoding of ARIs that are defined in the context of an ADM. A NN 266 is calculated as a function of an ADM Moderated Namespace and the 267 type of object being identified. 269 7.1.1. Motivation for Compression 271 As identifiers, ARIs are used heavily in AMM object definitions, 272 particularly in those that define collections of objects. This makes 273 encoding ARIs an important consideration when trying to optimize the 274 size of AMP message. 276 Additionally, the majority of ARIs are defined in the context of an 277 ADM. Certain AMM objects types (EDDs, OPs, CTBRs, TBLTs) can only be 278 defined in the context of an ADM. Other object types (VARs, CONSTs, 279 RPTTs) may have common, useful objects defined in an ADM as well. 280 The structure of an ADM, to include its use of a Moderated Namespace 281 and collections by object type, provide a regular structure that can 282 be exploited for creating a compact representation. 284 In particular, as specified in [I-D.birrane-dtn-adm], ARIs can be 285 grouped by (1) their namespace and (2) the type of AMM object being 286 identified. For example, consider the following ARIs of type EDD 287 defined in ADM1 with a Moderated Namespace of "/DTN/ADM1/". 289 ari:/DTN/ADM1/Edd.item_1 ari:/DTN/ADM1/Edd.item_2 ... ari:/DTN/ADM1/ 290 Edd.item_1974 292 In this case, the namespace (/DTN/ADM1/) and the object type (Edd) 293 are good candidates for enumeration because their string encoding is 294 very verbose and their information follows a regular structure shared 295 across multiple ARIs. Separately, the string representation of 296 object names (item_1, item_2, etc...) may be very verbose and they 297 are also candidates for enumeration as they occupy a particular ADM 298 object type in a particular order as published in the ADM. 300 7.1.2. ADM Enumeration 302 Any ARI defined in an ADM exists in the context of a Moderated 303 Namespace. These namespaces provide a unique string name for the 304 ADM. However, ADMs can also be assigned a unique enumeration by the 305 same moderating entities that ensure namespace uniqueness. 307 An ADM enumeration is an unsigned integer in the range of 0 to 308 (2^64)/20. This range provides effective support for thousands of 309 trillions of ADMs. 311 The formal set of ADMs, similar to SNMP MIBs and NETCONF YANG models, 312 will be moderated and published. Additionally, a set of informal 313 ADMs may be developed on a network-by-network or on an organization- 314 by-organization bases. 316 Since informal ADMs exist within a predefined context (a network, an 317 organization, or some other entity) they do not have individual ADM 318 enumerations and are assigned the special enumeration "0". ARIs that 319 are not defined in formal ADMs rely on other context information to 320 help with their encoding (see Section 8.3). 322 7.1.3. ADM Object Type Enumeration 324 An ADM Object Type Enumeration is an unsigned integer in the range of 325 0 - 19. This covers all of the standard areas for the ADM Template 326 as defined in [I-D.birrane-dtn-adm]. Each of these types are 327 enumerated in Table 1. 329 +-----------------+-------------+ 330 | AMM Object Type | Enumeration | 331 +-----------------+-------------+ 332 | CONST | 0 | 333 | | | 334 | CTBR | 1 | 335 | | | 336 | EDD | 2 | 337 | | | 338 | MAC | 3 | 339 | | | 340 | OPER | 4 | 341 | | | 342 | RPTT | 5 | 343 | | | 344 | SBR | 6 | 345 | | | 346 | TBLT | 7 | 347 | | | 348 | TBR | 8 | 349 | | | 350 | VAR | 9 | 351 | | | 352 | metadata | 10 | 353 | | | 354 | reserved | 11-19 | 355 +-----------------+-------------+ 357 Table 1: ADM Type Enumerations 359 7.1.4. Nickname Definition 361 As an enumeration, a Nickname is captured as a 64-bit unsigned 362 integer (UVAST) calculated as a function of the ADM enumeration and 363 the ADM type enumeration, as follows. 365 NN = ((ADM Enumeration) * 20) + (ADM Object Type Enumeration) 367 Considering the example set of ARIs from Section 7.1.1, assuming that 368 ADM1 has ADM enumeration 9 and given that objects in the example were 369 of type EDD, the NN for each of the 1974 items would be: (9 * 20) + 2 370 = 182. In this particular example, the ARI "/DTN/ADM1/Edd.item_1974" 371 can be encoded in 5 bytes: two bytes to CBOR encode the nickname 372 (182) and 3 bytes to CBOR encode the item's offset in the Edd 373 collection (1974). 375 7.1.5. ADM Enumeration Considerations 377 The assignment of formal ADM enumerations SHOULD take into 378 consideration the nature of the applications and protocols to which 379 the ADM applies. Those ADMs that are likely to be used in challenged 380 networks SHOULD be allocated low enumeration numbers (e.g. those that 381 will fit into 1-2 bytes) while ADMs that are likely to only be used 382 in well resourced networks SHOULD be allocated higher enumeration 383 numbers. It SHOULD NOT be the case that ADM enumerations are 384 allocated on a first-come, first-served basis. It is recommended 385 that ADM enumerations should be labeled based on the number of bytes 386 of the Nickname as a function of the size of the ADM enumeration. 387 These labels are shown in Table 2. 389 +-------------+--------+--------------+-----------------------------+ 390 | ADM Enum | NN | Label | Comment | 391 | | Size | | | 392 +-------------+--------+--------------+-----------------------------+ 393 | 0x1 - 0xCCC | 1-2 | Challenged | Constraints imposed by | 394 | | Bytes | Networks | physical layer and power. | 395 | | | | | 396 | 0xCCD - | 3-4 | Congested | Constraints imposed by | 397 | 0xCCCCCCC | Bytes | Networks | network traffic. | 398 | | | | | 399 | >=0xCCCCCCD | 5-8 | Resourced | Generally unconstrained | 400 | | Bytes | Networks | networks. | 401 +-------------+--------+--------------+-----------------------------+ 403 Table 2: ADM Enumerations Labels 405 8. Encodings 407 This section describes the binary encoding of logical data constructs 408 using the Concise Binary Object Representation (CBOR) defined in 409 [RFC7049]. 411 8.1. CBOR Considerations 413 The following considerations act as guidance for CBOR encoders and 414 decoders implementing the AMP. 416 o All AMP encodings are of definite length and, therefore, 417 indefinite encodings MUST NOT be used. 419 o AMP encodings MUST NOT use CBOR tags. Identification mechanisms 420 in the AMP capture structure and other information such that tags 421 are not necessary. 423 o Canonical CBOR MUST be used for all encoding. All AMP CBOR 424 decoders MUST run in strict mode. 426 o Encodings MUST result in smallest data representations. There are 427 several cases where the AMM defines types with less granularity 428 than CBOR. For example, AMM defines the UINT type to represent 429 unsigned integers up to 32 bits in length. CBOR supports separate 430 definitions of unsigned integers of 8, 16, or 32 bits in length. 431 In cases where an AMM type MAY be encoded in multiple ways in 432 CBOR, the smallest data representation MUST be used. For example, 433 UINT values of 0-255 MUST be encoded as a uint8_t, and so on. 435 8.2. AMM Type Encodings 437 8.2.1. Primitive Types 439 The AMP encodes AMM primitive types as outlined in Table 3. 441 +--------+-------------+--------------------------------------------+ 442 | AMM | CBOR Major | Comments | 443 | Type | Type | | 444 +--------+-------------+--------------------------------------------+ 445 | BYTE | unsigned | BYTEs are individually encoded as unsigned | 446 | | int or byte | integers unless the are defined as part of | 447 | | string | a byte string, in which case they are | 448 | | | encoded as a single byte in the byte | 449 | | | string. | 450 | | | | 451 | INT | unsigned | INTs are encoded as positive or negative | 452 | | integer or | integers from (u)int8_t up to (u)int32_t. | 453 | | negative | | 454 | | integer | | 455 | | | | 456 | UINT | unsigned | UINTs are unsigned integers from uint8_t | 457 | | integer | up to uint32_t. | 458 | | | | 459 | VAST | unsigned | VASTs are encoding as positive or negative | 460 | | integer or | integers up to (u)int64_t. | 461 | | negative | | 462 | | integer | | 463 | | | | 464 | UVAST | unsigned | VASTs are unsigned integers up to | 465 | | integer | uint64_t. | 466 | | | | 467 | REAL32 | floating | Up to an IEEE-754 Single Precision Float. | 468 | | point | | 469 | | | | 470 | REAL64 | floating | Up to an IEEE-754 Double Precision Float. | 471 | | point | | 472 | | | | 473 | STRING | text string | Uses CBOR encoding unmodified. | 474 | | | | 475 | BOOL | Simple | 0 is considered FALSE. 1 is considered | 476 | | Value | TRUE. | 477 +--------+-------------+--------------------------------------------+ 479 Table 3: Standard Numeric Types 481 8.2.2. Derived Types 483 This section provides the CBOR encodings for AMM derived types. 485 8.2.2.1. Byte String Encoding 487 The AMM derived type Byte String (BYTESTR) is encoded as a CBOR byte 488 string. 490 8.2.2.2. Time Values (TV) and Timestamps (TS) 492 An TV is encoded as a UVAST. Similarly, a TS is also encoded as a 493 UVAST since a TS is simply an absolute TV. 495 Rather than define two separate encodings for TVs (one for absolute 496 TVs and one for relative TVs) a single, unambiguous encoding can be 497 generated by defining a Relative Time Epoch (RTE) and interpreting 498 the type of TV in relation to that epoch. Time values less than the 499 RTE MUST be interpreted as relative times. Time values greater than 500 or equal to the RTE MUST be interpreted as absolute time values. 502 A relative TV is encoded as the number of seconds after an initiating 503 event. An absolute TV (and TS) is encoded as the number of seconds 504 that have elapsed since 1 Jan 2000 00:00:00 (Unix Time 946684800). 506 The RTE is defined as the timestamp value for September 9th, 2017 507 (Unix time 1504915200). Since TS values are the number of seconds 508 since 1 Jan 2000 00:00:00, the RTE as a TS value is 1504915200 - 509 946684800 = 558230400. 511 The potential values of TV, and how they should be interpreted as 512 relative or absolute is illustrated below. 514 Potential Time values 515 ________________________/\________________________ 516 / \ 517 Relative Times Absolute Times 518 <------------------------><------------------------> 519 0 - 558,230,400 558,230,401 - 2^64 521 |------------------------|-------------------------| 522 | | 523 00:00:00 1 Jan 2000 00:00:00 9 Sep 2017 524 Unix Time 946684800 Unix Time 1504915200 526 For example, a time value of "10" is a relative time representing 10 527 seconds after an initiating event. A time value of "600,000,000" 528 refers to Saturday, 5 Jan, 2019 10:40:00. 530 NOTE: Absolute and relative times are interchangeable. An absolute 531 time can be converted into a relative time by subtracting the current 532 time from the absolute time. A relative time can be converted into 533 an absolute time by adding to the relative time the timestamp of its 534 relative event. A pseudo-code example of converting a relative time 535 to an absolute time is as follows, assuming that current-time is 536 expressed in Unix Epoch time. 538 IF (time_value <= 558230400) THEN 539 absolute_time = (event_time - 946684800) + time_value 540 ELSE 541 absolute_time = time_value 543 8.2.2.3. Type-Name-Value (TNV) 545 TNV values are encoded as a CBOR array that comprises four distinct 546 pieces of information: a set of flags, a type, an optional name, and 547 an optional value. In the E(TNV) the flag and type information are 548 compressed into a single value. The CBOR array MUST have length 1, 549 2, or 3 depending on the number of optional fields appearing in the 550 encoding. The E(TNV) format is illustrated in Figure 2. 552 +---------+ 553 | TNV | 554 | [ARRAY] | 555 +----++---+ 556 || 557 || 558 _______________/ \________________ 559 / \ 560 +------------+-----------+----------+ 561 | Flags/Type | Name | Value | 562 | [UINT] | [TXT STR] | [Varies] | 563 | | (opt) | (opt) | 564 +------------+-----------+----------+ 566 Figure 2: E(TNV) Format 568 The E(TNV) fields are defined as follows. 570 Flags/Type 571 The first byte of the E(TNV) describes the type associated 572 with the TNV and which optional components are present. The 573 layout of this byte is illustrated in Figure 3. 575 E(TNV) Flag/Type Byte Format 577 +------+---------------+ 578 | Name | Struct | 579 | Flag | Type | 580 +------+---------------+ 581 | 7 | 6 5 4 3 2 1 0 | 582 +------+---------------+ 583 MSB LSB 585 Figure 3 587 Name Flag 588 This flag indicates that the TNV contains a name 589 field. When set to 1 the Name field MUST be present 590 in the E(TNV). When set to 0 the Name field MUST NOT 591 be present in the E(TNV). 593 Struct Type 594 This field lists the type associated with this TNV 595 and MUST contain one of the types defined in 596 [I-D.birrane-dtn-adm] with the exception that the 597 type of a TNV MUST NOT be a TNV. 599 Name 600 This optional field captures the human-readable name for the 601 TNV encoded as a CBOR text string. If there are 3 elements 602 in the TNV array OR there are 2 elements in the array and the 603 Name Flag is set, then this field MUST be present. 604 Otherwise, this field MUST NOT be present. 606 Value 607 This optional field captures the encoded value associated 608 with this TNV. The value is encoded in accordance with AMP 609 rules for encoding of items of the type of this TNV. If 610 there are 3 elements in the TNV array OR there are 2 elements 611 in the array and the Name Flag is not set, then this field 612 MUST be present. Otherwise, this field MUST NOT be present. 614 8.2.3. Collections 616 8.2.3.1. Type-Name-Value Collection (TNVC) 618 A TNV Collection (TNVC) is a series of multiple TNV values. This is 619 encoded as a CBOR array with each element in the array represented by 620 the encoding of a TNV in accordance with Section 8.2.2.3. 622 8.2.3.2. Type-Then-Value Collection (TTVC) 624 A Types-Then-Value Collection (TTVC) provides a mechanism for 625 communicating a typed set of values by separating the types from the 626 values themselves. This construction is useful both for rapidly 627 performing type verification and for efficiently omitted type 628 information where appropriate. 630 Extracting type information to the "front" of the collection 631 optimizes the performance of type validators. A validator can 632 inspect the first array to ensure that element values match type 633 expectations. If type information were distributed throughout the 634 collection, as in the case with the TNVC, a type validator would need 635 to scan through the entire set of data to validate each type in the 636 collection. A TTVC SHOULD be used in lieu of a TNVC whenever type 637 validation must be performed. 639 In certain circumstances, a set of values can be communicated without 640 any type information when type information can be inferred from 641 context. In these circumstances, separating types from values allows 642 for an efficient way to omit type information when necessary. 644 The TTVC is encoded as a CBOR array with either one or two elements. 645 If the array has 1 element, then it MUST be a CBOR array of values. 646 If the TTVC array has 2 elements, then it MUST contain a CBOR byte 647 string of type information followed by a CBOR array of values. In 648 cases where both types and values are present, the number of types 649 MUST be the same as the number of elements as the array of values. 650 The order of types MUST correspond to the order of values in the 651 second array. 653 The E(TTVC) format is illustrated in Figure 4 654 E(TTVC) Format 656 +---------+ 657 | TTVC | 658 | [ARRAY] | 659 +----++---+ 660 || 661 || 662 ________/ \_________ 663 / \ 664 +-----------+---------+ 665 | Types | Values | 666 | [BYTESTR] | [ARRAY] | 667 | (opt) | | 668 +-----------+---------+ 670 Figure 4 672 These fields are defined as follows. 674 Types 675 The Types field is encoded as a CBOR byte string with each 676 element of the array encoded as a byte. Each byte represents 677 a type and MUST match a type enumeration as defined in 678 [I-D.birrane-dtn-adm]. 680 Values 681 The Values array is encoded as a CBOR array with each element 682 of the array encoded as a CBOR byte string containing the 683 CBOR encoding of the value, based on its type as required by 684 this specification. 686 8.2.3.3. ARI Collections (AC) 688 An ARI collection is an ordered collection of ARI values. It is 689 encoded as a CBOR array with each element being an encoded ARI, as 690 illustrated in Figure 5. 692 E(AC) Format 694 +---------+ 695 | AC | 696 | [ARRAY] | 697 +----++---+ 698 || 699 || 700 ________/ \_________ 701 / \ 702 +-------+ +-------+ 703 | ARI 1 | ... | ARI N | 704 | [ARI] | | [ARI] | 705 +-------+ +-------+ 707 Figure 5 709 8.2.3.4. Expressions (EXPR) 711 The Expression object encapsulates a typed postfix expression in 712 which each operator MUST be of type OPER and each operand MUST be the 713 typed result of an operator or one of EDD, VAR, LIT, or CONST. 715 The Expression object is encoded as a CBOR byte string whose format 716 is illustrated in Figure 6. 718 E(EXPR) Format 720 +--------+------------+ 721 | Type | Expression | 722 | [BYTE] | [AC] | 723 +--------+------------+ 725 Figure 6 727 Type 728 The enumeration representing the type of the result of the 729 evaluated expression. This type MUST be defined in 730 [I-D.birrane-dtn-adm] as a "Primitive Type". 732 Expression 733 An expression is represented in the AMP as an ARI collection, 734 where each ARI in the ordered collection represents either an 735 operand or operator in postfix form. 737 8.3. AMM Resource Identifier (ARI) 739 The ARI, as defined in [I-D.birrane-dtn-adm], identifies an AMM 740 object. There are two kinds of objects that can be identified in 741 this scheme: literal objects (of type LIT) and all other objects. 743 8.3.1. Encoding ARIs of Type LITERAL 745 A literal identifier is one that is literally defined by its value, 746 such as numbers (0, 3.14) and strings ("example"). ARIs of type 747 LITERAL do not have issuers or nicknames or parameters. They are 748 simply typed basic values. 750 The E(ARI) of a LIT object is encoded as a CBOR byte string and 751 consists of a mandatory flag BYTE and the value of the LIT. 753 The E(ARI) structure for LIT types is illustrated in Figure 7. 755 E(ARI) Literal Format 757 +--------+----------+ 758 | Flags | Value | 759 | [BYTE] | [VARIES] | 760 +--------+----------+ 762 Figure 7 764 These fields are defined as follows. 766 Flags 767 The Flags byte identifies the object as being of type LIT and 768 also captures the primitive type of the following value. The 769 layout of this byte is illustrated in Figure 8. 771 E(ARI) Literal Flag Byte Format 773 +------------+-------------+ 774 | VALUE TYPE | STRUCT TYPE | 775 +------------+-------------| 776 | 7 6 5 4 | 3 2 1 0 | 777 +------------+-------------+ 778 MSB LSB 780 Figure 8 782 Value Type 783 The high nibble of the flag byte describes the type 784 of the value of the ARI being encoded. This type 785 MUST be one of the AMM data types defined in 786 [I-D.birrane-dtn-adm] as a "Primitive Type". 788 Structure Type 789 The lower nibble of the flag byte identifies the type 790 of AMM Object being identified by the ARI. In this 791 instance, this value MUST be LIT, as defined in 792 [I-D.birrane-dtn-adm]. 794 Value 795 This field captures the CBOR encoding of the value. Values 796 are encoded according to their Value Type as specified in the 797 flag byte in accordance with the encoding rules provided in 798 Section 8.2.1. 800 8.3.2. Encoding Non-Literal ARIs 802 All other ARIs are defined in the context of AMM objects and may 803 contain parameters and other meta-data. The AMP, as a machine-to- 804 machine binary encoding of this information removes human-readable 805 information such as Name and Description from the E(ARI). 806 Additionally, this encoding adds other information to improve the 807 efficiency of the encoding, such as the concept of Nicknames, defined 808 in Section 7.1. 810 The E(ARI) is encoded as a CBOR byte string and consists of a 811 mandatory flag byte, an encoded object name, and optional annotations 812 to assist with filtering, access control, and parameterization. The 813 E(ARI) structure is illustrated in Figure 9. 815 E(ARI) General Format 817 +--------+---------+-----------+---------+---------+-----------+ 818 | Flags | NN | Name | Parms | Issuer | Tag | 819 | [BYTE] | [UVAST] | [BYTESTR] | [TTVC] | [UVAST] | [BYTESTR] | 820 | | (opt) | | (opt) | (opt) | opt) | 821 +--------+---------+-----------+---------+---------+-----------+ 823 Figure 9 825 These fields are defined as follows. 827 Flags 828 Flags describe the type of structure and which optional 829 fields are present in the encoding. The layout of the flag 830 byte is illustrated in Figure 10. 832 E(ARI) General Flag Byte Format 834 +----+------+-----+-----+-------------+ 835 | NN | PARM | ISS | TAG | STRUCT TYPE | 836 +----+------+-----+-----+-------------+ 837 | 7 | 6 | 5 | 4 | 3 2 1 0 | 838 +----+------+-----+-----+-------------+ 839 MSB LSB 841 Figure 10 843 Nickname (NN) 844 This flag indicates that ADM compression is used for 845 this E(ARI). When set to 1 the Nickname field MUST 846 be present in the E(ARI). When set to 0 the Nickname 847 field MUST NOT be present in the E(ARI). When an ARI 848 is user-defined, there are no semantics for Nicknames 849 and, therefore, this field MUST be 0 when the Issuer 850 flag is set to 1. Implementations SHOULD use 851 Nicknames whenever possible to reduce the size of the 852 E(ARI). 854 Parameters Present (PARM) 855 This flag indicates that this ARI can be 856 parameterized and that parameter information is 857 included in the E(ARI). When set to 1 the Parms 858 field MUST be present in the E(ARI). When set to 0 859 the Parms field MUST NOT be present in the E(ARI). 861 Issuer Present (ISS) 862 This flag indicates that this ARI is defined in the 863 context of a specific issuing entity. When set to 1 864 the Issuer field MUST be present in the E(ARI). When 865 set to 0 the Issuer field MUST NOT be present in the 866 E(ARI). 868 Tag Present (TAG) 869 This flag indicates that the ARI is defined in the 870 context of a specific issuing entity and that issuing 871 entity adds additional information in the form of a 872 tag. When set to 1 the Tag field MUST be present in 873 the E(ARI). When set to 0 the Tag field MUST NOT be 874 present in the E(ARI). This flag MUST be set to 0 if 875 the Issuer Present flag is set to 0. 877 Structure Type (STRUCT TYPE) 878 The lower nibble of the E(ARI) flag byte identifies 879 the kind of structure being identified. This field 880 MUST contain one of the AMM object types defined in 881 [I-D.birrane-dtn-adm]. 883 Nickname (NN) 884 This optional field contains the Nickname as calculated 885 according to Section 7.1. 887 Object Name 888 This mandatory field contains an encoding of the ADM object. 889 For elements defined in an ADM Template (e.g., where the 890 Issuer Flag is set to 0) this is the 0-based index into the 891 ADM collection holding this element. For all user-defined 892 ADM objects, (e.g., where the Issuer Flag is set to 1) this 893 value is as defined by the Issuing organization. 895 Parameters 896 The parameters field is represented as a Types Then Value 897 Collection (TTVC) as defined in Section 8.2.3.2. The overall 898 number of items in the collection represents the number of 899 parameters. The types of the TTVC represent the types of 900 each parameter, with the first listed type associated with 901 the first parameter, and so on. The values, if present, 902 represent the values of the parameters, with the first listed 903 value being the value of the first parameter, and so on. 905 Issuer 906 This is a binary identifier representing a predetermined 907 issuer name. The AMP protocol does not parse or validate 908 this identifier, using it only as a distinguishing bit 909 pattern to ensure uniqueness. This value, for example, may 910 come from a global registry of organizations, an issuing node 911 address, or some other network-unique marking. The issuer 912 field MUST NOT be present for any ARI defined in an ADM. 914 Tag 915 A value used to disambiguate multiple ARIs with the same 916 Issuer. The definition of the tag is left to the discretion 917 of the Issuer. The Tag field MUST be present if the Tag Flag 918 is set in the flag byte and MUST NOT be present otherwise. 920 8.4. ADM Object Encodings 922 The autonomy model codified in [I-D.birrane-dtn-adm] comprises 923 multiple individual objects. This section describes the CBOR 924 encoding of these objects. 926 Note: The encoding of an object refers to the way in which the 927 complete object can be encoded such that the object as it exists on a 928 Manager may be re-created on an Agent, and vice-versa. In cases 929 where both a Manager and an Agent already have the definition of an 930 object, then only the encoded ARI of the object needs to be 931 communicated. This is the case for all objects defined in a 932 published ADM and any user-defined object that has been synchronized 933 between an Agent and Manager. 935 8.4.1. Externally Defined Data (EDD) 937 Externally defined data (EDD) are solely defined in the ADMs for 938 various applications and protocols. EDDs represent values that are 939 calculated external to an AMA Agent, such as values measured by 940 firmware. 942 The representation of these data is simply their identifying ARIs. 943 The representation of an EDD is illustrated in Figure 11. 945 E(EDD) Format 947 +-------+ 948 | ID | 949 | [ARI] | 950 +-------+ 952 Figure 11 954 ID 955 This is the ARI identifying the EDD. Since EDDs are always 956 defined solely in the context of an ADM, this ARI MUST NOT 957 have an ISSUER field and MUST NOT have a TAG field. This ARI 958 may be defined with parameters. 960 8.4.2. Constants (CONST) 962 Unlike Literals, a Constant is an immutable, typed, named value. 963 Examples of constants include PI to some number of digits or the UNIX 964 Epoch. 966 Since ADM definitions are preconfigured on Agents and Managers in an 967 AMA, the type information for a given Constant is known by all actors 968 in the system and the encoding of the Constant needs to only be the 969 name of the constant as the Manager and Agent can derive the type and 970 value from the unique Constant name. 972 The format of a Constant is illustrated in Figure 12. 974 E(CONST) Format 976 +-------+ 977 | ID | 978 | [ARI] | 979 +-------+ 981 Figure 12 983 ID 984 This is the ARI identifying the Constant. Since Constant 985 definitions are always provided in an ADM, this ARI MUST NOT 986 have an ISSUER field and MUST NOT have a TAG field. The ARI 987 MUST NOT have parameters. 989 8.4.3. Controls (CTBR) 991 A Control represents a pre-defined and optionally parameterized 992 opcode that can be run on an Agent. Controls in the AMP are always 993 defined in the context of an AMA; there is no concept of an operator- 994 defined Control. Since Controls are pre-configured in Agents and 995 Managers as part of ADM support, their representation is the ARI that 996 identifies them, similar to EDDs. 998 The format of a Control is illustrated in Figure 13. 1000 E(CTBR) Format 1002 +-------+ 1003 | ID | 1004 | [ARI] | 1005 +-------+ 1007 Figure 13 1009 ID 1010 This is the ARI identifying the Control. This ARI MUST NOT 1011 have an ISSUER field and MUST NOT have a TAG field. This ARI 1012 may have parameters. 1014 8.4.4. Macros (MAC) 1016 Macros in the AMP are ordered collections of ARIs (an AC) that 1017 contain Controls or other Macros. When run by an Agent, each ARI in 1018 the AC MUST be run in order. 1020 Any AMP implementation MUST allow at least 4 levels of Macro nesting. 1021 Implementations MUST prevent recursive nesting of Macros. 1023 The ARI associated with a Macro MAY contain parameters. Each 1024 parameter present in a Macro ARI MUST contain type, name, and value 1025 information. Any Control or Macro encapsulated within a 1026 parameterized Macro MAY also contain parameters. If an encapsulated 1027 object parameter contains only name information, then the parameter 1028 value MUST be taken from the named parameter provided by the 1029 encapsulating Macro. Otherwise, the value provided to the object 1030 MUST be used instead. 1032 The format of a Macro is illustrated in Figure 14. 1034 E(MAC) Format 1036 +-------+------------+ 1037 | ID | Definition | 1038 | [ARI] | [AC] | 1039 +-------+------------+ 1041 Figure 14 1043 ID 1044 This is the ARI identifying the Macro. When a Macro is 1045 defined in an ADM this ARI MUST NOT have an ISSUER field and 1046 MUST NOT have a TAG field. When the Macro is defined outside 1047 of an ADM, the ARI MUST have an ISSUER field and MAY have a 1048 TAG field. 1050 Definition 1051 This is the ordered collection of ARIs that identify the 1052 Controls and other Macros that should be run as part of 1053 running this Macro. 1055 8.4.5. Operators (OPER) 1057 Operators are always defined in the context of an ADM. There is no 1058 concept of a user-defined operator, as operators represent 1059 mathematical functions implemented by the firmware on an Agent. 1060 Since Operators are preconfigured in Agents and Managers as part of 1061 ADM support, their representation is simply the ARI that identifies 1062 them. 1064 The ADM definition of an Operator MUST specify how many parameters 1065 are expected and the expected type of each parameter. For example, 1066 the unary NOT Operator ("!") would accept one parameter. The binary 1067 PLUS Operator ("+") would accept two parameters. A custom function 1068 to calculate the average of the last 10 samples of a data item should 1069 accept 10 parameters. 1071 Operators are always evaluated in the context of an Expression. The 1072 encoding of an Operator is illustrated in Figure 15. 1074 E(OP) Format 1076 +-------+ 1077 | ID | 1078 | [ARI] | 1079 +-------+ 1081 Figure 15 1083 ID 1084 This is the ARI identifying the Operator. Since Operators 1085 are always defined solely in the context of an ADM, this ARI 1086 MUST NOT have an ISSUER field and MUST NOT have a TAG field. 1088 8.4.6. Report Templates (RPTT) 1090 A Report Template is an ordered collection of identifiers that 1091 describe the order and format of data in any Report built in 1092 compliance with the template. A template is a schema for a class of 1093 reports. It contains no actual values and may be defined in a formal 1094 ADM or configured by users in the context of a network deployment. 1096 A Report Template is modeled as an AC, as each data definition in the 1097 template is identified by an ARI. 1099 E(RPTT) Format 1101 +-----------------+ 1102 | Report Contents | 1103 | [AC] | 1104 +-----------------+ 1106 Figure 16 1108 8.4.7. Report (RPT) 1110 A Report is a set of data values populated using a given Report 1111 Template. While Reports do not contain name information, they MAY 1112 contain type information in cases where recipients wish to perform 1113 type validation prior to interpreting the Report contents in the 1114 context of a Report Template. Reports are "anonymous" in the sense 1115 that any individual Report does not contain a unique identifier. 1116 Reports can be differentiated by examining the combination of (1) the 1117 Report Template being populated, (2) the time at which the Report was 1118 populated, and (3) the Agent producing the report. 1120 A Report object is comprised of the identifier of the template used 1121 to populate the report, an optional timestamp, and the contents of 1122 the report. A Report is encoded as a CBOR array with either 2 or 3 1123 elements. If the array has 2 elements then the optional Timestamp 1124 MUST NOT be in the Report encoding. If the array has 3 elements then 1125 the optional timestamp MUST be included in the Report encoding. The 1126 Report encoding is illustrated in Figure 17. 1128 E(RPT) Format 1130 +---------+ 1131 | RPT | 1132 | [ARRAY] | 1133 +---++----+ 1134 || 1135 || 1136 _____________/ \_____________ 1137 / \ 1138 +----------+-----------+---------+ 1139 | Template | Timestamp | Entries | 1140 | [ARI] | [TS] | [TTVC] | 1141 | | (opt) | | 1142 +----------+-----------+---------+ 1144 Figure 17 1146 Template 1147 This is the ARI identifying the template used to interpret 1148 the data in this report. 1150 This ARI may be parameterized and, if so, the parameters MUST 1151 include a name field and have been passed-by-name to the 1152 template contents when constructing the report. 1154 Timestamp 1155 The timestamp marks the time at which the report was created. 1156 This timestamp may be omitted in cases where the time of the 1157 report generation can be inferred from other information. 1158 For example, if a report is included in a message group such 1159 that the timestamp of the message group is equivalent to the 1160 timestamp of the report, the report timestamp may be omitted 1161 and the timestamp of the included message group used instead. 1163 Entries 1164 This is the collection of data values that comprise the 1165 report contents in accordance with the associated Report 1166 Template. 1168 8.4.8. State-Based Rules (SBR) 1170 A State-Based Rule (SBR) specifies that a particular action should be 1171 taken by an Agent based on some evaluation of the internal state of 1172 the Agent. A SBR specifies that starting at a particular START time 1173 an ACTION should be run by the Agent if some CONDITION evaluates to 1174 true, until the ACTION has been run COUNT times. When the SBR is no 1175 longer valid it may be discarded by the agent. 1177 Examples of SBRs include: 1179 Starting 2 hours from receipt, whenever V1 > 10, produce a Report 1180 for Report Template R1 no more than 20 times. 1182 Starting at some future absolute time, whenever V2 != V4, run 1183 Macro M1 no more than 36 times. 1185 An SBR object is encoded as a CBOR array with 5 elements as 1186 illustrated in Figure 18. 1188 E(SBR) Format 1190 +---------+ 1191 | SBR | 1192 | [ARRAY] | 1193 +---++----+ 1194 || 1195 || 1196 ___________________/ \___________________ 1197 / \ 1198 +-------+-------+--------+--------+--------+ 1199 | ID | START | COND | COUNT | ACTION | 1200 | [ARI] | [TV] | [EXPR] | [UINT] | [AC] | 1201 | | | | | | 1202 +-------+-------+--------+--------+--------+ 1204 Figure 18 1206 ID 1207 This is the ARI identifying the SBR. If this ARI contains 1208 parameters they MUST include a name in support of pass-by- 1209 name to each element of the Action AC. 1211 START 1212 The time at which the SBR condition should start to be 1213 evaluated. This will mark the first evaluation of the 1214 condition associated with the SBR. 1216 CONDITION 1217 The Expression which, if true, results in the SBR running the 1218 associated action. An EXPR is considered true if it 1219 evaluates to a non-zero value. 1221 COUNT 1222 The number of times the SBR action can be run. The special 1223 value of 0 indicates there is no limit on how many times the 1224 action can be run. 1226 ACTION 1227 The collection of Controls and/or Macros to run as part of 1228 the action. This is encoded as an AC in accordance with 1229 Section 8.2.3.3 with the stipulation that every ARI in this 1230 collection MUST be of type CTRL or MAC. 1232 8.4.9. Table Templates (TBLT) 1234 A Table Template (TBLT) describes the types, and optionally names, of 1235 the columns that define a Table. 1237 The TBLT Object is encoded as a CBOR array that MUST contain either 2 1238 or 3 elements. If the array is of size 2, then the column names 1239 array MUST NOT be present in the encoding. If the array is of size 3 1240 then the column names array MUST be present in the encoding. The 1241 format of the TBLT Object Array is illustrated in Figure 19. 1243 E(TBLT) Format 1245 +---------+ 1246 | TBLT | 1247 | [ARRAY] | 1248 +---++----+ 1249 || 1250 || 1251 ____________/ \_____________ 1252 / \ 1253 +-------+-----------+---------+ 1254 | ID | Types | Names | 1255 | [ARI] | [BYTESTR] | [ARRAY] | 1256 | | | (opt) | 1257 +-------+-----------+---------+ 1259 Figure 19 1261 The elements of the TBLT array are defined as follows. 1263 ID 1264 This is the ARI of the table template encoded in accordance 1265 with Section 8.3. 1267 Types 1268 The types field captures the data types of each column 1269 comprising the table template. Each type is represented by 1270 its enumeration as defined in [I-D.birrane-dtn-adm]. This 1271 field is encoded as a CBOR byte string with the length of the 1272 string equal to the number of columns in the template and 1273 each column type enumeration encoded as a byte. The Nth byte 1274 in the byte string represents the type of the Nth column. 1276 Names 1277 When present, column names are encoded as a CBOR array. This 1278 array MUST have the same number of elements as bytes in the 1279 Types byte string. Each element in the Names array is 1280 encoded as a CBOR text string and represents the string 1281 representation of the column name. The Nth text string in 1282 the array represents the name of the Nth column. 1284 8.4.10. Tables (TBL) 1286 A Table object describes the series of values associated with a 1287 Table Template. 1289 A Table object is encoded as a CBOR array, with the first element of 1290 the array identifying the Table Template and each subsequent element 1291 identifying a row in the table. The format of the TBL Object Array 1292 is illustrated in Figure 20. 1294 E(TBL) Format 1296 +---------+ 1297 | TBL | 1298 | [ARRAY] | 1299 +---++----+ 1300 || 1301 || 1302 ______________/ \_______________ 1303 / \ 1304 +---------+--------+ +--------+ 1305 | TBLT ID | Row 1 | | Row N | 1306 | [ARI] | [TTVC] | ... | [TTVC] | 1307 +---------+--------+ +--------+ 1309 Figure 20 1311 The TBL fields are defined as follows. 1313 Template ID (TBLT ID) 1314 This is the ARI of the table template describing the format 1315 of the table and is encoded in accordance with Section 8.3. 1317 Row 1318 Each row of the table is represented as a series of values 1319 with optional type information to aid in type checking table 1320 contents to column types. Each row is encoded as a TTVC and 1321 MAY include type information. AMP implementations should 1322 consider the impact of including type information for every 1323 row on the overall size of the encoded table. 1324 Each TTVC representing a row MUST contain the same number of 1325 elements as there are columns in the referenced 1326 Table Template. 1328 8.4.11. Time-Based Rules (TBR) 1330 A Time-Based Rule (TBR) specifies that a particular action should be 1331 taken by an Agent based on some time interval. A TBR specifies that 1332 starting at a particular START time, and for every PERIOD seconds 1333 thereafter, an ACTION should be run by the Agent until the ACTION has 1334 been run for COUNT times. When the TBR is no longer valid it MAY BE 1335 discarded by the Agent. 1337 Examples of TBRs include: 1339 Starting 2 hours from receipt, produce a Report for Report 1340 Template R1 every 10 hours ending after 20 times. 1342 Starting at the given absolute time, run Macro M1 every 24 hours 1343 ending after 365 times. 1345 The TBR object is encoded as a CBOR array with 5 elements as 1346 illustrated in Figure 21. 1348 E(TBR) Format 1350 +---------+ 1351 | TBR | 1352 | [ARRAY] | 1353 +---++----+ 1354 || 1355 || 1356 ___________________/ \___________________ 1357 / \ 1358 +-------+-------+--------+--------+--------+ 1359 | ID | START | PERIOD | COUNT | ACTION | 1360 | [ARI] | [TV] | [UINT] | [UINT] | [AC] | 1361 +-------+-------+--------+--------+--------+ 1363 Figure 21 1365 ID 1366 This is the ARI identifying the TBR and is encoded in 1367 accordance with Section 8.3. If this ARI contains parameters 1368 they MUST include a name in support of pass-by-name to each 1369 element of the Action AC. 1371 START 1372 The time at which the TBR condition should start to be 1373 evaluated. 1375 PERIOD 1376 The number of seconds to wait between running the action 1377 associated with the TBR. 1379 COUNT 1380 The number of times the TBR action can be run. The special 1381 value of 0 indicates there is no limit on how many times the 1382 action can be run. 1384 ACTION 1385 The collection of Controls and/or Macros to run as part of 1386 the action. This is encoded as an ARI Collection in 1387 accordance with Section 8.2.3.3 with the stipulation that 1388 every ARI in this collection MUST represent either a Control 1389 or a Macro. 1391 8.4.12. Variables (VAR) 1393 Variable objects are transmitted in the AMP without the human- 1394 readable description. 1396 Variable objects are encoded as a CBOR byte string whose format is 1397 illustrated in Figure 22. 1399 E(VAR) Format 1401 +------------+ 1402 | Variable | 1403 | [BYTESTR] | 1404 +-----++-----+ 1405 || 1406 || 1407 ______________/ \____________ 1408 / \ 1409 +-------+--------+-------------+ 1410 | ID | Type | Initializer | 1411 | [ARI] | [BYTE] | [EXPR] | 1412 +-------+--------+-------------+ 1414 Figure 22 1416 ID 1417 This is the ARI identifying the VAR and is encoded in 1418 accordance with Section 8.3. This ARI MUST NOT include 1419 parameters. 1421 Type 1422 This field captures the data type of the Variable encoded as 1423 a BYTE. This data type MUST be one of the data types defined 1424 in [I-D.birrane-dtn-adm]. 1425 It is possible to specify a type different than the resultant 1426 type of the initializing Expression. For example, if an 1427 Expression adds two single-precision floating point numbers, 1428 the VAR MAY have an integer type associated with it. In 1429 cases where this is the case, numeric conversions MUST be 1430 handled in accordance with [I-D.birrane-dtn-adm]. 1432 Initializer 1433 The initial value of the Variable is calculated by an 1434 Expression encoded in accordance with Section 8.2.3.4. 1436 9. Functional Specification 1438 This section describes the format of the messages that comprise the 1439 AMP protocol. 1441 9.1. AMP Message Summary 1443 The AMP message specification is limited to three basic 1444 communications: 1446 +------------+-------------+----------------------------------------+ 1447 | Message | Enumeration | Description | 1448 +------------+-------------+----------------------------------------+ 1449 | Register | 0 | Add Agents to the list of managed | 1450 | Agent | | devices known to a Manager. | 1451 | | | | 1452 | Report Set | 1 | Receiving a Report of one or more | 1453 | | | Report Entries from an Agent. | 1454 | | | | 1455 | Perform | 2 | Sending a Macro of one or more | 1456 | Control | | Controls to an Agent. | 1457 +------------+-------------+----------------------------------------+ 1459 Table 4: ADM Message Type Enumerations 1461 The entire management of a network can be performed using these three 1462 messages and the configurations from associated ADMs. 1464 9.2. Message Group Format 1466 Individual messages within the AMP are combined into a single group 1467 for communication with another AMP Actor. Messages within a group 1468 MUST be received and applied as an atomic unit. The format of a 1469 message group is illustrated in Figure 23. These message groups are 1470 assumed communicated amongst Agents and Managers as the payloads of 1471 encapsulating protocols which should provide additional security and 1472 data integrity features as needed. 1474 A message group is encoded as a CBOR array with at least 2 elements, 1475 the first being the time the group was created followed by 1 or more 1476 messages that comprise the group. The format of the message group is 1477 illustrated in Figure 23. 1479 AMP Message Group Format 1481 +---------------+ 1482 | Message Group | 1483 | [ARRAY] | 1484 +------++-------+ 1485 || 1486 ____________________||___________________ 1487 / \ 1488 +-----------+-----------+ +-----------+ 1489 | Timestamp | Message 1 | ... | Message N | 1490 | [TS] | [BYTESTR] | | [BYTESTR] | 1491 +-----------+-----------+ +-----------+ 1493 Figure 23 1495 Timestamp 1496 The creation time for this messaging group. Individual 1497 messages may have their own creation timestamps based on 1498 their type, but the group timestamp also serves as the 1499 default creation timestamp for every message in the group. 1500 This is encoded in accordance with Table 3. 1502 Message N 1503 The Nth message in the group. 1505 9.3. Message Format 1507 Each message identified in the AMP specification adheres to a common 1508 message format, illustrated in Figure 24, consisting of a message 1509 header, a message body, and an optional trailer. 1511 Each message in the AMP is encode as a CBOR byte string formatted in 1512 accordance with Figure 24. 1514 AMP Message Format 1516 +--------+----------+----------+ 1517 | Header | Body | Trailer | 1518 | [BYTE] | [VARIES] | [VARIES] | 1519 | | | (opt.) | 1520 +--------+----------+----------+ 1522 Figure 24 1524 Header 1525 The message header BYTE is shown in Figure 25. The header 1526 identifies a message context and opcode as well as flags that 1527 control whether a Report should be generated on message 1528 success (Ack) and whether a Report should be generated on 1529 message failure (Nack). 1531 AMP Common Message Header 1533 +----------+-----+------+-----+----------+ 1534 | Reserved | ACL | Nack | Ack | Opcode | 1535 +----------+-----+------+-----+----------+ 1536 | 7 6 | 5 | 4 | 3 | 2 1 0 | 1537 +----------+-----+------+-----+----------+ 1538 MSB LSB 1540 Figure 25 1542 Opcode 1543 The opcode field identifies which AMP message is 1544 being represented. 1546 ACK Flag 1547 The ACK flag describes whether successful application 1548 of the message must generate an acknowledgment back 1549 to the message sender. If this flag is set (1) then 1550 the receiving actor MUST generate a Report 1551 communicating this status. Otherwise, the actor MAY 1552 generate such a Report based on other criteria. 1554 NACK Flag 1555 The NACK flag describes whether a failure applying 1556 the message must generate an error notice back to the 1557 message sender. If this flag is set (1) then the 1558 receiving Actor MUST generate a Report communicating 1559 this status. Otherwise, the Actor MAY generate such 1560 a Report based on other criteria. 1562 ACL Used Flag 1563 The ACL used flag indicates whether the message has a 1564 trailer associated with it that specifies the list of 1565 AMP actors that may participate in the Actions or 1566 definitions associated with the message. This area 1567 is still under development. 1569 Body 1570 The message body contains the information associated with the 1571 given message. 1573 Trailer 1574 An OPTIONAL access control list (ACL) may be appended as a 1575 trailer to a message. When present, the ACL for a message 1576 identifiers the agents and managers that can be affected by 1577 the definitions and actions contained within the message. 1578 The explicit impact of an ACL is described in the context of 1579 each message below. When an ACL trailer is not present, the 1580 message results may be visible to any AMP Actor in the 1581 network, pursuant to other security protocol implementations. 1583 9.4. Register Agent 1585 The Register Agent message is used to inform an AMP Manager of the 1586 presence of another Agent in the network. 1588 The body of this message is the name of the new agent, encoded as 1589 illustrated in Figure 26. 1591 Register Agent Message Body 1593 +-----------+ 1594 | Agent ID | 1595 | [BYTESTR] | 1596 +-----------+ 1598 Figure 26 1600 Agent ID 1601 The Agent ID MUST represent the unique address of the Agent 1602 in whatever protocol is used to communicate with the Agent. 1604 9.5. Report Set 1606 The Report Set message contains a set of 1 or more Reports produced 1607 by an AMP Agent and sent to an AMP Manager. 1609 The body of this message contains information on the recipient of the 1610 reports followed by one or more Reports. The body is encoded as 1611 illustrated in Figure 27. 1613 Report Set Message Body 1615 +----------+--------+ +--------+ 1616 | RX Names | RPT 1 | | RPT N | 1617 | [ARRAY] | [RPT] | ... | [RPT] | 1618 +----------+--------+ +--------+ 1620 Figure 27 1622 RX Names 1623 This field captures the set of Managers that have been sent 1624 this report set. This is encoded as a CBOR array that MUST 1625 have at least one entry. Each entry in this array is 1626 encdoded as a CBOR text string. 1628 RPT N 1629 The Nth Report encoded in accordance with Section 8.4.7. 1631 9.6. Perform Control 1633 The perform control message causes the receiving AMP Actor to run one 1634 or more preconfigured Controls provided in the message. 1636 The body of this message is the start time for the controls followed 1637 by the controls themselves, as illustrated in Figure 28. 1639 Perform Control Message Body 1641 +-------+-----------+ 1642 | Start | Controls | 1643 | [TV] | [AC] | 1644 +-------+-----------+ 1646 Figure 28 1648 Start 1649 The time at which the Controls/Macros should be run. 1651 Controls 1652 The collection of ARIs that represent the Controls and/or 1653 Macros to be run by the AMP Actor. Every ARI in this 1654 collection MUST be either a Control or a Macro. 1656 10. IANA Considerations 1658 A Nickname registry needs to be established. 1660 11. Security Considerations 1662 Security within the AMP exists in two layers: transport layer 1663 security and access control. 1665 Transport-layer security addresses the questions of authentication, 1666 integrity, and confidentiality associated with the transport of 1667 messages between and amongst Managers and Agents. This security is 1668 applied before any particular Actor in the system receives data and, 1669 therefore, is outside of the scope of this document. 1671 Finer grain application security is done via ACLs provided in the AMP 1672 message headers. 1674 12. References 1676 12.1. Informative References 1678 [I-D.birrane-dtn-ama] 1679 Birrane, E., "Asynchronous Management Architecture", 1680 draft-birrane-dtn-ama-07 (work in progress), June 2018. 1682 12.2. Normative References 1684 [I-D.birrane-dtn-adm] 1685 Birrane, E., DiPietro, E., and D. Linko, "AMA Application 1686 Data Model", draft-birrane-dtn-adm-02 (work in progress), 1687 June 2018. 1689 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1690 Requirement Levels", BCP 14, RFC 2119, 1691 DOI 10.17487/RFC2119, March 1997, 1692 . 1694 [RFC7049] Bormann, C. and P. Hoffman, "Concise Binary Object 1695 Representation (CBOR)", RFC 7049, DOI 10.17487/RFC7049, 1696 October 2013, . 1698 Appendix A. Acknowledgements 1700 The following participants contributed technical material, use cases, 1701 and useful thoughts on the overall approach to this protocol 1702 specification: Jeremy Pierce-Mayer of INSYEN AG contributed the 1703 concept of the typed data collection and early type checking in the 1704 protocol. David Linko and Evana DiPietro of the Johns Hopkins 1705 University Applied Physics Laboratory contributed appreciated review 1706 and type checking of various elements of this specification. 1708 Author's Address 1710 Edward J. Birrane 1711 Johns Hopkins Applied Physics Laboratory 1713 Email: Edward.Birrane@jhuapl.edu