Textual Representation of IPFIX Abstract Data Types
Swiss Federal Institute of Technology Zurich
Gloriastrasse 358092 ZurichSwitzerland+41 44 632 70 13trammell@tik.ee.ethz.ch
Operations
IPFIX Working GroupThis 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.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, 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.Capitalized terms defined in the IPFIX Protocol
Specification and the IPFIX Information
Model are used in this document as defined in those documents. In
addition, this document defines the following terminology for its own
use: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.The IPFIX Information Element
Registry 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 for examples illustrating this principle.Each subsection of this section defines a textual encoding for the
abstract data types defined in . This section
uses ABNF, including the Core Rules in
Appendix B, to describe the format of textual representations of IPFIX
abstract data types.If the Enclosing Context defines a representation for binary
objects, that representation SHOULD be used.Otherwise, since the goal of textual representation of Information
Elements is readability over compactness, the values of Information
Elements of the octetArray data type are represented as a string of
pairs of hexadecimal digits, one pair per byte, in the order the bytes
would appear on the wire were the octetArray encoded directly in IPFIX
per . Whitespace
may occur between any pair of digits to assist in human readability of
the string, but is not necessary, and must be disregarded by any
process reading the string. In ABNF:hex-octet = 2HEXDIGIToctetarray = 1* (hex-octet [WSP])If the Enclosing Context defines a representation for unsigned
integers, that representation SHOULD be used.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. 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*HEXDIGLeading 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
below.typeminimummaximumunsigned80255unsigned16065536unsigned3204294967295unsigned64018446744073709551615If 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. In ABNF:sign = "+" / "-"signed = [sign] 1*DIGITIf the sign is omitted, it is assumed to be positive. 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
below.typeminimummaximumsigned8-128+127signed16-32768+32767signed32-2147483648+2147483647signed64-9223372036854775808+9223372036854775807If the Enclosing Context defines a representation for floating
point numbers, that representation SHOULD be used.Otherwise, the values of Information Elements of float32 or float64
types are represented as an optionally sign-prefixed, optionally
base-10 exponent-suffixed, floating point decimal number. In ABNF:sign = "+" / "-"exponent = 'e' 1*3DIGITright-decimal = '.' 0*DIGITmantissa = 1*DIGIT [right-decimal]float = [sign] mantissa [exponent]The expressed value is ( mantissa * 10 ^ exponent ). If the sign is
omitted, it is assumed to be positive. If the exponent is omitted, it
is assumed to be zero. Leading zeroes may appear in the mantissa
and/or the exponent.Minimum and maximum values for abstract data types are shown in
below.typeminimum abs(x)maximum abs(x)float325.877e-393.403e38float641.1125e-308+1.798e308If the Enclosing Context defines a representation for boolean
values, that representation SHOULD be used.Otherwise, a true boolean value should be represented with the
literal string 1, and a false boolean value with the literal string 0.
In ABNF:boolean-yes = "1"boolean-no = "0"boolean = boolean-yes / boolean-noMAC addresses are represented as IEEE 802 MAC-48 addresses,
hexadecimal bytes, most significant byte first, separated by colons. In
ABNF, using the hex-octet production from :macaddress = hex-octet 5( ":" hex-octet )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.Timestamp abstract data types are represented generally as in , with two important differences. First, all IPFIX
timestamps are expressed in terms of UTC, so textual representations of
these Information Elements are explictly in UTC as well. Time zone
offsets are therefore not required or supported. Second, there are four
timestamp abstract data types, separated by the precision which they
can express. Fractional seconds must be omitted in dateTimeSeconds,
expressed in milliseconds in dateTimeMilliseconds, and so on.In ABNF, taken from and modified:IP version 4 addresses are represented in dotted-quad format,
most-significant-byte first, as it would in a Uniform Resource
Identifier ; the ABNF for an IPv4 address is
taken from and reproduced below:IP version 6 addresses are represented as in section 2.2 of , as updated by section 4 of . The ABNF for an IPv6 address is taken from and reproduced below:These abstract data types, defined for IPFIX
Structured Data, do not represent actual data types; they are
instead designed to provide a mechanism by which complex structure can
be represented in IPFIX 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 MUST NOT be used in textual representations.This document does not present any additional security measures beyond those presented by .This document has no considerations for IANA.IP Flow Information Export Information Elements (http://www.iana.org/assignments/ipfix/ipfix.xml)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. shows a Template in IEspec format as defined in section 9.1 of . A Message containing this Template and a Data Record is shown in , and a corresponding JSON Object using the text format defined in this document is shown in .