idnits 2.17.1 draft-ietf-ipfix-text-adt-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 165: '... codepoint MAY be used to improve re...' RFC 2119 keyword, line 269: '... writers MAY sacrifice precision to ...' RFC 2119 keyword, line 386: '...these Data Types MUST NOT be used in t...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (April 14, 2014) is 3658 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- == Missing Reference: 'WSP' is mentioned on line 154, but not defined Summary: 1 error (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 IPFIX Working Group B. Trammell 3 Internet-Draft ETH Zurich 4 Intended status: Informational April 14, 2014 5 Expires: October 16, 2014 7 Textual Representation of IPFIX Abstract Data Types 8 draft-ietf-ipfix-text-adt-03.txt 10 Abstract 12 This document defines UTF-8 representations for IPFIX abstract data 13 types, to support interoperable usage of the IPFIX Information 14 Elements with protocols based on textual encodings. 16 Status of This Memo 18 This Internet-Draft is submitted in full conformance with the 19 provisions of BCP 78 and BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF). Note that other groups may also distribute 23 working documents as Internet-Drafts. The list of current Internet- 24 Drafts is at http://datatracker.ietf.org/drafts/current/. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 This Internet-Draft will expire on October 16, 2014. 33 Copyright Notice 35 Copyright (c) 2014 IETF Trust and the persons identified as the 36 document authors. All rights reserved. 38 This document is subject to BCP 78 and the IETF Trust's Legal 39 Provisions Relating to IETF Documents 40 (http://trustee.ietf.org/license-info) in effect on the date of 41 publication of this document. Please review these documents 42 carefully, as they describe your rights and restrictions with respect 43 to this document. Code Components extracted from this document must 44 include Simplified BSD License text as described in Section 4.e of 45 the Trust Legal Provisions and are provided without warranty as 46 described in the Simplified BSD License. 48 Table of Contents 50 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 51 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 52 3. Identifying Information Elements . . . . . . . . . . . . . . 3 53 4. Data Type Encodings . . . . . . . . . . . . . . . . . . . . . 3 54 4.1. octetArray . . . . . . . . . . . . . . . . . . . . . . . 3 55 4.2. unsigned8, unsigned16, unsigned32, and unsigned64 . . . . 4 56 4.3. signed8, signed16, signed32, and signed64 . . . . . . . . 5 57 4.4. float32 and float64 . . . . . . . . . . . . . . . . . . . 6 58 4.5. boolean . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 4.6. macAddress . . . . . . . . . . . . . . . . . . . . . . . 7 60 4.7. string . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 4.8. dateTime* . . . . . . . . . . . . . . . . . . . . . . . . 7 62 4.9. ipv4Address . . . . . . . . . . . . . . . . . . . . . . . 8 63 4.10. ipv6Address . . . . . . . . . . . . . . . . . . . . . . . 8 64 4.11. basicList, subTemplateList, and subTemplateMultiList . . 9 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . 9 66 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 9 67 7. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 9 68 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 69 8.1. Normative References . . . . . . . . . . . . . . . . . . 10 70 8.2. Informative References . . . . . . . . . . . . . . . . . 10 71 Appendix A. Example . . . . . . . . . . . . . . . . . . . . . . 11 72 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 12 74 1. Introduction 76 The IPFIX Information Model[RFC7012] provides a set of abstract data 77 types for the IANA IPFIX Information Element Registry [IANA-IPFIX], 78 which contains a rich set of Information Elements for description of 79 information about network entities and network traffic data, and 80 abstract data types for these Information Elements. The IPFIX 81 Protocol Specification [RFC7011], in turn, defines a big-endian 82 binary encoding for these abstract data types suitable for use with 83 the IPFIX Protocol. 85 However, present and future operations and management protocols and 86 applications may use textual encodings, and generic framing and 87 structure, as in JSON or XML. A definition of canonical textual 88 encodings for the IPFIX abstract data types would allow this set of 89 Information Elements to be used for such applications, and for these 90 applications to interoperate with IPFIX applications at the 91 Information Element definition level. 93 In most cases where a textual representation will be used, an 94 explicit tradeoff is made for human readability or manipulability 95 over compactness; this assumption is used in defining standard 96 representations of IPFIX ADTs. 98 Note that templating or other mechanisms for data description for 99 such applications and protocols are application specific, and 100 therefore out of scope for this document: only Information Element 101 identification and data value representation are defined here. 103 2. Terminology 105 Capitalized terms defined in the IPFIX Protocol Specification 106 [RFC7011] and the IPFIX Information Model [RFC7012] are used in this 107 document as defined in those documents. In addition, this document 108 defines the following terminology for its own use: 110 Enclosing Context 111 A textual representation of IPFIX data values is applied to use 112 the IPFIX Information Model within some existing textual format 113 (e.g. XML, JSON). This outer format is referred to as the 114 Enclosing Context within this document. Enclosing Contexts define 115 escaping and quoting rules for represented data values. 117 3. Identifying Information Elements 119 The IPFIX Information Element Registry [IANA-IPFIX] defines a set of 120 Information Elements numbered by Information Element Identifiers and 121 named for human-readability. These Information Element Identifiers 122 are meant for use with the IPFIX protocol, and have little meaning 123 when applying the IPFIX Information Element Registry to textual 124 representations. 126 Instead, applications using textual representations of Information 127 Elements should use Information Element names to identify them; see 128 Appendix A for examples illustrating this principle. 130 4. Data Type Encodings 132 Each subsection of this section defines a textual encoding for the 133 abstract data types defined in [RFC7012]. This section uses ABNF, 134 including the Core Rules in Appendix B of [RFC5234], to describe the 135 format of textual representations of IPFIX abstract data types. 137 4.1. octetArray 139 If the Enclosing Context defines a representation for binary objects, 140 that representation should be used. 142 Otherwise, since the goal of textual representation of Information 143 Elements is human-readability over compactness, the values of 144 Information Elements of the octetArray data type are represented as a 145 string of pairs of hexadecimal digits, one pair per byte, in the 146 order the bytes would appear on the wire were the octetArray encoded 147 directly in IPFIX per [RFC7011]. Whitespace may occur between any 148 pair of digits to assist in human readability of the string, but is 149 not necessary, and is disregarded by any process reading the string. 150 In ABNF: 152 hex-octet = 2HEXDIGIT 154 octetarray = 1*(hex-octet [WSP]) 156 4.2. unsigned8, unsigned16, unsigned32, and unsigned64 158 If the Enclosing Context defines a representation for unsigned 159 integers, that representation should be used. 161 In the special case that the unsigned Information Element has 162 identifier semantics, and refers to a set of codepoints, either in an 163 external registry, a sub-registry, or directly in the description of 164 the Information Element, then the name or short description for that 165 codepoint MAY be used to improve readability. 167 Otherwise, the values of Information Elements of an unsigned integer 168 type may be represented either as unprefixed base-10 (decimal) 169 strings, as base-16 (hexadecimal) strings prefixed by "0x", or as 170 base-2 (binary) strings prefixed by "0b". In ABNF: 172 unsigned = 1*DIGIT / "0x" 1*HEXDIG / "0b" 1*BIT 174 Leading zeroes are allowed in any either encoding, and do not signify 175 base-8 (octal) encoding. Binary encoding is intended for use with 176 Information Elements with flag semantics, but can be used in any 177 case. 179 The encoded value must be in range for the corresponding abstract 180 data type or Information Element. Out of range values should be 181 interpreted as clipped to the implicit range for the Information 182 Element as defined by the abstract data type, or to the explicit 183 range of the Information Element if defined. Minimum and maximum 184 values for abstract data types are shown in Table 1 below. 186 +------------+---------+----------------------------+ 187 | type | minimum | maximum | 188 +------------+---------+----------------------------+ 189 | unsigned8 | 0 | 255 | 190 | unsigned16 | 0 | 65 536 | 191 | unsigned32 | 0 | 42 94 967 295 | 192 | unsigned64 | 0 | 18 446 744 073 709 551 615 | 193 +------------+---------+----------------------------+ 195 Table 1: Ranges for unsigned abstract data types 197 4.3. signed8, signed16, signed32, and signed64 199 If the Enclosing Context defines a representation for signed 200 integers, that representation should be used. 202 Otherwise, the values of Information Elements of signed integer types 203 should be represented as optionally-prefixed base-10 (decimal) 204 strings. In ABNF: 206 sign = "+" / "-" 208 signed = [sign] 1*DIGIT 210 If the sign is omitted, it is assumed to be positive. Leading zeroes 211 are allowed, and do not signify base-8 (octal) encoding. The 212 representation "-0" is explicitly allowed, and is equal to zero. 214 The encoded value must be in range for the corresponding abstract 215 data type or Information Element. Out of range values should be 216 interpreted as clipped to the implicit range for the Information 217 Element as defined by the abstract data type, or to the explicit 218 range of the Information Element if defined. Minimum and maximum 219 values for abstract data types are shown in Table 2 below. 221 +----------+---------------------------+----------------------------+ 222 | type | minimum | maximum | 223 +----------+---------------------------+----------------------------+ 224 | signed8 | -128 | +127 | 225 | signed16 | -32 768 | +32 767 | 226 | signed32 | -2 147 483 648 | +2 147 483 647 | 227 | signed64 | -9 223 372 036 854 775 | +9 223 372 036 854 775 807 | 228 | | 808 | | 229 +----------+---------------------------+----------------------------+ 231 Table 2: Ranges for signed abstract data types 233 4.4. float32 and float64 235 If the Enclosing Context defines a representation for floating point 236 numbers, that representation should be used. 238 Otherwise, the values of Information Elements of float32 or float64 239 types are represented as optionally sign-prefixed, optionally base-10 240 exponent-suffixed, floating point decimal numbers, as in 241 [IEEE.754.2008]. The special strings "NaN", "+inf", and "-inf" 242 represent not a number, positive infinity and negative infinity, 243 respectively. 245 In ABNF: 247 sign = "+" / "-" 249 exponent = ( "e" / "E" ) [sign] 1*3DIGIT 251 right-decimal = "." *DIGIT 253 mantissa = 1*DIGIT [right-decimal] 255 num = [sign] mantissa [exponent] 257 naninf = "NaN" / sign "inf" 259 float = num / naninf 261 The expressed value is ( mantissa * 10 ^ exponent ). If the sign is 262 omitted, it is assumed to be positive. If the exponent is omitted, 263 it is assumed to be zero. Leading zeroes may appear in the mantissa 264 and/or the exponent. Values must be within range for [IEEE.754.2008] 265 single or double precision numbers. Finite values outside the range 266 must be clamped to be within the range. 268 Note that, since this representation is meant for human readability, 269 writers MAY sacrifice precision to use a more human-readable 270 representation of a given value, at the expense of the ability to 271 recover the exact bit pattern at the reader. 273 4.5. boolean 275 If the Enclosing Context defines a representation for boolean values, 276 that representation should be used. 278 Otherwise, a true boolean value is represented by the literal string 279 "true", and a false boolean value with the literal string "false". 280 In ABNF: 282 boolean-true = "true" 284 boolean-false = "false" 286 boolean = boolean-true / boolean-false 288 4.6. macAddress 290 MAC addresses are represented as IEEE 802 MAC-48 addresses, 291 hexadecimal bytes, most significant byte first, separated by colons. 292 In ABNF: 294 hex-octet = 2HEXDIGIT 296 macaddress = hex-octet 5( ":" hex-octet ) 298 4.7. string 300 As Information Elements of the string type are simply UTF-8 encoded 301 strings, they are represented directly, subject to the escaping and 302 encoding rules of the Enclosing Context. If the Enclosing Context 303 cannot natively represent UTF-8 characters, the escaping facility 304 provided by the Enclosing Context must be used for non-representable 305 characters. Additionally, strings containing characters reserved in 306 the Enclosing Context (e.g. markup characters, quotes) must be 307 escaped or quoted according to the rules of the Enclosing Context. 309 4.8. dateTime* 311 Timestamp abstract data types are represented generally as in 312 [RFC3339], with two important differences. First, all IPFIX 313 timestamps are expressed in terms of UTC, so textual representations 314 of these Information Elements are explicitly in UTC as well. Time 315 zone offsets are therefore not required or supported. Second, there 316 are four timestamp abstract data types, separated by the precision 317 which they can express. Fractional seconds must be omitted in 318 dateTimeSeconds, expressed in milliseconds in dateTimeMilliseconds, 319 and so on. 321 In ABNF, taken from [RFC3339] and modified: 323 date-fullyear = 4DIGIT 324 date-month = 2DIGIT ; 01-12 325 date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 326 time-hour = 2DIGIT ; 00-23 327 time-minute = 2DIGIT ; 00-59 328 time-second = 2DIGIT ; 00-58, 00-59, 00-60 329 time-msec = "." 3DIGIT 330 time-usec = "." 6DIGIT 331 time-nsec = "." 9DIGIT 332 full-date = date-fullyear "-" date-month "-" date-mday 333 partial-time = time-hour ":" time-minute ":" time-second 335 datetimeseconds = full-date "T" partial-time 336 datetimemilliseconds = full-date "T" partial-time "." time-msec 337 datetimemicroseconds = full-date "T" partial-time "." time-usec 338 datetimenanoseconds = full-date "T" partial-time "." time-nsec 340 4.9. ipv4Address 342 IP version 4 addresses are represented in dotted-quad format, most- 343 significant-byte first, as it would in a Uniform Resource Identifier 344 [RFC3986]; the ABNF for an IPv4 address is taken from [RFC3986] and 345 reproduced below: 347 dec-octet = DIGIT ; 0-9 348 / %x31-39 DIGIT ; 10-99 349 / "1" 2DIGIT ; 100-199 350 / "2" %x30-34 DIGIT ; 200-249 351 / "25" %x30-35 ; 250-255 353 ipv4address = dec-octet 3( "." dec-octet ) 355 4.10. ipv6Address 357 IP version 6 addresses are represented as in section 2.2 of 358 [RFC4291], as updated by section 4 of [RFC5952]. The ABNF for an 359 IPv6 address is taken from [RFC3986] and reproduced below, using the 360 ipv4address production from the previous section: 362 ls32 = ( h16 ":" h16 ) / ipv4address 363 ; least-significant 32 bits of address 364 h16 = 1*4HEXDIG 365 ; 16 bits of address represented in hexadecimal 366 ; zeroes to suppressed as in RFC 5952 368 ipv6address = 6( h16 ":" ) ls32 369 / "::" 5( h16 ":" ) ls32 370 / [ h16 ] "::" 4( h16 ":" ) ls32 371 / [ h16 ":" h16 ] "::" 3( h16 ":" ) ls32 372 / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32 373 / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32 374 / [ *4( h16 ":" ) h16 ] "::" ls32 375 / [ *5( h16 ":" ) h16 ] "::" h16 376 / [ *6( h16 ":" ) h16 ] "::" 378 4.11. basicList, subTemplateList, and subTemplateMultiList 380 These abstract data types, defined for IPFIX Structured Data 381 [RFC6313], do not represent actual data types; they are instead 382 designed to provide a mechanism by which complex structure can be 383 represented in IPFIX below the template level. It is assumed that 384 protocols using textual Information Element representation will 385 provide their own structure. Therefore, Information Elements of 386 these Data Types MUST NOT be used in textual representations. 388 5. Security Considerations 390 The security considerations for the IPFIX Protocol [RFC7011] apply; 391 this document presents no additional security considerations. 392 Implementations of decoders of Information Element values using these 393 representations must take care to correctly handle invalid input, but 394 the encodings presented here are not special in that respect. 396 6. IANA Considerations 398 This document has no considerations for IANA. 400 7. Acknowledgments 402 Thanks to Paul Aitken, Andrew Feren, and Juergen Quittek for the 403 review and comments. Thanks to Dave Thaler and Stephan Neuhaus for 404 discussions which improved the floating-point representation section. 405 This work is materially supported by the European Union Seventh 406 Framework Programme under grant agreement 318627 mPlane. 408 8. References 410 8.1. Normative References 412 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 413 Internet: Timestamps", RFC 3339, July 2002. 415 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 416 Resource Identifier (URI): Generic Syntax", STD 66, RFC 417 3986, January 2005. 419 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 420 Architecture", RFC 4291, February 2006. 422 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 423 Specifications: ABNF", STD 68, RFC 5234, January 2008. 425 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 426 Address Text Representation", RFC 5952, August 2010. 428 [RFC7011] Claise, B., Trammell, B., and P. Aitken, "Specification of 429 the IP Flow Information Export (IPFIX) Protocol for the 430 Exchange of Flow Information", STD 77, RFC 7011, September 431 2013. 433 [IANA-IPFIX] 434 Internet Assigned Numbers Authority, , "IP Flow 435 Information Export Information Elements 436 (http://www.iana.org/assignments/ipfix/ipfix.xml)", 437 November 2012. 439 8.2. Informative References 441 [RFC6313] Claise, B., Dhandapani, G., Aitken, P., and S. Yates, 442 "Export of Structured Data in IP Flow Information Export 443 (IPFIX)", RFC 6313, July 2011. 445 [RFC7012] Claise, B. and B. Trammell, "Information Model for IP Flow 446 Information Export (IPFIX)", RFC 7012, September 2013. 448 [RFC7013] Trammell, B. and B. Claise, "Guidelines for Authors and 449 Reviewers of IP Flow Information Export (IPFIX) 450 Information Elements", BCP 184, RFC 7013, September 2013. 452 [IEEE.754.2008] 453 Instute of Electrical and Electronic Engineers, , 454 "Standard for Floating-Point Arithmetic (IEEE Standard 455 754)", August 2008. 457 Appendix A. Example 459 In this section, we examine an IPFIX Template and a Data Record 460 defined by that Template, and show how that Data Record would be 461 represented in JSON according to the specification in this document. 462 Note that this is specifically NOT a recommendation for a particular 463 representation, merely an illustration of the encodings in this 464 document; the quoting and formatting in the example are JSON- 465 specific. 467 Figure 1 shows a Template in IESpec format as defined in section 10.1 468 of [RFC7013]. A Message containing this Template and a Data Record 469 is shown in Figure 2, and a corresponding JSON Object using the text 470 format defined in this document is shown in Figure 3. 472 flowStartMilliseconds(152)[8] 473 flowEndMilliseconds(153)[8] 474 octetDeltaCount(1)[4] 475 packetDeltaCount(2)[4] 476 sourceIPv6Address(27)[4]{key} 477 destinationIPv6Address(28)[4]{key} 478 sourceTransportPort(7)[2]{key} 479 destinationTransportPort(11)[2]{key} 480 protocolIdentifier(4)[1]{key} 481 tcpControlBits(6)[1] 482 flowEndReason(136)[1] 484 Figure 1: Sample flow template in IESpec format 486 1 2 3 4 5 6 487 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 488 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 489 | 0x000a | length 135 | export time 1352140263 | msg 490 | sequence 0 | domain 1 | hdr 491 | SetID 2 | length 52 | tid 256 | fields 11 | tmpl 492 | IE 152 | length 8 | IE 153 | length 8 | set 493 | IE 1 | length 4 | IE 2 | length 4 | 494 | IE 27 | length 16 | IE 28 | length 16 | 495 | IE 7 | length 2 | IE 11 | length 2 | 496 | IE 4 | length 1 | IE 6 | length 1 | 497 | IE 136 | length 1 | SetID 256 | length 83 | data 498 | start time 1352140261135 | set 499 | end time 1352140262880 | 500 | octets 195383 | packets 88 | 501 | sip6 | 502 | 2001:0db8:000c:1337:0000:0000:0000:0002 | 503 | dip6 | 504 | 2001:0db8:000c:1337:0000:0000:0000:0003 | 505 | sp 80 | dp 32991 | prt 6 | tcp 19| fe 3 | 506 +-------------------------------------------------------+ 508 Figure 2: IPFIX Message containing sample flow 510 { 511 "flowStartMilliseconds": "2012-11-05T18:31:01.135", 512 "flowEndMilliseconds": "2012-11-05T18:31:02.880", 513 "octetDeltaCount": 195383, 514 "packetDeltaCount": 88, 515 "sourceIPv6Address": "2001:db8:c:1337::2", 516 "destinationIPv6Address": "2001:db8:c:1337::3", 517 "sourceTransportPort": 80, 518 "destinationTransportPort": 32991, 519 "protocolIdentifier": "tcp", 520 "tcpControlBits": 19, 521 "flowEndReason": 3 522 } 524 Figure 3: JSON object containing sample flow 526 Author's Address 527 Brian Trammell 528 Swiss Federal Institute of Technology Zurich 529 Gloriastrasse 35 530 8092 Zurich 531 Switzerland 533 Phone: +41 44 632 70 13 534 Email: trammell@tik.ee.ethz.ch