Subject: [Dots] Signal CBOR / JSON Mapping

From: "Jon Shallow" <[email-masked]>
Date: Fri, 22 Dec 2017 17:11:27 -0000

Hi WG,

There are a lot of YANG parameters that we are using that are defined as
int64.  JSON only safely supports up to 53 bits of precision.

RFC 7493 2.2 Numbers

   An I-JSON sender cannot expect a receiver to treat an integer whose

   absolute value is greater than 9007199254740991 (i.e., that is

   outside the range [-(2**53)+1, (2**53)-1]) as an exact value.

   For applications that require the exact interchange of numbers with

   greater magnitude or precision, it is RECOMMENDED to encode them in

   JSON string values.  This requires that the receiving program

   understand the intended semantic of the value.  An example would be

   64-bit integers, even though modern hardware can deal with them,

   because of the limited scope of JavaScript numbers.

RFC7049 3.6 Numbers

   CBOR-based protocols should take into account that different language

   environments pose different restrictions on the range and precision

   of numbers that are representable.  For example, the JavaScript

   number system treats all numbers as floating point, which may result

   in silent loss of precision in decoding integers with more than 53

   significant bits.  A protocol that uses numbers should define its

   expectations on the handling of non-trivial numbers in decoders and

   receiving applications.

====

An option is to make all of these int64 decimal64 for the signal channel,
but that does not cover the 64 bit counters in the netmod-acl.  However, as
the netmod-acl counters are also fed back via the mitigate status, we do not
necessarily need to support the netmod-acl counters.

If, however, we follow RFC 7493, in CBOR the data can be passed across as 64
bits, and as the parameter is a CBOR mapping, we can know how to encode /
decode the JSON value as appropriate.  However, RFC 7493 does not say
whether this should be base64, base64url or numeric string representation
(i.e. "1234567890").  RFC7049 refers to bignum (major type 6, tag value 2 or
3) should be encoded as base64url (4.1 Converting from CBOR to JSON) - but
int64 can be held in CBOR as type 0 or 1.

I prefer the numeric string representation as it is humanly easy to read and
easy to convert into 64 bit integers.

If we take this approach of using the parameter which is a CBOR mapping key
to key off how to encode / decode the JSON, I would suggest that we could
extend this to include IP addresses, Dates and client-identifiers (or their
possible new names of request-nonce and client-domain-hash) to further
minimize the actual number of bytes sent in a COAP packet.

The CBOR mapping Table could then be extended to look something like (but it
is too wide I think)

/----------------------+-------------+------+---------------+--------+------
---\

| Parameter name       | YANG type   | CBOR | CBOR major    | JSON   | JSON
|  

|                      |             | key  | type          | type   |
Example |

|----------------------+-------------+------+---------------+--------+------
---|

| mitigation-scope     | grouping    |   1  | 5 map         | Object |
|  

| scope                | list        |   2  | 4 array       | Array  |
|  

| mitigation-id        | int32       |   3  | 0 unsigned    | Number | 54321
|  

| acl-list             | list        |   4  | 4 array       | Array  |
|  

| target-port-range    | list        |   5  | 4 array       | Array  |
|  

| lower-port           | port-number |   6  | 0 number      | Number | 1111
|  

| upper-port           | port-number |   7  | 0 number      | Number | 1111
|  

| target-protocol      | leaf-list   |      | 4 array       | Array  |
|  

|                      | uint8       |   8  | 0 number      | Number | 6
|

| target-fqdn          | leaf-list   |      | 4 array       | Array  |
|

|                      | domain-name |   9  | 3 text string | String |
"a.com" |

| target-uri           | leaf-list   |      | 4 array       | Array  |
|  

|                      | uri         |  10  | 3 text string | String |
|

| alias-name           | leaf-list   |      | 4 array       | Array  |
|  

|                      | string      |  11  | 3 text string | String | "web"
|  

| lifetime             | int32       |  12  | 0 number      | Number |
|  

| attack-status        | enumeration |  13  | 0 number      | Number | 1
|  

