idnits 2.17.1 draft-trammell-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 : ---------------------------------------------------------------------------- ** There are 2 instances of too long lines in the document, the longest one being 1 character in excess of 72. ** 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 120: '... Elements SHOULD use Information Ele...' RFC 2119 keyword, line 133: '... that representation SHOULD be used....' RFC 2119 keyword, line 152: '...s, that representation SHOULD be used....' RFC 2119 keyword, line 158: '... codepoint MAY be used to improve re...' RFC 2119 keyword, line 191: '...s, that representation SHOULD be used....' (3 more instances...) Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (November 08, 2013) is 3822 days in the past. Is this intentional? Checking references for intended status: Informational ---------------------------------------------------------------------------- No issues found here. Summary: 2 errors (**), 0 flaws (~~), 1 warning (==), 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 November 08, 2013 5 Expires: May 12, 2014 7 Textual Representation of IPFIX Abstract Data Types 8 draft-trammell-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 May 12, 2014. 33 Copyright Notice 35 Copyright (c) 2013 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 . . . . . . . . . . . . . . . . . . . 5 58 4.5. boolean . . . . . . . . . . . . . . . . . . . . . . . . . 6 59 4.6. macAddress . . . . . . . . . . . . . . . . . . . . . . . 6 60 4.7. string . . . . . . . . . . . . . . . . . . . . . . . . . 6 61 4.8. dateTime* . . . . . . . . . . . . . . . . . . . . . . . . 7 62 4.9. ipv4Address . . . . . . . . . . . . . . . . . . . . . . . 7 63 4.10. ipv6Address . . . . . . . . . . . . . . . . . . . . . . . 8 64 4.11. basicList, subTemplateList, and subTemplateMultiList . . 8 65 5. Security Considerations . . . . . . . . . . . . . . . . . . . 8 66 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 8 67 7. References . . . . . . . . . . . . . . . . . . . . . . . . . 9 68 7.1. Normative References . . . . . . . . . . . . . . . . . . 9 69 7.2. Informative References . . . . . . . . . . . . . . . . . 9 70 Appendix A. Example . . . . . . . . . . . . . . . . . . . . . . 9 71 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . 11 73 1. Introduction 75 The IPFIX Information Model, as defined by the IANA IPFIX Information 76 Element Registry, provides a rich set of Information Elements for 77 description of information about network entities and network traffic 78 data, and abstract data types for these Information Elements. The 79 IPFIX Protocol Specification [RFC7011], in turn, defines a big-endian 80 binary encoding for these abstract data types suitable for use with 81 the IPFIX Protocol. 83 However, present and future operations and management protocols and 84 applications may use textual encodings, and generic framing and 85 structure as in JSON or XML. A definition of canonical textual 86 encodings for the IPFIX abstract data types would allow this set of 87 Information Elements to be used for such applications, and for these 88 applications to interoperate with IPFIX applications at the 89 Information Element definition level. 91 Note that templating or other mechanisms for data description for 92 such applications and protocols are application specific, and 93 therefore out of scope for this document: only Information Element 94 identification and data value representation are defined here. 96 2. Terminology 98 Capitalized terms defined in the IPFIX Protocol Specification 99 [RFC7011] and the IPFIX Information Model [RFC7012] are used in this 100 document as defined in those documents. In addition, this document 101 defines the following terminology for its own use: 103 Enclosing Context 104 Textual representation of IPFIX data values is applied to use the 105 IPFIX Information Model within some existing textual format (e.g. 106 XML, JSON). This outer format is referred to as the Enclosing 107 Context within this document. Enclosing Contexts define escaping 108 and quoting rules for represented data values. 110 3. Identifying Information Elements 112 The IPFIX Information Element Registry [iana-ipfix-assignments] 113 defines a set of Information Elements and numbered by Information 114 Element Identifiers, and named for human-readability. These 115 Information Element Identifiers are meant for use with the IPFIX 116 protocol, and have little meaning when applying the IPFIX Information 117 Element Registry to textual representations. 119 Instead, applications using textual representations of Information 120 Elements SHOULD use Information Element names to identify them; see 121 Appendix A for examples illustrating this principle. 123 4. Data Type Encodings 125 Each subsection of this section defines a textual encoding for the 126 abstract data types defined in [RFC7012]. This section uses ABNF 127 [RFC5234], including the Core Rules in Appendix B, to describe the 128 format of textual representations of IPFIX abstract data types. 130 4.1. octetArray 132 If the Enclosing Context defines a representation for binary objects, 133 that representation SHOULD be used. 135 Otherwise, since the goal of textual representation of Information 136 Elements is readability over compactness, the values of Information 137 Elements of the octetArray data type are represented as a string of 138 pairs of hexadecimal digits, one pair per byte, in the order the 139 bytes would appear on the wire were the octetArray encoded directly 140 in IPFIX per [RFC7011]. Whitespace may occur between any pair of 141 digits to assist in human readability of the string, but is not 142 necessary, and must be disregarded by any process reading the string. 143 In ABNF: 145 hex-octet = 2HEXDIGIT 147 octetarray = 1* (hex-octet [WSP]) 149 4.2. unsigned8, unsigned16, unsigned32, and unsigned64 151 If the Enclosing Context defines a representation for unsigned 152 integers, that representation SHOULD be used. 154 In the special case that the unsigned Information Element has 155 identifier semantics, and refers to a set of codepoints, either in an 156 external registry, a sub-registry, or directly in the description of 157 the Information Element, then the name or short description for that 158 codepoint MAY be used to improve readability. 160 Otherwise, the values of Information Elements of an unsigned integer 161 type may be represented either as unprefixed base-10 (decimal) 162 strings, or as base-16 (hexadecimal) strings prefixed by '0x'; in 163 ABNF: 165 unsigned = 1*DIGIT / '0x' 1*HEXDIG 167 Leading zeroes are allowed in either encoding, and do not signify 168 base-8 (octal) encoding. 170 The encoded value must be in range for the corresponding abstract 171 data type or Information Element. Out of range values should be 172 interpreted as clipped to the implicit range for the Information 173 Element as defined by the abstract data type, or to the explicit 174 range of the Information Element if defined. Minimum and maximum 175 values for abstract data types are shown in Table 1 below. 177 +------------+---------+----------------------+ 178 | type | minimum | maximum | 179 +------------+---------+----------------------+ 180 | unsigned8 | 0 | 255 | 181 | unsigned16 | 0 | 65536 | 182 | unsigned32 | 0 | 4294967295 | 183 | unsigned64 | 0 | 18446744073709551615 | 184 +------------+---------+----------------------+ 186 Table 1: Ranges for unsigned abstract data types 188 4.3. signed8, signed16, signed32, and signed64 190 If the Enclosing Context defines a representation for signed 191 integers, that representation SHOULD be used. 193 Otherwise, the values of Information Elements of signed integer types 194 should be represented as optionally-prefixed base-10 (decimal) 195 strings. In ABNF: 197 sign = "+" / "-" 199 signed = [sign] 1*DIGIT 201 If the sign is omitted, it is assumed to be positive. Leading zeroes 202 are allowed, and do not signify base-8 (octal) encoding. 204 The encoded value must be in range for the corresponding abstract 205 data type or Information Element. Out of range values should be 206 interpreted as clipped to the implicit range for the Information 207 Element as defined by the abstract data type, or to the explicit 208 range of the Information Element if defined. Minimum and maximum 209 values for abstract data types are shown in Table 2 below. 211 +----------+----------------------+----------------------+ 212 | type | minimum | maximum | 213 +----------+----------------------+----------------------+ 214 | signed8 | -128 | +127 | 215 | signed16 | -32768 | +32767 | 216 | signed32 | -2147483648 | +2147483647 | 217 | signed64 | -9223372036854775808 | +9223372036854775807 | 218 +----------+----------------------+----------------------+ 220 Table 2: Ranges for signed abstract data types 222 4.4. float32 and float64 224 If the Enclosing Context defines a representation for floating point 225 numbers, that representation SHOULD be used. 227 Otherwise, the values of Information Elements of float32 or float64 228 types are represented as an optionally sign-prefixed, optionally 229 base-10 exponent-suffixed, floating point decimal number. In ABNF: 231 sign = "+" / "-" 233 exponent = 'e' 1*3DIGIT 235 right-decimal = '.' 0*DIGIT 236 mantissa = 1*DIGIT [right-decimal] 238 float = [sign] mantissa [exponent] 240 The expressed value is ( mantissa * 10 ^ exponent ). If the sign is 241 omitted, it is assumed to be positive. If the exponent is omitted, 242 it is assumed to be zero. Leading zeroes may appear in the mantissa 243 and/or the exponent. 245 Minimum and maximum values for abstract data types are shown in Table 246 3below. 248 +---------+----------------+----------------+ 249 | type | minimum abs(x) | maximum abs(x) | 250 +---------+----------------+----------------+ 251 | float32 | 5.877e-39 | 3.403e38 | 252 | float64 | 1.1125e-308 | +1.798e308 | 253 +---------+----------------+----------------+ 255 Table 3: Ranges for floating-point abstract data types 257 4.5. boolean 259 If the Enclosing Context defines a representation for boolean values, 260 that representation SHOULD be used. 262 Otherwise, a true boolean value should be represented with the 263 literal string 1, and a false boolean value with the literal string 264 0. In ABNF: 266 boolean-yes = "1" 268 boolean-no = "0" 270 boolean = boolean-yes / boolean-no 272 4.6. macAddress 274 MAC addresses are represented as IEEE 802 MAC-48 addresses, 275 hexadecimal bytes, most significant byte first, separated by colons. 276 In ABNF, using the hex-octet production from Section 4.1: 278 macaddress = hex-octet 5( ":" hex-octet ) 280 4.7. string 282 As Information Elements of the string type are simply UTF-8 encoded 283 strings, they are represented directly, subject to the escaping and 284 encoding rules of the Enclosing Context. If the Enclosing Context 285 cannot natively represent UTF-8 characters, the escaping facility 286 provided by the Enclosing Context must be used for non-representable 287 characters. Additionally, strings containing characters reserved in 288 the Enclosing Context (e.g. markup characters, quotes) must be 289 escaped or quoted according to the rules of the Enclosing Context. 291 4.8. dateTime* 293 Timestamp abstract data types are represented generally as in 294 [RFC3339], with two important differences. First, all IPFIX 295 timestamps are expressed in terms of UTC, so textual representations 296 of these Information Elements are explictly in UTC as well. Time 297 zone offsets are therefore not required or supported. Second, there 298 are four timestamp abstract data types, separated by the precision 299 which they can express. Fractional seconds must be omitted in 300 dateTimeSeconds, expressed in milliseconds in dateTimeMilliseconds, 301 and so on. 303 In ABNF, taken from [RFC3339] and modified: 305 date-fullyear = 4DIGIT 306 date-month = 2DIGIT ; 01-12 307 date-mday = 2DIGIT ; 01-28, 01-29, 01-30, 01-31 308 time-hour = 2DIGIT ; 00-23 309 time-minute = 2DIGIT ; 00-59 310 time-second = 2DIGIT ; 00-58, 00-59, 00-60 311 time-msec = "." 3*DIGIT 312 time-usec = "." 6*DIGIT 313 time-nsec = "." 9*DIGIT 314 partial-time = time-hour ":" time-minute ":" time-second 316 datetimeseconds = full-date "T" partial-time 317 datetimemilliseconds = full-date "T" partial-time "." time-msec 318 datetimemicroseconds = full-date "T" partial-time "." time-usec 319 datetimenanoseconds = full-date "T" partial-time "." time-nsec 321 4.9. ipv4Address 323 IP version 4 addresses are represented in dotted-quad format, most- 324 significant-byte first, as it would in a Uniform Resource Identifier 325 [RFC3986]; the ABNF for an IPv4 address is taken from [RFC3986] and 326 reproduced below: 328 dec-octet = DIGIT ; 0-9 329 / %x31-39 DIGIT ; 10-99 330 / "1" 2DIGIT ; 100-199 331 / "2" %x30-34 DIGIT ; 200-249 332 / "25" %x30-35 ; 250-255 334 ipv4address = dec-octet 3("." dec-octet) 336 4.10. ipv6Address 338 IP version 6 addresses are represented as in section 2.2 of 339 [RFC4291], as updated by section 4 of [RFC5952]. The ABNF for an 340 IPv6 address is taken from [RFC3986] and reproduced below: 342 ls32 = ( h16 ":" h16 ) / IPv4address 343 ; least-significant 32 bits of address 344 h16 = 1*4HEXDIG 345 ; 16 bits of address represented in hexadecimal 346 ; zeroes to suppressed as in RFC 5952 348 ipv6address = 6( h16 ":" ) ls32 349 / "::" 5( h16 ":" ) ls32 350 / [ h16 ] "::" 4( h16 ":" ) ls32 351 / [ *1( h16 ":" ) h16 ] "::" 3( h16 ":" ) ls32 352 / [ *2( h16 ":" ) h16 ] "::" 2( h16 ":" ) ls32 353 / [ *3( h16 ":" ) h16 ] "::" h16 ":" ls32 354 / [ *4( h16 ":" ) h16 ] "::" ls32 355 / [ *5( h16 ":" ) h16 ] "::" h16 356 / [ *6( h16 ":" ) h16 ] "::" 358 4.11. basicList, subTemplateList, and subTemplateMultiList 360 These abstract data types, defined for IPFIX Structured Data 361 [RFC6313], do not represent actual data types; they are instead 362 designed to provide a mechanism by which complex structure can be 363 represented in IPFIX below the template level. It is assumed that 364 protocols using textual Information Element representation will 365 provide their own structure. Therefore, Information Elements of 366 these Data Types MUST NOT be used in textual representations. 368 5. Security Considerations 370 This document does not present any additional security measures 371 beyond those presented by [RFC7011]. 373 6. IANA Considerations 375 This document has no considerations for IANA. 377 7. References 379 7.1. Normative References 381 [RFC3339] Klyne, G., Ed. and C. Newman, "Date and Time on the 382 Internet: Timestamps", RFC 3339, July 2002. 384 [RFC3986] Berners-Lee, T., Fielding, R., and L. Masinter, "Uniform 385 Resource Identifier (URI): Generic Syntax", STD 66, RFC 386 3986, January 2005. 388 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 389 Architecture", RFC 4291, February 2006. 391 [RFC5234] Crocker, D. and P. Overell, "Augmented BNF for Syntax 392 Specifications: ABNF", STD 68, RFC 5234, January 2008. 394 [RFC5952] Kawamura, S. and M. Kawashima, "A Recommendation for IPv6 395 Address Text Representation", RFC 5952, August 2010. 397 [RFC7011] Claise, B., Trammell, B., and P. Aitken, "Specification of 398 the IP Flow Information Export (IPFIX) Protocol for the 399 Exchange of Flow Information", STD 77, RFC 7011, September 400 2013. 402 [iana-ipfix-assignments] 403 Internet Assigned Numbers Authority, ., "IP Flow 404 Information Export Information Elements 405 (http://www.iana.org/assignments/ipfix/ipfix.xml)", 406 November 2012. 408 7.2. Informative References 410 [RFC6313] Claise, B., Dhandapani, G., Aitken, P., and S. Yates, 411 "Export of Structured Data in IP Flow Information Export 412 (IPFIX)", RFC 6313, July 2011. 414 [RFC7012] Claise, B. and B. Trammell, "Information Model for IP Flow 415 Information Export (IPFIX)", RFC 7012, September 2013. 417 [RFC7013] Trammell, B. and B. Claise, "Guidelines for Authors and 418 Reviewers of IP Flow Information Export (IPFIX) 419 Information Elements", BCP 184, RFC 7013, September 2013. 421 Appendix A. Example 423 In this section, we examine an IPFIX Template and a Data Record 424 defined by that Template, and show how that Data Record would be 425 represented in JSON according to the specification in this document. 426 Note that this is specifically NOT a recommendation for a particular 427 representation, merely an illustration of the encodings in this 428 document. 430 Figure 1 shows a Template in IEspec format as defined in section 9.1 431 of [RFC7013]. A Message containing this Template and a Data Record 432 is shown in Figure 2, and a corresponding JSON Object using the text 433 format defined in this document is shown in Figure 3. 435 flowStartMilliseconds(152)[8] 436 flowEndMilliseconds(153)[8] 437 octetDeltaCount(1)[4] 438 packetDeltaCount(2)[4] 439 sourceIPv6Address(27)[4]{key} 440 destinationIPv6Address(28)[4]{key} 441 sourceTransportPort(7)[2]{key} 442 destinationTransportPort(11)[2]{key} 443 protocolIdentifier(4)[1]{key} 444 tcpControlBits(6)[1] 445 flowEndReason(136)[1] 447 Figure 1: Sample flow template (IPFIX) 449 1 2 3 4 5 6 450 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 451 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 452 | 0x000a | length 135 | export time 1352140263 | msg 453 | sequence 0 | domain 1 | hdr 454 | SetID 2 | length 52 | tid 256 | fields 11 | tmpl 455 | IE 152 | length 8 | IE 153 | length 8 | set 456 | IE 1 | length 4 | IE 2 | length 4 | 457 | IE 27 | length 16 | IE 28 | length 16 | 458 | IE 7 | length 2 | IE 11 | length 2 | 459 | IE 4 | length 1 | IE 6 | length 1 | 460 | IE 136 | length 1 | SetID 256 | length 83 | data 461 | start time 1352140261135 | set 462 | end time 1352140262880 | 463 | octets 195383 | packets 88 | 464 | sip6 | 465 | 2001:0db8:000c:1337:0000:0000:0000:0002 | 466 | dip6 | 467 | 2001:0db8:000c:1337:0000:0000:0000:0003 | 468 | sp 80 | dp 32991 | prt 6 | tcp 19| fe 3 | 469 +-------------------------------------------------------+ 471 Figure 2: IPFIX message containing sample flow 473 { 474 "flowStartMilliseconds": "2012-11-05T18:31:01.135", 475 "flowEndMilliseconds": "2012-11-05T18:31:02.880", 476 "octetDeltaCount": 195383, 477 "packetDeltaCount": 88, 478 "sourceIPv6Address": "2001:db8:c:1337::2", 479 "destinationIPv6Address": "2001:db8:c:1337::3", 480 "sourceTransportPort": 80, 481 "destinationTransportPort": 32991, 482 "protocolIdentifier": "tcp", 483 "tcpControlBits": 19, 484 "flowEndReason": 3 485 } 487 Figure 3: JSON object containing sample flow 489 Author's Address 491 Brian Trammell 492 Swiss Federal Institute of Technology Zurich 493 Gloriastrasse 35 494 8092 Zurich 495 Switzerland 497 Phone: +41 44 632 70 13 498 Email: trammell@tik.ee.ethz.ch