idnits 2.17.1 draft-ietf-cbor-network-addresses-11.txt: -(5): Line appears to be too long, but this could be caused by non-ascii characters in UTF-8 encoding 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: ---------------------------------------------------------------------------- == There are 5 instances of lines with non-ascii characters in the document. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year -- The document date (8 October 2021) is 930 days in the past. Is this intentional? Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Obsolete informational reference (is this intentional?): RFC 7042 (Obsoleted by RFC 9542) Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 2 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 CBOR Working Group M. Richardson 3 Internet-Draft Sandelman Software Works 4 Intended status: Standards Track C. Bormann 5 Expires: 11 April 2022 Universität Bremen TZI 6 8 October 2021 8 CBOR tags for IPv4 and IPv6 addresses and prefixes 9 draft-ietf-cbor-network-addresses-11 11 Abstract 13 This specification defines two CBOR Tags for use with IPv6 and IPv4 14 addresses and prefixes. 16 // RFC-EDITOR-please-remove: This work is tracked at 17 // https://github.com/cbor-wg/cbor-network-address 19 Status of This Memo 21 This Internet-Draft is submitted in full conformance with the 22 provisions of BCP 78 and BCP 79. 24 Internet-Drafts are working documents of the Internet Engineering 25 Task Force (IETF). Note that other groups may also distribute 26 working documents as Internet-Drafts. The list of current Internet- 27 Drafts is at https://datatracker.ietf.org/drafts/current/. 29 Internet-Drafts are draft documents valid for a maximum of six months 30 and may be updated, replaced, or obsoleted by other documents at any 31 time. It is inappropriate to use Internet-Drafts as reference 32 material or to cite them other than as "work in progress." 34 This Internet-Draft will expire on 11 April 2022. 36 Copyright Notice 38 Copyright (c) 2021 IETF Trust and the persons identified as the 39 document authors. All rights reserved. 41 This document is subject to BCP 78 and the IETF Trust's Legal 42 Provisions Relating to IETF Documents (https://trustee.ietf.org/ 43 license-info) in effect on the date of publication of this document. 44 Please review these documents carefully, as they describe your rights 45 and restrictions with respect to this document. Code Components 46 extracted from this document must include Simplified BSD License text 47 as described in Section 4.e of the Trust Legal Provisions and are 48 provided without warranty as described in the Simplified BSD License. 50 Table of Contents 52 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . 2 53 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 54 3. Protocol . . . . . . . . . . . . . . . . . . . . . . . . . . 3 55 3.1. Three Forms . . . . . . . . . . . . . . . . . . . . . . . 3 56 3.1.1. Addresses . . . . . . . . . . . . . . . . . . . . . . 3 57 3.1.2. Prefixes . . . . . . . . . . . . . . . . . . . . . . 3 58 3.1.3. Interface Definition . . . . . . . . . . . . . . . . 4 59 3.2. IPv6 . . . . . . . . . . . . . . . . . . . . . . . . . . 4 60 3.3. IPv4 . . . . . . . . . . . . . . . . . . . . . . . . . . 5 61 4. Tag validity . . . . . . . . . . . . . . . . . . . . . . . . 6 62 4.1. Deterministic Encoding . . . . . . . . . . . . . . . . . 6 63 4.2. Encoder Considerations for Prefixes . . . . . . . . . . . 6 64 4.3. Decoder Considerations for Prefixes . . . . . . . . . . . 7 65 4.3.1. Example implementation . . . . . . . . . . . . . . . 7 66 5. CDDL . . . . . . . . . . . . . . . . . . . . . . . . . . . . 8 67 6. Security Considerations . . . . . . . . . . . . . . . . . . . 9 68 7. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 69 7.1. Tag 54 - IPv6 . . . . . . . . . . . . . . . . . . . . . . 10 70 7.2. Tag 52 - IPv4 . . . . . . . . . . . . . . . . . . . . . . 10 71 7.3. Tags 260 and 261 . . . . . . . . . . . . . . . . . . . . 10 72 8. References . . . . . . . . . . . . . . . . . . . . . . . . . 10 73 8.1. Normative References . . . . . . . . . . . . . . . . . . 10 74 8.2. Informative References . . . . . . . . . . . . . . . . . 11 75 Appendix A. Changelog . . . . . . . . . . . . . . . . . . . . . 11 76 Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . . 12 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 12 79 1. Introduction 81 [RFC8949] defines a number of CBOR Tags for common items. Tags 260 82 and 261 were later defined in drafts listed with IANA 83 [IANA.cbor-tags]. These tags were intended to cover addresses (260) 84 and prefixes (261). Tag 260 distinguishes between IPv6, IPv4, and 85 MAC [RFC7042] addresses only through the length of the byte string 86 making it impossible, for example, to drop trailing zeros in the 87 encoding of IP addresses. Tag 261 was not documented well enough for 88 use. 90 This specification defines tags 54 and 52 achieving an explicit 91 indication of IPv6 or IPv4 by the tag number. These new tags are 92 intended to be used in preference to tags 260 and 261. They provide 93 formats for IPv6 and IPv4 addresses, prefixes, and addresses with 94 prefixes, achieving an explicit indication of IPv6 or IPv4. The 95 prefix format omits trailing zeroes in the address part. (Due to the 96 complexity of testing, the value of omitting trailing zeros for the 97 pure address format was considered non-essential and support for that 98 is not provided in this specification.) This specification does not 99 deal with 6- or 8-byte Ethernet addresses. 101 2. Terminology 103 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 104 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 105 "OPTIONAL" in this document are to be interpreted as described in 106 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 107 capitals, as shown here. 109 3. Protocol 111 3.1. Three Forms 113 3.1.1. Addresses 115 These tags can be applied to byte strings to represent a single 116 address. 118 This form is called the Address Format. 120 3.1.2. Prefixes 122 When applied to an array that starts with an unsigned integer, they 123 represent a CIDR-style prefix of that length. 125 When the Address Format (i.e., without prefix) appears in a context 126 where a prefix is expected, then it is to be assumed that all bits 127 are relevant. That is, for IPv4, a /32 is implied, and for IPv6, a 128 /128 is implied. 130 This form is called the Prefix Format. 132 3.1.3. Interface Definition 134 When applied to an array that starts with a byte string, which stands 135 for an IP address, followed by an unsigned integer giving the bit 136 length of a prefix built out of the first length bits of the address, 137 they represent information that is commonly used to specify both the 138 network prefix and the IP address of an interface. 140 The length of the byte string is always 16 bytes (for IPv6) and 4 141 bytes (for IPv4). 143 This form is called the Interface Format. 145 Interface Format definitions support an optional third element to the 146 array, which is to be used as the IPv6 Link-Local zone identifier 147 from Section 4 of [RFC3542] and Section 6 of [RFC4007]; for symmetry 148 this is also provided for IPv4 as in [RFC4001] and [RFC6991]. The 149 zone identifier may be an integer, in which case it is to be 150 interpreted as the interface index. It may be a text string, in 151 which case it is to be interpreted as an interface name. 153 As explained in [RFC4007] the zone identifiers are strictly local to 154 the node. They are useful for communications within a node about 155 connected addresses (for instance, where a link-local peer is 156 discovered by one daemon, and another daemon needs to be informed). 157 They may also have utility in some management protocols. 159 In the cases where the Interface Format is being used to represent 160 only an address with a zone identifier, and no interface prefix 161 information, then the prefix length may be replaced with the CBOR 162 "null" (0xF6). 164 3.2. IPv6 166 IANA has allocated tag 54 for IPv6 uses. (This is the ASCII code for 167 '6'.) 169 An IPv6 address is to be encoded as a sixteen-byte byte string 170 (Section 3.1 of [RFC8949], major type 2), enclosed in Tag number 54. 172 For example: 174 54(h'20010db81234deedbeefcafefacefeed') 176 An IPv6 prefix, such as 2001:db8:1234::/48 is to be encoded as a two 177 element array, with the length of the prefix first. See Section 4 178 for the detailed construction of the second element. 180 For example: 182 54([48, h'20010db81234']) 184 An IPv6 address combined with a prefix length, such as being used for 185 configuring an interface, is to be encoded as a two element array, 186 with the (full-length) IPv6 address first and the length of the 187 associated network the prefix next; a third element can be added for 188 the zone identifier. 190 For example: 192 54([h'20010db81234deedbeefcafefacefeed', 56]) 194 The address-with-prefix form can be reliably distinguished from the 195 prefix form only in the sequence of the array elements. 197 Some example of a link-local IPv6 address with a 64-bit prefix: 199 54([h'fe8000000000020202fffffffe030303', 64, 'eth0']) 201 with a numeric zone identifier: 203 54([h'fe8000000000020202fffffffe030303', 64, 42]) 205 An IPv6 link-local address without a prefix length: 207 54([h'fe8000000000020202fffffffe030303', null, 42]) 209 Zone identifiers may be used with any kind of IP address, not just 210 Link-Local addresses. In particular, they are valid for multicast 211 addresses, and there may still be some significance for Globally 212 Unique Addresses (GUA). 214 3.3. IPv4 216 IANA has allocated tag 52 for IPv4 uses. (This is the ASCII code for 217 '4'.) 219 An IPv4 address is to be encoded as a four-byte byte string 220 (Section 3.1 of [RFC8949], major type 2), enclosed in Tag number 52. 222 For example: 224 52(h'c0000201') 225 An IPv4 prefix, such as 192.0.2.0/24 is to be encoded as a two 226 element array, with the length of the prefix first. See Section 4 227 for the detailed construction of the second element. 229 For example: 231 52([24, h'c00002']) 233 An IPv4 address combined with a prefix length, such as being used for 234 configuring an interface, is to be encoded as a two element array, 235 with the (full-length) IPv4 address first and the length of the 236 associated network the prefix next; a third element can be added for 237 the zone identifier. 239 For example, 192.0.2.1/24 is to be encoded as a two element array, 240 with the length of the prefix (implied 192.0.2.0/24) last. 242 52([h'c0000201', 24]) 244 The address-with-prefix form can be reliably distinguished from the 245 prefix form only in the sequence of the array elements. 247 4. Tag validity 249 This section discusses when a tag 54 or tag 52 is valid 250 (Section 5.3.2 of [RFC8949]). As with all CBOR tags, validity 251 checking can be handled in a generic CBOR library or in the 252 application. A generic CBOR library needs to document whether and 253 how it handles validity checking. 255 The rule ip-address-or-prefix in Figure 1 shows how to check the 256 overall structure of these tags and their content, the ranges of 257 integer values, and the lengths of byte strings. An instance of tag 258 52 or 54 is valid if it matches that rule and, for ipv6-prefix and 259 ipv4-prefix, the considerations of Sections 4.2 and 4.3. 261 4.1. Deterministic Encoding 263 The tag validity rules, combined with the rules in Section 4.2.1 of 264 [RFC8949], lead to deterministic encoding for tags 54 and 52 and 265 require no further Additional Deterministic Encoding Considerations 266 as per Section 4.2.2 of [RFC8949]. 268 4.2. Encoder Considerations for Prefixes 270 For the byte strings used as the second element in the array 271 representing a prefix: 273 (1) An encoder MUST set any unused bytes, and any unused bits in the 274 final byte, if any, to zero. Unused bytes/bits are bytes/bits that 275 are not covered by the prefix length given. So for example, 276 2001:db8:1230::/44 MUST be encoded as: 278 54([44, h'20010db81230']) 280 even though variations like: 282 54([44, h'20010db81233']) 283 54([44, h'20010db8123f']) 284 54([44, h'20010db8123012']) 286 start with the same 44 bits, but are not valid. 288 (Analogous examples can be constructed for IPv4 prefixes.) 290 (2) An encoder MUST then omit any right-aligned (trailing) sequence 291 of bytes that are all zero. 293 There is no relationship between the number of bytes omitted and the 294 prefix length. For instance, the prefix 2001:db8::/64 is encoded as: 296 54([64, h'20010db8']) 298 4.3. Decoder Considerations for Prefixes 300 A decoder MUST check that all unused bits encoded in the byte string 301 ipv6-prefix-bytes/ipv4-prefix-bytes, i.e., the bits to the right of 302 the prefix length, are zero. 304 A decoder MUST also check that the byte string does not end in a zero 305 byte. 307 Since encoders are required to remove zero-valued trailing bytes, a 308 decoder MUST handle the case where a prefix length specifies that 309 more bits are relevant than are actually present in the byte-string. 311 As an example, ::/128 is encoded as 313 54([128, h'']) 315 4.3.1. Example implementation 317 A recommendation for prefix decoder implementations is to first 318 create an array of 16 (or 4) zero bytes. 320 Then taking whichever is smaller between (a) the length of the 321 included byte-string, and (b) the number of bytes covered by the 322 prefix-length rounded up to the next multiple of 8: fail if that 323 number is greater than 16 (or 4), and then copy that many bytes from 324 the byte-string into the byte array. 326 Finally, looking at the number of unused bits in the last byte (if 327 any) of the range covered by the prefix length, check that any unused 328 bits in the byte string are zero: 330 unused_bits = (8 - (prefix_length_in_bits % 8)) % 8; 331 if (length_in_bytes > 0 && 332 (address_bytes[length_in_bytes - 1] & ~(0xFF << unused_bits)) 333 != 0) 334 fail(); 336 5. CDDL 338 For use with CDDL [RFC8610], the typenames defined in Figure 1 are 339 recommended: 341 ip-address-or-prefix = ipv6-address-or-prefix / 342 ipv4-address-or-prefix 344 ipv6-address-or-prefix = #6.54(ipv6-address / 345 ipv6-address-with-prefix / 346 ipv6-prefix) 347 ipv4-address-or-prefix = #6.52(ipv4-address / 348 ipv4-address-with-prefix / 349 ipv4-prefix) 351 ipv6-address = bytes .size 16 352 ipv4-address = bytes .size 4 354 ipv6-address-with-prefix = [ipv6-address, 355 ipv6-prefix-length / null, 356 ?ip-zone-identifier] 357 ipv4-address-with-prefix = [ipv4-address, 358 ipv4-prefix-length / null, 359 ?ip-zone-identifier] 361 ipv6-prefix-length = 0..128 362 ipv4-prefix-length = 0..32 364 ipv6-prefix = [ipv6-prefix-length, ipv6-prefix-bytes] 365 ipv4-prefix = [ipv4-prefix-length, ipv4-prefix-bytes] 367 ipv6-prefix-bytes = bytes .size (uint .le 16) 368 ipv4-prefix-bytes = bytes .size (uint .le 4) 370 ip-zone-identifier = uint / text 372 Figure 1: CDDL types for tags 54 and 52 374 6. Security Considerations 376 This document provides an CBOR encoding for IPv4 and IPv6 address 377 information. Any applications using these encodings will need to 378 consider the security implications of these data in their specific 379 context. For example, identifying which byte sequences in a protocol 380 are addresses may allow an attacker or eavesdropper to better 381 understand what parts of a packet to attack. 383 Applications need to check the validity (Section 4) of a tag before 384 acting on any of its contents. If the validity checking is not done 385 in the generic CBOR decoder, it needs to be done in the application; 386 in any case it needs to be done before the tag is transformed into a 387 platform-specific representation that could conceal validity errors. 389 The right-hand bits of the prefix, after the prefix-length, are set 390 to zero by this protocol. (Otherwise, a malicious party could use 391 them to transmit covert data in a way that would not affect the 392 primary use of this encoding. Such abuse is detected by tag validity 393 checking, and can also be detected by examination of the raw protocol 394 bytes.) 396 7. IANA Considerations 398 IANA has allocated two tags from the Specification Required area of 399 the Concise Binary Object Representation (CBOR) Tags 400 [IANA.cbor-tags]: 402 7.1. Tag 54 - IPv6 404 Data Item: byte string or array 405 Semantics: IPv6, [prefixlen,IPv6], [IPv6,prefixpart] 407 7.2. Tag 52 - IPv4 409 Data Item: byte string or array 410 Semantics: IPv4, [prefixlen,IPv4], [IPv4,prefixpart] 412 7.3. Tags 260 and 261 414 IANA is requested to add the note "DEPRECATED in favor of 52 and 54 415 for IP addresses" to registrations 260 and 261 417 8. References 419 8.1. Normative References 421 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 422 Requirement Levels", BCP 14, RFC 2119, 423 DOI 10.17487/RFC2119, March 1997, 424 . 426 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 427 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 428 May 2017, . 430 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 431 Definition Language (CDDL): A Notational Convention to 432 Express Concise Binary Object Representation (CBOR) and 433 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 434 June 2019, . 436 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 437 Representation (CBOR)", STD 94, RFC 8949, 438 DOI 10.17487/RFC8949, December 2020, 439 . 441 8.2. Informative References 443 [IANA.cbor-tags] 444 IANA, "Concise Binary Object Representation (CBOR) Tags", 445 . 447 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 448 "Advanced Sockets Application Program Interface (API) for 449 IPv6", RFC 3542, DOI 10.17487/RFC3542, May 2003, 450 . 452 [RFC4001] Daniele, M., Haberman, B., Routhier, S., and J. 453 Schoenwaelder, "Textual Conventions for Internet Network 454 Addresses", RFC 4001, DOI 10.17487/RFC4001, February 2005, 455 . 457 [RFC4007] Deering, S., Haberman, B., Jinmei, T., Nordmark, E., and 458 B. Zill, "IPv6 Scoped Address Architecture", RFC 4007, 459 DOI 10.17487/RFC4007, March 2005, 460 . 462 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 463 RFC 6991, DOI 10.17487/RFC6991, July 2013, 464 . 466 [RFC7042] Eastlake 3rd, D. and J. Abley, "IANA Considerations and 467 IETF Protocol and Documentation Usage for IEEE 802 468 Parameters", BCP 141, RFC 7042, DOI 10.17487/RFC7042, 469 October 2013, . 471 Appendix A. Changelog 473 This section is to be removed before publishing as an RFC. 475 * 03 477 * 02 479 * 01 added security considerations about covert channel 481 Acknowledgements 483 Roman Danyliw, Donald Eastlake, Ben Kaduk, Barry Leiba, and Éric 484 Vyncke reviewed the document and provided suggested text. Jürgen 485 Schönwälder helped finding the history of IPv4 zone identifiers. 487 Authors' Addresses 489 Michael Richardson 490 Sandelman Software Works 492 Email: mcr+ietf@sandelman.ca 494 Carsten Bormann 495 Universität Bremen TZI 496 Germany 498 Email: cabo@tzi.org