| signal-config        | grouping    |  14  | 5 map         | Object |
|  

| heartbeat-interval   | grouping    |  15  | 5 map         | Object |
|  

| max-retransmit       | grouping    |  16  | 5 map         | Object |
|  

| ack-timeout          | grouping    |  17  | 5 map         | Object |
|  

| ack-random-factor    | grouping    |  18  | 5 map         | Object |
|  

| min-value            | int16       |  19  | 0 number      | Number | 1
|  

| max-value            | int16       |  20  | 0 number      | Number | 1
|  

| status               | enumeration |  21  | 0 number      | Number | 1
|  

| conflict-information | grouping    |  22  | 5 map         | Object |
|  

| conflict-status      | enumeration |  23  | 0 number      | Number | 1
|  

| conflict-cause       | enumeration |  24  | 0 number      | Number | 1
|  

| retry-timer          | int32       |  25  | 0 number      | Number | 1800
|  

| bytes-dropped        | counter64   |  26  | 0 number      | String |
"1234"  |  

| bps-dropped          | counter64   |  27  | 0 number      | String |
"1234"  |  

| pkts-dropped         | counter64   |  28  | 0 number      | String |
"1234"  |  

| pps-dropped          | counter64   |  29  | 0 number      | String |
"1234"  |  

| session-id           | int32       |  30  | 0 number      | Number | 65432
|  

| trigger-mitigation   | boolean     |  31  | 7 simple      | T / F  |
|  

| missing-hb-allowed   | grouping    |  32  | 5 map         | Object |
|  

| current-value        | int16       |  33  | 0 number      | Number | 10
|  

| mitigation-start     | decimal64   |  34  | 7 FP          | Number | 10.21
|  

| target-prefix        | leaf-list   |      | 4 array       | Array  |
|  

|                      | ip-prefix   |  35  | 3 text string | String |
|  

| client-domain-hash   | leaf-list   |      | 4 array       | Array  |
|

|                      | binary      |  36  | 2 byte string | String |
"abcdf" |

| alt-server           | string      |  37  | 3 text string | String |
|  

| alt-server-record    | list        |  38  | 4 array       | Array  |
|  

| addr                 | string      |  39  | 3 text string | String |
|  

| ttl                  | int32       |  40  | 0 number      | Number | 1800
|  

| conflict-scope       | grouping    |  41  | 5 map         | Object |
|  

| acl-name             | string      |  42  | 3 text string | String |
"aname" |  

| acl-type             | string      |  43  | 3 text string | String |
"ipv4"  |  

| config-interval      | int32       |  44  | 0 number      | Number | 11
|  

| mitigating-config    | grouping    |  45  | 5 map         | Object |
|  

| idle-config          | grouping    |  46  | 5 map         | Object |
|  

| request-nonce        | binary      |  47  | 2 byte string | String | "xxx"
|  

| min-value-decimal    | decimal64   |  48  | 7 FP          | Number | 1.1
|  

| max-value-decimal    | decimal64   |  49  | 7 FP          | Number | 1.1
|  

| current-value-decimal| decimal64   |  50  | 7 FP          | Number | 1.1
|  

\----------------------+-------------+------+---------------+--------+------
---/

Comments / suggestions?

Regards

Jon

---

From: "Konda, Tirumaleswar Reddy" <[email-masked]>
Date: Sat, 23 Dec 2017 07:06:16 +0000

We should just follow the CBOR Encoding of Data Modeled with YANG defined in https://tools.ietf.org/html/draft-ietf-core-yang-cbor-05 and JSON Encoding of Data Modeled with YANG
defined in https://tools.ietf.org/html/rfc7951.

-Tiru

From: Dots [mailto:[email-masked]] On Behalf Of Jon Shallow
Sent: Friday, December 22, 2017 10:41 PM
To: [email-masked]
Subject: [Dots] Signal CBOR / JSON Mapping

Hi WG,

There are a lot of YANG parameters that we are using that are defined as int64.  JSON only safely supports up to 53 bits of precision.

