< draft-birrane-dtn-amp-05.txt   draft-birrane-dtn-amp-06.txt >
Delay-Tolerant Networking E. Birrane Delay-Tolerant Networking E. Birrane
Internet-Draft Johns Hopkins Applied Physics Laboratory Internet-Draft Johns Hopkins Applied Physics Laboratory
Intended status: Standards Track July 2, 2018 Intended status: Standards Track March 11, 2019
Expires: January 3, 2019 Expires: September 12, 2019
Asynchronous Management Protocol Asynchronous Management Protocol
draft-birrane-dtn-amp-05 draft-birrane-dtn-amp-06
Abstract Abstract
This document describes a binary encoding of the Asynchronous This document describes a binary encoding of the Asynchronous
Management Model (AMM) and a protocol for the exchange of these Management Model (AMM) and a protocol for the exchange of these
encoded items over a network. This Asynchronous Management Protocol encoded items over a network. This Asynchronous Management Protocol
(AMP) does not require transport-layer sessions, operates over (AMP) does not require transport-layer sessions, operates over
unidirectional links, and seeks to reduce the energy and compute unidirectional links, and seeks to reduce the energy and compute
power necessary for performing network management on resource power necessary for performing network management on resource
constrained devices. constrained devices.
skipping to change at page 1, line 36 skipping to change at page 1, line 36
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF). Note that other groups may also distribute Task Force (IETF). Note that other groups may also distribute
working documents as Internet-Drafts. The list of current Internet- working documents as Internet-Drafts. The list of current Internet-
Drafts is at https://datatracker.ietf.org/drafts/current/. Drafts is at https://datatracker.ietf.org/drafts/current/.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
This Internet-Draft will expire on January 3, 2019. This Internet-Draft will expire on September 12, 2019.
Copyright Notice Copyright Notice
Copyright (c) 2018 IETF Trust and the persons identified as the Copyright (c) 2019 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(https://trustee.ietf.org/license-info) in effect on the date of (https://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
skipping to change at page 2, line 30 skipping to change at page 2, line 30
7.1.2. ADM Enumeration . . . . . . . . . . . . . . . . . . . 7 7.1.2. ADM Enumeration . . . . . . . . . . . . . . . . . . . 7
7.1.3. ADM Object Type Enumeration . . . . . . . . . . . . . 7 7.1.3. ADM Object Type Enumeration . . . . . . . . . . . . . 7
7.1.4. Nickname Definition . . . . . . . . . . . . . . . . . 8 7.1.4. Nickname Definition . . . . . . . . . . . . . . . . . 8
7.1.5. ADM Enumeration Considerations . . . . . . . . . . . 9 7.1.5. ADM Enumeration Considerations . . . . . . . . . . . 9
8. Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . 9 8. Encodings . . . . . . . . . . . . . . . . . . . . . . . . . . 9
8.1. CBOR Considerations . . . . . . . . . . . . . . . . . . . 9 8.1. CBOR Considerations . . . . . . . . . . . . . . . . . . . 9
8.2. AMM Type Encodings . . . . . . . . . . . . . . . . . . . 10 8.2. AMM Type Encodings . . . . . . . . . . . . . . . . . . . 10
8.2.1. Primitive Types . . . . . . . . . . . . . . . . . . . 10 8.2.1. Primitive Types . . . . . . . . . . . . . . . . . . . 10
8.2.2. Derived Types . . . . . . . . . . . . . . . . . . . . 11 8.2.2. Derived Types . . . . . . . . . . . . . . . . . . . . 11
8.2.3. Collections . . . . . . . . . . . . . . . . . . . . . 14 8.2.3. Collections . . . . . . . . . . . . . . . . . . . . . 14
8.3. AMM Resource Identifier (ARI) . . . . . . . . . . . . . . 18 8.3. AMM Resource Identifier (ARI) . . . . . . . . . . . . . . 19
8.3.1. Encoding ARIs of Type LITERAL . . . . . . . . . . . . 18 8.3.1. Encoding ARIs of Type LITERAL . . . . . . . . . . . . 19
8.3.2. Encoding Non-Literal ARIs . . . . . . . . . . . . . . 19 8.3.2. Encoding Non-Literal ARIs . . . . . . . . . . . . . . 20
8.4. ADM Object Encodings . . . . . . . . . . . . . . . . . . 21 8.4. ADM Object Encodings . . . . . . . . . . . . . . . . . . 22
8.4.1. Externally Defined Data (EDD) . . . . . . . . . . . . 22 8.4.1. Externally Defined Data (EDD) . . . . . . . . . . . . 23
8.4.2. Constants (CONST) . . . . . . . . . . . . . . . . . . 22 8.4.2. Constants (CONST) . . . . . . . . . . . . . . . . . . 23
8.4.3. Controls (CTBR) . . . . . . . . . . . . . . . . . . . 23 8.4.3. Controls (CTRL) . . . . . . . . . . . . . . . . . . . 24
8.4.4. Macros (MAC) . . . . . . . . . . . . . . . . . . . . 23 8.4.4. Macros (MAC) . . . . . . . . . . . . . . . . . . . . 24
8.4.5. Operators (OPER) . . . . . . . . . . . . . . . . . . 24 8.4.5. Operators (OPER) . . . . . . . . . . . . . . . . . . 25
8.4.6. Report Templates (RPTT) . . . . . . . . . . . . . . . 25 8.4.6. Report Templates (RPTT) . . . . . . . . . . . . . . . 26
8.4.7. Report (RPT) . . . . . . . . . . . . . . . . . . . . 25 8.4.7. Report (RPT) . . . . . . . . . . . . . . . . . . . . 26
8.4.8. State-Based Rules (SBR) . . . . . . . . . . . . . . . 27 8.4.8. State-Based Rules (SBR) . . . . . . . . . . . . . . . 28
8.4.9. Table Templates (TBLT) . . . . . . . . . . . . . . . 28 8.4.9. Table Templates (TBLT) . . . . . . . . . . . . . . . 29
8.4.10. Tables (TBL) . . . . . . . . . . . . . . . . . . . . 29 8.4.10. Tables (TBL) . . . . . . . . . . . . . . . . . . . . 30
8.4.11. Time-Based Rules (TBR) . . . . . . . . . . . . . . . 30 8.4.11. Time-Based Rules (TBR) . . . . . . . . . . . . . . . 31
8.4.12. Variables (VAR) . . . . . . . . . . . . . . . . . . . 31 8.4.12. Variables (VAR) . . . . . . . . . . . . . . . . . . . 32
9. Functional Specification . . . . . . . . . . . . . . . . . . 32 9. Functional Specification . . . . . . . . . . . . . . . . . . 33
9.1. AMP Message Summary . . . . . . . . . . . . . . . . . . . 33 9.1. AMP Message Summary . . . . . . . . . . . . . . . . . . . 33
9.2. Message Group Format . . . . . . . . . . . . . . . . . . 33 9.2. Message Group Format . . . . . . . . . . . . . . . . . . 34
9.3. Message Format . . . . . . . . . . . . . . . . . . . . . 34 9.3. Message Format . . . . . . . . . . . . . . . . . . . . . 35
9.4. Register Agent . . . . . . . . . . . . . . . . . . . . . 36 9.4. Register Agent . . . . . . . . . . . . . . . . . . . . . 36
9.5. Report Set . . . . . . . . . . . . . . . . . . . . . . . 36 9.5. Report Set . . . . . . . . . . . . . . . . . . . . . . . 37
9.6. Perform Control . . . . . . . . . . . . . . . . . . . . . 37 9.6. Perform Control . . . . . . . . . . . . . . . . . . . . . 37
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 38
11. Security Considerations . . . . . . . . . . . . . . . . . . . 37 11. Security Considerations . . . . . . . . . . . . . . . . . . . 38
12. References . . . . . . . . . . . . . . . . . . . . . . . . . 38 12. Implementation Notes . . . . . . . . . . . . . . . . . . . . 38
12.1. Informative References . . . . . . . . . . . . . . . . . 38 13. References . . . . . . . . . . . . . . . . . . . . . . . . . 38
12.2. Normative References . . . . . . . . . . . . . . . . . . 38 13.1. Informative References . . . . . . . . . . . . . . . . . 39
Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 38 13.2. Normative References . . . . . . . . . . . . . . . . . . 39
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 38 Appendix A. Acknowledgements . . . . . . . . . . . . . . . . . . 39
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 39
1. Introduction 1. Introduction
Network management in challenged and resource constrained networks Network management in challenged and resource constrained networks
must be accomplished differently than the network management methods must be accomplished differently than the network management methods
in high-rate, high-availability networks. The Asynchronous in high-rate, high-availability networks. The Asynchronous
Management Architecture (AMA) [I-D.birrane-dtn-ama] provides an Management Architecture (AMA) [I-D.birrane-dtn-ama] provides an
overview and justification of an alternative to "synchronous" overview and justification of an alternative to "synchronous"
management services such as those provided by NETCONF. In management services such as those provided by NETCONF. In
particular, the AMA defines the need for a flexible, robust, and particular, the AMA defines the need for a flexible, robust, and
skipping to change at page 6, line 43 skipping to change at page 6, line 43
type of object being identified. type of object being identified.
7.1.1. Motivation for Compression 7.1.1. Motivation for Compression
As identifiers, ARIs are used heavily in AMM object definitions, As identifiers, ARIs are used heavily in AMM object definitions,
particularly in those that define collections of objects. This makes particularly in those that define collections of objects. This makes
encoding ARIs an important consideration when trying to optimize the encoding ARIs an important consideration when trying to optimize the
size of AMP message. size of AMP message.
Additionally, the majority of ARIs are defined in the context of an Additionally, the majority of ARIs are defined in the context of an
ADM. Certain AMM objects types (EDDs, OPs, CTBRs, TBLTs) can only be ADM. Certain AMM objects types (EDDs, OPs, CTRLs, TBLTs) can only be
defined in the context of an ADM. Other object types (VARs, CONSTs, defined in the context of an ADM. Other object types (VARs, CONSTs,
RPTTs) may have common, useful objects defined in an ADM as well. RPTTs) may have common, useful objects defined in an ADM as well.
The structure of an ADM, to include its use of a Moderated Namespace The structure of an ADM, to include its use of a Moderated Namespace
and collections by object type, provide a regular structure that can and collections by object type, provide a regular structure that can
be exploited for creating a compact representation. be exploited for creating a compact representation.
In particular, as specified in [I-D.birrane-dtn-adm], ARIs can be In particular, as specified in [I-D.birrane-dtn-adm], ARIs can be
grouped by (1) their namespace and (2) the type of AMM object being grouped by (1) their namespace and (2) the type of AMM object being
identified. For example, consider the following ARIs of type EDD identified. For example, consider the following ARIs of type EDD
defined in ADM1 with a Moderated Namespace of "/DTN/ADM1/". defined in ADM1 with a Moderated Namespace of "/DTN/ADM1/".
skipping to change at page 8, line 10 skipping to change at page 8, line 10
An ADM Object Type Enumeration is an unsigned integer in the range of An ADM Object Type Enumeration is an unsigned integer in the range of
0 - 19. This covers all of the standard areas for the ADM Template 0 - 19. This covers all of the standard areas for the ADM Template
as defined in [I-D.birrane-dtn-adm]. Each of these types are as defined in [I-D.birrane-dtn-adm]. Each of these types are
enumerated in Table 1. enumerated in Table 1.
+-----------------+-------------+ +-----------------+-------------+
| AMM Object Type | Enumeration | | AMM Object Type | Enumeration |
+-----------------+-------------+ +-----------------+-------------+
| CONST | 0 | | CONST | 0 |
| | | | | |
| CTBR | 1 | | CTRL | 1 |
| | | | | |
| EDD | 2 | | EDD | 2 |
| | | | | |
| MAC | 3 | | MAC | 3 |
| | | | | |
| OPER | 4 | | OPER | 4 |
| | | | | |
| RPTT | 5 | | RPTT | 5 |
| | | | | |
| SBR | 6 | | SBR | 6 |
skipping to change at page 13, line 33 skipping to change at page 13, line 33
+---------+ +---------+
| TNV | | TNV |
| [ARRAY] | | [ARRAY] |
+----++---+ +----++---+
|| ||
|| ||
_______________/ \________________ _______________/ \________________
/ \ / \
+------------+-----------+----------+ +------------+-----------+----------+
| Flags/Type | Name | Value | | Flags/Type | Name | Value |
| [UINT] | [TXT STR] | [Varies] | | [BYTE] | [TXT STR] | [Varies] |
| | (opt) | (opt) | | | (opt) | (opt) |
+------------+-----------+----------+ +------------+-----------+----------+
Figure 2: E(TNV) Format Figure 2: E(TNV) Format
The E(TNV) fields are defined as follows. The E(TNV) fields are defined as follows.
Flags/Type Flags/Type
The first byte of the E(TNV) describes the type associated The first byte of the E(TNV) describes the type associated
with the TNV and which optional components are present. The with the TNV and which optional components are present. The
skipping to change at page 14, line 48 skipping to change at page 14, line 48
with this TNV. The value is encoded in accordance with AMP with this TNV. The value is encoded in accordance with AMP
rules for encoding of items of the type of this TNV. If rules for encoding of items of the type of this TNV. If
there are 3 elements in the TNV array OR there are 2 elements there are 3 elements in the TNV array OR there are 2 elements
in the array and the Name Flag is not set, then this field in the array and the Name Flag is not set, then this field
MUST be present. Otherwise, this field MUST NOT be present. MUST be present. Otherwise, this field MUST NOT be present.
8.2.3. Collections 8.2.3. Collections
8.2.3.1. Type-Name-Value Collection (TNVC) 8.2.3.1. Type-Name-Value Collection (TNVC)
A TNV Collection (TNVC) is a series of multiple TNV values. This is A TNV Collection (TNVC) is an ordered set of TNVs with special
encoded as a CBOR array with each element in the array represented by semantics for more efficiently encoding sets of TNVs with identical
the encoding of a TNV in accordance with Section 8.2.2.3. attributes.
8.2.3.2. Type-Then-Value Collection (TTVC)
A Types-Then-Value Collection (TTVC) provides a mechanism for A TNV, defined in Section 8.2.2.3, consists of three distinct
communicating a typed set of values by separating the types from the components: a type, a name, and a value. When all of the TNVs in the
values themselves. This construction is useful both for rapidly TNVC have the same format (such as they all include type information)
performing type verification and for efficiently omitted type then the encoding of the TNVC can use this information to save
information where appropriate. encoding space and make processing more efficient. In cases when all
TNVs have the same format, the types (if present), names (if
present), and values (if present) are separated into their own arrays
for individual processing with type information (if present) always
appearing first.
Extracting type information to the "front" of the collection Extracting type information to the "front" of the collection
optimizes the performance of type validators. A validator can optimizes the performance of type validators. A validator can
inspect the first array to ensure that element values match type inspect the first array to ensure that element values match type
expectations. If type information were distributed throughout the expectations. If type information were distributed throughout the
collection, as in the case with the TNVC, a type validator would need collection, as in the case with the TNVC, a type validator would need
to scan through the entire set of data to validate each type in the to scan through the entire set of data to validate each type in the
collection. A TTVC SHOULD be used in lieu of a TNVC whenever type collection.
validation must be performed.
In certain circumstances, a set of values can be communicated without A TNVC is encoded as a CBOR array with at least one element, the
any type information when type information can be inferred from flags which represent the optional portions of the collection that
context. In these circumstances, separating types from values allows are present. If the TNVC represents an empty set, there will be no
for an efficient way to omit type information when necessary. additional entries. The format of a TNVC is illustrated in Figure 4.
The TTVC is encoded as a CBOR array with either one or two elements. +----------+
If the array has 1 element, then it MUST be a CBOR array of values. | TNVC |
If the TTVC array has 2 elements, then it MUST contain a CBOR byte | [ARRAY] |
string of type information followed by a CBOR array of values. In +----++----+
cases where both types and values are present, the number of types ||
MUST be the same as the number of elements as the array of values. ||
The order of types MUST correspond to the order of values in the ______________________/ \_______________________
second array. / \
+--------+-----------+---------+---------+---------+
| Flags | Types | Names | Values | Mixed |
| [BYTE] | [BYTESTR] | [ARRAY] | [ARRAY] | [ARRAY] |
| | (Opt) | (Opt) | (Opt) | (Opt) |
+--------+-----------+---------+---------+---------+
The E(TTVC) format is illustrated in Figure 4 Figure 4: E(TNVC) Format
E(TTVC) Format
+---------+ The E(TNVC) fields are defined as follows.
| TTVC |
| [ARRAY] |
+----++---+
||
||
________/ \_________
/ \
+-----------+---------+
| Types | Values |
| [BYTESTR] | [ARRAY] |
| (opt) | |
+-----------+---------+
Figure 4 Flags
The first byte of the E(TNVC) describes which optional
portions of a TNV will be present for each TNV in the
collection. The layout of this byte is illustrated in
Figure 5.
These fields are defined as follows. E(TNV) Flag Byte Format
+----------+------+------+------+------+
| Reserved | Mix | Type | Name | Val |
| Flags | Flag | Flag | Flag | Flag |
+----------+------+------+------+------+
| 7-4 | 3 | 2 | 1 | 0 |
+----------+------+------+------+------+
MSB LSB
Figure 5
Type Flag
This flag indicates that the set of TNVs in the
collection do not all share the same properties and,
therefore, the collection is a mix of different types
of TNV. When set to 1 the E(TNVC) MUST contain the
Mixed Values field and all other flags in this byte
MUST be set to 0. When set to 0 the E(TNVC) MUST NOT
contain the Mixed Values field.
Type Flag
This flag indicates whether each TNV in the
collection has type information associated with it.
When set to 1 the E(TNVC) MUST contain type
information for each TNV. When set to 0, type
information MUST NOT be present.
Name Flag
This flag indicates whether each TNV in the
collection has name information associated with it.
When set to 1 the E(TNVC) MUST contain name
information for each TNV. When set to 0, name
information MUST NOT be present.
Value Flag
This flag indicates whether each TNV in the
collection has value information associated with it.
When set to 1 the E(TNVC) MUST contain value
information for each TNV. When set to 0, value
information MUST NOT be present.
Types Types
The Types field is encoded as a CBOR byte string with each The types field is encoded as a CBOR byte string with length
element of the array encoded as a byte. Each byte represents equal to the number of items in the collection. The Nth byte
a type and MUST match a type enumeration as defined in in the byte string represents the type for the Nth TNV in the
[I-D.birrane-dtn-adm]. collection. This field MUST be present in the E(TNVC) when
the Type Flag is set to 1 and MUST NOT be present otherwise.
Names
The names field is encoded as a CBOR array with one entry for
each item in the collection. Each entry in the array is
encoded as a CBOR string and represents the name of a TNV in
the collection. The Nth string in the array represents the
name for the Nth TNV in the collection. This field MUST be
present in the E(TNVC) when the Name Flag is set to 1 and
MUST NOT be present otherwise.
Values Values
The Values array is encoded as a CBOR array with each element The values field is encoded as a CBOR array with one entry
of the array encoded as a CBOR byte string containing the for each item in the collection. Each entry in the array is
CBOR encoding of the value, based on its type as required by encoded as follows. If the Type Flag is set to 1 then each
this specification. entry will be encoded in accordance with the corresponding
index in the type field. For example, the 1st entry in the
value array will be encoded as the first entry in the type
bytestring. If the Type Flag is set to 0 then the entries in
the value array will be encoded as a native CBOR type. CBOR
types do not have a one-to-one mapping with AMP types and it
is the responsibility of the transmitting AMP actor and the
receiving AMP actor to determine how to map these to AMP
types. This field MUST be present in the E(TNVC) when the
Value Flag is set to 1 and MUST NOT be present otherwise.
8.2.3.3. ARI Collections (AC) Mixed
The mixed field is encoded as a CBOR array with one entry for
each item in the collection. Each entry in the array
contains a E(TNV). This field MUST be present in the E(TNVC)
when the Mix Flag is set to 1 and MUST NOT be present
otherwise.
8.2.3.2. ARI Collections (AC)
An ARI collection is an ordered collection of ARI values. It is An ARI collection is an ordered collection of ARI values. It is
encoded as a CBOR array with each element being an encoded ARI, as encoded as a CBOR array with each element being an encoded ARI, as
illustrated in Figure 5. illustrated in Figure 6.
E(AC) Format E(AC) Format
+---------+ +---------+
| AC | | AC |
| [ARRAY] | | [ARRAY] |
+----++---+ +----++---+
|| ||
|| ||
________/ \_________ ________/ \_________
/ \ / \
+-------+ +-------+ +-------+ +-------+
| ARI 1 | ... | ARI N | | ARI 1 | ... | ARI N |
| [ARI] | | [ARI] | | [ARI] | | [ARI] |
+-------+ +-------+ +-------+ +-------+
Figure 5 Figure 6
8.2.3.4. Expressions (EXPR) 8.2.3.3. Expressions (EXPR)
The Expression object encapsulates a typed postfix expression in The Expression object encapsulates a typed postfix expression in
which each operator MUST be of type OPER and each operand MUST be the which each operator MUST be of type OPER and each operand MUST be the
typed result of an operator or one of EDD, VAR, LIT, or CONST. typed result of an operator or one of EDD, VAR, LIT, or CONST.
The Expression object is encoded as a CBOR byte string whose format The Expression object is encoded as a CBOR byte string whose format
is illustrated in Figure 6. is illustrated in Figure 7.
E(EXPR) Format E(EXPR) Format
+--------+------------+ +--------+------------+
| Type | Expression | | Type | Expression |
| [BYTE] | [AC] | | [BYTE] | [AC] |
+--------+------------+ +--------+------------+
Figure 6 Figure 7
Type Type
The enumeration representing the type of the result of the The enumeration representing the type of the result of the
evaluated expression. This type MUST be defined in evaluated expression. This type MUST be defined in
[I-D.birrane-dtn-adm] as a "Primitive Type". [I-D.birrane-dtn-adm] as a "Primitive Type".
Expression Expression
An expression is represented in the AMP as an ARI collection, An expression is represented in the AMP as an ARI collection,
where each ARI in the ordered collection represents either an where each ARI in the ordered collection represents either an
operand or operator in postfix form. operand or operator in postfix form.
skipping to change at page 18, line 21 skipping to change at page 19, line 21
8.3.1. Encoding ARIs of Type LITERAL 8.3.1. Encoding ARIs of Type LITERAL
A literal identifier is one that is literally defined by its value, A literal identifier is one that is literally defined by its value,
such as numbers (0, 3.14) and strings ("example"). ARIs of type such as numbers (0, 3.14) and strings ("example"). ARIs of type
LITERAL do not have issuers or nicknames or parameters. They are LITERAL do not have issuers or nicknames or parameters. They are
simply typed basic values. simply typed basic values.
The E(ARI) of a LIT object is encoded as a CBOR byte string and The E(ARI) of a LIT object is encoded as a CBOR byte string and
consists of a mandatory flag BYTE and the value of the LIT. consists of a mandatory flag BYTE and the value of the LIT.
The E(ARI) structure for LIT types is illustrated in Figure 7. The E(ARI) structure for LIT types is illustrated in Figure 8.
E(ARI) Literal Format E(ARI) Literal Format
+--------+----------+ +--------+----------+
| Flags | Value | | Flags | Value |
| [BYTE] | [VARIES] | | [BYTE] | [VARIES] |
+--------+----------+ +--------+----------+
Figure 7 Figure 8
These fields are defined as follows. These fields are defined as follows.
Flags Flags
The Flags byte identifies the object as being of type LIT and The Flags byte identifies the object as being of type LIT and
also captures the primitive type of the following value. The also captures the primitive type of the following value. The
layout of this byte is illustrated in Figure 8. layout of this byte is illustrated in Figure 9.
E(ARI) Literal Flag Byte Format E(ARI) Literal Flag Byte Format
+------------+-------------+ +------------+-------------+
| VALUE TYPE | STRUCT TYPE | | VALUE TYPE | STRUCT TYPE |
+------------+-------------| +------------+-------------|
| 7 6 5 4 | 3 2 1 0 | | 7 6 5 4 | 3 2 1 0 |
+------------+-------------+ +------------+-------------+
MSB LSB MSB LSB
Figure 8 Figure 9
Value Type Value Type
The high nibble of the flag byte describes the type The high nibble of the flag byte describes the type
of the value of the ARI being encoded. This type of the value of the ARI being encoded. This type
MUST be one of the AMM data types defined in MUST be one of the AMM data types defined in
[I-D.birrane-dtn-adm] as a "Primitive Type". [I-D.birrane-dtn-adm] as a "Primitive Type".
Structure Type Structure Type
The lower nibble of the flag byte identifies the type The lower nibble of the flag byte identifies the type
of AMM Object being identified by the ARI. In this of AMM Object being identified by the ARI. In this
skipping to change at page 19, line 32 skipping to change at page 20, line 32
contain parameters and other meta-data. The AMP, as a machine-to- contain parameters and other meta-data. The AMP, as a machine-to-
machine binary encoding of this information removes human-readable machine binary encoding of this information removes human-readable
information such as Name and Description from the E(ARI). information such as Name and Description from the E(ARI).
Additionally, this encoding adds other information to improve the Additionally, this encoding adds other information to improve the
efficiency of the encoding, such as the concept of Nicknames, defined efficiency of the encoding, such as the concept of Nicknames, defined
in Section 7.1. in Section 7.1.
The E(ARI) is encoded as a CBOR byte string and consists of a The E(ARI) is encoded as a CBOR byte string and consists of a
mandatory flag byte, an encoded object name, and optional annotations mandatory flag byte, an encoded object name, and optional annotations
to assist with filtering, access control, and parameterization. The to assist with filtering, access control, and parameterization. The
E(ARI) structure is illustrated in Figure 9. E(ARI) structure is illustrated in Figure 10.
E(ARI) General Format E(ARI) General Format
+--------+---------+-----------+---------+---------+-----------+ +--------+---------+-----------+---------+---------+-----------+
| Flags | NN | Name | Parms | Issuer | Tag | | Flags | NN | Name | Parms | Issuer | Tag |
| [BYTE] | [UVAST] | [BYTESTR] | [TTVC] | [UVAST] | [BYTESTR] | | [BYTE] | [UVAST] | [BYTESTR] | [TNVC] | [UVAST] | [BYTESTR] |
| | (opt) | | (opt) | (opt) | opt) | | | (opt) | | (opt) | (opt) | opt) |
+--------+---------+-----------+---------+---------+-----------+ +--------+---------+-----------+---------+---------+-----------+
Figure 9 Figure 10
These fields are defined as follows. These fields are defined as follows.
Flags Flags
Flags describe the type of structure and which optional Flags describe the type of structure and which optional
fields are present in the encoding. The layout of the flag fields are present in the encoding. The layout of the flag
byte is illustrated in Figure 10. byte is illustrated in Figure 11.
E(ARI) General Flag Byte Format E(ARI) General Flag Byte Format
+----+------+-----+-----+-------------+ +----+------+-----+-----+-------------+
| NN | PARM | ISS | TAG | STRUCT TYPE | | NN | PARM | ISS | TAG | STRUCT TYPE |
+----+------+-----+-----+-------------+ +----+------+-----+-----+-------------+
| 7 | 6 | 5 | 4 | 3 2 1 0 | | 7 | 6 | 5 | 4 | 3 2 1 0 |
+----+------+-----+-----+-------------+ +----+------+-----+-----+-------------+
MSB LSB MSB LSB
Figure 10 Figure 11
Nickname (NN) Nickname (NN)
This flag indicates that ADM compression is used for This flag indicates that ADM compression is used for
this E(ARI). When set to 1 the Nickname field MUST this E(ARI). When set to 1 the Nickname field MUST
be present in the E(ARI). When set to 0 the Nickname be present in the E(ARI). When set to 0 the Nickname
field MUST NOT be present in the E(ARI). When an ARI field MUST NOT be present in the E(ARI). When an ARI
is user-defined, there are no semantics for Nicknames is user-defined, there are no semantics for Nicknames
and, therefore, this field MUST be 0 when the Issuer and, therefore, this field MUST be 0 when the Issuer
flag is set to 1. Implementations SHOULD use flag is set to 1. Implementations SHOULD use
Nicknames whenever possible to reduce the size of the Nicknames whenever possible to reduce the size of the
skipping to change at page 21, line 20 skipping to change at page 22, line 20
Object Name Object Name
This mandatory field contains an encoding of the ADM object. This mandatory field contains an encoding of the ADM object.
For elements defined in an ADM Template (e.g., where the For elements defined in an ADM Template (e.g., where the
Issuer Flag is set to 0) this is the 0-based index into the Issuer Flag is set to 0) this is the 0-based index into the
ADM collection holding this element. For all user-defined ADM collection holding this element. For all user-defined
ADM objects, (e.g., where the Issuer Flag is set to 1) this ADM objects, (e.g., where the Issuer Flag is set to 1) this
value is as defined by the Issuing organization. value is as defined by the Issuing organization.
Parameters Parameters
The parameters field is represented as a Types Then Value The parameters field is represented as a Type Name Value
Collection (TTVC) as defined in Section 8.2.3.2. The overall Collection (TNVC) as defined in Section 8.2.3.1. The overall
number of items in the collection represents the number of number of items in the collection represents the number of
parameters. The types of the TTVC represent the types of parameters. The types of the TNVC represent the types of
each parameter, with the first listed type associated with each parameter, with the first listed type associated with
the first parameter, and so on. The values, if present, the first parameter, and so on. The values, if present,
represent the values of the parameters, with the first listed represent the values of the parameters, with the first listed
value being the value of the first parameter, and so on. value being the value of the first parameter, and so on.
Issuer Issuer
This is a binary identifier representing a predetermined This is a binary identifier representing a predetermined
issuer name. The AMP protocol does not parse or validate issuer name. The AMP protocol does not parse or validate
this identifier, using it only as a distinguishing bit this identifier, using it only as a distinguishing bit
pattern to ensure uniqueness. This value, for example, may pattern to ensure uniqueness. This value, for example, may
skipping to change at page 22, line 19 skipping to change at page 23, line 19
between an Agent and Manager. between an Agent and Manager.
8.4.1. Externally Defined Data (EDD) 8.4.1. Externally Defined Data (EDD)
Externally defined data (EDD) are solely defined in the ADMs for Externally defined data (EDD) are solely defined in the ADMs for
various applications and protocols. EDDs represent values that are various applications and protocols. EDDs represent values that are
calculated external to an AMA Agent, such as values measured by calculated external to an AMA Agent, such as values measured by
firmware. firmware.
The representation of these data is simply their identifying ARIs. The representation of these data is simply their identifying ARIs.
The representation of an EDD is illustrated in Figure 11. The representation of an EDD is illustrated in Figure 12.
E(EDD) Format E(EDD) Format
+-------+ +-------+
| ID | | ID |
| [ARI] | | [ARI] |
+-------+ +-------+
Figure 11 Figure 12
ID ID
This is the ARI identifying the EDD. Since EDDs are always This is the ARI identifying the EDD. Since EDDs are always
defined solely in the context of an ADM, this ARI MUST NOT defined solely in the context of an ADM, this ARI MUST NOT
have an ISSUER field and MUST NOT have a TAG field. This ARI have an ISSUER field and MUST NOT have a TAG field. This ARI
may be defined with parameters. may be defined with parameters.
8.4.2. Constants (CONST) 8.4.2. Constants (CONST)
Unlike Literals, a Constant is an immutable, typed, named value. Unlike Literals, a Constant is an immutable, typed, named value.
Examples of constants include PI to some number of digits or the UNIX Examples of constants include PI to some number of digits or the UNIX
Epoch. Epoch.
Since ADM definitions are preconfigured on Agents and Managers in an Since ADM definitions are preconfigured on Agents and Managers in an
AMA, the type information for a given Constant is known by all actors AMA, the type information for a given Constant is known by all actors
in the system and the encoding of the Constant needs to only be the in the system and the encoding of the Constant needs to only be the
name of the constant as the Manager and Agent can derive the type and name of the constant as the Manager and Agent can derive the type and
value from the unique Constant name. value from the unique Constant name.
The format of a Constant is illustrated in Figure 12. The format of a Constant is illustrated in Figure 13.
E(CONST) Format E(CONST) Format
+-------+ +-------+
| ID | | ID |
| [ARI] | | [ARI] |
+-------+ +-------+
Figure 12 Figure 13
ID ID
This is the ARI identifying the Constant. Since Constant This is the ARI identifying the Constant. Since Constant
definitions are always provided in an ADM, this ARI MUST NOT definitions are always provided in an ADM, this ARI MUST NOT
have an ISSUER field and MUST NOT have a TAG field. The ARI have an ISSUER field and MUST NOT have a TAG field. The ARI
MUST NOT have parameters. MUST NOT have parameters.
8.4.3. Controls (CTBR) 8.4.3. Controls (CTRL)
A Control represents a pre-defined and optionally parameterized A Control represents a pre-defined and optionally parameterized
opcode that can be run on an Agent. Controls in the AMP are always opcode that can be run on an Agent. Controls in the AMP are always
defined in the context of an AMA; there is no concept of an operator- defined in the context of an AMA; there is no concept of an operator-
defined Control. Since Controls are pre-configured in Agents and defined Control. Since Controls are pre-configured in Agents and
Managers as part of ADM support, their representation is the ARI that Managers as part of ADM support, their representation is the ARI that
identifies them, similar to EDDs. identifies them, similar to EDDs.
The format of a Control is illustrated in Figure 13. The format of a Control is illustrated in Figure 14.
E(CTBR) Format E(CTRL) Format
+-------+ +-------+
| ID | | ID |
| [ARI] | | [ARI] |
+-------+ +-------+
Figure 13 Figure 14
ID ID
This is the ARI identifying the Control. This ARI MUST NOT This is the ARI identifying the Control. This ARI MUST NOT
have an ISSUER field and MUST NOT have a TAG field. This ARI have an ISSUER field and MUST NOT have a TAG field. This ARI
may have parameters. may have parameters.
8.4.4. Macros (MAC) 8.4.4. Macros (MAC)
Macros in the AMP are ordered collections of ARIs (an AC) that Macros in the AMP are ordered collections of ARIs (an AC) that
contain Controls or other Macros. When run by an Agent, each ARI in contain Controls or other Macros. When run by an Agent, each ARI in
skipping to change at page 24, line 14 skipping to change at page 25, line 14
The ARI associated with a Macro MAY contain parameters. Each The ARI associated with a Macro MAY contain parameters. Each
parameter present in a Macro ARI MUST contain type, name, and value parameter present in a Macro ARI MUST contain type, name, and value
information. Any Control or Macro encapsulated within a information. Any Control or Macro encapsulated within a
parameterized Macro MAY also contain parameters. If an encapsulated parameterized Macro MAY also contain parameters. If an encapsulated
object parameter contains only name information, then the parameter object parameter contains only name information, then the parameter
value MUST be taken from the named parameter provided by the value MUST be taken from the named parameter provided by the
encapsulating Macro. Otherwise, the value provided to the object encapsulating Macro. Otherwise, the value provided to the object
MUST be used instead. MUST be used instead.
The format of a Macro is illustrated in Figure 14. The format of a Macro is illustrated in Figure 15.
E(MAC) Format E(MAC) Format
+-------+------------+ +-------+------------+
| ID | Definition | | ID | Definition |
| [ARI] | [AC] | | [ARI] | [AC] |
+-------+------------+ +-------+------------+
Figure 14 Figure 15
ID ID
This is the ARI identifying the Macro. When a Macro is This is the ARI identifying the Macro. When a Macro is
defined in an ADM this ARI MUST NOT have an ISSUER field and defined in an ADM this ARI MUST NOT have an ISSUER field and
MUST NOT have a TAG field. When the Macro is defined outside MUST NOT have a TAG field. When the Macro is defined outside
of an ADM, the ARI MUST have an ISSUER field and MAY have a of an ADM, the ARI MUST have an ISSUER field and MAY have a
TAG field. TAG field.
Definition Definition
This is the ordered collection of ARIs that identify the This is the ordered collection of ARIs that identify the
skipping to change at page 25, line 6 skipping to change at page 26, line 6
them. them.
The ADM definition of an Operator MUST specify how many parameters The ADM definition of an Operator MUST specify how many parameters
are expected and the expected type of each parameter. For example, are expected and the expected type of each parameter. For example,
the unary NOT Operator ("!") would accept one parameter. The binary the unary NOT Operator ("!") would accept one parameter. The binary
PLUS Operator ("+") would accept two parameters. A custom function PLUS Operator ("+") would accept two parameters. A custom function
to calculate the average of the last 10 samples of a data item should to calculate the average of the last 10 samples of a data item should
accept 10 parameters. accept 10 parameters.
Operators are always evaluated in the context of an Expression. The Operators are always evaluated in the context of an Expression. The
encoding of an Operator is illustrated in Figure 15. encoding of an Operator is illustrated in Figure 16.
E(OP) Format E(OP) Format
+-------+ +-------+
| ID | | ID |
| [ARI] | | [ARI] |
+-------+ +-------+
Figure 15 Figure 16
ID ID
This is the ARI identifying the Operator. Since Operators This is the ARI identifying the Operator. Since Operators
are always defined solely in the context of an ADM, this ARI are always defined solely in the context of an ADM, this ARI
MUST NOT have an ISSUER field and MUST NOT have a TAG field. MUST NOT have an ISSUER field and MUST NOT have a TAG field.
8.4.6. Report Templates (RPTT) 8.4.6. Report Templates (RPTT)
A Report Template is an ordered collection of identifiers that A Report Template is an ordered collection of identifiers that
describe the order and format of data in any Report built in describe the order and format of data in any Report built in
compliance with the template. A template is a schema for a class of compliance with the template. A template is a schema for a class of
reports. It contains no actual values and may be defined in a formal reports. It contains no actual values and may be defined in a formal
ADM or configured by users in the context of a network deployment. ADM or configured by users in the context of a network deployment.
A Report Template is modeled as an AC, as each data definition in the The encoding of a RPTT is illustrated in Figure 17.
template is identified by an ARI.
E(RPTT) Format E(RPTT) Format
+-----------------+ +-------+----------+
| Report Contents | | ID | Contents |
| [AC] | | [ARI] | [AC] |
+-----------------+ +-------+----------+
Figure 16 Figure 17
ID
This is the ARI identifying the report template.
Contents
This is the ordered collection of ARIs that define the
template.
8.4.7. Report (RPT) 8.4.7. Report (RPT)
A Report is a set of data values populated using a given Report A Report is a set of data values populated using a given Report
Template. While Reports do not contain name information, they MAY Template. While Reports do not contain name information, they MAY
contain type information in cases where recipients wish to perform contain type information in cases where recipients wish to perform
type validation prior to interpreting the Report contents in the type validation prior to interpreting the Report contents in the
context of a Report Template. Reports are "anonymous" in the sense context of a Report Template. Reports are "anonymous" in the sense
that any individual Report does not contain a unique identifier. that any individual Report does not contain a unique identifier.
Reports can be differentiated by examining the combination of (1) the Reports can be differentiated by examining the combination of (1) the
Report Template being populated, (2) the time at which the Report was Report Template being populated, (2) the time at which the Report was
populated, and (3) the Agent producing the report. populated, and (3) the Agent producing the report.
A Report object is comprised of the identifier of the template used A Report object is comprised of the identifier of the template used
to populate the report, an optional timestamp, and the contents of to populate the report, an optional timestamp, and the contents of
the report. A Report is encoded as a CBOR array with either 2 or 3 the report. A Report is encoded as a CBOR array with either 2 or 3
elements. If the array has 2 elements then the optional Timestamp elements. If the array has 2 elements then the optional Timestamp
MUST NOT be in the Report encoding. If the array has 3 elements then MUST NOT be in the Report encoding. If the array has 3 elements then
the optional timestamp MUST be included in the Report encoding. The the optional timestamp MUST be included in the Report encoding. The
Report encoding is illustrated in Figure 17. Report encoding is illustrated in Figure 18.
E(RPT) Format E(RPT) Format
+---------+ +---------+
| RPT | | RPT |
| [ARRAY] | | [ARRAY] |
+---++----+ +---++----+
|| ||
|| ||
_____________/ \_____________ _____________/ \_____________
/ \ / \
+----------+-----------+---------+ +----------+-----------+---------+
| Template | Timestamp | Entries | | Template | Timestamp | Entries |
| [ARI] | [TS] | [TTVC] | | [ARI] | [TS] | [TNVC] |
| | (opt) | | | | (opt) | |
+----------+-----------+---------+ +----------+-----------+---------+
Figure 17 Figure 18
Template Template
This is the ARI identifying the template used to interpret This is the ARI identifying the template used to interpret
the data in this report. the data in this report.
This ARI may be parameterized and, if so, the parameters MUST This ARI may be parameterized and, if so, the parameters MUST
include a name field and have been passed-by-name to the include a name field and have been passed-by-name to the
template contents when constructing the report. template contents when constructing the report.
Timestamp Timestamp
skipping to change at page 27, line 23 skipping to change at page 28, line 30
Examples of SBRs include: Examples of SBRs include:
Starting 2 hours from receipt, whenever V1 > 10, produce a Report Starting 2 hours from receipt, whenever V1 > 10, produce a Report
for Report Template R1 no more than 20 times. for Report Template R1 no more than 20 times.
Starting at some future absolute time, whenever V2 != V4, run Starting at some future absolute time, whenever V2 != V4, run
Macro M1 no more than 36 times. Macro M1 no more than 36 times.
An SBR object is encoded as a CBOR array with 5 elements as An SBR object is encoded as a CBOR array with 5 elements as
illustrated in Figure 18. illustrated in Figure 19.
E(SBR) Format E(SBR) Format
+---------+ +---------+
| SBR | | SBR |
| [ARRAY] | | [ARRAY] |
+---++----+ +---++----+
|| ||
|| ||
___________________/ \___________________ _______________________/ \_______________________
/ \ / \
+-------+-------+--------+--------+--------+ +-------+-------+--------+--------+--------+--------+
| ID | START | COND | COUNT | ACTION | | ID | START | COND | EVALS | FIRES | ACTION |
| [ARI] | [TV] | [EXPR] | [UINT] | [AC] | | [ARI] | [TV] | [EXPR] | [UINT] | [UINT] | [AC] |
| | | | | | +-------+-------+--------+--------+--------+--------+
+-------+-------+--------+--------+--------+
Figure 18 Figure 19
ID ID
This is the ARI identifying the SBR. If this ARI contains This is the ARI identifying the SBR. If this ARI contains
parameters they MUST include a name in support of pass-by- parameters they MUST include a name in support of pass-by-
name to each element of the Action AC. name to each element of the Action AC.
START START
The time at which the SBR condition should start to be The time at which the SBR condition should start to be
evaluated. This will mark the first evaluation of the evaluated. This will mark the first evaluation of the
condition associated with the SBR. condition associated with the SBR.
CONDITION CONDITION
The Expression which, if true, results in the SBR running the The Expression which, if true, results in the SBR running the
associated action. An EXPR is considered true if it associated action. An EXPR is considered true if it
evaluates to a non-zero value. evaluates to a non-zero value.
COUNT EVALS
The number of times the SBR condition can be evaluated. The
special value of 0 indicates there is no limit on how many
times the condition can be evaluated.
FIRES
The number of times the SBR action can be run. The special The number of times the SBR action can be run. The special
value of 0 indicates there is no limit on how many times the value of 0 indicates there is no limit on how many times the
action can be run. action can be run.
ACTION ACTION
The collection of Controls and/or Macros to run as part of The collection of Controls and/or Macros to run as part of
the action. This is encoded as an AC in accordance with the action. This is encoded as an AC in accordance with
Section 8.2.3.3 with the stipulation that every ARI in this Section 8.2.3.2 with the stipulation that every ARI in this
collection MUST be of type CTRL or MAC. collection MUST be of type CTRL or MAC.
8.4.9. Table Templates (TBLT) 8.4.9. Table Templates (TBLT)
A Table Template (TBLT) describes the types, and optionally names, of A Table Template (TBLT) describes the types, and optionally names, of
the columns that define a Table. the columns that define a Table.
The TBLT Object is encoded as a CBOR array that MUST contain either 2 Because TBLTs are only defined in the context of an ADM, their
or 3 elements. If the array is of size 2, then the column names definition cannot change operationally. Therefore, a TBLT is encoded
array MUST NOT be present in the encoding. If the array is of size 3 simply as the ARI for the template. The format of the TBLT Object
then the column names array MUST be present in the encoding. The Array is illustrated in Figure 20.
format of the TBLT Object Array is illustrated in Figure 19.
E(TBLT) Format E(TBLT) Format
+---------+ +-------+
| TBLT | | ID |
| [ARRAY] | | [ARI] |
+---++----+ +-------+
||
||
____________/ \_____________
/ \
+-------+-----------+---------+
| ID | Types | Names |
| [ARI] | [BYTESTR] | [ARRAY] |
| | | (opt) |
+-------+-----------+---------+
Figure 19 Figure 20
The elements of the TBLT array are defined as follows. The elements of the TBLT array are defined as follows.
ID ID
This is the ARI of the table template encoded in accordance This is the ARI of the table template encoded in accordance
with Section 8.3. with Section 8.3.
Types
The types field captures the data types of each column
comprising the table template. Each type is represented by
its enumeration as defined in [I-D.birrane-dtn-adm]. This
field is encoded as a CBOR byte string with the length of the
string equal to the number of columns in the template and
each column type enumeration encoded as a byte. The Nth byte
in the byte string represents the type of the Nth column.
Names
When present, column names are encoded as a CBOR array. This
array MUST have the same number of elements as bytes in the
Types byte string. Each element in the Names array is
encoded as a CBOR text string and represents the string
representation of the column name. The Nth text string in
the array represents the name of the Nth column.
8.4.10. Tables (TBL) 8.4.10. Tables (TBL)
A Table object describes the series of values associated with a A Table object describes the series of values associated with a
Table Template. Table Template.
A Table object is encoded as a CBOR array, with the first element of A Table object is encoded as a CBOR array, with the first element of
the array identifying the Table Template and each subsequent element the array identifying the Table Template and each subsequent element
identifying a row in the table. The format of the TBL Object Array identifying a row in the table. The format of the TBL Object Array
is illustrated in Figure 20. is illustrated in Figure 21.
E(TBL) Format E(TBL) Format
+---------+ +---------+
| TBL | | TBL |
| [ARRAY] | | [ARRAY] |
+---++----+ +---++----+
|| ||
|| ||
______________/ \_______________ ______________/ \_______________
/ \ / \
+---------+--------+ +--------+ +---------+--------+ +--------+
| TBLT ID | Row 1 | | Row N | | TBLT ID | Row 1 | | Row N |
| [ARI] | [TTVC] | ... | [TTVC] | | [ARI] | [TNVC] | ... | [TNVC] |
+---------+--------+ +--------+ +---------+--------+ +--------+
Figure 20 Figure 21
The TBL fields are defined as follows. The TBL fields are defined as follows.
Template ID (TBLT ID) Template ID (TBLT ID)
This is the ARI of the table template describing the format This is the ARI of the table template describing the format
of the table and is encoded in accordance with Section 8.3. of the table and is encoded in accordance with Section 8.3.
Row Row
Each row of the table is represented as a series of values Each row of the table is represented as a series of values
with optional type information to aid in type checking table with optional type information to aid in type checking table
contents to column types. Each row is encoded as a TTVC and contents to column types. Each row is encoded as a TNVC and
MAY include type information. AMP implementations should MAY include type information. AMP implementations should
consider the impact of including type information for every consider the impact of including type information for every
row on the overall size of the encoded table. row on the overall size of the encoded table.
Each TTVC representing a row MUST contain the same number of Each TNVC representing a row MUST contain the same number of
elements as there are columns in the referenced elements as there are columns in the referenced
Table Template. Table Template.
8.4.11. Time-Based Rules (TBR) 8.4.11. Time-Based Rules (TBR)
A Time-Based Rule (TBR) specifies that a particular action should be A Time-Based Rule (TBR) specifies that a particular action should be
taken by an Agent based on some time interval. A TBR specifies that taken by an Agent based on some time interval. A TBR specifies that
starting at a particular START time, and for every PERIOD seconds starting at a particular START time, and for every PERIOD seconds
thereafter, an ACTION should be run by the Agent until the ACTION has thereafter, an ACTION should be run by the Agent until the ACTION has
been run for COUNT times. When the TBR is no longer valid it MAY BE been run for COUNT times. When the TBR is no longer valid it MAY BE
skipping to change at page 30, line 38 skipping to change at page 31, line 34
Examples of TBRs include: Examples of TBRs include:
Starting 2 hours from receipt, produce a Report for Report Starting 2 hours from receipt, produce a Report for Report
Template R1 every 10 hours ending after 20 times. Template R1 every 10 hours ending after 20 times.
Starting at the given absolute time, run Macro M1 every 24 hours Starting at the given absolute time, run Macro M1 every 24 hours
ending after 365 times. ending after 365 times.
The TBR object is encoded as a CBOR array with 5 elements as The TBR object is encoded as a CBOR array with 5 elements as
illustrated in Figure 21. illustrated in Figure 22.
E(TBR) Format E(TBR) Format
+---------+ +---------+
| TBR | | TBR |
| [ARRAY] | | [ARRAY] |
+---++----+ +---++----+
|| ||
|| ||
___________________/ \___________________ ___________________/ \___________________
/ \ / \
+-------+-------+--------+--------+--------+ +-------+-------+--------+--------+--------+
| ID | START | PERIOD | COUNT | ACTION | | ID | START | PERIOD | COUNT | ACTION |
| [ARI] | [TV] | [UINT] | [UINT] | [AC] | | [ARI] | [TV] | [UINT] | [UINT] | [AC] |
+-------+-------+--------+--------+--------+ +-------+-------+--------+--------+--------+
Figure 21 Figure 22
ID ID
This is the ARI identifying the TBR and is encoded in This is the ARI identifying the TBR and is encoded in
accordance with Section 8.3. If this ARI contains parameters accordance with Section 8.3. If this ARI contains parameters
they MUST include a name in support of pass-by-name to each they MUST include a name in support of pass-by-name to each
element of the Action AC. element of the Action AC.
START START
The time at which the TBR condition should start to be The time at which the TBR condition should start to be
evaluated. evaluated.
skipping to change at page 31, line 44 skipping to change at page 32, line 27
associated with the TBR. associated with the TBR.
COUNT COUNT
The number of times the TBR action can be run. The special The number of times the TBR action can be run. The special
value of 0 indicates there is no limit on how many times the value of 0 indicates there is no limit on how many times the
action can be run. action can be run.
ACTION ACTION
The collection of Controls and/or Macros to run as part of The collection of Controls and/or Macros to run as part of
the action. This is encoded as an ARI Collection in the action. This is encoded as an ARI Collection in
accordance with Section 8.2.3.3 with the stipulation that accordance with Section 8.2.3.2 with the stipulation that
every ARI in this collection MUST represent either a Control every ARI in this collection MUST represent either a Control
or a Macro. or a Macro.
8.4.12. Variables (VAR) 8.4.12. Variables (VAR)
Variable objects are transmitted in the AMP without the human- Variable objects are transmitted in the AMP without the human-
readable description. readable description.
Variable objects are encoded as a CBOR byte string whose format is Variable objects are encoded as a CBOR byte string whose format is
illustrated in Figure 22. illustrated in Figure 23.
E(VAR) Format E(VAR) Format
+------------+ +------------+
| Variable | | Variable |
| [BYTESTR] | | [BYTESTR] |
+-----++-----+ +-----++-----+
|| ||
|| ||
______________/ \____________ ______/ \_____
/ \ / \
+-------+--------+-------------+ +-------+-------+
| ID | Type | Initializer | | ID | Value |
| [ARI] | [BYTE] | [EXPR] | | [ARI] | [TNV] |
+-------+--------+-------------+ +-------+-------+
Figure 22 Figure 23
ID ID
This is the ARI identifying the VAR and is encoded in This is the ARI identifying the VAR and is encoded in
accordance with Section 8.3. This ARI MUST NOT include accordance with Section 8.3. This ARI MUST NOT include
parameters. parameters.
Type Value
This field captures the data type of the Variable encoded as This field captures the value (and optionally the type and
a BYTE. This data type MUST be one of the data types defined name) of the variable, encoded as a TNV.
in [I-D.birrane-dtn-adm].
It is possible to specify a type different than the resultant
type of the initializing Expression. For example, if an
Expression adds two single-precision floating point numbers,
the VAR MAY have an integer type associated with it. In
cases where this is the case, numeric conversions MUST be
handled in accordance with [I-D.birrane-dtn-adm].
Initializer
The initial value of the Variable is calculated by an
Expression encoded in accordance with Section 8.2.3.4.
9. Functional Specification 9. Functional Specification
This section describes the format of the messages that comprise the This section describes the format of the messages that comprise the
AMP protocol. AMP protocol.
9.1. AMP Message Summary 9.1. AMP Message Summary
The AMP message specification is limited to three basic The AMP message specification is limited to three basic
communications: communications:
skipping to change at page 33, line 33 skipping to change at page 34, line 28
Table 4: ADM Message Type Enumerations Table 4: ADM Message Type Enumerations
The entire management of a network can be performed using these three The entire management of a network can be performed using these three
messages and the configurations from associated ADMs. messages and the configurations from associated ADMs.
9.2. Message Group Format 9.2. Message Group Format
Individual messages within the AMP are combined into a single group Individual messages within the AMP are combined into a single group
for communication with another AMP Actor. Messages within a group for communication with another AMP Actor. Messages within a group
MUST be received and applied as an atomic unit. The format of a MUST be received and applied as an atomic unit. The format of a
message group is illustrated in Figure 23. These message groups are message group is illustrated in Figure 24. These message groups are
assumed communicated amongst Agents and Managers as the payloads of assumed communicated amongst Agents and Managers as the payloads of
encapsulating protocols which should provide additional security and encapsulating protocols which should provide additional security and
data integrity features as needed. data integrity features as needed.
A message group is encoded as a CBOR array with at least 2 elements, A message group is encoded as a CBOR array with at least 2 elements,
the first being the time the group was created followed by 1 or more the first being the time the group was created followed by 1 or more
messages that comprise the group. The format of the message group is messages that comprise the group. The format of the message group is
illustrated in Figure 23. illustrated in Figure 24.
AMP Message Group Format AMP Message Group Format
+---------------+ +---------------+
| Message Group | | Message Group |
| [ARRAY] | | [ARRAY] |
+------++-------+ +------++-------+
|| ||
____________________||___________________ ____________________||___________________
/ \ / \
+-----------+-----------+ +-----------+ +-----------+-----------+ +-----------+
| Timestamp | Message 1 | ... | Message N | | Timestamp | Message 1 | ... | Message N |
| [TS] | [BYTESTR] | | [BYTESTR] | | [TS] | [BYTESTR] | | [BYTESTR] |
+-----------+-----------+ +-----------+ +-----------+-----------+ +-----------+
Figure 23 Figure 24
Timestamp Timestamp
The creation time for this messaging group. Individual The creation time for this messaging group. Individual
messages may have their own creation timestamps based on messages may have their own creation timestamps based on
their type, but the group timestamp also serves as the their type, but the group timestamp also serves as the
default creation timestamp for every message in the group. default creation timestamp for every message in the group.
This is encoded in accordance with Table 3. This is encoded in accordance with Table 3.
Message N Message N
The Nth message in the group. The Nth message in the group.
9.3. Message Format 9.3. Message Format
Each message identified in the AMP specification adheres to a common Each message identified in the AMP specification adheres to a common
message format, illustrated in Figure 24, consisting of a message message format, illustrated in Figure 25, consisting of a message
header, a message body, and an optional trailer. header, a message body, and an optional trailer.
Each message in the AMP is encode as a CBOR byte string formatted in Each message in the AMP is encode as a CBOR byte string formatted in
accordance with Figure 24. accordance with Figure 25.
AMP Message Format AMP Message Format
+--------+----------+----------+ +--------+----------+----------+
| Header | Body | Trailer | | Header | Body | Trailer |
| [BYTE] | [VARIES] | [VARIES] | | [BYTE] | [VARIES] | [VARIES] |
| | | (opt.) | | | | (opt.) |
+--------+----------+----------+ +--------+----------+----------+
Figure 24 Figure 25
Header Header
The message header BYTE is shown in Figure 25. The header The message header BYTE is shown in Figure 26. The header
identifies a message context and opcode as well as flags that identifies a message context and opcode as well as flags that
control whether a Report should be generated on message control whether a Report should be generated on message
success (Ack) and whether a Report should be generated on success (Ack) and whether a Report should be generated on
message failure (Nack). message failure (Nack).
AMP Common Message Header AMP Common Message Header
+----------+-----+------+-----+----------+ +----------+-----+------+-----+----------+
| Reserved | ACL | Nack | Ack | Opcode | | Reserved | ACL | Nack | Ack | Opcode |
+----------+-----+------+-----+----------+ +----------+-----+------+-----+----------+
| 7 6 | 5 | 4 | 3 | 2 1 0 | | 7 6 | 5 | 4 | 3 | 2 1 0 |
+----------+-----+------+-----+----------+ +----------+-----+------+-----+----------+
MSB LSB MSB LSB
Figure 25 Figure 26
Opcode Opcode
The opcode field identifies which AMP message is The opcode field identifies which AMP message is
being represented. being represented.
ACK Flag ACK Flag
The ACK flag describes whether successful application The ACK flag describes whether successful application
of the message must generate an acknowledgment back of the message must generate an acknowledgment back
to the message sender. If this flag is set (1) then to the message sender. If this flag is set (1) then
the receiving actor MUST generate a Report the receiving actor MUST generate a Report
skipping to change at page 36, line 19 skipping to change at page 36, line 50
each message below. When an ACL trailer is not present, the each message below. When an ACL trailer is not present, the
message results may be visible to any AMP Actor in the message results may be visible to any AMP Actor in the
network, pursuant to other security protocol implementations. network, pursuant to other security protocol implementations.
9.4. Register Agent 9.4. Register Agent
The Register Agent message is used to inform an AMP Manager of the The Register Agent message is used to inform an AMP Manager of the
presence of another Agent in the network. presence of another Agent in the network.
The body of this message is the name of the new agent, encoded as The body of this message is the name of the new agent, encoded as
illustrated in Figure 26. illustrated in Figure 27.
Register Agent Message Body Register Agent Message Body
+-----------+ +-----------+
| Agent ID | | Agent ID |
| [BYTESTR] | | [BYTESTR] |
+-----------+ +-----------+
Figure 26 Figure 27
Agent ID Agent ID
The Agent ID MUST represent the unique address of the Agent The Agent ID MUST represent the unique address of the Agent
in whatever protocol is used to communicate with the Agent. in whatever protocol is used to communicate with the Agent.
9.5. Report Set 9.5. Report Set
The Report Set message contains a set of 1 or more Reports produced The Report Set message contains a set of 1 or more Reports produced
by an AMP Agent and sent to an AMP Manager. by an AMP Agent and sent to an AMP Manager.
The body of this message contains information on the recipient of the The body of this message contains information on the recipient of the
reports followed by one or more Reports. The body is encoded as reports followed by one or more Reports. The body is encoded as
illustrated in Figure 27. illustrated in Figure 28.
Report Set Message Body Report Set Message Body
+----------+--------+ +--------+ +----------+--------+ +--------+
| RX Names | RPT 1 | | RPT N | | RX Names | RPT 1 | | RPT N |
| [ARRAY] | [RPT] | ... | [RPT] | | [ARRAY] | [RPT] | ... | [RPT] |
+----------+--------+ +--------+ +----------+--------+ +--------+
Figure 27 Figure 28
RX Names RX Names
This field captures the set of Managers that have been sent This field captures the set of Managers that have been sent
this report set. This is encoded as a CBOR array that MUST this report set. This is encoded as a CBOR array that MUST
have at least one entry. Each entry in this array is have at least one entry. Each entry in this array is
encdoded as a CBOR text string. encdoded as a CBOR text string.
RPT N RPT N
The Nth Report encoded in accordance with Section 8.4.7. The Nth Report encoded in accordance with Section 8.4.7.
9.6. Perform Control 9.6. Perform Control
The perform control message causes the receiving AMP Actor to run one The perform control message causes the receiving AMP Actor to run one
or more preconfigured Controls provided in the message. or more preconfigured Controls provided in the message.
The body of this message is the start time for the controls followed The body of this message is the start time for the controls followed
by the controls themselves, as illustrated in Figure 28. by the controls themselves, as illustrated in Figure 29.
Perform Control Message Body Perform Control Message Body
+-------+-----------+ +-------+-----------+
| Start | Controls | | Start | Controls |
| [TV] | [AC] | | [TV] | [AC] |
+-------+-----------+ +-------+-----------+
Figure 28 Figure 29
Start Start
The time at which the Controls/Macros should be run. The time at which the Controls/Macros should be run.
Controls Controls
The collection of ARIs that represent the Controls and/or The collection of ARIs that represent the Controls and/or
Macros to be run by the AMP Actor. Every ARI in this Macros to be run by the AMP Actor. Every ARI in this
collection MUST be either a Control or a Macro. collection MUST be either a Control or a Macro.
10. IANA Considerations 10. IANA Considerations
skipping to change at page 38, line 8 skipping to change at page 38, line 40
Transport-layer security addresses the questions of authentication, Transport-layer security addresses the questions of authentication,
integrity, and confidentiality associated with the transport of integrity, and confidentiality associated with the transport of
messages between and amongst Managers and Agents. This security is messages between and amongst Managers and Agents. This security is
applied before any particular Actor in the system receives data and, applied before any particular Actor in the system receives data and,
therefore, is outside of the scope of this document. therefore, is outside of the scope of this document.
Finer grain application security is done via ACLs provided in the AMP Finer grain application security is done via ACLs provided in the AMP
message headers. message headers.
12. References 12. Implementation Notes
12.1. Informative References A reference implementation of this version of the AMP specification
is available in the 3.6.2 release of the ION open source code base
available from sourceforge at https://sourceforge.net/projects/ion-
dtn/.
13. References
13.1. Informative References
[I-D.birrane-dtn-ama] [I-D.birrane-dtn-ama]
Birrane, E., "Asynchronous Management Architecture", Birrane, E., "Asynchronous Management Architecture",
draft-birrane-dtn-ama-07 (work in progress), June 2018. draft-birrane-dtn-ama-07 (work in progress), June 2018.
12.2. Normative References 13.2. Normative References
[I-D.birrane-dtn-adm] [I-D.birrane-dtn-adm]
Birrane, E., DiPietro, E., and D. Linko, "AMA Application Birrane, E., DiPietro, E., and D. Linko, "AMA Application
Data Model", draft-birrane-dtn-adm-02 (work in progress), Data Model", draft-birrane-dtn-adm-02 (work in progress),
June 2018. June 2018.
[RFC2119] Bradner, S., "Key words for use in RFCs to Indicate [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate
Requirement Levels", BCP 14, RFC 2119, Requirement Levels", BCP 14, RFC 2119,
DOI 10.17487/RFC2119, March 1997, DOI 10.17487/RFC2119, March 1997,
<https://www.rfc-editor.org/info/rfc2119>. <https://www.rfc-editor.org/info/rfc2119>.
 End of changes. 95 change blocks. 
218 lines changed or deleted 260 lines changed or added

This html diff was produced by rfcdiff 1.47. The latest version is available from http://tools.ietf.org/tools/rfcdiff/