4.4. float32 and float64

If 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 optionally sign-prefixed, optionally base-10 exponent-suffixed, floating point decimal numbers, as in [IEEE.754.2008]. The special strings "NaN", "+inf", and "-inf" represent not a number, positive infinity and negative infinity, respectively.

In ABNF:

sign = "+" / "-"

exponent = "e" [sign] 1*3DIGIT

right-decimal = "." 1*DIGIT

mantissa = 1*DIGIT [right-decimal]

num = [sign] mantissa [exponent]

naninf = "NaN" / (sign "inf")

float = num / naninf

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. Values MUST be within range for [IEEE.754.2008] single or double precision numbers; finite values outside the approprate range are to be interpreted as clamped to be within the range. Note that no more than three digits are required or allowed for exponents in this encoding due to these ranges.

Note that, since this representation is meant for human readability, writers MAY sacrifice precision to use a more human-readable representation of a given value, at the expense of the ability to recover the exact bit pattern at the reader. Therefore, decoders MUST NOT assume that the represented values are exactly compararable for equality.

4.5. boolean

If the Enclosing Context defines a representation for boolean values, that representation SHOULD be represented.

Otherwise, a true boolean value is represented by the literal string "true", and a false boolean value with the literal string "false". In ABNF:

boolean-true = "true"

boolean-false = "false"

boolean = boolean-true / boolean-false

4.6. macAddress

MAC addresses are represented as IEEE 802 MAC-48 addresses, hexadecimal bytes, most significant byte first, separated by colons. In ABNF:

hex-octet = 2HEXDIG

macaddress = hex-octet 5( ":" hex-octet )

4.7. string

As Information Elements of the string type are simply Unicode strings (encoded as UTF-8 when appearing in Data Sets in IPFIX Messages [RFC7011]), they are represented directly, using the Unicode encoding rules and quoting and escaping rules of the Enclosing Context.

If the Enclosing Context cannot natively represent Unicode 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. control characters, markup characters, quotes) MUST be escaped or quoted according to the rules of the Enclosing Context.

It is presumed that the Enclosing Context has sufficient restrictions on the use of Unicode to prevent the unsafe use of non-printing and control characters. As there is no accepted solution for the processing and safe display of mixed-direction strings, mixed-direction strings should be avoided using this encoding. Note also that, since this draft presents no additional requirements for the normalization of Unicode strings, care must be taken when comparing strings using this encoding; direct byte-pattern comparisons are not sufficient for determining whether two strings are equivalent. See [RFC6885] and [I-D.ietf-precis-framework] for more on possible unexpected results and related risks in comparing Unicode strings.

4.8. The dateTime ADTs

Timestamp abstract data types are represented generally as in [RFC3339], with two important differences. First, all IPFIX timestamps are expressed in terms of UTC, so textual representations of these Information Elements are explicitly 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 are omitted in dateTimeSeconds, expressed in milliseconds in dateTimeMilliseconds, and so on.

In ABNF, taken from [RFC3339] and modified:

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       = "." 3DIGIT
time-usec       = "." 6DIGIT
time-nsec       = "." 9DIGIT
full-date       = date-fullyear "-" date-month "-" date-mday
integer-time    = time-hour ":" time-minute ":" time-second

datetimeseconds      = full-date "T" integer-time
datetimemilliseconds = full-date "T" integer-time "." time-msec
datetimemicroseconds = full-date "T" integer-time "." time-usec
datetimenanoseconds  = full-date "T" integer-time "." time-nsec
        

4.9. ipv4Address

IP version 4 addresses are represented in dotted-quad format, most-significant-byte first, as it would in a Uniform Resource Identifier [RFC3986]; the ABNF for an IPv4 address is taken from [RFC3986] and reproduced below:

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 )
        

4.10. ipv6Address

IP version 6 addresses are represented as in section 2.2 of [RFC4291], as updated by section 4 of [RFC5952]. The ABNF for an IPv6 address is taken from [RFC3986] and reproduced below, using the ipv4address production from the previous section:

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
            / [     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 ] "::"
        

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

5. Security Considerations

The security considerations for the IPFIX Protocol [RFC7011] apply.

Implementations of decoders of Information Element values using these representations must take care to correctly handle invalid input, but the encodings presented here are not special in that respect.

The encoding specified in this document, and representations that may be built upon it, are specifically not intended for the storage of data. However, since storage of data in the format in which it is exchanged is a very common practice, and the ubiquity of tools for indexing and searching text significantly increases the ease of searching and the risk of privacy-sensitive data being accidentally indexed or searched, the privacy considerations in Section 11.8 of [RFC7011] are especially important to observe when storing data using the encoding specified in this document that was derived from the measurement of network traffic.

When using representations based on this encoding to transmit or store network traffic data, consider omitting especially privacy-sensitive values by not representing the columns or keys containing those values, as in black-marker anonymization as discussed in Section 4 of [RFC6235]. Other anonymization techinques described in [RFC6235] may also be useful in these situations.

The encodings for all Abstract Data Types other than 'string' are defined in such a way as to be representable in the US-ASCII character set, and therefore should be unproblematic for all Enclosing Contexts. However, the 'string' Abstract Data Type may be vulnerable to problems with ill-formed UTF-8 strings as discussed in section 6.1.6 of [RFC7011]; see [UTF8-EXPLOIT] for background.

6. IANA Considerations

This document has no considerations for IANA.

7. Acknowledgments

Thanks to Paul Aitken, Benoit Claise, Andrew Feren, Juergen Quittek, David Black, and the IESG for the review and comments. Thanks to Dave Thaler and Stephan Neuhaus for discussions which improved the floating-point representation section. This work is materially supported by the European Union Seventh Framework Programme under grant agreement 318627 mPlane.

8. References

8.1. Normative References

8.2. Informative References

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; the quoting and formatting in the example are JSON-specific.

Figure 1 shows a Template in IESpec format as defined in section 10.1 of [RFC7013]; a corresponding JSON Object representing a record defined by this template in the text format specified in this document is shown in Figure 2.

      flowStartMilliseconds(152)<dateTimeMilliseconds>[8]
      flowEndMilliseconds(153)<dateTimeMilliseconds>[8]
      octetDeltaCount(1)<unsigned64>[4]
      packetDeltaCount(2)<unsigned64>[4]
      sourceIPv6Address(27)<ipv6Address>[16]{key}
      destinationIPv6Address(28)<ipv6Address>[16]{key}
      sourceTransportPort(7)<unsigned16>[2]{key}
      destinationTransportPort(11)<unsigned16>[2]{key}
      protocolIdentifier(4)<unsigned8>[1]{key}
      tcpControlBits(6)<unsigned8>[1]
      flowEndReason(136)<unsigned8>[1]
      

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