[IPFIX] review of draft-trammell-ipfix-text-adt-00

[Paul Aitken <[e-mail]>]

Brian,

Here's a review of draft-trammell-ipfix-text-adt-00.

Please find comments inline.


>
>
>
> IPFIX Working Group                                          B. Trammell
> Internet-Draft                                                ETH Zurich
> Intended status: Informational                          November 5, 2012
> Expires: May 9, 2013
>
>
>           Textual Representation of IPFIX Abstract Data Types
>                   draft-trammell-ipfix-text-adt-00.txt
>
> Abstract
>
>    This document defines UTF-8 representations for IPFIX abstract data
>    types, to support interoperable usage of the IPFIX Information
>    Elements with protocols based on textual encodings.
>
> Status of this Memo
>
>    This Internet-Draft is submitted in full conformance with the
>    provisions of BCP 78 and BCP 79.
>
>    Internet-Drafts are working documents of the Internet Engineering
>    Task Force (IETF).  Note that other groups may also distribute
>    working documents as Internet-Drafts.  The list of current Internet-
>    Drafts is at http://datatracker.ietf.org/drafts/current/.
>
>    Internet-Drafts are draft documents valid for a maximum of six months
>    and may be updated, replaced, or obsoleted by other documents at any
>    time.  It is inappropriate to use Internet-Drafts as reference
>    material or to cite them other than as "work in progress."
>
>    This Internet-Draft will expire on May 9, 2013.
>
> Copyright Notice
>
>    Copyright (c) 2012 IETF Trust and the persons identified as the
>    document authors.  All rights reserved.
>
>    This document is subject to BCP 78 and the IETF Trust's Legal
>    Provisions Relating to IETF Documents
>    (http://trustee.ietf.org/license-info) in effect on the date of
>    publication of this document.  Please review these documents
>    carefully, as they describe your rights and restrictions with respect
>    to this document.  Code Components extracted from this document must
>    include Simplified BSD License text as described in Section 4.e of
>    the Trust Legal Provisions and are provided without warranty as
>    described in the Simplified BSD License.
>
>
>
>
>
> Trammell                   Expires May 9, 2013 [Page 1]
> 
> Internet-Draft              IPFIX Text Types November 2012
>
>
> Table of Contents
>
>    1.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3
>    2.  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  3
>    3.  Identifying Information Elements . . . . . . . . . . . . . . .  3
>    4.  Data Type Encodings  . . . . . . . . . . . . . . . . . . . . .  4
>      4.1.  octetArray . . . . . . . . . . . . . . . . . . . . . . . .  4
>      4.2.  unsigned*  . . . . . . . . . . . . . . . . . . . . . . . .  4
>      4.3.  signed*  . . . . . . . . . . . . . . . . . . . . . . . . .  5
>      4.4.  float* . . . . . . . . . . . . . . . . . . . . . . . . . .  6
>      4.5.  boolean  . . . . . . . . . . . . . . . . . . . . . . . . .  6
>      4.6.  macAddress . . . . . . . . . . . . . . . . . . . . . . . .  6
>      4.7.  string . . . . . . . . . . . . . . . . . . . . . . . . . .  6
>      4.8.  dateTime*  . . . . . . . . . . . . . . . . . . . . . . . .  6
>      4.9.  ipv4Address  . . . . . . . . . . . . . . . . . . . . . . .  7
>      4.10. ipv6Address  . . . . . . . . . . . . . . . . . . . . . . .  7
>      4.11. basicList, subTemplateList, and subTemplateMultiList . . .  7
>    5.  Security Considerations  . . . . . . . . . . . . . . . . . . .  7
>    6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . .  7
>    7.  References . . . . . . . . . . . . . . . . . . . . . . . . . .  7
>      7.1.  Normative References . . . . . . . . . . . . . . . . . . .  7
>      7.2.  Informative References . . . . . . . . . . . . . . . . . .  8
>    Appendix A.  Example . . . . . . . . . . . . . . . . . . . . . . .  8
>    Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 10
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> Trammell                   Expires May 9, 2013 [Page 2]
> 
> Internet-Draft              IPFIX Text Types November 2012
>
>
> 1.  Introduction
>
>    The IPFIX Information Model, as defined by the IANA IPFIX Information
>    Element Registry, provides a rich set of Information Elements for
>    description of information about network entities and network traffic
>    data, and abstract data types for these Information Elements. The
>    IPFIX Protocol Specification [I-D.ietf-ipfix-protocol-rfc5101bis], in
>    turn, defines a big-endian binary encoding for these abstract data
>    types suitable for use with the IPFIX Protocol.
>
>    However, present and future operations and management protocols and
>    applications may use textual encodings, and generic framing and
>    structure as in JSON or XML.  A definition of canonical textual
>    encodings for the IPFIX abstract data types would allow this set of
>    Information Elements to be used for such applications, and for these
>    applications to interoperate with IPFIX applications at the
>    Information Element definition level.
>
>    Note that templating or other mechanisms for data description for
>    such applications and protocols are application specific, and
>    therefore out of scope for this document: only Information Element
>    identification and data value representation are defined here.
>
>
> 2.  Terminology
>
>    Capitalized terms defined in the IPFIX Protocol Specification
>    [I-D.ietf-ipfix-protocol-rfc5101bis] and the IPFIX Information Model
>    [I-D.ietf-ipfix-information-model-rfc5102bis] are used in this
>    document as defined in those documents.  In addition, this document
>    defines the following terminology for its own use:
>
>    Enclosing Context
>       Textual representation of IPFIX data values is applied to use the
>       IPFIX Information Model within some existing textual format (e.g.
>       XML, JSON).  This outer format is referred to as the Enclosing
>       Context within this document.  Enclosing Contexts define escaping
>       and quoting rules for represented data values.
>
>
> 3.  Identifying Information Elements
>
>    The IPFIX Information Element Registry [iana-ipfix-assignments]
>    defines a set of Information Elements and numbered by Information

Doesn't parse. Remove "and".


>    Element Identifiers, and named for human-readability.  These
>    Information Element Identifiers are meant for use with the IPFIX
>    protocol, and have little meaning when applying the IPFIX Information
>    Element Registry to textual representations.
>
>
>
> Trammell                   Expires May 9, 2013 [Page 3]
> 
> Internet-Draft              IPFIX Text Types November 2012
>
>
>    Instead, applications using textual representations of Information
>    Elements SHOULD use Information Element names to identify them; see
>    Appendix A for examples illustrating this principle.

If the names are to be the (joint?) primary reference for IEs, then IE 
doctors should review all the IE names to ensure consistency, and define 
rules for new IE names to ensure that consistency is maintained.


>
>
> 4.  Data Type Encodings
>
>    [FIXME frontmatter]
>
>    This section uses ABNF [RFC5234], including the Core Rules in

Where is "Core Rules" defined?


>    Appendix B, to describe the format of textual representations of
>    IPFIX abstract data types.
>
> 4.1.  octetArray
>
>    [FIXME: native hex strings for comparative human readabilty.]
>
> 4.2.  unsigned*

* it's a pointer?


>
>    First, in the special case that the unsigned Information Element has
>    identifier semantics, and refers to a set of codepoints, either in an
>    external registry, a sub-registry, or directly in the description of
>    the Information Element, then the name or short description for that
>    codepoint MAY be used to improve readability.
>
>    If the Enclosing Context defines a representation for unsigned
>    integers, that representation SHOULD be used.
>
>    Otherwise, the values of Information Elements of an unsigned integer
>    type may be represented either as unprefixed base-10 (decimal)
>    strings, or as base-16 (hexadecimal) strings prefixed by '0x'; in
>    ABNF:
>
>    unsigned = 1*DIGIT / '0x' 1*HEXDIG

RFC5234, sigh: / looks like division, although it's intended as "OR".

Consider allowing binary or any arbitrary number base to be used.


>
>    Leading zeroes are allowed in either encoding, and do not signify
>    base-8 (octal) encoding.
>
>    The encoded value must be in range for the corresponding abstract
>    data type or Information Element.  Out of range values should be
>    interpreted as clipped to the implicit range for the Information
>    Element as defined by the abstract data type, or to the explicit
>    range of the Information Element if defined.  Minimum and maximum
>    values for abstract data types are shown in Table 1 below.
>
>
>
>
>
>
>
> Trammell                   Expires May 9, 2013 [Page 4]
> 
> Internet-Draft              IPFIX Text Types November 2012
>
>
>               +------------+---------+----------------------+
>               |       type | minimum |              maximum |
>               +------------+---------+----------------------+
>               |  unsigned8 |       0 |                  255 |
>               | unsigned16 |       0 |                65536 |
>               | unsigned32 |       0 |           4294967295 |
>               | unsigned64 |       0 | 18446744073709551615 |
>               +------------+---------+----------------------+
>
>              Table 1: Ranges for unsigned abstract data types
>

Can we ever get away from the idea that u8, u16, u32, and u64 are 
different types?
Rather, they're just different size encodings of the same type.


> 4.3.  signed*

(Same comments for this section as for "unsigned" above.)


>
>    If the Enclosing Context defines a representation for signed
>    integers, that representation should be used.
>
>    Otherwise, the values of Information Elements of signed integer types
>    should be represented as optionally-prefixed base-10 (decimal)
>    strings; if the sign is omitted, it is assumed to be positive. In
>    ABNF:
>
>    sign = "+" / "-"
>
>    signed = [sign] 1*DIGIT
>
>    Leading zeroes are allowed, and do not signify base-8 (octal)
>    encoding.
>
>    The encoded value must be in range for the corresponding abstract
>    data type or Information Element.  Out of range values should be
>    interpreted as clipped to the implicit range for the Information
>    Element as defined by the abstract data type, or to the explicit
>    range of the Information Element if defined.  Minimum and maximum
>    values for abstract data types are shown in Table 2 below.
>
>         +----------+----------------------+----------------------+
>         |     type |              minimum |              maximum |
>         +----------+----------------------+----------------------+
>         |  signed8 |                 -128 |                 +127 |
>         | signed16 |               -32768 |               +32767 |
>         | signed32 |          -2147483648 |          [phone] |
>         | signed64 | -9223372036854775808 | +9223372036854775807 |
>         +----------+----------------------+----------------------+
>
>               Table 2: Ranges for signed abstract data types
>
>
>
>
>
>
> Trammell                   Expires May 9, 2013 [Page 5]
> 
> Internet-Draft              IPFIX Text Types November 2012
>
>
> 4.4.  float*
>
>    If the Enclosing Context defines a representation for floating point
>    numbers, that representation should be used.
>
>    [FIXME: there appears to be no defined (non-interchange) format for
>    floating point numbers, but we probably want to define something
>    reasonably human-readable without getting too into locale issues.]
>
>    exponent = 'e' 1*3DIGIT
>
>    right-decimal = '.' 0*DIGIT

ie, a decimal point with at least zero digits following? Why? The 
decimal point is only required when there are following digits.


>
>    float = [sign] 1*DIGIT [right-decimal] [exponent]
>
> 4.5.  boolean
>
>    [FIXME: frontmatter. note that booleans may also be natually

Typo, "naturally".


>    represented by the presence or absence of a value in the structure of
>    the document in the Enclosing Context.]
>
>    boolean-yes = "1" / "y" / "Y" / "t" / "T"
>
>    boolean-no = "0" / "n" / "N" / "f" / "F"
>
>    boolean = boolean-yes / boolean-no

RFC5235 ABNF inconsistently uses - as a range indicator while also 
allowing it in rule names.


>
> 4.6.  macAddress
>
>    [FIXME: frontmatter]
>
>    macaddress = 2*HEXDIG 5*( ":" 2*HEXDIG )

Should be "5*5" to constrain the maximum size too, since exactly 6 pairs 
of digits are required.


>
> 4.7.  string
>
>    As Information Elements of the string type are simply UTF-8 encoded
>    strings, they are represented directly, subject to the escaping and
>    encoding rules of the Enclosing Context.  If the Enclosing Context
>    cannot natively represent UTF-8 characters, the escaping facility
>    provided by the Enclosing Context must be used for non-representable
>    characters.  Additionally, strings containing characters reserved in
>    the Enclosing Context (e.g. markup characters, quotes) must be
>    escaped or quoted according to the rules of the Enclosing Context.
>
> 4.8.  dateTime*
>
>    [FIXME: [RFC3339]]
>
>
>
>
> Trammell                   Expires May 9, 2013 [Page 6]
> 
> Internet-Draft              IPFIX Text Types November 2012
>
>
>    [FIXME: explain precision rules]
>
> 4.9.  ipv4Address
>
>    [FIXME: frontmatter. dotted-quad.]
>
>    ipv4address = 1*3DIGIT 3*( "." 1*3DIGIT )

Again, use 3*3 to constrain the maximum length, since exactly 4 digits 
are required.


>
> 4.10.  ipv6Address
>
>    [FIXME: section 2.2 of [RFC4291], recommend section 4 of [RFC5952]]
>
> 4.11.  basicList, subTemplateList, and subTemplateMultiList
>
>    These abstract data types, defined for IPFIX Structured Data
>    [RFC6313], do not represent actual data types; they are instead
>    designed to provide a mechanism by which complex structure below the
>    template level.  It is assumed that protocols using textual
>    Information Element representation will provide their own structure.
>    Therefore, Information Elements of these Data Types should not be
>    used in textual representations.

Doesn't make sense.


>
>
> 5.  Security Considerations
>
>    [FIXME: content would be nice]
>
>
> 6.  IANA Considerations
>
>    This document has no considerations for IANA.
>
>
> 7.  References
>
> 7.1.  Normative References
>
>    [I-D.ietf-ipfix-protocol-rfc5101bis]
>               Claise, B. and B. Trammell, "Specification of the IP Flow
>               Information eXport (IPFIX) Protocol for the Exchange of
>               Flow Information", draft-ietf-ipfix-protocol-rfc5101bis-02
>               (work in progress), June 2012.
>
>    [RFC3339]  Klyne, G., Ed. and C. Newman, "Date and Time on the
>               Internet: Timestamps", RFC 3339, July 2002.
>
>    [RFC4291]  Hinden, R. and S. Deering, "IP Version 6 Addressing
>               Architecture", RFC 4291, February 2006.
>
>
>
> Trammell                   Expires May 9, 2013 [Page 7]
> 
> Internet-Draft              IPFIX Text Types November 2012
>
>
>    [RFC5234]  Crocker, D. and P. Overell, "Augmented BNF for Syntax
>               Specifications: ABNF", STD 68, RFC 5234, January 2008.
>
>    [RFC5952]  Kawamura, S. and M. Kawashima, "A Recommendation for IPv6
>               Address Text Representation", RFC 5952, August 2010.
>
>    [iana-ipfix-assignments]
>               Internet Assigned Numbers Authority, "IP Flow Information
>               Export Information Elements
>               (http://www.iana.org/assignments/ipfix/ipfix.xml)",
>               November 2012.
>
> 7.2.  Informative References
>
>    [I-D.ietf-ipfix-information-model-rfc5102bis]
>               Claise, B. and B. Trammell, "Information Model for IP Flow
>               Information eXport (IPFIX)",
>               draft-ietf-ipfix-information-model-rfc5102bis-06 (work in
>               progress), October 2012.
>
>    [I-D.ietf-ipfix-ie-doctors]
>               Trammell, B. and B. Claise, "Guidelines for Authors and
>               Reviewers of IPFIX Information Elements",
>               draft-ietf-ipfix-ie-doctors-07 (work in progress),
>               October 2012.
>
>    [RFC6313]  Claise, B., Dhandapani, G., Aitken, P., and S. Yates,
>               "Export of Structured Data in IP Flow Information Export
>               (IPFIX)", RFC 6313, July 2011.
>
>
> Appendix A.  Example
>
>    In this section, we examine an IPFIX Template and a Data Record
>    defined by that Template, and show how that Data Record would be
>    represented in JSON according to the specification in this document.
>    Note that this is specifically NOT a recommendation for a particular
>    representation, merely an illustration of the encodings in this
>    document.
>
>    [FIXME improve frontmatter] Figure 1 shows a Template in IEspec
>    format as defined in section 9.1 of [I-D.ietf-ipfix-ie-doctors].  A
>    Message containing this Template and a Data Record is shown in
>    Figure 2, and a corresponding JSON Object using the text format
>    defined in this document is shown in Figure 3.

Personally I'd rather that each description immediately precedes the 
corresponding figure.

P.


>
>
>
>
>
>
> Trammell                   Expires May 9, 2013 [Page 8]
> 
> Internet-Draft              IPFIX Text Types November 2012
>
>
>          flowStartMilliseconds(152)<dateTimeMilliseconds>[8]
>          flowEndMilliseconds(153)<dateTimeMilliseconds>[8]
>          octetDeltaCount(1)<unsigned64>[4]
>          packetDeltaCount(2)<unsigned64>[4]
>          sourceIPv6Address(27)<ipv4Address>[4]{key}
>          destinationIPv6Address(28)<ipv4Address>[4]{key}
>          sourceTransportPort(7)<unsigned16>[2]{key}
>          destinationTransportPort(11)<unsigned16>[2]{key}
>          protocolIdentifier(4)<unsigned8>[1]{key}
>          tcpControlBits(6)<unsigned8>[1]
>          flowEndReason(136)<unsigned8>[1]
>
>                   Figure 1: Sample flow template (IPFIX)
>
>
>              1         2         3         4         5         6
>    0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2 4 6 8 0 2
> +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+
>   | 0x000a        | length 135    | export time 1352140263 | msg
>   | sequence 0                    | domain 1 | hdr
>   | SetID 2       | length 52     | tid 256       | fields 11 | tmpl
>   | IE 152        | length 8      | IE 153        | length 8 | set
>   | IE 1          | length 4      | IE 2          | length 4 |
>   | IE 27         | length 16     | IE 28         | length 16 |
>   | IE 7          | length 2      | IE 11         | length 2 |
>   | IE 4          | length 1      | IE 6          | length 1 |
>   | IE 136        | length 1      | SetID 256     | length 83 | data
>   | start time                                     1352140261135 | set
>   | end time                                       1352140262880 |
>   | octets                195383  | packets                   88 |
>   | sip6 |
>   |                       2001:0db8:000c:1337:0000:0000:0000:0002 |
>   | dip6 |
>   |                       2001:0db8:000c:1337:0000:0000:0000:0003 |
>   | sp        80  | dp     32991  | prt 6 | tcp 19| fe 3  |
>   +-------------------------------------------------------+
>
>               Figure 2: IPFIX message containing sample flow
>
>
>
>
>
>
>
>
>
>
>
>
>
> Trammell                   Expires May 9, 2013 [Page 9]
> 
> Internet-Draft              IPFIX Text Types November 2012
>
>
>            {
>                "flowStartMilliseconds": "2012-11-05 18:31:01.135",
>                "flowEndMilliseconds": "2012-11-05 18:31:02.880",
>                "octetDeltaCount": 195383,
>                "packetDeltaCount": 88,
>                "sourceIPv6Address": "2001:db8:c:1337::2",
>                "destinationIPv6Address": "2001:db8:c:1337::3",
>                "sourceTransportPort": 80,
>                "destinationTransportPort": 32991,
>                "protocolIdentifier": "tcp",
>                "tcpControlBits": 19,
>                "flowEndReason": 3
>            }
>
>                Figure 3: JSON object containing sample flow
>
>
> Author's Address
>
>    Brian Trammell
>    Swiss Federal Institute of Technology Zurich
>    Gloriastrasse 35
>    8092 Zurich
>    Switzerland
>
>    Phone: [phone]
>    Email: [e-mail]
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
>
> Trammell                   Expires May 9, 2013 [Page 10]
>