Textual Representation of IPFIX Abstract Data Types
draft-trammell-ipfix-text-adt-01.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 November 23, 2013.

Copyright Notice

Copyright (c) 2013 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.

Table of Contents

• 1. Introduction
• 2. Terminology
• 3. Identifying Information Elements
• 4. Data Type Encodings
• 4.1. octetArray
• 4.2. unsigned*
• 4.3. signed*
• 4.4. float*
• 4.5. boolean
• 4.6. macAddress
• 4.7. string
• 4.8. dateTime*
• 4.9. ipv4Address
• 4.10. ipv6Address
• 4.11. basicList, subTemplateList, and subTemplateMultiList
• 5. Security Considerations
• 6. IANA Considerations
• 7. References
• 7.1. Normative References
• 7.2. Informative References
• Appendix A. Example
• Author's Address

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 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.

Instead, applications using textual representations of Information Elements SHOULD use Information Element names to identify them; see Appendix A for examples illustrating this principle.

4. Data Type Encodings

[FIXME frontmatter]

This section uses ABNF [RFC5234], including the Core Rules in 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*

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

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.

      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]
      

           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  |
+-------------------------------------------------------+
      

        {
            "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
        }