idnits 2.17.1 draft-ietf-cbor-network-addresses-13.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 (22 October 2021) is 888 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) No issues found here. Summary: 0 errors (**), 0 flaws (~~), 2 warnings (==), 1 comment (--). 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: 25 April 2022 Universität Bremen TZI 6 22 October 2021 8 CBOR tags for IPv4 and IPv6 addresses and prefixes 9 draft-ietf-cbor-network-addresses-13 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 25 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 . . . . . . . . . . . . . . . . . . . . . . . . 11 77 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . 11 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 MAC addresses (Section 2 of [RFC7042]) such as they are 100 used for Ethernet. 102 2. Terminology 104 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 105 "SHOULD", "SHOULD NOT", "RECOMMENDED", "NOT RECOMMENDED", "MAY", and 106 "OPTIONAL" in this document are to be interpreted as described in 107 BCP 14 [RFC2119] [RFC8174] when, and only when, they appear in all 108 capitals, as shown here. 110 3. Protocol 112 3.1. Three Forms 114 3.1.1. Addresses 116 These tags can be applied to byte strings to represent a single 117 address. 119 This form is called the Address Format. 121 3.1.2. Prefixes 123 When applied to an array that starts with an unsigned integer, they 124 represent a CIDR-style prefix of that length. 126 When the Address Format (i.e., without prefix) appears in a context 127 where a prefix is expected, then it is to be assumed that all bits 128 are relevant. That is, for IPv4, a /32 is implied, and for IPv6, a 129 /128 is implied. 131 This form is called the Prefix Format. 133 3.1.3. Interface Definition 135 When applied to an array that starts with a byte string, which stands 136 for an IP address, followed by an unsigned integer giving the bit 137 length of a prefix built out of the first length bits of the address, 138 they represent information that is commonly used to specify both the 139 network prefix and the IP address of an interface. 141 The length of the byte string is always 16 bytes (for IPv6) and 4 142 bytes (for IPv4). 144 This form is called the Interface Format. 146 Interface Format definitions support an optional third element to the 147 array, which is to be used as the IPv6 Link-Local zone identifier 148 from Section 6 of [RFC4007]; for symmetry this is also provided for 149 IPv4 as in [RFC4001] and [RFC6991]. The zone identifier may be an 150 integer, in which case it is to be interpreted as the interface 151 index. It may be a text string, in which case it is to be 152 interpreted as an interface name. 154 As explained in [RFC4007] the zone identifiers are strictly local to 155 the node. They are useful for communications within a node about 156 connected addresses (for instance, where a link-local peer is 157 discovered by one daemon, and another daemon needs to be informed). 158 They may also have utility in some management protocols. 160 In the cases where the Interface Format is being used to represent 161 only an address with a zone identifier, and no interface prefix 162 information, then the prefix length may be replaced with the CBOR 163 "null" (0xF6). 165 3.2. IPv6 167 IANA has allocated tag 54 for IPv6 uses. (This is the ASCII code for 168 '6'.) 170 An IPv6 address is to be encoded as a sixteen-byte byte string 171 (Section 3.1 of [RFC8949], major type 2), enclosed in Tag number 54. 173 For example: 175 54(h'20010db81234deedbeefcafefacefeed') 177 An IPv6 prefix, such as 2001:db8:1234::/48 is to be encoded as a two 178 element array, with the length of the prefix first. See Section 4 179 for the detailed construction of the second element. 181 For example: 183 54([48, h'20010db81234']) 185 An IPv6 address combined with a prefix length, such as being used for 186 configuring an interface, is to be encoded as a two element array, 187 with the (full-length) IPv6 address first and the length of the 188 associated network the prefix next; a third element can be added for 189 the zone identifier. 191 For example: 193 54([h'20010db81234deedbeefcafefacefeed', 56]) 195 The address-with-prefix form can be reliably distinguished from the 196 prefix form only in the sequence of the array elements. 198 Some example of a link-local IPv6 address with a 64-bit prefix: 200 54([h'fe8000000000020202fffffffe030303', 64, 'eth0']) 202 with a numeric zone identifier: 204 54([h'fe8000000000020202fffffffe030303', 64, 42]) 206 An IPv6 link-local address without a prefix length: 208 54([h'fe8000000000020202fffffffe030303', null, 42]) 210 Zone identifiers may be used with any kind of IP address, not just 211 Link-Local addresses. In particular, they are valid for multicast 212 addresses, and there may still be some significance for Globally 213 Unique Addresses (GUA). 215 3.3. IPv4 217 IANA has allocated tag 52 for IPv4 uses. (This is the ASCII code for 218 '4'.) 220 An IPv4 address is to be encoded as a four-byte byte string 221 (Section 3.1 of [RFC8949], major type 2), enclosed in Tag number 52. 223 For example: 225 52(h'c0000201') 226 An IPv4 prefix, such as 192.0.2.0/24 is to be encoded as a two 227 element array, with the length of the prefix first. See Section 4 228 for the detailed construction of the second element. 230 For example: 232 52([24, h'c00002']) 234 An IPv4 address combined with a prefix length, such as being used for 235 configuring an interface, is to be encoded as a two element array, 236 with the (full-length) IPv4 address first and the length of the 237 associated network the prefix next; a third element can be added for 238 the zone identifier. 240 For example, 192.0.2.1/24 is to be encoded as a two element array, 241 with the length of the prefix (implied 192.0.2.0/24) last. 243 52([h'c0000201', 24]) 245 The address-with-prefix form can be reliably distinguished from the 246 prefix form only in the sequence of the array elements. 248 4. Tag validity 250 This section discusses when a tag 54 or tag 52 is valid 251 (Section 5.3.2 of [RFC8949]). As with all CBOR tags, validity 252 checking can be handled in a generic CBOR library or in the 253 application. A generic CBOR library needs to document whether and 254 how it handles validity checking. 256 The rule ip-address-or-prefix in Figure 1 shows how to check the 257 overall structure of these tags and their content, the ranges of 258 integer values, and the lengths of byte strings. An instance of tag 259 52 or 54 is valid if it matches that rule and, for ipv6-prefix and 260 ipv4-prefix, the considerations of Sections 4.2 and 4.3. 262 4.1. Deterministic Encoding 264 The tag validity rules, combined with the rules in Section 4.2.1 of 265 [RFC8949], lead to deterministic encoding for tags 54 and 52 and 266 require no further Additional Deterministic Encoding Considerations 267 as per Section 4.2.2 of [RFC8949]. 269 4.2. Encoder Considerations for Prefixes 271 For the byte strings used as the second element in the array 272 representing a prefix: 274 (1) An encoder MUST set any unused bytes, and any unused bits in the 275 final byte, if any, to zero. Unused bytes/bits are bytes/bits that 276 are not covered by the prefix length given. So for example, 277 2001:db8:1230::/44 MUST be encoded as: 279 54([44, h'20010db81230']) 281 even though variations like: 283 54([44, h'20010db81233']) 284 54([44, h'20010db8123f']) 285 54([44, h'20010db8123012']) 287 start with the same 44 bits, but are not valid. 289 (Analogous examples can be constructed for IPv4 prefixes.) 291 (2) An encoder MUST then omit any right-aligned (trailing) sequence 292 of bytes that are all zero. 294 There is no relationship between the number of bytes omitted and the 295 prefix length. For instance, the prefix 2001:db8::/64 is encoded as: 297 54([64, h'20010db8']) 299 4.3. Decoder Considerations for Prefixes 301 A decoder MUST check that all unused bits encoded in the byte string 302 ipv6-prefix-bytes/ipv4-prefix-bytes, i.e., the bits to the right of 303 the prefix length, are zero. 305 A decoder MUST also check that the byte string does not end in a zero 306 byte. 308 Since encoders are required to remove zero-valued trailing bytes, a 309 decoder MUST handle the case where a prefix length specifies that 310 more bits are relevant than are actually present in the byte-string. 312 As an example, ::/128 is encoded as 314 54([128, h'']) 316 4.3.1. Example implementation 318 A recommendation for prefix decoder implementations is to first 319 create an array of 16 (or 4) zero bytes. 321 Then taking whichever is smaller between (a) the length of the 322 included byte-string, and (b) the number of bytes covered by the 323 prefix-length rounded up to the next multiple of 8: fail if that 324 number is greater than 16 (or 4), and then copy that many bytes from 325 the byte-string into the byte array. 327 Finally, looking at the number of unused bits in the last byte (if 328 any) of the range covered by the prefix length, check that any unused 329 bits in the byte string are zero: 331 unused_bits = (8 - (prefix_length_in_bits % 8)) % 8; 332 if (length_in_bytes > 0 && 333 (address_bytes[length_in_bytes - 1] & ~(0xFF << unused_bits)) 334 != 0) 335 fail(); 337 5. CDDL 339 For use with CDDL [RFC8610], the typenames defined in Figure 1 are 340 recommended: 342 ip-address-or-prefix = ipv6-address-or-prefix / 343 ipv4-address-or-prefix 345 ipv6-address-or-prefix = #6.54(ipv6-address / 346 ipv6-address-with-prefix / 347 ipv6-prefix) 348 ipv4-address-or-prefix = #6.52(ipv4-address / 349 ipv4-address-with-prefix / 350 ipv4-prefix) 352 ipv6-address = bytes .size 16 353 ipv4-address = bytes .size 4 355 ipv6-address-with-prefix = [ipv6-address, 356 ipv6-prefix-length / null, 357 ?ip-zone-identifier] 358 ipv4-address-with-prefix = [ipv4-address, 359 ipv4-prefix-length / null, 360 ?ip-zone-identifier] 362 ipv6-prefix-length = 0..128 363 ipv4-prefix-length = 0..32 365 ipv6-prefix = [ipv6-prefix-length, ipv6-prefix-bytes] 366 ipv4-prefix = [ipv4-prefix-length, ipv4-prefix-bytes] 368 ipv6-prefix-bytes = bytes .size (uint .le 16) 369 ipv4-prefix-bytes = bytes .size (uint .le 4) 371 ip-zone-identifier = uint / text 373 Figure 1: CDDL types for tags 54 and 52 375 6. Security Considerations 377 This document provides an CBOR encoding for IPv4 and IPv6 address 378 information. Any applications using these encodings will need to 379 consider the security implications of these data in their specific 380 context. For example, identifying which byte sequences in a protocol 381 are addresses may allow an attacker or eavesdropper to better 382 understand what parts of a packet to attack. 384 Applications need to check the validity (Section 4) of a tag before 385 acting on any of its contents. If the validity checking is not done 386 in the generic CBOR decoder, it needs to be done in the application; 387 in any case it needs to be done before the tag is transformed into a 388 platform-specific representation that could conceal validity errors. 390 The right-hand bits of the prefix, after the prefix-length, are set 391 to zero by this protocol. (Otherwise, a malicious party could use 392 them to transmit covert data in a way that would not affect the 393 primary use of this encoding. Such abuse is detected by tag validity 394 checking, and can also be detected by examination of the raw protocol 395 bytes.) 397 7. IANA Considerations 399 IANA has allocated two tags from the Specification Required area of 400 the Concise Binary Object Representation (CBOR) Tags 401 [IANA.cbor-tags]: 403 7.1. Tag 54 - IPv6 405 Data Item: byte string or array 406 Semantics: IPv6, [prefixlen,IPv6], [IPv6,prefixpart] 408 7.2. Tag 52 - IPv4 410 Data Item: byte string or array 411 Semantics: IPv4, [prefixlen,IPv4], [IPv4,prefixpart] 413 7.3. Tags 260 and 261 415 IANA is requested to add the note "DEPRECATED in favor of 52 and 54 416 for IP addresses" to registrations 260 and 261 418 8. References 420 8.1. Normative References 422 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 423 Requirement Levels", BCP 14, RFC 2119, 424 DOI 10.17487/RFC2119, March 1997, 425 . 427 [RFC8174] Leiba, B., "Ambiguity of Uppercase vs Lowercase in RFC 428 2119 Key Words", BCP 14, RFC 8174, DOI 10.17487/RFC8174, 429 May 2017, . 431 [RFC8610] Birkholz, H., Vigano, C., and C. Bormann, "Concise Data 432 Definition Language (CDDL): A Notational Convention to 433 Express Concise Binary Object Representation (CBOR) and 434 JSON Data Structures", RFC 8610, DOI 10.17487/RFC8610, 435 June 2019, . 437 [RFC8949] Bormann, C. and P. Hoffman, "Concise Binary Object 438 Representation (CBOR)", STD 94, RFC 8949, 439 DOI 10.17487/RFC8949, December 2020, 440 . 442 8.2. Informative References 444 [IANA.cbor-tags] 445 IANA, "Concise Binary Object Representation (CBOR) Tags", 446 . 448 [RFC4001] Daniele, M., Haberman, B., Routhier, S., and J. 449 Schoenwaelder, "Textual Conventions for Internet Network 450 Addresses", RFC 4001, DOI 10.17487/RFC4001, February 2005, 451 . 453 [RFC4007] Deering, S., Haberman, B., Jinmei, T., Nordmark, E., and 454 B. Zill, "IPv6 Scoped Address Architecture", RFC 4007, 455 DOI 10.17487/RFC4007, March 2005, 456 . 458 [RFC6991] Schoenwaelder, J., Ed., "Common YANG Data Types", 459 RFC 6991, DOI 10.17487/RFC6991, July 2013, 460 . 462 [RFC7042] Eastlake 3rd, D. and J. Abley, "IANA Considerations and 463 IETF Protocol and Documentation Usage for IEEE 802 464 Parameters", BCP 141, RFC 7042, DOI 10.17487/RFC7042, 465 October 2013, . 467 Appendix A. Changelog 469 This section is to be removed before publishing as an RFC. 471 * 03 473 * 02 475 * 01 added security considerations about covert channel 477 Acknowledgements 479 Roman Danyliw, Donald Eastlake, Ben Kaduk, Barry Leiba, and Éric 480 Vyncke reviewed the document and provided suggested text. Jürgen 481 Schönwälder helped finding the history of IPv4 zone identifiers. 483 Authors' Addresses 484 Michael Richardson 485 Sandelman Software Works 487 Email: mcr+ietf@sandelman.ca 489 Carsten Bormann 490 Universität Bremen TZI 491 Germany 493 Email: cabo@tzi.org