One document matched: draft-trammell-ipfix-text-adt-01.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-trammell-ipfix-text-adt-01.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="2013"/>
<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 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 <xref
target="I-D.ietf-ipfix-protocol-rfc5101bis">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="I-D.ietf-ipfix-protocol-rfc5101bis">IPFIX Protocol
Specification</xref> and the <xref
target="I-D.ietf-ipfix-information-model-rfc5102bis">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>[FIXME frontmatter]</t>
<t>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">
<t>[FIXME: native hex strings for comparative human readabilty.]</t>
</section>
<section title="unsigned*">
<t>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. </t>
<t>If the Enclosing Context defines a representation for unsigned
integers, that representation SHOULD be used.</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="signed*">
<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="float*">
<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>
</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:</t>
<t>macaddress = 2*HEXDIG 5*( ":" 2*HEXDIG )</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 data types are represented as in <xref target="RFC3339"/>.</t>
<t>[FIXME: elaborate, and explain precision rules]</t>
</section>
<section title="ipv4Address">
<t>IPv4 addresses are represented in dotted-quad format, most-significant-byte first. In ABNF:</t>
<t>ipv4address = 1*3DIGIT 3*( "." 1*3DIGIT )</t>
<t>[FIXME: elaborate]</t>
</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"/>.</t>
<t>[FIXME: elaborate]</t>
</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
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>[FIXME: content would be nice]</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.I-D.ietf-ipfix-protocol-rfc5101bis" ?>
<?rfc include="reference.RFC.3339" ?>
<?rfc include="reference.RFC.4291" ?>
<?rfc include="reference.RFC.5234" ?>
<?rfc include="reference.RFC.5952" ?>
<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.I-D.ietf-ipfix-information-model-rfc5102bis" ?>
<?rfc include="reference.I-D.ietf-ipfix-ie-doctors" ?>
<?rfc include="reference.RFC.6313" ?>
</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>[FIXME improve frontmatter] <xref target="fig-tmpl"/> shows a Template in IEspec format as defined in section 9.1 of <xref target="I-D.ietf-ipfix-ie-doctors"/>. 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-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
}
]]></artwork></figure>
</section>
</back>
</rfc>| PAFTECH AB 2003-2026 | 2026-04-24 05:41:03 |