One document matched: draft-ietf-ipfix-text-adt-00.xml
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<rfc ipr="trust200902" category="info" docName="draft-ietf-ipfix-text-adt-00.txt">
<?rfc compact="yes"?>
<?rfc subcompact="no"?>
<?rfc toc="yes"?>
<?rfc symrefs="yes"?>
<front>
<title abbrev="IPFIX Text Types">
Textual Representation of IPFIX Abstract Data Types
</title>
<author initials="B." surname="Trammell" fullname="Brian Trammell">
<organization abbrev="ETH Zurich">
Swiss Federal Institute of Technology Zurich
</organization>
<address>
<postal>
<street>Gloriastrasse 35</street>
<city>8092 Zurich</city>
<country>Switzerland</country>
</postal>
<phone>+41 44 632 70 13</phone>
<email>trammell@tik.ee.ethz.ch</email>
</address>
</author>
<date year="2014" month="January" day="20"/>
<area>Operations</area>
<workgroup>IPFIX Working Group</workgroup>
<abstract>
<t>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.</t>
</abstract>
</front>
<middle>
<section anchor="sec-intro" title="Introduction">
<t>The IPFIX Information Model, as defined by the <xref target="iana-ipfix-assignments">IANA IPFIX Information
Element Registry</xref>, 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 <xref
target="RFC7011">IPFIX Protocol
Specification</xref>, in turn, defines a big-endian binary encoding for
these abstract data types suitable for use with the IPFIX Protocol.</t>
<t>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.</t>
<t>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.</t>
</section>
<section title="Terminology">
<t>Capitalized terms defined in the <xref
target="RFC7011">IPFIX Protocol
Specification</xref> and the <xref
target="RFC7012">IPFIX Information
Model</xref> are used in this document as defined in those documents. In
addition, this document defines the following terminology for its own
use:</t>
<t><list style="hanging">
<t hangText="Enclosing Context"><vspace/>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.</t>
</list></t>
</section>
<section title="Identifying Information Elements">
<t>The <xref target="iana-ipfix-assignments">IPFIX Information Element
Registry</xref> 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.</t>
<t>Instead, applications using textual representations of Information
Elements SHOULD use Information Element names to identify them; see <xref
target="sec-examples"/> for examples illustrating this principle.</t>
</section>
<section title="Data Type Encodings">
<t>Each subsection of this section defines a textual encoding for the
abstract data types defined in <xref
target="RFC7012"/>. This section
uses <xref target="RFC5234">ABNF</xref>, including the Core Rules in
Appendix B, to describe the format of textual representations of IPFIX
abstract data types.</t>
<section title="octetArray" anchor="sec-octetarray">
<t>If the Enclosing Context defines a representation for binary
objects, that representation SHOULD be used.</t>
<t>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 <xref target="RFC7011"/>. 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:</t>
<t>hex-octet = 2HEXDIGIT</t>
<t>octetarray = 1* (hex-octet [WSP])</t>
</section>
<section title="unsigned8, unsigned16, unsigned32, and unsigned64">
<t>If the Enclosing Context defines a representation for unsigned
integers, that representation SHOULD be used.</t>
<t>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. </t>
<t>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:</t>
<t>unsigned = 1*DIGIT / '0x' 1*HEXDIG</t>
<t>Leading zeroes are allowed in either encoding, and do not signify
base-8 (octal) encoding.</t>
<t>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 <xref target="tab-unsigned-range"/>
below.</t>
<texttable anchor="tab-unsigned-range" align="center"
title="Ranges for unsigned abstract data types">
<ttcol align="right">type</ttcol>
<ttcol align="right">minimum</ttcol>
<ttcol align="right">maximum</ttcol>
<c>unsigned8</c> <c>0</c> <c>255</c>
<c>unsigned16</c> <c>0</c> <c>65536</c>
<c>unsigned32</c> <c>0</c> <c>4294967295</c>
<c>unsigned64</c> <c>0</c> <c>18446744073709551615</c>
</texttable>
</section>
<section title="signed8, signed16, signed32, and signed64">
<t>If the Enclosing Context defines a representation for signed
integers, that representation SHOULD be used.</t>
<t>Otherwise, the values of Information Elements of signed integer
types should be represented as optionally-prefixed base-10 (decimal)
strings. In ABNF:</t>
<t>sign = "+" / "-"</t>
<t>signed = [sign] 1*DIGIT</t>
<t>If the sign is omitted, it is assumed to be positive. Leading zeroes
are allowed, and do not signify base-8 (octal) encoding.</t>
<t>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 <xref target="tab-signed-range"/>
below.</t>
<texttable anchor="tab-signed-range" align="center"
title="Ranges for signed abstract data types">
<ttcol align="right">type</ttcol>
<ttcol align="right">minimum</ttcol>
<ttcol align="right">maximum</ttcol>
<c>signed8</c> <c>-128</c> <c>+127</c>
<c>signed16</c> <c>-32768</c> <c>+32767</c>
<c>signed32</c> <c>-2147483648</c> <c>+2147483647</c>
<c>signed64</c> <c>-9223372036854775808</c> <c>+9223372036854775807</c>
</texttable>
</section>
<section title="float32 and float64">
<t>If the Enclosing Context defines a representation for floating
point numbers, that representation SHOULD be used.</t>
<t>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:</t>
<t>sign = "+" / "-"</t>
<t>exponent = 'e' 1*3DIGIT</t>
<t>right-decimal = '.' 0*DIGIT</t>
<t>mantissa = 1*DIGIT [right-decimal]</t>
<t>float = [sign] mantissa [exponent]</t>
<t>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.</t>
<t>Minimum and maximum values for abstract data types are shown in
<xref target="tab-float-range"/>below.</t>
<texttable anchor="tab-float-range" align="center"
title="Ranges for floating-point abstract data types">
<ttcol align="right">type</ttcol>
<ttcol align="right">minimum abs(x)</ttcol>
<ttcol align="right">maximum abs(x)</ttcol>
<c>float32</c> <c>5.877e-39</c> <c>3.403e38</c>
<c>float64</c> <c>1.1125e-308</c> <c>+1.798e308</c>
</texttable>
</section>
<section title="boolean">
<t>If the Enclosing Context defines a representation for boolean
values, that representation SHOULD be used.</t>
<t>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:</t>
<t>boolean-yes = "1"</t>
<t>boolean-no = "0"</t>
<t>boolean = boolean-yes / boolean-no</t>
</section>
<section title="macAddress">
<t>MAC 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 <xref
target="sec-octetarray"/>:</t>
<t>macaddress = hex-octet 5( ":" hex-octet )</t>
</section>
<section title="string">
<t>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.</t>
</section>
<section title="dateTime*">
<t>Timestamp abstract data types are represented generally as in <xref
target="RFC3339"/>, 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.</t>
<t>In ABNF, taken from <xref target="RFC3339"/> and modified:</t>
<figure><artwork>
date-fullyear = 4DIGIT
date-month = 2DIGIT ; 01-12
date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31
time-hour = 2DIGIT ; 00-23
time-minute = 2DIGIT ; 00-59
time-second = 2DIGIT ; 00-58, 00-59, 00-60
time-msec = "." 3*DIGIT
time-usec = "." 6*DIGIT
time-nsec = "." 9*DIGIT
partial-time = time-hour ":" time-minute ":" time-second
datetimeseconds = full-date "T" partial-time
datetimemilliseconds = full-date "T" partial-time "." time-msec
datetimemicroseconds = full-date "T" partial-time "." time-usec
datetimenanoseconds = full-date "T" partial-time "." time-nsec
</artwork></figure>
</section>
<section title="ipv4Address">
<t>IP version 4 addresses are represented in dotted-quad format,
most-significant-byte first, as it would in a Uniform Resource
Identifier <xref target="RFC3986"/>; the ABNF for an IPv4 address is
taken from <xref target="RFC3986"/> and reproduced below:</t>
<figure><artwork>
dec-octet = DIGIT ; 0-9
/ %x31-39 DIGIT ; 10-99
/ "1" 2DIGIT ; 100-199
/ "2" %x30-34 DIGIT ; 200-249
/ "25" %x30-35 ; 250-255
ipv4address = dec-octet 3("." dec-octet)
</artwork></figure>
</section>
<section title="ipv6Address">
<t>IP version 6 addresses are represented as in section 2.2 of <xref
target="RFC4291"/>, as updated by section 4 of <xref
target="RFC5952"/>. The ABNF for an IPv6 address is taken from <xref
target="RFC3986"/> and reproduced below:</t>
<figure><artwork>
ls32 = ( h16 ":" h16 ) / IPv4address
; least-significant 32 bits of address
h16 = 1*4HEXDIG
; 16 bits of address represented in hexadecimal
; zeroes to suppressed as in RFC 5952
ipv6address = 6( h16 ":" ) ls32
/ "::" 5( h16 ":" ) ls32
/ [ h16 ] "::" 4( h16 ":" ) ls32
/ [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32
/ [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32
/ [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32
/ [ *4( h16 ":" ) h16 ] "::" ls32
/ [ *5( h16 ":" ) h16 ] "::" h16
/ [ *6( h16 ":" ) h16 ] "::"
</artwork></figure>
</section>
<section title="basicList, subTemplateList, and subTemplateMultiList">
<t>These abstract data types, defined for <xref target="RFC6313">IPFIX
Structured Data</xref>, 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.</t>
</section>
</section>
<section title="Security Considerations">
<t>This document does not present any additional security measures beyond those presented by <xref target="RFC7011"/>.</t>
</section>
<section title="IANA Considerations">
<t>This document has no considerations for IANA.</t>
</section>
</middle>
<back>
<references title="Normative References">
<?rfc include="reference.RFC.3339" ?>
<?rfc include="reference.RFC.3986" ?>
<?rfc include="reference.RFC.4291" ?>
<?rfc include="reference.RFC.5234" ?>
<?rfc include="reference.RFC.5952" ?>
<?rfc include="reference.RFC.7011" ?>
<reference anchor='iana-ipfix-assignments'>
<front>
<title>IP Flow Information Export Information Elements (http://www.iana.org/assignments/ipfix/ipfix.xml)</title>
<author surname="Internet Assigned Numbers Authority"/>
<date month="November" year="2012"/>
</front>
</reference>
</references>
<references title="Informative References">
<?rfc include="reference.RFC.6313" ?>
<?rfc include="reference.RFC.7012" ?>
<?rfc include="reference.RFC.7013" ?>
</references>
<section anchor="sec-examples" title="Example">
<t>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.</t>
<t><xref target="fig-tmpl"/> shows a Template in IESpec format as defined in section 10.1 of <xref target="RFC7013"/>. A Message containing this Template and a Data Record is shown in <xref target="fig-ipfix"/>, and a corresponding JSON Object using the text format defined in this document is shown in <xref target="fig-json"/>.</t>
<figure title="Sample flow template (IPFIX)" anchor="fig-tmpl">
<artwork><![CDATA[
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]
]]></artwork></figure>
<figure title="IPFIX message containing sample flow" anchor="fig-ipfix">
<artwork><![CDATA[
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 |
+-------------------------------------------------------+
]]></artwork></figure>
<figure title="JSON object containing sample flow" anchor="fig-json">
<artwork><![CDATA[
{
"flowStartMilliseconds": "2012-11-05T18:31:01.135",
"flowEndMilliseconds": "2012-11-05T18: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
}
]]></artwork></figure>
</section>
</back>
</rfc>| PAFTECH AB 2003-2026 | 2026-04-23 09:27:36 |