RFC 7493 2.2 Numbers

RFC7049 3.6 Numbers

====

An option is to make all of these int64 decimal64 for the signal channel, but that does not cover the 64 bit counters in the netmod-acl.  However, as the netmod-acl counters are also fed back via the mitigate status, we do not necessarily need to support the netmod-acl counters.

If, however, we follow RFC 7493, in CBOR the data can be passed across as 64 bits, and as the parameter is a CBOR mapping, we can know how to encode / decode the JSON value as appropriate.  However, RFC 7493 does not say whether this should be base64, base64url or numeric string representation (i.e. "1234567890").  RFC7049 refers to bignum (major type 6, tag value 2 or 3) should be encoded as base64url (4.1 Converting from CBOR to JSON) - but int64 can be held in CBOR as type 0 or 1.

I prefer the numeric string representation as it is humanly easy to read and easy to convert into 64 bit integers.

If we take this approach of using the parameter which is a CBOR mapping key to key off how to encode / decode the JSON, I would suggest that we could extend this to include IP addresses, Dates and client-identifiers (or their possible new names of request-nonce and client-domain-hash) to further minimize the actual number of bytes sent in a COAP packet.

The CBOR mapping Table could then be extended to look something like (but it is too wide I think)

/----------------------+-------------+------+---------------+--------+---------\
| Parameter name       | YANG type   | CBOR | CBOR major    | JSON   | JSON    |
|                      |             | key  | type          | type   | Example |
|----------------------+-------------+------+---------------+--------+---------|
| mitigation-scope     | grouping    |   1  | 5 map         | Object |         |
| scope                | list        |   2  | 4 array       | Array  |         |
| mitigation-id        | int32       |   3  | 0 unsigned    | Number | 54321   |
| acl-list             | list        |   4  | 4 array       | Array  |         |
| target-port-range    | list        |   5  | 4 array       | Array  |         |
| lower-port           | port-number |   6  | 0 number      | Number | 1111    |
| upper-port           | port-number |   7  | 0 number      | Number | 1111    |
| target-protocol      | leaf-list   |      | 4 array       | Array  |         |
|                      | uint8       |   8  | 0 number      | Number | 6       |
| target-fqdn          | leaf-list   |      | 4 array       | Array  |         |
|                      | domain-name |   9  | 3 text string | String | "a.com" |
| target-uri           | leaf-list   |      | 4 array       | Array  |         |
|                      | uri         |  10  | 3 text string | String |         |
| alias-name           | leaf-list   |      | 4 array       | Array  |         |
|                      | string      |  11  | 3 text string | String | "web"   |
| lifetime             | int32       |  12  | 0 number      | Number |         |
| attack-status        | enumeration |  13  | 0 number      | Number | 1       |
| signal-config        | grouping    |  14  | 5 map         | Object |         |
| heartbeat-interval   | grouping    |  15  | 5 map         | Object |         |
| max-retransmit       | grouping    |  16  | 5 map         | Object |         |
| ack-timeout          | grouping    |  17  | 5 map         | Object |         |
| ack-random-factor    | grouping    |  18  | 5 map         | Object |         |
| min-value            | int16       |  19  | 0 number      | Number | 1       |
| max-value            | int16       |  20  | 0 number      | Number | 1       |
| status               | enumeration |  21  | 0 number      | Number | 1       |
| conflict-information | grouping    |  22  | 5 map         | Object |         |
| conflict-status      | enumeration |  23  | 0 number      | Number | 1       |
| conflict-cause       | enumeration |  24  | 0 number      | Number | 1       |
| retry-timer          | int32       |  25  | 0 number      | Number | 1800    |
| bytes-dropped        | counter64   |  26  | 0 number      | String | "1234"  |
| bps-dropped          | counter64   |  27  | 0 number      | String | "1234"  |
| pkts-dropped         | counter64   |  28  | 0 number      | String | "1234"  |
| pps-dropped          | counter64   |  29  | 0 number      | String | "1234"  |
| session-id           | int32       |  30  | 0 number      | Number | 65432   |
| trigger-mitigation   | boolean     |  31  | 7 simple      | T / F  |         |
| missing-hb-allowed   | grouping    |  32  | 5 map         | Object |         |
| current-value        | int16       |  33  | 0 number      | Number | 10      |
| mitigation-start     | decimal64   |  34  | 7 FP          | Number | 10.21   |
| target-prefix        | leaf-list   |      | 4 array       | Array  |         |
|                      | ip-prefix   |  35  | 3 text string | String |         |
| client-domain-hash   | leaf-list   |      | 4 array       | Array  |         |
|                      | binary      |  36  | 2 byte string | String | "abcdf" |
| alt-server           | string      |  37  | 3 text string | String |         |
| alt-server-record    | list        |  38  | 4 array       | Array  |         |
| addr                 | string      |  39  | 3 text string | String |         |
| ttl                  | int32       |  40  | 0 number      | Number | 1800    |
| conflict-scope       | grouping    |  41  | 5 map         | Object |         |
| acl-name             | string      |  42  | 3 text string | String | "aname" |
| acl-type             | string      |  43  | 3 text string | String | "ipv4"  |
| config-interval      | int32       |  44  | 0 number      | Number | 11      |
| mitigating-config    | grouping    |  45  | 5 map         | Object |         |
| idle-config          | grouping    |  46  | 5 map         | Object |         |
| request-nonce        | binary      |  47  | 2 byte string | String | "xxx"   |
| min-value-decimal    | decimal64   |  48  | 7 FP          | Number | 1.1     |
| max-value-decimal    | decimal64   |  49  | 7 FP          | Number | 1.1     |
| current-value-decimal| decimal64   |  50  | 7 FP          | Number | 1.1     |
\----------------------+-------------+------+---------------+--------+---------/

Comments / suggestions?

Regards

Jon

---

From: "Jon Shallow" <[email-masked]>
Date: Thu, 28 Dec 2017 21:02:10 -0000

Hi Tiru,

Thanks for pointing me to these references.

RFC7951

6.1.  Numeric Types

   A value of the "int8", "int16", "int32", "uint8", "uint16", or

   "uint32" type is represented as a JSON number.

   A value of the "int64", "uint64", or "decimal64" type is represented

   as a JSON string whose content is the lexical representation of the

   corresponding YANG type as specified in Sections 9.2.1 and 9.3.1 of

   [RFC7950].

   For example, if the type of the leaf "foo" in Section 5.1 was

   "uint64" instead of "uint8", the instance would have to be encoded as

   "foo": "123"

--

So, we now have a way of handling int64/uint64 which should be used moving
forward.

However, my JSON implementation (as well as many others I suspect) natively
supports decimal64, so does not necessarily need to display it as a lexical
representation string.  Do we follow RFC7951 here as well?

I do not think that we should be following the augmented JSON parameter
naming in RFC7951 "4. Names and Namespaces" otherwise we will start ending
up with JSON/CBOR parameter names such as
"ietf-dots-signal:mitigation-scope".  If we do go with this, then the CBOR
mapping table will need to get extended to cover the old, but some parameter
name in different places.  Comments?

As we are working with YANG, JSON and CBOR interrelation , I still think we
need a table similar to below to aid implementers - referring as appropriate
to the different RFCs - no-one has full knowledge of all the evolving RFCs. 

Regards

Jon

From: Dots [mailto: [email-masked]] On Behalf Of Konda, Tirumaleswar
Reddy
Sent: 23 December 2017 07:06
To: Jon Shallow; [email-masked]
Subject: Re: [Dots] Signal CBOR / JSON Mapping

We should just follow the CBOR Encoding of Data Modeled with YANG defined in
https://tools.ietf.org/html/draft-ietf-core-yang-cbor-05 and JSON Encoding
of Data Modeled with YANG

-Tiru

Hi WG,

RFC 7493 2.2 Numbers

RFC7049 3.6 Numbers

   receiving applications.

====

 

Comments / suggestions?

Regards

Jon