idnits 2.17.1 draft-stevens-advanced-api-03.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** Cannot find the required boilerplate sections (Copyright, IPR, etc.) in this document. Expected boilerplate is as follows today (2024-04-25) according to https://trustee.ietf.org/license-info : IETF Trust Legal Provisions of 28-dec-2009, Section 6.a: This Internet-Draft is submitted in full conformance with the provisions of BCP 78 and BCP 79. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 2: Copyright (c) 2024 IETF Trust and the persons identified as the document authors. All rights reserved. IETF Trust Legal Provisions of 28-dec-2009, Section 6.b(i), paragraph 3: This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (https://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents carefully, as they describe your rights and restrictions with respect to this document. Code Components extracted from this document must include Simplified BSD License text as described in Section 4.e of the Trust Legal Provisions and are provided without warranty as described in the Simplified BSD License. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** Missing expiration date. The document expiration date should appear on the first and last page. ** The document seems to lack a 1id_guidelines paragraph about Internet-Drafts being working documents. ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity. ** The document seems to lack a 1id_guidelines paragraph about the list of current Internet-Drafts. ** The document seems to lack a 1id_guidelines paragraph about the list of Shadow Directories. == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) ** The document seems to lack separate sections for Informative/Normative References. All references will be assumed normative when checking for downward references. ** There are 139 instances of too long lines in the document, the longest one being 11 characters in excess of 72. ** The abstract seems to contain references ([RFC-2133]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. == There are 5 instances of lines with non-RFC2606-compliant FQDNs in the document. ** 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 566: '... via raw sockets MUST be in network by...' Miscellaneous warnings: ---------------------------------------------------------------------------- == Line 250 has weird spacing: '...ip6_vfc ip6_...' == Line 251 has weird spacing: '...p6_flow ip6_c...' == Line 252 has weird spacing: '...p6_plen ip6_c...' == Line 253 has weird spacing: '...ip6_nxt ip6_...' == Line 254 has weird spacing: '...p6_hlim ip6_c...' == (40 more instances...) -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (June 27, 1997) is 9799 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) -- Looks like a reference, but probably isn't: '3' on line 2345 -- Looks like a reference, but probably isn't: '1' on line 2329 -- Looks like a reference, but probably isn't: '2' on line 2337 -- Looks like a reference, but probably isn't: '4' on line 346 -- Looks like a reference, but probably isn't: '0' on line 467 -- Looks like a reference, but probably isn't: '8' on line 728 ** Obsolete normative reference: RFC 1883 (Obsoleted by RFC 2460) ** Obsolete normative reference: RFC 2133 (Obsoleted by RFC 2553) ** Obsolete normative reference: RFC 1981 (Obsoleted by RFC 8201) ** Obsolete normative reference: RFC 1970 (Obsoleted by RFC 2461) Summary: 15 errors (**), 0 flaws (~~), 8 warnings (==), 9 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 INTERNET-DRAFT W. Richard Stevens (Consultant) 3 Expires: December 27, 1997 Matt Thomas (AltaVista) 4 June 27, 1997 6 Advanced Sockets API for IPv6 7 9 Abstract 11 Specifications are in progress for changes to the sockets API to 12 support IP version 6 [RFC-2133]. These changes are for TCP and UDP- 13 based applications and will support most end-user applications in use 14 today: Telnet and FTP clients and servers, HTTP clients and servers, 15 and the like. 17 But another class of applications exists that will also be run under 18 IPv6. We call these "advanced" applications and today this includes 19 programs such as Ping, Traceroute, routing daemons, multicast routing 20 daemons, router discovery daemons, and the like. The API feature 21 typically used by these programs that make them "advanced" is a raw 22 socket to access ICMPv4, IGMPv4, or IPv4, along with some knowledge 23 of the packet header formats used by these protocols. To provide 24 portability for applications that use raw sockets under IPv6, some 25 standardization is needed for the advanced API features. 27 There are other features of IPv6 that some applications will need to 28 access: interface identification (specifying the outgoing interface 29 and determining the incoming interface) and IPv6 extension headers 30 that are not addressed in [RFC-2133]: Hop-by-Hop options, Destination 31 options, and the Routing header (source routing). This document 32 provides API access to these features too. 34 Status of this Memo 36 This document is an Internet Draft. Internet Drafts are working 37 documents of the Internet Engineering Task Force (IETF), its Areas, 38 and its Working Groups. Note that other groups may also distribute 39 working documents as Internet Drafts. 41 Internet Drafts are draft documents valid for a maximum of six 42 months. Internet Drafts may be updated, replaced, or obsoleted by 43 other documents at any time. It is not appropriate to use Internet 44 Drafts as reference material or to cite them other than as a "working 45 draft" or "work in progress". 47 To learn the current status of any Internet-Draft, please check the 48 "1id-abstracts.txt" listing contained in the internet-drafts Shadow 49 Directories on: ftp.is.co.za (Africa), nic.nordu.net (Europe), 50 ds.internic.net (US East Coast), ftp.isi.edu (US West Coast), and 51 munnari.oz.au (Pacific Rim). 53 Table of Contents 55 1. Introduction .................................................... 5 57 2. Common Structures and Definitions ............................... 6 58 2.1. The ip6_hdr Structure ...................................... 6 59 2.1.1. IPv6 Next Header Values ............................. 7 60 2.1.2. IPv6 Extension Headers .............................. 7 61 2.2. The icmp6_hdr Structure .................................... 9 62 2.2.1. ICMPv6 Type and Code Values ......................... 9 63 2.2.2. ICMPv6 Neighbor Discovery Type and Code Values ...... 10 64 2.3. Address Testing Macros ..................................... 12 65 2.4. Protocols File ............................................. 13 67 3. IPv6 Raw Sockets ................................................ 13 68 3.1. Checksums .................................................. 15 69 3.2. ICMPv6 Type Filtering ...................................... 15 71 4. Ancillary Data .................................................. 18 72 4.1. The msghdr Structure ....................................... 18 73 4.2. The cmsghdr Structure ...................................... 19 74 4.3. Ancillary Data Object Macros ............................... 20 75 4.3.1. CMSG_FIRSTHDR ....................................... 21 76 4.3.2. CMSG_NXTHDR ......................................... 22 77 4.3.3. CMSG_DATA ........................................... 23 78 4.3.4. CMSG_SPACE .......................................... 23 79 4.3.5. CMSG_LEN ............................................ 24 80 4.4. Summary of Options Described Using Ancillary Data .......... 24 81 4.5. IPV6_PKTOPTIONS Socket Option .............................. 26 82 4.5.1. TCP Sticky Options .................................. 27 83 4.5.2. UDP and Raw Socket Sticky Options ................... 27 85 5. Packet Information .............................................. 27 86 5.1. Specifying/Receiving the Interface ......................... 28 87 5.2. Specifying/Receiving Source/Destination Address ............ 29 88 5.3. Specifying/Receiving the Hop Limit ......................... 29 89 5.4. Specifying the Next Hop Address ............................ 30 90 5.5. Additional Errors with sendmsg() ........................... 31 92 6. Hop-By-Hop Options .............................................. 31 93 6.1. Receiving Hop-by-Hop Options ............................... 33 94 6.2. Sending Hop-by-Hop Options ................................. 33 95 6.3. Hop-by-Hop and Destination Options Processing .............. 33 96 6.3.1. inet6_option_space .................................. 33 97 6.3.2. inet6_option_init ................................... 34 98 6.3.3. inet6_option_append ................................. 34 99 6.3.4. inet6_option_alloc .................................. 35 100 6.3.5. inet6_option_next ................................... 36 101 6.3.6. inet6_option_find ................................... 36 102 6.3.7. Options Examples .................................... 37 104 7. Destination Options ............................................. 44 105 7.1. Receiving Destination Options .............................. 44 106 7.2. Sending Destination Options ................................ 45 108 8. Routing Header Option ........................................... 45 109 8.1. inet6_rthdr_space .......................................... 46 110 8.2. inet6_rthdr_init ........................................... 47 111 8.3. inet6_rthdr_add ............................................ 47 112 8.4. inet6_rthdr_lasthop ........................................ 48 113 8.5. inet6_rthdr_reverse ........................................ 48 114 8.6. inet6_rthdr_segments ....................................... 48 115 8.7. inet6_rthdr_getaddr ........................................ 49 116 8.8. inet6_rthdr_getflags ....................................... 49 117 8.9. Routing Header Example ..................................... 49 119 9. Ordering of Ancillary Data and IPv6 Extension Headers ........... 54 121 10. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses ........... 56 123 11. rresvport_af .................................................... 56 125 12. Future Items .................................................... 57 126 12.1. Flow Labels ............................................... 57 127 12.2. Path MTU Discovery and UDP ................................ 57 128 12.3. Neighbor Reachability and UDP ............................. 58 130 13. Summary of New Definitions ...................................... 58 132 14. Security Considerations ......................................... 61 134 15. Change History .................................................. 61 136 16. References ...................................................... 66 138 17. Acknowledgments ................................................. 67 140 18. Authors' Addresses .............................................. 67 142 1. Introduction 144 Specifications are in progress for changes to the sockets API to 145 support IP version 6 [RFC-2133]. These changes are for TCP and UDP- 146 based applications. The current document defines some the "advanced" 147 features of the sockets API that are required for applications to 148 take advantage of additional features of IPv6. 150 Today, the portability of applications using IPv4 raw sockets is 151 quite high, but this is mainly because most IPv4 implementations 152 started from a common base (the Berkeley source code) or at least 153 started with the Berkeley headers. This allows programs such as Ping 154 and Traceroute, for example, to compile with minimal effort on many 155 hosts that support the sockets API. With IPv6, however, there is no 156 common source code base that implementors are starting from, and the 157 possibility for divergence at this level between different 158 implementations is high. To avoid a complete lack of portability 159 amongst applications that use raw IPv6 sockets, some standardization 160 is necessary. 162 There are also features from the basic IPv6 specification that are 163 not addressed in [RFC-2133]: sending and receiving Hop-by-Hop 164 options, Destination options, and Routing headers, specifying the 165 outgoing interface, and being told of the receiving interface. 167 This document can be divided into the following main sections. 169 1. Definitions of the basic constants and structures required for 170 applications to use raw IPv6 sockets. This includes structure 171 definitions for the IPv6 and ICMPv6 headers and all associated 172 constants (e.g., values for the Next Header field). 174 2. Some basic semantic definitions for IPv6 raw sockets. For 175 example, a raw ICMPv4 socket requires the application to 176 calculate and store the ICMPv4 header checksum. But with IPv6 177 this would require the application to choose the source IPv6 178 address because the source address is part of the pseudo header 179 that ICMPv6 now uses for its checksum computation. It should be 180 defined that with a raw ICMPv6 socket the kernel always 181 calculates and stores the ICMPv6 header checksum. 183 3. Packet information: how applications can obtain the received 184 interface, destination address, and received hop limit, along 185 with specifying these values on a per-packet basis. There are a 186 class of applications that need this capability and the technique 187 should be portable. 189 4. Access to the optional Hop-by-Hop, Destination, and Routing 190 headers. 192 5. Additional features required for IPv6 application portability. 194 The packet information along with access to the extension headers 195 (Hop-by-Hop options, Destination options, and Routing header) are 196 specified using the "ancillary data" fields that were added to the 197 4.3BSD Reno sockets API in 1990. The reason is that these ancillary 198 data fields are part of the Posix.1g standard (which should be 199 approved in 1997) and should therefore be adopted by most vendors. 201 This document does not address application access to either the 202 authentication header or the encapsulating security payload header. 204 All examples in this document omit error checking in favor of brevity 205 and clarity. 207 We note that many of the functions and socket options defined in this 208 document may have error returns that are not defined in this 209 document. Many of these possible error returns will be recognized 210 only as implementations proceed. 212 Datatypes in this document follow the Posix.1g format: intN_t means a 213 signed integer of exactly N bits (e.g., int16_t) and uintN_t means an 214 unsigned integer of exactly N bits (e.g., uint32_t). 216 Note that we use the (unofficial) terminology ICMPv4, IGMPv4, and 217 ARPv4 to avoid any confusion with the newer ICMPv6 protocol. 219 2. Common Structures and Definitions 221 Many advanced applications examine fields in the IPv6 header and set 222 and examine fields in the various ICMPv6 headers. Common structure 223 definitions for these headers are required, along with common 224 constant definitions for the structure members. 226 Two new headers are defined: and . 228 When an include file is specified, that include file is allowed to 229 include other files that do the actual declaration or definition. 231 2.1. The ip6_hdr Structure 233 The following structure is defined as a result of including 234 . Note that this is a new header. 236 struct ip6_hdr { 237 union { 238 struct ip6_hdrctl { 239 uint32_t ip6_un1_flow; /* 24 bits of flow-ID */ 240 uint16_t ip6_un1_plen; /* payload length */ 241 uint8_t ip6_un1_nxt; /* next header */ 242 uint8_t ip6_un1_hlim; /* hop limit */ 243 } ip6_un1; 244 uint8_t ip6_un2_vfc; /* 4 bits version, 4 bits priority */ 245 } ip6_ctlun; 246 struct in6_addr ip6_src; /* source address */ 247 struct in6_addr ip6_dst; /* destination address */ 248 }; 250 #define ip6_vfc ip6_ctlun.ip6_un2_vfc 251 #define ip6_flow ip6_ctlun.ip6_un1.ip6_un1_flow 252 #define ip6_plen ip6_ctlun.ip6_un1.ip6_un1_plen 253 #define ip6_nxt ip6_ctlun.ip6_un1.ip6_un1_nxt 254 #define ip6_hlim ip6_ctlun.ip6_un1.ip6_un1_hlim 255 #define ip6_hops ip6_ctlun.ip6_un1.ip6_un1_hlim 257 2.1.1. IPv6 Next Header Values 259 IPv6 defines many new values for the Next Header field. The 260 following constants are defined as a result of including 261 . 263 #define IPPROTO_HOPOPTS 0 /* IPv6 Hop-by-Hop options */ 264 #define IPPROTO_IPV6 41 /* IPv6 header */ 265 #define IPPROTO_ROUTING 43 /* IPv6 Routing header */ 266 #define IPPROTO_FRAGMENT 44 /* IPv6 fragmentation header */ 267 #define IPPROTO_ESP 50 /* encapsulating security payload */ 268 #define IPPROTO_AH 51 /* authentication header */ 269 #define IPPROTO_ICMPV6 58 /* ICMPv6 */ 270 #define IPPROTO_NONE 59 /* IPv6 no next header */ 271 #define IPPROTO_DSTOPTS 60 /* IPv6 Destination options */ 273 Berkeley-derived IPv4 implementations also define IPPROTO_IP to be 0. 274 This should not be a problem since IPPROTO_IP is used only with IPv4 275 sockets and IPPROTO_HOPOPTS only with IPv6 sockets. 277 2.1.2. IPv6 Extension Headers 279 Six extension headers are defined for IPv6. We define structures for 280 all except the Authentication header and Encapsulating Security 281 Payload header, both of which are beyond the scope of this document. 282 The following structures are defined as a result of including 283 . 285 /* Hop-by-Hop options header */ 286 /* XXX should we pad it to force alignment on an 8-byte boundary? */ 287 struct ip6_hbh { 288 uint8_t ip6h_nxt; /* next header */ 289 uint8_t ip6h_len; /* length in units of 8 octets */ 290 /* followed by options */ 291 }; 293 /* Destination options header */ 294 /* XXX should we pad it to force alignment on an 8-byte boundary? */ 295 struct ip6_dest { 296 uint8_t ip6d_nxt; /* next header */ 297 uint8_t ip6d_len; /* length in units of 8 octets */ 298 /* followed by options */ 299 }; 301 /* Routing header */ 302 struct ip6_rthdr { 303 uint8_t ip6r_nxt; /* next header */ 304 uint8_t ip6r_len; /* length in units of 8 octets */ 305 uint8_t ip6r_type; /* routing type */ 306 uint8_t ip6r_segleft; /* segments left */ 307 /* followed by routing type specific data */ 308 }; 310 /* Type 0 Routing header */ 311 struct ip6_rthdr0 { 312 uint8_t ip6r0_nxt; /* next header */ 313 uint8_t ip6r0_len; /* length in units of 8 octets */ 314 uint8_t ip6r0_type; /* always zero */ 315 uint8_t ip6r0_segleft; /* segments left */ 316 uint8_t ip6r0_reserved; /* reserved field */ 317 uint8_t ip6r0_slmap[3]; /* strict/loose bit map */ 318 struct in6_addr ip6r0_addr[1]; /* up to 23 addresses */ 319 }; 321 /* Fragment header */ 322 struct ip6_frag { 323 uint8_t ip6f_nxt; /* next header */ 324 uint8_t ip6f_reserved; /* reserved field */ 325 uint16_t ip6f_offlg; /* offset, reserved, and flag */ 326 uint32_t ip6f_ident; /* identification */ 327 }; 328 #define IP6F_OFF_MASK 0xfff8 /* mask out offset from _offlg */ 329 #define IP6F_RESERVED_MASK 0x0006 /* reserved bits in ip6f_offlg */ 330 #define IP6F_MORE_FRAG 0x0001 /* more-fragments flag */ 332 2.2. The icmp6_hdr Structure 334 The ICMPv6 header is needed by numerous IPv6 applications including 335 Ping, Traceroute, router discovery daemons, and neighbor discovery 336 daemons. The following structure is defined as a result of including 337 . Note that this is a new header. 339 struct icmp6_hdr { 340 uint8_t icmp6_type; /* type field */ 341 uint8_t icmp6_code; /* code field */ 342 uint16_t icmp6_cksum; /* checksum field */ 343 union { 344 uint32_t icmp6_un_data32[1]; /* type-specific field */ 345 uint16_t icmp6_un_data16[2]; /* type-specific field */ 346 uint8_t icmp6_un_data8[4]; /* type-specific field */ 347 } icmp6_dataun; 348 }; 350 #define icmp6_data32 icmp6_dataun.icmp6_un_data32 351 #define icmp6_data16 icmp6_dataun.icmp6_un_data16 352 #define icmp6_data8 icmp6_dataun.icmp6_un_data8 353 #define icmp6_pptr icmp6_data32[0] /* parameter prob */ 354 #define icmp6_mtu icmp6_data32[0] /* packet too big */ 355 #define icmp6_id icmp6_data16[0] /* echo request/reply */ 356 #define icmp6_seq icmp6_data16[1] /* echo request/reply */ 357 #define icmp6_maxdelay icmp6_data16[0] /* mcast group membership */ 359 2.2.1. ICMPv6 Type and Code Values 361 In addition to a common structure for the ICMPv6 header, common 362 definitions are required for the ICMPv6 type and code fields. The 363 following constants are also defined as a result of including 364 . 366 #define ICMP6_DST_UNREACH 1 367 #define ICMP6_PACKET_TOO_BIG 2 368 #define ICMP6_TIME_EXCEEDED 3 369 #define ICMP6_PARAM_PROB 4 371 #define ICMP6_INFOMSG_MASK 0x80 /* all informational messages */ 372 #define ICMP6_ECHO_REQUEST 128 373 #define ICMP6_ECHO_REPLY 129 374 #define ICMP6_MEMBERSHIP_QUERY 130 375 #define ICMP6_MEMBERSHIP_REPORT 131 376 #define ICMP6_MEMBERSHIP_REDUCTION 132 378 #define ICMP6_DST_UNREACH_NOROUTE 0 /* no route to destination */ 379 #define ICMP6_DST_UNREACH_ADMIN 1 /* communication with destination */ 380 /* administratively prohibited */ 381 #define ICMP6_DST_UNREACH_NOTNEIGHBOR 2 /* not a neighbor */ 382 #define ICMP6_DST_UNREACH_ADDR 3 /* address unreachable */ 383 #define ICMP6_DST_UNREACH_NOPORT 4 /* bad port */ 385 #define ICMP6_TIME_EXCEED_TRANSIT 0 /* Hop Limit == 0 in transit */ 386 #define ICMP6_TIME_EXCEED_REASSEMBLY 1 /* Reassembly time out */ 388 #define ICMP6_PARAMPROB_HEADER 0 /* erroneous header field */ 389 #define ICMP6_PARAMPROB_NEXTHEADER 1 /* unrecognized Next Header */ 390 #define ICMP6_PARAMPROB_OPTION 2 /* unrecognized IPv6 option */ 392 The five ICMP message types defined by IPv6 neighbor discovery 393 (133-137) are defined in the next section. 395 2.2.2. ICMPv6 Neighbor Discovery Type and Code Values 397 The following structures and definitions are defined as a result of 398 including . 400 #define ND_ROUTER_SOLICIT 133 401 #define ND_ROUTER_ADVERT 134 402 #define ND_NEIGHBOR_SOLICIT 135 403 #define ND_NEIGHBOR_ADVERT 136 404 #define ND_REDIRECT 137 406 struct nd_router_solicit { /* router solicitation */ 407 struct icmp6_hdr nd_rs_hdr; 408 /* could be followed by options */ 409 }; 411 #define nd_rs_type nd_rs_hdr.icmp6_type 412 #define nd_rs_code nd_rs_hdr.icmp6_code 413 #define nd_rs_cksum nd_rs_hdr.icmp6_cksum 414 #define nd_rs_reserved nd_rs_hdr.icmp6_data32[0] 416 struct nd_router_advert { /* router advertisement */ 417 struct icmp6_hdr nd_ra_hdr; 418 uint32_t nd_ra_reachable; /* reachable time */ 419 uint32_t nd_ra_retransmit; /* retransmit timer */ 420 /* could be followed by options */ 421 }; 423 #define nd_ra_type nd_ra_hdr.icmp6_type 424 #define nd_ra_code nd_ra_hdr.icmp6_code 425 #define nd_ra_cksum nd_ra_hdr.icmp6_cksum 426 #define nd_ra_curhoplimit nd_ra_hdr.icmp6_data8[0] 427 #define nd_ra_flags_reserved nd_ra_hdr.icmp6_data8[1] 428 #define ND_RA_FLAG_MANAGED 0x80 429 #define ND_RA_FLAG_OTHER 0x40 430 #define nd_ra_router_lifetime nd_ra_hdr.icmp6_data16[1] 432 struct nd_neighbor_solicit { /* neighbor solicitation */ 433 struct icmp6_hdr nd_ns_hdr; 434 struct in6_addr nd_ns_target; /* target address */ 435 /* could be followed by options */ 436 }; 438 #define nd_ns_type nd_ns_hdr.icmp6_type 439 #define nd_ns_code nd_ns_hdr.icmp6_code 440 #define nd_ns_cksum nd_ns_hdr.icmp6_cksum 441 #define nd_ns_reserved nd_ns_hdr.icmp6_data32[0] 443 struct nd_neighbor_advert { /* neighbor advertisement */ 444 struct icmp6_hdr nd_na_hdr; 445 struct in6_addr nd_na_target; /* target address */ 446 /* could be followed by options */ 447 }; 449 #define nd_na_type nd_na_hdr.icmp6_type 450 #define nd_na_code nd_na_hdr.icmp6_code 451 #define nd_na_cksum nd_na_hdr.icmp6_cksum 452 #define nd_na_flags_reserved nd_na_hdr.icmp6_data32[0] 453 #define ND_NA_FLAG_ROUTER 0x80000000 454 #define ND_NA_FLAG_SOLICITED 0x40000000 455 #define ND_NA_FLAG_OVERRIDE 0x20000000 457 struct nd_redirect { /* redirect */ 458 struct icmp6_hdr nd_rd_hdr; 459 struct in6_addr nd_rd_target; /* target address */ 460 struct in6_addr nd_rd_dst; /* destination address */ 461 /* could be followed by options */ 462 }; 464 #define nd_rd_type nd_rd_hdr.icmp6_type 465 #define nd_rd_code nd_rd_hdr.icmp6_code 466 #define nd_rd_cksum nd_rd_hdr.icmp6_cksum 467 #define nd_rd_reserved nd_rd_hdr.icmp6_data32[0] 469 struct nd_opt_hdr { /* Neighbor discovery option header */ 470 uint8_t nd_opt_type; 471 uint8_t nd_opt_len; /* in units of 8 octets */ 472 /* followed by option specific data */ 473 }; 475 #define ND_OPT_SOURCE_LINKADDR 1 476 #define ND_OPT_TARGET_LINKADDR 2 477 #define ND_OPT_PREFIX_INFORMATION 3 478 #define ND_OPT_REDIRECTED_HEADER 4 479 #define ND_OPT_MTU 5 481 struct nd_opt_prefix_info { /* prefix information */ 482 uint8_t nd_opt_pi_type; 483 uint8_t nd_opt_pi_len; 484 uint8_t nd_opt_pi_prefix_len; 485 uint8_t nd_opt_pi_flags_reserved; 486 uint32_t nd_opt_pi_valid_time; 487 uint32_t nd_opt_pi_preferred_time; 488 uint32_t nd_opt_pi_reserved2; 489 struct in6_addr nd_opt_pi_prefix; 490 }; 492 #define ND_OPT_PI_FLAG_ONLINK 0x80 493 #define ND_OPT_PI_FLAG_AUTO 0x40 495 struct nd_opt_rd_hdr { /* redirected header */ 496 uint8_t nd_opt_rh_type; 497 uint8_t nd_opt_rh_len; 498 uint16_t nd_opt_rh_reserved1; 499 uint32_t nd_opt_rh_reserved2; 500 /* followed by IP header and data */ 501 }; 503 struct nd_opt_mtu { /* MTU option */ 504 uint8_t nd_opt_mtu_type; 505 uint8_t nd_opt_mtu_len; 506 uint16_t nd_opt_mtu_reserved; 507 uint32_t nd_opt_mtu_mtu; 508 }; 510 2.3. Address Testing Macros 512 The basic API ([RFC-2133]) defines some macros for testing an IPv6 513 address for certain properties. This API extends those definitions 514 with additional address testing macros, defined as a result of 515 including . 517 int IN6_ARE_ADDR_EQUAL(const struct in6_addr *, 518 const struct in6_addr *); 520 2.4. Protocols File 522 Many hosts provide the file /etc/protocols that contains the names of 523 the various IP protocols and their protocol number (e.g., the value 524 of the protocol field in the IPv4 header for that protocol, such as 1 525 for ICMP). Some programs then call the function getprotobyname() to 526 obtain the protocol value that is then specified as the third 527 argument to the socket() function. For example, the Ping program 528 contains code of the form 530 struct protoent *proto; 532 proto = getprotobyname("icmp"); 534 s = socket(AF_INET, SOCK_RAW, proto->p_proto); 536 Common names are required for the new IPv6 protocols in this file, to 537 provide portability of applications that call the getprotoXXX() 538 functions. 540 We define the following protocol names with the values shown. These 541 are taken from ftp://ftp.isi.edu/in-notes/iana/assignments/protocol- 542 numbers. 544 hopopt 0 # hop-by-hop options for ipv6 545 ipv6 41 # ipv6 546 ipv6-route 43 # routing header for ipv6 547 ipv6-frag 44 # fragment header for ipv6 548 esp 50 # encapsulating security payload for ipv6 549 ah 51 # authentication header for ipv6 550 ipv6-icmp 58 # icmp for ipv6 551 ipv6-nonxt 59 # no next header for ipv6 552 ipv6-opts 60 # destination options for ipv6 554 3. IPv6 Raw Sockets 556 Raw sockets bypass the transport layer (TCP or UDP). With IPv4, raw 557 sockets are used to access ICMPv4, IGMPv4, and to read and write IPv4 558 datagrams containing a protocol field that the kernel does not 559 process. An example of the latter is a routing daemon for OSPF, 560 since it uses IPv4 protocol field 89. With IPv6 raw sockets will be 561 used for ICMPv6 and to read and write IPv6 datagrams containing a 562 Next Header field that the kernel does not process. Examples of the 563 latter are a routing daemon for OSPF for IPv6 and RSVP (protocol 564 field 46). 566 All data sent via raw sockets MUST be in network byte order and all 567 data received via raw sockets will be in network byte order. This 568 differs from the IPv4 raw sockets, which did not specify a byte 569 ordering and typically used the host's byte order. 571 Another difference from IPv4 raw sockets is that complete packets 572 (that is, IPv6 packets with extension headers) cannot be read or 573 written using the IPv6 raw sockets API. Instead, ancillary data 574 objects are used to transfer the extension headers, as described 575 later in this document. Should an application need access to the 576 complete IPv6 packet, some other technique, such as the datalink 577 interfaces BPF or DLPI, must be used. 579 All fields in the IPv6 header that an application might want to 580 change (i.e., everything other than the version number) can be 581 modified using ancillary data and/or socket options by the 582 application for output. All fields in a received IPv6 header (other 583 than the version number and Next Header fields) and all extension 584 headers are also made available to the application as ancillary data 585 on input. Hence there is no need for a socket option similar to the 586 IPv4 IP_HDRINCL socket option. 588 When writing to a raw socket the kernel will automatically fragment 589 the packet if its size exceeds the path MTU, inserting the required 590 fragmentation headers. On input the kernel reassembles received 591 fragments, so the reader of a raw socket never sees any fragment 592 headers. 594 When we say "an ICMPv6 raw socket" we mean a socket created by 595 calling the socket function with the three arguments PF_INET6, 596 SOCK_RAW, and IPPROTO_ICMPV6. 598 Most IPv4 implementations give special treatment to a raw socket 599 created with a third argument to socket() of IPPROTO_RAW, whose value 600 is normally 255. We note that this value has no special meaning to 601 an IPv6 raw socket (and the IANA currently reserves the value of 255 602 when used as a next-header field). (Note: This feature was added to 603 IPv4 in 1988 by Van Jacobson to support traceroute, allowing a 604 complete IP header to be passed by the application, before the 605 IP_HDRINCL socket option was added.) 607 3.1. Checksums 609 The kernel will calculate and insert the ICMPv6 checksum for ICMPv6 610 raw sockets, since this checksum is mandatory. 612 For other raw IPv6 sockets (that is, for raw IPv6 sockets created 613 with a third argument other than IPPROTO_ICMPV6), the application 614 must set the new IPV6_CHECKSUM socket option to have the kernel (1) 615 compute and store a checksum for output, and (2) verify the received 616 checksum on input, discarding the packet if the checksum is in error. 617 This option prevents applications from having to perform source 618 address selection on the packets they send. The checksum will 619 incorporate the IPv6 pseudo-header, defined in Section 8.1 of 620 [RFC-1883]. This new socket option also specifies an integer offset 621 into the user data of where the checksum is located. 623 int offset = 2; 624 setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, sizeof(offset)); 626 By default, this socket option is disabled. Setting the offset to -1 627 also disables the option. By disabled we mean (1) the kernel will 628 not calculate and store a checksum for outgoing packets, and (2) the 629 kernel will not verify a checksum for received packets. 631 (Note: Since the checksum is always calculated by the kernel for an 632 ICMPv6 socket, applications are not able to generate ICMPv6 packets 633 with incorrect checksums (presumably for testing purposes) using this 634 API.) 636 3.2. ICMPv6 Type Filtering 638 ICMPv4 raw sockets receive most ICMPv4 messages received by the 639 kernel. (We say "most" and not "all" because Berkeley-derived 640 kernels never pass echo requests, timestamp requests, or address mask 641 requests to a raw socket. Instead these three messages are processed 642 entirely by the kernel.) But ICMPv6 is a superset of ICMPv4, also 643 including the functionality of IGMPv4 and ARPv4. This means that an 644 ICMPv6 raw socket can potentially receive many more messages than 645 would be received with an ICMPv4 raw socket: ICMP messages similar to 646 ICMPv4, along with neighbor solicitations, neighbor advertisements, 647 and the three group membership messages. 649 Most applications using an ICMPv6 raw socket care about only a small 650 subset of the ICMPv6 message types. To transfer extraneous ICMPv6 651 messages from the kernel to user can incur a significant overhead. 652 Therefore this API includes a method of filtering ICMPv6 messages by 653 the ICMPv6 type field. 655 Each ICMPv6 raw socket has an associated filter whose datatype is 656 defined as 658 struct icmp6_filter; 660 This structure, along with the macros and constants defined later in 661 this section, are defined as a result of including the 662 header. 664 The current filter is fetched and stored using getsockopt() and 665 setsockopt() with a level of IPPROTO_ICMPV6 and an option name of 666 ICMP6_FILTER. 668 Six macros operate on an icmp6_filter structure: 670 void ICMP6_FILTER_SETPASSALL (struct icmp6_filter *); 671 void ICMP6_FILTER_SETBLOCKALL(struct icmp6_filter *); 673 void ICMP6_FILTER_SETPASS ( int, struct icmp6_filter *); 674 void ICMP6_FILTER_SETBLOCK( int, struct icmp6_filter *); 676 int ICMP6_FILTER_WILLPASS (int, const struct icmp6_filter *); 677 int ICMP6_FILTER_WILLBLOCK(int, const struct icmp6_filter *); 679 The first argument to the last four macros (an integer) is an ICMPv6 680 message type, between 0 and 255. The pointer argument to all six 681 macros is a pointer to a filter that is modified by the first four 682 macros examined by the last two macros. 684 The first two macros, SETPASSALL and SETBLOCKALL, let us specify that 685 all ICMPv6 messages are passed to the application or that all ICMPv6 686 messages are blocked from being passed to the application. 688 The next two macros, SETPASS and SETBLOCK, let us specify that 689 messages of a given ICMPv6 type should be passed to the application 690 or not passed to the application (blocked). 692 The final two macros, WILLPASS and WILLBLOCK, return true or false 693 depending whether the specified message type is passed to the 694 application or blocked from being passed to the application by the 695 filter pointed to by the second argument. 697 When an ICMPv6 raw socket is created, it will by default pass all 698 ICMPv6 message types to the application. 700 As an example, a program that wants to receive only router 701 advertisements could execute the following: 703 struct icmp6_filter myfilt; 705 fd = socket(PF_INET6, SOCK_RAW, IPPROTO_ICMPV6); 707 ICMP6_FILTER_SETBLOCKALL(&myfilt); 708 ICMP6_FILTER_SETPASS(ND_ROUTER_ADVERT, &myfilt); 709 setsockopt(fd, IPPROTO_ICMPV6, ICMP6_FILTER, &myfilt, sizeof(myfilt)); 711 The filter structure is declared and then initialized to block all 712 messages types. The filter structure is then changed to allow router 713 advertisement messages to be passed to the application and the filter 714 is installed using setsockopt(). 716 The icmp6_filter structure is similar to the fd_set datatype used 717 with the select() function in the sockets API. The icmp6_filter 718 structure is an opaque datatype and the application should not care 719 how it is implemented. All the application does with this datatype 720 is allocate a variable of this type, pass a pointer to a variable of 721 this type to getsockopt() and setsockopt(), and operate on a variable 722 of this type using the six macros that we just defined. 724 Nevertheless, it is worth showing a simple implementation of this 725 datatype and the six macros. 727 struct icmp6_filter { 728 uint32_t icmp6_filt[8]; /* 8*32 = 256 bits */ 729 }; 731 #define ICMP6_FILTER_WILLPASS(type, filterp) \ 732 ((((filterp)->icmp6_filt[(type) >> 5]) & (1 << ((type) & 31))) != 0) 733 #define ICMP6_FILTER_WILLBLOCK(type, filterp) \ 734 ((((filterp)->icmp6_filt[(type) >> 5]) & (1 << ((type) & 31))) == 0) 735 #define ICMP6_FILTER_SETPASS(type, filterp) \ 736 ((((filterp)->icmp6_filt[(type) >> 5]) |= (1 << ((type) & 31)))) 737 #define ICMP6_FILTER_SETBLOCK(type, filterp) \ 738 ((((filterp)->icmp6_filt[(type) >> 5]) &= ~(1 << ((type) & 31)))) 739 #define ICMP6_FILTER_SETPASSALL(filterp) \ 740 memset((filterp), 0xFF, sizeof(struct icmp6_filter)) 741 #define ICMP6_FILTER_SETBLOCKALL(filterp) \ 742 memset((filterp), 0, sizeof(struct icmp6_filter)) 744 (Note: These sample definitions have two limitations that an 745 implementation may want to change. The first four macros evaluate 746 their first argument two times. The second two macros require the 747 inclusion of the header for the memset() function.) 749 4. Ancillary Data 751 4.2BSD allowed file descriptors to be transferred between separate 752 processes across a UNIX domain socket using the sendmsg() and 753 recvmsg() functions. Two members of the msghdr structure, 754 msg_accrights and msg_accrightslen, were used to send and receive the 755 descriptors. When the OSI protocols were added to 4.3BSD Reno in 756 1990 the names of these two fields in the msghdr structure were 757 changed to msg_control and msg_controllen, because they were used by 758 the OSI protocols for "control information", although the comments in 759 the source code call this "ancillary data". 761 Other than the OSI protocols, the use of ancillary data has been 762 rare. In 4.4BSD, for example, the only use of ancillary data with 763 IPv4 is to return the destination address of a received UDP datagram 764 if the IP_RECVDSTADDR socket option is set. With Unix domain sockets 765 ancillary data is still used to send and receive descriptors. 767 Nevertheless the ancillary data fields of the msghdr structure 768 provide a clean way to pass information in addition to the data that 769 is being read or written. The inclusion of the msg_control and 770 msg_controllen members of the msghdr structure along with the cmsghdr 771 structure that is pointed to by the msg_control member is required by 772 the Posix.1g sockets API standard (which should be completed during 773 1997). 775 In this document ancillary data is used to exchange the following 776 optional information between the application and the kernel: 778 1. the send/receive interface and source/destination address, 779 2. the hop limit, 780 3. next hop address, 781 4. Hop-by-Hop options, 782 5. Destination options, and 783 6. Routing header. 785 Before describing these uses in detail, we review the definition of 786 the msghdr structure itself, the cmsghdr structure that defines an 787 ancillary data object, and some functions that operate on the 788 ancillary data objects. 790 4.1. The msghdr Structure 792 The msghdr structure is used by the recvmsg() and sendmsg() 793 functions. Its Posix.1g definition is: 795 struct msghdr { 796 void *msg_name; /* ptr to socket address structure */ 797 socklen_t msg_namelen; /* size of socket address structure */ 798 struct iovec *msg_iov; /* scatter/gather array */ 799 size_t msg_iovlen; /* # elements in msg_iov */ 800 void *msg_control; /* ancillary data */ 801 socklen_t msg_controllen; /* ancillary data buffer length */ 802 int msg_flags; /* flags on received message */ 803 }; 805 The structure is declared as a result of including . 807 (Note: Before Posix.1g the two "void *" pointers were typically "char 808 *", and the two socklen_t members and the size_t member were 809 typically integers. Earlier drafts of Posix.1g had the two socklen_t 810 members as size_t, but Draft 6.6 of Posix.1g, apparently the final 811 draft, changed these to socklen_t to simplify binary portability for 812 64-bit implementations and to align Posix.1g with X/Open's Networking 813 Services, Issue 5. The change in msg_control to a "void *" pointer 814 affects any code that increments this pointer.) 816 Most Berkeley-derived implementations limit the amount of ancillary 817 data in a call to sendmsg() to no more than 108 bytes (an mbuf). 818 This API requires a minimum of 10240 bytes of ancillary data, but it 819 is recommended that the amount be limited only by the buffer space 820 reserved by the socket (which can be modified by the SO_SNDBUF socket 821 option). (Note: This magic number 10240 was picked as a value that 822 should always be large enough. 108 bytes is clearly too small as the 823 maximum size of a Type 0 Routing header is 376 bytes.) 825 4.2. The cmsghdr Structure 827 The cmsghdr structure describes ancillary data objects transferred by 828 recvmsg() and sendmsg(). Its Posix.1g definition is: 830 struct cmsghdr { 831 socklen_t cmsg_len; /* #bytes, including this header */ 832 int cmsg_level; /* originating protocol */ 833 int cmsg_type; /* protocol-specific type */ 834 /* followed by unsigned char cmsg_data[]; */ 835 }; 837 This structure is declared as a result of including . 839 As shown in this definition, normally there is no member with the 840 name cmsg_data[]. Instead, the data portion is accessed using the 841 CMSG_xxx() macros, as described shortly. Nevertheless, it is common 842 to refer to the cmsg_data[] member. 844 (Note: Before Posix.1g the cmsg_len member was an integer, and not a 845 socklen_t. See the Note in the previous section for why socklen_t is 846 used here.) 848 When ancillary data is sent or received, any number of ancillary data 849 objects can be specified by the msg_control and msg_controllen 850 members of the msghdr structure, because each object is preceded by a 851 cmsghdr structure defining the object's length (the cmsg_len member). 852 Historically Berkeley-derived implementations have passed only one 853 object at a time, but this API allows multiple objects to be passed 854 in a single call to sendmsg() or recvmsg(). The following example 855 shows two ancillary data objects in a control buffer. 857 |<--------------------------- msg_controllen -------------------------->| 858 | | 859 |<----- ancillary data object ----->|<----- ancillary data object ----->| 860 |<---------- CMSG_SPACE() --------->|<---------- CMSG_SPACE() --------->| 861 | | | 862 |<---------- cmsg_len ---------->| |<--------- cmsg_len ----------->| | 863 |<--------- CMSG_LEN() --------->| |<-------- CMSG_LEN() ---------->| | 864 | | | | | 865 +-----+-----+-----+--+-----------+--+-----+-----+-----+--+-----------+--+ 866 |cmsg_|cmsg_|cmsg_|XX| |XX|cmsg_|cmsg_|cmsg_|XX| |XX| 867 |len |level|type |XX|cmsg_data[]|XX|len |level|type |XX|cmsg_data[]|XX| 868 +-----+-----+-----+--+-----------+--+-----+-----+-----+--+-----------+--+ 869 ^ 870 | 871 msg_control 872 points here 874 The fields shown as "XX" are possible padding, between the cmsghdr 875 structure and the data, and between the data and the next cmsghdr 876 structure, if required by the implementation. 878 4.3. Ancillary Data Object Macros 880 To aid in the manipulation of ancillary data objects, three macros 881 from 4.4BSD are defined by Posix.1g: CMSG_DATA(), CMSG_NXTHDR(), and 882 CMSG_FIRSTHDR(). Before describing these macros, we show the 883 following example of how they might be used with a call to recvmsg(). 885 struct msghdr msg; 886 struct cmsghdr *cmsgptr; 888 /* fill in msg */ 890 /* call recvmsg() */ 892 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 893 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 894 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 895 u_char *ptr; 897 ptr = CMSG_DATA(cmsgptr); 898 /* process data pointed to by ptr */ 899 } 900 } 902 We now describe the three Posix.1g macros, followed by two more that 903 are new with this API: CMSG_SPACE() and CMSG_LEN(). All these macros 904 are defined as a result of including . 906 4.3.1. CMSG_FIRSTHDR 908 struct cmsghdr *CMSG_FIRSTHDR(const struct msghdr *mhdr); 910 CMSG_FIRSTHDR() returns a pointer to the first cmsghdr structure in 911 the msghdr structure pointed to by mhdr. The macro returns NULL if 912 there is no ancillary data pointed to the by msghdr structure (that 913 is, if either msg_control is NULL or if msg_controllen is less than 914 the size of a cmsghdr structure). 916 One possible implementation could be 918 #define CMSG_FIRSTHDR(mhdr) \ 919 ( (mhdr)->msg_controllen >= sizeof(struct cmsghdr) ? \ 920 (struct cmsghdr *)(mhdr)->msg_control : \ 921 (struct cmsghdr *)NULL ) 923 (Note: Most existing implementations do not test the value of 924 msg_controllen, and just return the value of msg_control. The value 925 of msg_controllen must be tested, because if the application asks 926 recvmsg() to return ancillary data, by setting msg_control to point 927 to the application's buffer and setting msg_controllen to the length 928 of this buffer, the kernel indicates that no ancillary data is 929 available by setting msg_controllen to 0 on return. It is also 930 easier to put this test into this macro, than making the application 931 perform the test.) 933 4.3.2. CMSG_NXTHDR 935 struct cmsghdr *CMSG_NXTHDR(const struct msghdr *mhdr, 936 const struct cmsghdr *cmsg); 938 CMSG_NXTHDR() returns a pointer to the cmsghdr structure describing 939 the next ancillary data object. mhdr is a pointer to a msghdr 940 structure and cmsg is a pointer to a cmsghdr structure. If there is 941 not another ancillary data object, the return value is NULL. 943 The following behavior of this macro is new to this API: if the value 944 of the cmsg pointer is NULL, a pointer to the cmsghdr structure 945 describing the first ancillary data object is returned. That is, 946 CMSG_NXTHDR(mhdr, NULL) is equivalent to CMSG_FIRSTHDR(mhdr). If 947 there are no ancillary data objects, the return value is NULL. This 948 provides an alternative way of coding the processing loop shown 949 earlier: 951 struct msghdr msg; 952 struct cmsghdr *cmsgptr = NULL; 954 /* fill in msg */ 956 /* call recvmsg() */ 958 while ((cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) != NULL) { 959 if (cmsgptr->cmsg_level == ... && cmsgptr->cmsg_type == ... ) { 960 u_char *ptr; 962 ptr = CMSG_DATA(cmsgptr); 963 /* process data pointed to by ptr */ 964 } 965 } 967 One possible implementation could be: 969 #define CMSG_NXTHDR(mhdr, cmsg) \ 970 ( ((cmsg) == NULL) ? CMSG_FIRSTHDR(mhdr) : \ 971 (((u_char *)(cmsg) + ALIGN((cmsg)->cmsg_len) \ 972 + ALIGN(sizeof(struct cmsghdr)) > \ 973 (u_char *)((mhdr)->msg_control) + (mhdr)->msg_controllen) ? \ 974 (struct cmsghdr *)NULL : \ 975 (struct cmsghdr *)((u_char *)(cmsg) + ALIGN((cmsg)->cmsg_len))) ) 977 The macro ALIGN(), which is implementation dependent, rounds its 978 argument up to the next even multiple of whatever alignment is 979 required (probably a multiple of 4 or 8 bytes). 981 4.3.3. CMSG_DATA 983 unsigned char *CMSG_DATA(const struct cmsghdr *cmsg); 985 CMSG_DATA() returns a pointer to the data (what is called the 986 cmsg_data[] member, even though such a member is not defined in the 987 structure) following a cmsghdr structure. 989 One possible implementation could be: 991 #define CMSG_DATA(cmsg) ( (u_char *)(cmsg) + \ 992 ALIGN(sizeof(struct cmsghdr)) ) 994 4.3.4. CMSG_SPACE 996 unsigned int CMSG_SPACE(unsigned int length); 998 This macro is new with this API. Given the length of an ancillary 999 data object, CMSG_SPACE() returns the space required by the object 1000 and its cmsghdr structure, including any padding needed to satisfy 1001 alignment requirements. This macro can be used, for example, to 1002 allocate space dynamically for the ancillary data. This macro should 1003 not be used to initialize the cmsg_len member of a cmsghdr structure; 1004 instead use the CMSG_LEN() macro. 1006 One possible implementation could be: 1008 #define CMSG_SPACE(length) ( ALIGN(sizeof(struct cmsghdr)) + \ 1009 ALIGN(length) ) 1011 4.3.5. CMSG_LEN 1013 unsigned int CMSG_LEN(unsigned int length); 1015 This macro is new with this API. Given the length of an ancillary 1016 data object, CMSG_LEN() returns the value to store in the cmsg_len 1017 member of the cmsghdr structure, taking into account any padding 1018 needed to satisfy alignment requirements. 1020 One possible implementation could be: 1022 #define CMSG_LEN(length) ( ALIGN(sizeof(struct cmsghdr)) + length ) 1024 Note the difference between CMSG_SPACE() and CMSG_LEN(), shown also 1025 in the figure in Section 4.2: the former accounts for any required 1026 padding at the end of the ancillary data object and the latter is the 1027 actual length to store in the cmsg_len member of the ancillary data 1028 object. 1030 4.4. Summary of Options Described Using Ancillary Data 1032 There are six types of optional information described in this 1033 document that are passed between the application and the kernel using 1034 ancillary data: 1036 1. the send/receive interface and source/destination address, 1037 2. the hop limit, 1038 3. next hop address, 1039 4. Hop-by-Hop options, 1040 5. Destination options, and 1041 6. Routing header. 1043 First, to receive any of this optional information (other than the 1044 next hop address, which can only be set), the application must call 1045 setsockopt() to turn on the corresponding flag: 1047 int on = 1; 1049 setsockopt(fd, IPPROTO_IPV6, IPV6_PKTINFO, &on, sizeof(on)); 1050 setsockopt(fd, IPPROTO_IPV6, IPV6_HOPLIMIT, &on, sizeof(on)); 1051 setsockopt(fd, IPPROTO_IPV6, IPV6_HOPOPTS, &on, sizeof(on)); 1052 setsockopt(fd, IPPROTO_IPV6, IPV6_DSTOPTS, &on, sizeof(on)); 1053 setsockopt(fd, IPPROTO_IPV6, IPV6_RTHDR, &on, sizeof(on)); 1055 When any of these options are enabled, the corresponding data is 1056 returned as control information by recvmsg(), as one or more 1057 ancillary data objects. 1059 Nothing special need be done to send any of this optional 1060 information; the application just calls sendmsg() and specifies one 1061 or more ancillary data objects as control information. 1063 We also summarize the three cmsghdr fields that describe the 1064 ancillary data objects: 1066 cmsg_level cmsg_type cmsg_data[] #times 1067 ------------ ------------ ------------------------ ------ 1068 IPPROTO_IPV6 IPV6_PKTINFO in6_pktinfo structure once 1069 IPPROTO_IPV6 IPV6_HOPLIMIT int once 1070 IPPROTO_IPV6 IPV6_NEXTHOP socket address structure once 1071 IPPROTO_IPV6 IPV6_HOPOPTS implementation dependent mult. 1072 IPPROTO_IPV6 IPV6_DSTOPTS implementation dependent mult. 1073 IPPROTO_IPV6 IPV6_RTHDR implementation dependent once 1075 The final column indicates how many times an ancillary data object of 1076 that type can appear as control information. The Hop-by-Hop and 1077 Destination options can appear multiple times, while all the others 1078 can appear only one time. 1080 All these options are described in detail in following sections. All 1081 the constants beginning with IPV6_ are defined as a result of 1082 including the header. 1084 (Note: We intentionally use the same constant for the cmsg_level 1085 member as is used as the second argument to getsockopt() and 1086 setsockopt() (what is called the "level"), and the same constant for 1087 the cmsg_type member as is used as the third argument to getsockopt() 1088 and setsockopt() (what is called the "option name"). This is 1089 consistent with the existing use of ancillary data in 4.4BSD: 1090 returning the destination address of an IPv4 datagram.) 1092 (Note: It is up to the implementation what it passes as ancillary 1093 data for the Hop-by-Hop option, Destination option, and Routing 1094 header option, since the API to these features is through a set of 1095 inet6_option_XXX() and inet6_rthdr_XXX() functions that we define 1096 later. These functions serve two purposes: to simplify the interface 1097 to these features (instead of requiring the application to know the 1098 intimate details of the extension header formats), and to hide the 1099 actual implementation from the application. Nevertheless, we show 1100 some examples of these features that store the actual extension 1101 header as the ancillary data. Implementations need not use this 1102 technique.) 1104 4.5. IPV6_PKTOPTIONS Socket Option 1106 The summary in the previous section assumes a UDP socket. Sending 1107 and receiving ancillary data is easy with UDP: the application calls 1108 sendmsg() and recvmsg() instead of sendto() and recvfrom(). 1110 But there might be cases where a TCP application wants to send or 1111 receive this optional information. For example, a TCP client might 1112 want to specify a Routing header and this needs to be done before 1113 calling connect(). Similarly a TCP server might want to know the 1114 received interface after accept() returns along with any Destination 1115 options. 1117 A new socket option is defined that provides access to the optional 1118 information described in the previous section, but without using 1119 recvmsg() and sendmsg(). Setting the socket option specifies any of 1120 the optional output fields: 1122 setsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, len); 1124 The fourth argument points to a buffer containing one or more 1125 ancillary data objects, and the fifth argument is the total length of 1126 all these objects. The application fills in this buffer exactly as 1127 if the buffer were being passed to sendmsg() as control information. 1129 The options set by calling setsockopt() for IPV6_PKTOPTIONS are 1130 called "sticky" options because once set they apply to all packets 1131 sent on that socket. The application can call setsockopt() again to 1132 change all the sticky options, or it can call setsockopt() with a 1133 length of 0 to remove all the sticky options for the socket. 1135 The corresponding receive option 1137 getsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, &buf, &len); 1139 returns a buffer with one or more ancillary data objects for all the 1140 optional receive information that the application has previously 1141 specified that it wants to receive. The fourth argument points to 1142 the buffer that is filled in by the call. The fifth argument is a 1143 pointer to a value-result integer: when the function is called the 1144 integer specifies the size of the buffer pointed to by the fourth 1145 argument, and on return this integer contains the actual number of 1146 bytes that were returned. The application processes this buffer 1147 exactly as if the buffer were returned by recvmsg() as control 1148 information. 1150 To simplify this document, in the remaining sections when we say "can 1151 be specified as ancillary data to sendmsg()" we mean "can be 1152 specified as ancillary data to sendmsg() or specified as a sticky 1153 option using setsockopt() and the IPV6_PKTOPTIONS socket option". 1154 Similarly when we say "can be returned as ancillary data by 1155 recvmsg()" we mean "can be returned as ancillary data by recvmsg() or 1156 returned by getsockopt() with the IPV6_PKTOPTIONS socket option". 1158 4.5.1. TCP Sticky Options 1160 When using getsockopt() with the IPV6_PKTOPTIONS option and a TCP 1161 socket, only the options from the most recently received segment are 1162 retained and returned to the caller, and only after the socket option 1163 has been set. That is, TCP need not start saving a copy of the 1164 options until the application says to do so. 1166 The application is not allowed to specify ancillary data in a call to 1167 sendmsg() on a TCP socket, and none of the ancillary data that we 1168 describe in this document is ever returned as control information by 1169 recvmsg() on a TCP socket. 1171 4.5.2. UDP and Raw Socket Sticky Options 1173 The IPV6_PKTOPTIONS socket option can also be used with a UDP socket 1174 or with a raw IPv6 socket, normally to set some of the options once, 1175 instead of with each call to sendmsg(). 1177 Unlike the TCP case, the sticky options can be overridden on a per- 1178 packet basis with ancillary data specified in a call to sendmsg() on 1179 a UDP or raw IPv6 socket. If any ancillary data is specified in a 1180 call to sendmsg(), none of the sticky options are sent with that 1181 datagram. 1183 5. Packet Information 1185 There are four pieces of information that an application can specify 1186 for an outgoing packet using ancillary data: 1188 1. the source IPv6 address, 1189 2. the outgoing interface index, 1190 3. the outgoing hop limit, and 1191 4. the next hop address. 1193 Three similar pieces of information can be returned for a received 1194 packet as ancillary data: 1196 1. the destination IPv6 address, 1197 2. the arriving interface index, and 1198 3. the arriving hop limit. 1200 The first two pieces of information are contained in an in6_pktinfo 1201 structure that is sent as ancillary data with sendmsg() and received 1202 as ancillary data with recvmsg(). This structure is defined as a 1203 result of including the header. 1205 struct in6_pktinfo { 1206 struct in6_addr ipi6_addr; /* src/dst IPv6 address */ 1207 int ipi6_ifindex; /* send/recv interface index */ 1208 }; 1210 In the cmsghdr structure containing this ancillary data, the 1211 cmsg_level member will be IPPROTO_IPV6, the cmsg_type member will be 1212 IPV6_PKTINFO, and the first byte of cmsg_data[] will be the first 1213 byte of the in6_pktinfo structure. 1215 This information is returned as ancillary data by recvmsg() only if 1216 the application has enabled the IPV6_PKTINFO socket option: 1218 int on = 1; 1219 setsockopt(fd, IPPROTO_IPV6, IPV6_PKTINFO, &on, sizeof(on)); 1221 Nothing special need be done to send this information: just specify 1222 the control information as ancillary data for sendmsg(). 1224 (Note: The hop limit is not contained in the in6_pktinfo structure 1225 for the following reason. Some UDP servers want to respond to client 1226 requests by sending their reply out the same interface on which the 1227 request was received and with the source IPv6 address of the reply 1228 equal to the destination IPv6 address of the request. To do this the 1229 application can enable just the IPV6_PKTINFO socket option and then 1230 use the received control information from recvmsg() as the outgoing 1231 control information for sendmsg(). The application need not examine 1232 or modify the in6_pktinfo structure at all. But if the hop limit 1233 were contained in this structure, the application would have to parse 1234 the received control information and change the hop limit member, 1235 since the received hop limit is not the desired value for an outgoing 1236 packet.) 1238 5.1. Specifying/Receiving the Interface 1240 Interfaces on an IPv6 node are identified by a small positive 1241 integer, as described in Section 4 of [RFC-2133]. That document also 1242 describes a function to map an interface name to its interface index, 1243 a function to map an interface index to its interface name, and a 1244 function to return all the interface names and indexes. Notice from 1245 this document that no interface is ever assigned an index of 0. 1247 When specifying the outgoing interface, if the ipi6_ifindex value is 1248 0, the kernel will choose the outgoing interface. If the application 1249 specifies an outgoing interface for a multicast packet, the interface 1250 specified by the ancillary data overrides any interface specified by 1251 the IPV6_MULTICAST_IF socket option (described in [RFC-2133]), for 1252 that call to sendmsg() only. 1254 When the IPV6_PKTINFO socket option is enabled, the received 1255 interface index is always returned as the ipi6_ifindex member of the 1256 in6_pktinfo structure. 1258 5.2. Specifying/Receiving Source/Destination Address 1260 The source IPv6 address can be specified by calling bind() before 1261 each output operation, but supplying the source address together with 1262 the data requires less overhead (i.e., fewer system calls) and 1263 requires less state to be stored and protected in a multithreaded 1264 application. 1266 When specifying the source IPv6 address as ancillary data, if the 1267 ipi6_addr member of the in6_pktinfo structure is the unspecified 1268 address (IN6ADDR_ANY_INIT), then (a) if an address is currently bound 1269 to the socket, it is used as the source address, or (b) if no address 1270 is currently bound to the socket, the kernel will choose the source 1271 address. If the ipi6_addr member is not the unspecified address, but 1272 the socket has already bound a source address, then the ipi6_addr 1273 value overrides the already-bound source address for this output 1274 operation only. 1276 The kernel must verify that the requested source address is indeed a 1277 unicast address assigned to the node. 1279 When the in6_pktinfo structure is returned as ancillary data by 1280 recvmsg(), the ipi6_addr member contains the destination IPv6 address 1281 from the received packet. 1283 5.3. Specifying/Receiving the Hop Limit 1285 The outgoing hop limit is normally specified with either the 1286 IPV6_UNICAST_HOPS socket option or the IPV6_MULTICAST_HOPS socket 1287 option, both of which are described in [RFC-2133]. Specifying the 1288 hop limit as ancillary data lets the application override either the 1289 kernel's default or a previously specified value, for either a 1290 unicast destination or a multicast destination, for a single output 1291 operation. Returning the received hop limit is useful for programs 1292 such as Traceroute and for IPv6 applications that need to verify that 1293 the received hop limit is 255 (e.g., that the packet has not been 1294 forwarded). 1296 The received hop limit is returned as ancillary data by recvmsg() 1297 only if the application has enabled the IPV6_HOPLIMIT socket option: 1299 int on = 1; 1300 setsockopt(fd, IPPROTO_IPV6, IPV6_HOPLIMIT, &on, sizeof(on)); 1302 In the cmsghdr structure containing this ancillary data, the 1303 cmsg_level member will be IPPROTO_IPV6, the cmsg_type member will be 1304 IPV6_HOPLIMIT, and the first byte of cmsg_data[] will be the first 1305 byte of the integer hop limit. 1307 Nothing special need be done to specify the outgoing hop limit: just 1308 specify the control information as ancillary data for sendmsg(). As 1309 specified in [RFC-2133], the interpretation of the integer hop limit 1310 value is 1312 x < -1: return an error of EINVAL 1313 x == -1: use kernel default 1314 0 <= x <= 255: use x 1315 x >= 256: return an error of EINVAL 1317 5.4. Specifying the Next Hop Address 1319 The IPV6_NEXTHOP ancillary data object specifies the next hop for the 1320 datagram as a socket address structure. In the cmsghdr structure 1321 containing this ancillary data, the cmsg_level member will be 1322 IPPROTO_IPV6, the cmsg_type member will be IPV6_NEXTHOP, and the 1323 first byte of cmsg_data[] will be the first byte of the socket 1324 address structure. 1326 This is a privileged option. (Note: It is implementation defined and 1327 beyond the scope of this document to define what "privileged" means. 1328 Unix systems use this term to mean the process must have an effective 1329 user ID of 0.) 1331 If the socket address structure contains an IPv6 address (e.g., the 1332 sin6_family member is AF_INET6), then the node identified by that 1333 address must be a neighbor of the sending host. If that address 1334 equals the destination IPv6 address of the datagram, then this is 1335 equivalent to the existing SO_DONTROUTE socket option. 1337 5.5. Additional Errors with sendmsg() 1339 With the IPV6_PKTINFO socket option there are no additional errors 1340 possible with the call to recvmsg(). But when specifying the 1341 outgoing interface or the source address, additional errors are 1342 possible from sendmsg(). The following are examples, but some of 1343 these may not be provided by some implementations, and some 1344 implementations may define additional errors: 1346 ENXIO The interface specified by ipi6_ifindex does not exist. 1348 ENETDOWN The interface specified by ipi6_ifindex is not enabled 1349 for IPv6 use. 1351 EADDRNOTAVAIL ipi6_ifindex specifies an interface but the address 1352 ipi6_addr is not available for use on that interface. 1354 EHOSTUNREACH No route to the destination exists over the interface 1355 specified by ifi6_ifindex. 1357 6. Hop-By-Hop Options 1359 A variable number of Hop-by-Hop options can appear in a single Hop- 1360 by-Hop options header. Each option in the header is TLV-encoded with 1361 a type, length, and value. 1363 Today only three Hop-by-Hop options are defined for IPv6 [RFC-1883]: 1364 Jumbo Payload, Pad1, and PadN, although a proposal exists for a 1365 router-alert Hop-by-Hop option. The Jumbo Payload option should not 1366 be passed back to an application and an application should receive an 1367 error if it attempts to set it. This option is processed entirely by 1368 the kernel. It is indirectly specified by datagram-based 1369 applications as the size of the datagram to send and indirectly 1370 passed back to these applications as the length of the received 1371 datagram. The two pad options are for alignment purposes and are 1372 automatically inserted by a sending kernel when needed and ignored by 1373 the receiving kernel. This section of the API is therefore defined 1374 for future Hop-by-Hop options that an application may need to specify 1375 and receive. 1377 Individual Hop-by-Hop options (and Destination options, which are 1378 described shortly, and which are similar to the Hop-by-Hop options) 1379 may have specific alignment requirements. For example, the 4-byte 1380 Jumbo Payload length should appear on a 4-byte boundary, and IPv6 1381 addresses are normally aligned on an 8-byte boundary. These 1382 requirements and the terminology used with these options are 1383 discussed in Section 4.2 and Appendix A of [RFC-1883]. The alignment 1384 of each option is specified by two values, called x and y, written as 1385 "xn + y". This states that the option must appear at an integer 1386 multiple of x bytes from the beginning of the options header (x can 1387 have the values 1, 2, 4, or 8), plus y bytes (y can have a value 1388 between 0 and 7, inclusive). The Pad1 and PadN options are inserted 1389 as needed to maintain the required alignment. Whatever code builds 1390 either a Hop-by-Hop options header or a Destination options header 1391 must know the values of x and y for each option. 1393 Multiple Hop-by-Hop options can be specified by the application. 1394 Normally one ancillary data object describes all the Hop-by-Hop 1395 options (since each option is itself TLV-encoded) but the application 1396 can specify multiple ancillary data objects for the Hop-by-Hop 1397 options, each object specifying one or more options. Care must be 1398 taken designing the API for these options since 1400 1. it may be possible for some future Hop-by-Hop options to be 1401 generated by the application and processed entirely by the 1402 application (e.g., the kernel may not know the alignment 1403 restrictions for the option), 1405 2. it must be possible for the kernel to insert its own Hop-by-Hop 1406 options in an outgoing packet (e.g., the Jumbo Payload option), 1408 3. the application can place one or more Hop-by-Hop options into a 1409 single ancillary data object, 1411 3. if the application specifies multiple ancillary data objects, 1412 each containing one or more Hop-by-Hop options, the kernel must 1413 combine these a single Hop-by-Hop options header, and 1415 4. it must be possible for the kernel to remove some Hop-by-Hop 1416 options from a received packet before returning the remaining 1417 Hop-by-Hop options to the application. (This removal might 1418 consist of the kernel converting the option into a pad option of 1419 the same length.) 1421 Finally, we note that access to some Hop-by-Hop options or to some 1422 Destination options, might require special privilege. That is, 1423 normal applications (without special privilege) might be forbidden 1424 from setting certain options in outgoing packets, and might never see 1425 certain options in received packets. 1427 6.1. Receiving Hop-by-Hop Options 1429 To receive Hop-by-Hop options the application must enable the 1430 IPV6_HOPOPTS socket option: 1432 int on = 1; 1433 setsockopt(fd, IPPROTO_IPV6, IPV6_HOPOPTS, &on, sizeof(on)); 1435 All the Hop-by-Hop options are returned as one ancillary data object 1436 described by a cmsghdr structure. The cmsg_level member will be 1437 IPPROTO_IPV6 and the cmsg_type member will be IPV6_HOPOPTS. These 1438 options are then processed by calling the inet6_option_next() and 1439 inet6_option_find() functions, described shortly. 1441 6.2. Sending Hop-by-Hop Options 1443 To send one or more Hop-by-Hop options, the application just 1444 specifies them as ancillary data in a call to sendmsg(). No socket 1445 option need be set. 1447 Normally all the Hop-by-Hop options are specified by a single 1448 ancillary data object. Multiple ancillary data objects, each 1449 containing one or more Hop-by-Hop options, can also be specified, in 1450 which case the kernel will combine all the Hop-by-Hop options into a 1451 single Hop-by-Hop extension header. But it should be more efficient 1452 to use a single ancillary data object to describe all the Hop-by-Hop 1453 options. The cmsg_level member is set to IPPROTO_IPV6 and the 1454 cmsg_type member is set to IPV6_HOPOPTS. The option is normally 1455 constructed using the inet6_option_init(), inet6_option_append(), and 1456 inet6_option_alloc() functions, described shortly. 1458 Additional errors may be possible from sendmsg() if the specified 1459 option is in error. 1461 6.3. Hop-by-Hop and Destination Options Processing 1463 Building and parsing the Hop-by-Hop and Destination options is 1464 complicated for the reasons given earlier. We therefore define a set 1465 of functions to help the application. The function prototypes for 1466 these functions are all in the header. 1468 6.3.1. inet6_option_space 1469 int inet6_option_space(int nbytes); 1471 This function returns the number of bytes required to hold an option 1472 when it is stored as ancillary data, including the cmsghdr structure 1473 at the beginning, and any padding at the end (to make its size a 1474 multiple of 8 bytes). The argument is the size of the structure 1475 defining the option, which must include any pad bytes at the 1476 beginning (the value y in the alignment term "xn + y"), the type 1477 byte, the length byte, and the option data. 1479 (Note: If multiple options are stored in a single ancillary data 1480 object, which is the recommended technique, this function 1481 overestimates the amount of space required by the size of N-1 cmsghdr 1482 structures, where N is the number of options to be stored in the 1483 object. This is of little consequence, since it is assumed that most 1484 Hop-by-Hop option headers and Destination option headers carry only 1485 one option (p. 33 of [RFC-1883]).) 1487 6.3.2. inet6_option_init 1489 int inet6_option_init(void *bp, struct cmsghdr **cmsgp, int type); 1491 This function is called once per ancillary data object that will 1492 contain either Hop-by-Hop or Destination options. It returns 0 on 1493 success or -1 on an error. 1495 bp is a pointer to previously allocated space that will contain the 1496 ancillary data object. It must be large enough to contain all the 1497 individual options to be added by later calls to 1498 inet6_option_append() and inet6_option_alloc(). 1500 cmsgp is a pointer to a pointer to a cmsghdr structure. *cmsgp is 1501 initialized by this function to point to the cmsghdr structure 1502 constructed by this function in the buffer pointed to by bp. 1504 type is either IPV6_HOPOPTS or IPV6_DSTOPTS. This type is stored in 1505 the cmsg_type member of the cmsghdr structure pointed to by *cmsgp. 1507 6.3.3. inet6_option_append 1509 int inet6_option_append(struct cmsghdr *cmsg, const uint8_t *typep, 1510 int multx, int plusy); 1512 This function appends a Hop-by-Hop option or a Destination option 1513 into an ancillary data object that has been initialized by 1514 inet6_option_init(). This function returns 0 if it succeeds or -1 on 1515 an error. 1517 cmsg is a pointer to the cmsghdr structure that must have been 1518 initialized by inet6_option_init(). 1520 typep is a pointer to the 8-bit option type. It is assumed that this 1521 field is immediately followed by the 8-bit option data length field, 1522 which is then followed immediately by the option data. The caller 1523 initializes these three fields (the type-length-value, or TLV) before 1524 calling this function. 1526 The option type must have a value from 2 to 255, inclusive. (0 and 1 1527 are reserved for the Pad1 and PadN options, respectively.) 1529 The option data length must have a value between 0 and 255, 1530 inclusive, and is the length of the option data that follows. 1532 multx is the value x in the alignment term "xn + y" described 1533 earlier. It must have a value of 1, 2, 4, or 8. 1535 plusy is the value y in the alignment term "xn + y" described 1536 earlier. It must have a value between 0 and 7, inclusive. 1538 6.3.4. inet6_option_alloc 1540 uint8_t *inet6_option_alloc(struct cmsghdr *cmsg, int datalen, 1541 int multx, int plusy); 1543 This function appends a Hop-by-Hop option or a Destination option 1544 into an ancillary data object that has been initialized by 1545 inet6_option_init(). This function returns a pointer to the 8-bit 1546 option type field that starts the option on success, or NULL on an 1547 error. 1549 The difference between this function and inet6_option_append() is 1550 that the latter copies the contents of a previously built option into 1551 the ancillary data object while the current function returns a 1552 pointer to the space in the data object where the option's TLV must 1553 then be built by the caller. 1555 cmsg is a pointer to the cmsghdr structure that must have been 1556 initialized by inet6_option_init(). 1558 datalen is the value of the option data length byte for this option. 1559 This value is required as an argument to allow the function to 1560 determine if padding must be appended at the end of the option. (The 1561 inet6_option_append() function does not need a data length argument 1562 since the option data length must already be stored by the caller.) 1564 multx is the value x in the alignment term "xn + y" described 1565 earlier. It must have a value of 1, 2, 4, or 8. 1567 plusy is the value y in the alignment term "xn + y" described 1568 earlier. It must have a value between 0 and 7, inclusive. 1570 6.3.5. inet6_option_next 1572 int inet6_option_next(const struct cmsghdr *cmsg, uint8_t **tptrp); 1574 This function processes the next Hop-by-Hop option or Destination 1575 option in an ancillary data object. If another option remains to be 1576 processed, the return value of the function is 0 and *tptrp points to 1577 the 8-bit option type field (which is followed by the 8-bit option 1578 data length, followed by the option data). If no more options remain 1579 to be processed, the return value is -1 and *tptrp is NULL. If an 1580 error occurs, the return value is -1 and *tptrp is not NULL. 1582 cmsg is a pointer to cmsghdr structure of which cmsg_level equals 1583 IPPROTO_IPV6 and cmsg_type equals either IPV6_HOPOPTS or 1584 IPV6_DSTOPTS. 1586 tptrp is a pointer to a pointer to an 8-bit byte and *tptrp is used 1587 by the function to remember its place in the ancillary data object 1588 each time the function is called. The first time this function is 1589 called for a given ancillary data object, *tptrp must be set to NULL. 1590 Each time this function returns success, *tptrp points to the 8-bit 1591 option type field for the next option to be processed. 1593 6.3.6. inet6_option_find 1595 int inet6_option_find(const struct cmsghdr *cmsg, uint8_t *tptrp, 1596 int type); 1598 This function is similar to the previously described 1599 inet6_option_next() function, except this function lets the caller 1600 specify the option type to be searched for, instead of always 1601 returning the next option in the ancillary data object. 1603 cmsg is a pointer to cmsghdr structure of which cmsg_level equals 1604 IPPROTO_IPV6 and cmsg_type equals either IPV6_HOPOPTS or 1605 IPV6_DSTOPTS. 1607 tptrp is a pointer to a pointer to an 8-bit byte and *tptrp is used 1608 by the function to remember its place in the ancillary data object 1609 each time the function is called. The first time this function is 1610 called for a given ancillary data object, *tptrp must be set to NULL. 1612 This function starts searching for an option of the specified type 1613 beginning after the value of *tptrp. If an option of the specified 1614 type is located, this function returns 0 and *tptrp points to the 1615 8-bit option type field for the option of the specified type. If an 1616 option of the specified type is not located, the return value is -1 1617 and *tptrp is NULL. If an error occurs, the return value is -1 and 1618 *tptrp is not NULL. 1620 6.3.7. Options Examples 1622 We now provide an example that builds two Hop-by-Hop options. First 1623 we define two options, called X and Y, taken from the example in 1624 Appendix A of [RFC-1883]. We assume that all options will have 1625 structure definitions similar to what is shown below. 1627 /* option X and option Y are defined in [RFC-1883], pp. 33-34 */ 1628 #define IP6_X_OPT_TYPE X /* replace X with assigned value */ 1629 #define IP6_X_OPT_LEN 12 1630 #define IP6_X_OPT_MULTX 8 /* 8n + 2 alignment */ 1631 #define IP6_X_OPT_OFFSETY 2 1633 struct ip6_X_opt { 1634 uint8_t ip6_X_opt_pad[IP6_X_OPT_OFFSETY]; 1635 uint8_t ip6_X_opt_type; 1636 uint8_t ip6_X_opt_len; 1637 uint32_t ip6_X_opt_val1; 1638 uint64_t ip6_X_opt_val2; 1639 }; 1641 #define IP6_Y_OPT_TYPE Y /* replace Y with assigned value */ 1642 #define IP6_Y_OPT_LEN 7 1643 #define IP6_Y_OPT_MULTX 4 /* 4n + 3 alignment */ 1644 #define IP6_Y_OPT_OFFSETY 3 1646 struct ip6_Y_opt { 1647 uint8_t ip6_Y_opt_pad[IP6_Y_OPT_OFFSETY]; 1648 uint8_t ip6_Y_opt_type; 1649 uint8_t ip6_Y_opt_len; 1650 uint8_t ip6_Y_opt_val1; 1651 uint16_t ip6_Y_opt_val2; 1652 uint32_t ip6_Y_opt_val3; 1653 }; 1655 We now show the code fragment to build one ancillary data object 1656 containing both options. 1658 struct msghdr msg; 1659 struct cmsghdr *cmsgptr; 1660 struct ip6_X_opt optX; 1661 struct ip6_Y_opt optY; 1663 msg.msg_control = inet6_option_space(sizeof(optX) + sizeof(optY)); 1665 inet6_option_init(msg.msg_control, &cmsgptr, IPV6_HOPOPTS); 1667 optX.ip6_X_opt_type = IP6_X_OPT_TYPE; 1668 optX.ip6_X_opt_len = IP6_X_OPT_LEN; 1669 optX.ip6_X_opt_val1 = <32-bit value>; 1670 optX.ip6_X_opt_val2 = <64-bit value>; 1671 inet6_option_append(cmsgptr, &optX.ip6_X_opt_type, 1672 IP6_X_OPT_MULTX, IP6_X_OPT_OFFSETY); 1674 optY.ip6_Y_opt_type = IP6_Y_OPT_TYPE; 1675 optY.ip6_Y_opt_len = IP6_Y_OPT_LEN; 1676 optY.ip6_Y_opt_val1 = <8-bit value>; 1677 optY.ip6_Y_opt_val2 = <16-bit value>; 1678 optY.ip6_Y_opt_val3 = <32-bit value>; 1679 inet6_option_append(cmsgptr, &optY.ip6_Y_opt_type, 1680 IP6_Y_OPT_MULTX, IP6_Y_OPT_OFFSETY); 1682 msg.msg_controllen = CMSG_LEN(cmsgptr->cmsg_len); 1684 The call to inet6_option_init() builds the cmsghdr structure in the 1685 control buffer. 1687 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1688 | cmsg_len = CMSG_LEN(0) = 12 | 1689 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1690 | cmsg_level = IPPROTO_IPV6 | 1691 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1692 | cmsg_type = IPV6_HOPOPTS | 1693 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1695 Here we assume a 32-bit architecture where sizeof(struct cmsghdr) 1696 equals 12, with a desired alignment of 4-byte boundaries (that is, 1697 the ALIGN() macro shown in the sample implementations of the 1698 CMSG_xxx() macros rounds up to a multiple of 4). 1700 The first call to inet6_option_append() appends the X option. Since 1701 this is the first option in the ancillary data object, 2 bytes are 1702 allocated for the Next Header byte and for the Hdr Ext Len byte. The 1703 former will be set by the kernel, depending on the type of header 1704 that follows this header, and the latter byte is set to 1. These 2 1705 bytes form the 2 bytes of padding (IP6_X_OPT_OFFSETY) required at the 1706 beginning of this option. 1708 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1709 | cmsg_len = 28 | 1710 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1711 | cmsg_level = IPPROTO_IPV6 | 1712 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1713 | cmsg_type = IPV6_HOPOPTS | 1714 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1715 | Next Header | Hdr Ext Len=1 | Option Type=X |Opt Data Len=12| 1716 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1717 | 4-octet field | 1718 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1719 | | 1720 + 8-octet field + 1721 | | 1722 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1724 The cmsg_len member of the cmsghdr structure is incremented by 16, 1725 the size of the option. 1727 The next call to inet6_option_append() appends the Y option to the 1728 ancillary data object. 1730 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1731 | cmsg_len = 44 | 1732 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1733 | cmsg_level = IPPROTO_IPV6 | 1734 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1735 | cmsg_type = IPV6_HOPOPTS | 1736 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1737 | Next Header | Hdr Ext Len=3 | Option Type=X |Opt Data Len=12| 1738 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1739 | 4-octet field | 1740 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1741 | | 1742 + 8-octet field + 1743 | | 1744 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1745 | PadN Option=1 |Opt Data Len=1 | 0 | Option Type=Y | 1746 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1747 |Opt Data Len=7 | 1-octet field | 2-octet field | 1748 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1749 | 4-octet field | 1750 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1751 | PadN Option=1 |Opt Data Len=2 | 0 | 0 | 1752 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1754 16 bytes are appended by this function, so cmsg_len becomes 44. The 1755 inet6_option_append() function notices that the appended data 1756 requires 4 bytes of padding at the end, to make the size of the 1757 ancillary data object a multiple of 8, and appends the PadN option 1758 before returning. The Hdr Ext Len byte is incremented by 2 to become 1759 3. 1761 Alternately, the application could build two ancillary data objects, 1762 one per option, although this will probably be less efficient than 1763 combining the two options into a single ancillary data object (as 1764 just shown). The kernel must combine these into a single Hop-by-Hop 1765 extension header in the final IPv6 packet. 1767 struct msghdr msg; 1768 struct cmsghdr *cmsgptr; 1769 struct ip6_X_opt optX; 1770 struct ip6_Y_opt optY; 1772 msg.msg_control = inet6_option_space(sizeof(optX)) + 1773 inet6_option_space(sizeof(optY)); 1775 inet6_option_init(msg.msg_control, &cmsgptr, IPPROTO_HOPOPTS); 1777 optX.ip6_X_opt_type = IP6_X_OPT_TYPE; 1778 optX.ip6_X_opt_len = IP6_X_OPT_LEN; 1779 optX.ip6_X_opt_val1 = <32-bit value>; 1780 optX.ip6_X_opt_val2 = <64-bit value>; 1781 inet6_option_append(cmsgptr, &optX.ip6_X_opt_type, 1782 IP6_X_OPT_MULTX, IP6_X_OPT_OFFSETY); 1783 msg.msg_controllen = CMSG_SPACE(cmsgptr->cmsg_len); 1785 inet6_option_init((u_char *)msg.msg_control + msg.msg_controllen, 1786 &cmsgptr, IPPROTO_HOPOPTS); 1788 optY.ip6_Y_opt_type = IP6_Y_OPT_TYPE; 1789 optY.ip6_Y_opt_len = IP6_Y_OPT_LEN; 1790 optY.ip6_Y_opt_val1 = <8-bit value>; 1791 optY.ip6_Y_opt_val2 = <16-bit value>; 1792 optY.ip6_Y_opt_val3 = <32-bit value>; 1793 inet6_option_append(cmsgptr, &optY.ip6_Y_opt_type, 1794 IP6_Y_OPT_MULTX, IP6_Y_OPT_OFFSETY); 1795 msg.msg_controllen += CMSG_LEN(cmsgptr->cmsg_len); 1797 Each call to inet6_option_init() builds a new cmsghdr structure, and 1798 the final result looks like the following: 1800 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1801 | cmsg_len = 28 | 1802 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1803 | cmsg_level = IPPROTO_IPV6 | 1804 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1805 | cmsg_type = IPV6_HOPOPTS | 1806 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1807 | Next Header | Hdr Ext Len=1 | Option Type=X |Opt Data Len=12| 1808 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1809 | 4-octet field | 1810 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1811 | | 1812 + 8-octet field + 1813 | | 1814 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1815 | cmsg_len = 28 | 1816 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1817 | cmsg_level = IPPROTO_IPV6 | 1818 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1819 | cmsg_type = IPV6_HOPOPTS | 1820 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1821 | Next Header | Hdr Ext Len=1 | Pad1 Option=0 | Option Type=Y | 1822 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1823 |Opt Data Len=7 | 1-octet field | 2-octet field | 1824 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1825 | 4-octet field | 1826 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1827 | PadN Option=1 |Opt Data Len=2 | 0 | 0 | 1828 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 1830 When the kernel combines these two options into a single Hop-by-Hop 1831 extension header, the first 3 bytes of the second ancillary data 1832 object (the Next Header byte, the Hdr Ext Len byte, and the Pad1 1833 option) will be combined into a PadN option occupying 3 bytes. 1835 The following code fragment is a redo of the first example shown 1836 (building two options in a single ancillary data object) but this 1837 time we use inet6_option_alloc(). 1839 uint8_t *typep; 1840 struct msghdr msg; 1841 struct cmsghdr *cmsgptr; 1842 struct ip6_X_opt *optXp; /* now a pointer, not a struct */ 1843 struct ip6_Y_opt *optYp; /* now a pointer, not a struct */ 1845 msg.msg_control = inet_option_space(sizeof(*optXp) + sizeof(*optYp)); 1846 inet6_option_init(msg.msg_control, &cmsgptr, IPV6_HOPOPTS); 1848 typep = inet6_option_alloc(cmsgptr, IP6_X_OPT_LEN, 1849 IP6_X_OPT_MULTX, IP6_X_OPT_OFFSETY); 1850 optXp = (struct ip6_X_opt *) (typep - IP6_X_OPT_OFFSETY); 1851 optXp->ip6_X_opt_type = IP6_X_OPT_TYPE; 1852 optXp->ip6_X_opt_len = IP6_X_OPT_LEN; 1853 optXp->ip6_X_opt_val1 = <32-bit value>; 1854 optXp->ip6_X_opt_val2 = <64-bit value>; 1856 typep = inet6_option_alloc(cmsgptr, IP6_Y_OPT_LEN, 1857 IP6_Y_OPT_MULTX, IP6_Y_OPT_OFFSETY); 1858 optYp = (struct ip6_Y_opt *) (typep - IP6_Y_OPT_OFFSETY); 1859 optYp->ip6_Y_opt_type = IP6_Y_OPT_TYPE; 1860 optYp->ip6_Y_opt_len = IP6_Y_OPT_LEN; 1861 optYp->ip6_Y_opt_val1 = <8-bit value>; 1862 optYp->ip6_Y_opt_val2 = <16-bit value>; 1863 optYp->ip6_Y_opt_val3 = <32-bit value>; 1865 msg.msg_controllen = CMSG_LEN(cmsgptr->cmsg_len); 1867 Notice that inet6_option_alloc() returns a pointer to the 8-bit 1868 option type field. If the program wants a pointer to an option 1869 structure that includes the padding at the front (as shown in our 1870 definitions of the ip6_X_opt and ip6_Y_opt structures), the y-offset 1871 at the beginning of the structure must be subtracted from the 1872 returned pointer. 1874 The following code fragment shows the processing of Hop-by-Hop 1875 options using the inet6_option_next() function. 1877 struct msghdr msg; 1878 struct cmsghdr *cmsgptr; 1880 /* fill in msg */ 1882 /* call recvmsg() */ 1884 for (cmsgptr = CMSG_FIRSTHDR(&msg); cmsgptr != NULL; 1885 cmsgptr = CMSG_NXTHDR(&msg, cmsgptr)) { 1886 if (cmsgptr->cmsg_level == IPPROTO_IPV6 && 1887 cmsgptr->cmsg_type == IPV6_HOPOPTS) { 1889 uint8_t *tptr = NULL; 1891 while (inet6_option_next(cmsgptr, &tptr) == 0) { 1892 if (*tptr == IP6_X_OPT_TYPE) { 1893 struct ip6_X_opt *optXp; 1894 optXp = (struct ip6_X_opt *) (tptr - IP6_X_OPT_OFFSETY); 1895 optXp->ip6_X_opt_val1; 1896 optXp->ip6_X_opt_val2; 1898 } else if (*tptr == IP6_Y_OPT_TYPE) { 1899 struct ip6_Y_opt *optYp; 1901 optYp = (struct ip6_Y_opt *) (tptr - IP6_Y_OPT_OFFSETY); 1902 optYp->ip6_Y_opt_val1; 1903 optYp->ip6_Y_opt_val2; 1904 optYp->ip6_Y_opt_val3; 1905 } 1906 } 1907 if (tptr != NULL) 1908 ; 1909 } 1910 } 1912 7. Destination Options 1914 A variable number of Destination options can appear in one or more 1915 Destination option headers. As defined in [RFC-1883], a Destination 1916 options header appearing before a Routing header is processed by the 1917 first destination plus any subsequent destinations specified in the 1918 Routing header, while a Destination options header appearing after a 1919 Routing header is processed only by the final destination. As with 1920 the Hop-by-Hop options, each option in a Destination options header 1921 is TLV-encoded with a type, length, and value. 1923 Today no Destination options are defined for IPv6 [RFC-1883], 1924 although proposals exist to use Destination options with mobility and 1925 anycasting. 1927 7.1. Receiving Destination Options 1929 To receive Destination options the application must enable the 1930 IPV6_DSTOPTS socket option: 1932 int on = 1; 1933 setsockopt(fd, IPPROTO_IPV6, IPV6_DSTOPTS, &on, sizeof(on)); 1935 All the Destination options appearing before a Routing header are 1936 returned as one ancillary data object described by a cmsghdr 1937 structure and all the Destination options appearing after a Routing 1938 header are returned as another ancillary data object described by a 1939 cmsghdr structure. For these ancillary data objects, the cmsg_level 1940 member will be IPPROTO_IPV6 and the cmsg_type member will be 1941 IPV6_HOPOPTS. These options are then processed by calling the 1942 inet6_option_next() and inet6_option_find() functions. 1944 7.2. Sending Destination Options 1946 To send one or more Destination options, the application just 1947 specifies them as ancillary data in a call to sendmsg(). No socket 1948 option need be set. 1950 As described earlier, one set of Destination options can appear 1951 before a Routing header, and one set can appear after a Routing 1952 header. Each set can consist of one or more options. 1954 Normally all the Destination options in a set are specified by a 1955 single ancillary data object, since each option is itself TLV- 1956 encoded. Multiple ancillary data objects, each containing one or 1957 more Destination options, can also be specified, in which case the 1958 kernel will combine all the Destination options in the set into a 1959 single Destination extension header. But it should be more efficient 1960 to use a single ancillary data object to describe all the Destination 1961 options in a set. The cmsg_level member is set to IPPROTO_IPV6 and 1962 the cmsg_type member is set to IPV6_DSTOPTS. The option is normally 1963 constructed using the inet6_option_init(), inet6_option_append(), and 1964 inet6_option_alloc() functions. 1966 Additional errors may be possible from sendmsg() if the specified 1967 option is in error. 1969 8. Routing Header Option 1971 Source routing in IPv6 is accomplished by specifying a Routing header 1972 as an extension header. There can be different types of Routing 1973 headers, but IPv6 currently defines only the Type 0 Routing header 1974 [RFC-1883]. This type supports up to 23 intermediate nodes. With 1975 this maximum number of intermediate nodes, a source, and a 1976 destination, there are 24 hops, each of which is defined as a strict 1977 or loose hop. 1979 Source routing with IPv4 sockets API (the IP_OPTIONS socket option) 1980 requires the application to build the source route in the format that 1981 appears as the IPv4 header option, requiring intimate knowledge of 1982 the IPv4 options format. This IPv6 API, however, defines eight 1983 functions that the application calls to build and examine a Routing 1984 header. Four functions build a Routing header: 1986 inet6_rthdr_space() - return #bytes required for ancillary data 1987 inet6_rthdr_init() - initialize ancillary data for Routing header 1988 inet6_rthdr_add() - add IPv6 address & flags to Routing header 1989 inet6_rthdr_lasthop() - specify the flags for the final hop 1991 Four functions deal with a returned Routing header: 1993 inet6_rthdr_reverse() - reverse a Routing header 1994 inet6_rthdr_segments() - return #segments in a Routing header 1995 inet6_rthdr_getaddr() - fetch one address from a Routing header 1996 inet6_rthdr_getflags() - fetch one flag from a Routing header 1998 The function prototypes for these functions are all in the 1999 header. 2001 To receive a Routing header the application must enable the 2002 IPV6_RTHDR socket option: 2004 int on = 1; 2005 setsockopt(fd, IPPROTO_IPV6, IPV6_RTHDR, &on, sizeof(on)); 2007 To send a Routing header the application just specifies it as 2008 ancillary data in a call to sendmsg(). 2010 A Routing header is passed between the application and the kernel as 2011 an ancillary data object. The cmsg_level member has a value of 2012 IPPROTO_IPV6 and the cmsg_type member has a value of IPV6_RTHDR. The 2013 contents of the cmsg_data[] member is implementation dependent and 2014 should not be accessed directly by the application, but should be 2015 accessed using the eight functions that we are about to describe. 2017 The following constants are defined in the header: 2019 #define IPV6_RTHDR_LOOSE 0 /* this hop need not be a neighbor */ 2020 #define IPV6_RTHDR_STRICT 1 /* this hop must be a neighbor */ 2022 #define IPV6_RTHDR_TYPE_0 0 /* IPv6 Routing header type 0 */ 2024 When a Routing header is specified, the destination address specified 2025 for connect(), sendto(), or sendmsg() is the final destination 2026 address of the datagram. The Routing header then contains the 2027 addresses of all the intermediate nodes. 2029 8.1. inet6_rthdr_space 2030 size_t inet6_rthdr_space(int type, int segments); 2032 This function returns the number of bytes required to hold a Routing 2033 header of the specified type containing the specified number of 2034 segments (addresses). For an IPv6 Type 0 Routing header, the number 2035 of segments must be between 1 and 23, inclusive. The return value 2036 includes the size of the cmsghdr structure that precedes the Routing 2037 header, and any required padding. 2039 If the return value is 0, then either the type of the Routing header 2040 is not supported by this implementation or the number of segments is 2041 invalid for this type of Routing header. 2043 (Note: This function returns the size but does not allocate the space 2044 required for the ancillary data. This allows an application to 2045 allocate a larger buffer, if other ancillary data objects are 2046 desired, since all the ancillary data objects must be specified to 2047 sendmsg() as a single msg_control buffer.) 2049 8.2. inet6_rthdr_init 2051 struct cmsghdr *inet6_rthdr_init(void *bp, int type); 2053 This function initializes the buffer pointed to by bp to contain a 2054 cmsghdr structure followed by a Routing header of the specified type. 2055 The cmsg_len member of the cmsghdr structure is initialized to the 2056 size of the structure plus the amount of space required by the 2057 Routing header. The cmsg_level and cmsg_type members are also 2058 initialized as required. 2060 The caller must allocate the buffer and its size can be determined by 2061 calling inet6_rthdr_space(). 2063 Upon success the return value is the pointer to the cmsghdr 2064 structure, and this is then used as the first argument to the next 2065 two functions. Upon an error the return value is NULL. 2067 8.3. inet6_rthdr_add 2069 int inet6_rthdr_add(struct cmsghdr *cmsg, 2070 const struct in6_addr *addr, unsigned int flags); 2072 This function adds the address pointed to by addr to the end of the 2073 Routing header being constructed and sets the type of this hop to the 2074 value of flags. For an IPv6 Type 0 Routing header, flags must be 2075 either IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT. 2077 If successful, the cmsg_len member of the cmsghdr structure is 2078 updated to account for the new address in the Routing header and the 2079 return value of the function is 0. Upon an error the return value of 2080 the function is -1. 2082 8.4. inet6_rthdr_lasthop 2084 int inet6_rthdr_lasthop(struct cmsghdr *cmsg, 2085 unsigned int flags); 2087 This function specifies the Strict/Loose flag for the final hop of a 2088 Routing header. For an IPv6 Type 0 Routing header, flags must be 2089 either IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT. 2091 The return value of the function is 0 upon success, or -1 upon an 2092 error. 2094 Notice that a Routing header specifying N intermediate nodes requires 2095 N+1 Strict/Loose flags. This requires N calls to inet6_rthdr_add() 2096 followed by one call to inet6_rthdr_lasthop(). 2098 8.5. inet6_rthdr_reverse 2100 int inet6_rthdr_reverse(const struct cmsghdr *in, struct cmsghdr *out); 2102 This function takes a Routing header that was received as ancillary 2103 data (pointed to by the first argument) and writes a new Routing 2104 header that sends datagrams along the reverse of that route. Both 2105 arguments are allowed to point to the same buffer (that is, the 2106 reversal can occur in place). 2108 The return value of the function is 0 on success, or -1 upon an 2109 error. 2111 8.6. inet6_rthdr_segments 2113 int inet6_rthdr_segments(const struct cmsghdr *cmsg) 2115 This function returns the number of segments (addresses) contained in 2116 the Routing header described by cmsg. On success the return value is 2117 between 1 and 23, inclusive. The return value of the function is -1 2118 upon an error. 2120 8.7. inet6_rthdr_getaddr 2122 struct in6_addr *inet6_rthdr_getaddr(struct cmsghdr *cmsg, int index); 2124 This function returns a pointer to the IPv6 address specified by 2125 index (which must have a value between 1 and the value returned by 2126 inet6_rthdr_segments()) in the Routing header described by cmsg. An 2127 application should first call inet6_rthdr_segments() to obtain the 2128 number of segments in the Routing header. 2130 Upon an error the return value of the function is NULL. 2132 8.8. inet6_rthdr_getflags 2134 int inet6_rthdr_getflags(const struct cmsghdr *cmsg, int index); 2136 This function returns the flags value specified by index (which must 2137 have a value between 0 and the value returned by 2138 inet6_rthdr_segments()) in the Routing header described by cmsg. For 2139 an IPv6 Type 0 Routing header the return value will be either 2140 IPV6_RTHDR_LOOSE or IPV6_RTHDR_STRICT. 2142 Upon an error the return value of the function is -1. 2144 (Note: Addresses are indexed starting at 1, and flags starting at 0, 2145 to maintain consistency with the terminology and figures in 2146 [RFC-1883].) 2148 8.9. Routing Header Example 2150 As an example of these Routing header functions, we go through the 2151 function calls for the example on p. 18 of [RFC-1883]. The source is 2152 S, the destination is D, and the three intermediate nodes are I1, I2, 2153 and I3. f0, f1, f2, and f3 are the Strict/Loose flags for each hop. 2155 f0 f1 f2 f3 2156 S -----> I1 -----> I2 -----> I3 -----> D 2158 src: * S S S S S 2159 dst: D I1 I2 I3 D D 2160 A[1]: I1 I2 I1 I1 I1 I1 2161 A[2]: I2 I3 I3 I2 I2 I2 2162 A[3]: I3 D D D I3 I3 2163 #seg: 3 3 2 1 0 3 2165 check: f0 f1 f2 f3 2167 src and dst are the source and destination IPv6 addresses in the IPv6 2168 header. A[1], A[2], and A[3] are the three addresses in the Routing 2169 header. #seg is the Segments Left field in the Routing header. 2170 check indicates which bit of the Strict/Loose Bit Map (0 through 3, 2171 specified as f0 through f3) that node checks. 2173 The six values in the column beneath node S are the values in the 2174 Routing header specified by the application using sendmsg(). The 2175 function calls by the sender would look like: 2177 void *ptr; 2178 struct msghdr msg; 2179 struct cmsghdr *cmsgptr; 2180 struct sockaddr_in6 I1, I2, I3, D; 2181 unsigned int f0, f1, f2, f3; 2183 ptr = malloc(inet6_rthdr_space(IPV6_RTHDR_TYPE_0, 3)); 2184 cmsgptr = inet6_rthdr_init(ptr, IPV6_RTHDR_TYPE_0); 2186 inet6_rthdr_add(cmsgptr, &I1.sin6_addr, f0); 2187 inet6_rthdr_add(cmsgptr, &I2.sin6_addr, f1); 2188 inet6_rthdr_add(cmsgptr, &I3.sin6_addr, f2); 2189 inet6_rthdr_lasthop(cmsgptr, f3); 2191 msg.msg_control = ptr; 2192 msg.msg_controllen = CMSG_LEN(cmsgptr->cmsg_len); 2194 /* finish filling in msg{}, msg_name = D */ 2195 /* call sendmsg() */ 2197 We also assume that the source address for the socket is not 2198 specified (i.e., the asterisk in the figure). 2200 The four columns of six values that are then shown between the five 2201 nodes are the values of the fields in the packet while the packet is 2202 in transit between the two nodes. Notice that before the packet is 2203 sent by the source node S, the source address is chosen (replacing 2204 the asterisk), I1 becomes the destination address of the datagram, 2205 the two addresses A[2] and A[3] are "shifted up", and D is moved to 2206 A[3]. If f0 is IPV6_RTHDR_STRICT, then I1 must be a neighbor of S. 2208 The columns of values that are shown beneath the destination node are 2209 the values returned by recvmsg(), assuming the application has 2210 enabled both the IPV6_PKTINFO and IPV6_RTHDR socket options. The 2211 source address is S (contained in the sockaddr_in6 structure pointed 2212 to by the msg_name member), the destination address is D (returned as 2213 an ancillary data object in an in6_pktinfo structure), and the 2214 ancillary data object specifying the Routing header will contain 2215 three addresses (I1, I2, and I3) and four flags (f0, f1, f2, and f3). 2216 The number of segments in the Routing header is known from the Hdr 2217 Ext Len field in the Routing header (a value of 6, indicating 3 2218 addresses). 2220 The return value from inet6_rthdr_segments() will be 3 and 2221 inet6_rthdr_getaddr(1) will return I1, inet6_rthdr_getaddr(2) will 2222 return I2, and inet6_rthdr_getaddr(3) will return I3, The return 2223 value from inet6_rthdr_flags(0) will be f0, inet6_rthdr_flags(1) will 2224 return f1, inet6_rthdr_flags(2) will return f2, and 2225 inet6_rthdr_flags(3) will return f3. 2227 If the receiving application then calls inet6_rthdr_reverse(), the 2228 order of the three addresses will become I3, I2, and I1, and the 2229 order of the four Strict/Loose flags will become f3, f2, f1, and f0. 2231 We can also show what an implementation might store in the ancillary 2232 data object as the Routing header is being built by the sending 2233 process. If we assume a 32-bit architecture where sizeof(struct 2234 cmsghdr) equals 12, with a desired alignment of 4-byte boundaries, 2235 then the call to inet6_rthdr_space(3) returns 68: 12 bytes for the 2236 cmsghdr structure and 56 bytes for the Routing header (8 + 3*16). 2238 The call to inet6_rthdr_init() initializes the ancillary data object 2239 to contain a Type 0 Routing header: 2241 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2242 | cmsg_len = 20 | 2243 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2244 | cmsg_level = IPPROTO_IPV6 | 2245 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2246 | cmsg_type = IPV6_RTHDR | 2247 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2248 | Next Header | Hdr Ext Len=0 | Routing Type=0| Seg Left=0 | 2249 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2250 | Reserved | Strict/Loose Bit Map | 2251 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2253 The first call to inet6_rthdr_add() adds I1 to the list. 2255 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2256 | cmsg_len = 36 | 2257 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2258 | cmsg_level = IPPROTO_IPV6 | 2259 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2260 | cmsg_type = IPV6_RTHDR | 2261 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2262 | Next Header | Hdr Ext Len=2 | Routing Type=0| Seg Left=1 | 2263 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2264 | Reserved |X| Strict/Loose Bit Map | 2265 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2266 | | 2267 + + 2268 | | 2269 + Address[1] = I1 + 2270 | | 2271 + + 2272 | | 2273 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2275 Bit 0 of the Strict/Loose Bit Map contains the value f0, which we 2276 just mark as X. cmsg_len is incremented by 16, the Hdr Ext Len field 2277 is incremented by 2, and the Segments Left field is incremented by 1. 2279 The next call to inet6_rthdr_add() adds I2 to the list. 2281 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2282 | cmsg_len = 52 | 2283 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2284 | cmsg_level = IPPROTO_IPV6 | 2285 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2286 | cmsg_type = IPV6_RTHDR | 2287 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2288 | Next Header | Hdr Ext Len=4 | Routing Type=0| Seg Left=2 | 2289 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2290 | Reserved |X|X| Strict/Loose Bit Map | 2291 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2292 | | 2293 + + 2294 | | 2295 + Address[1] = I1 + 2296 | | 2297 + + 2298 | | 2299 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2300 | | 2301 + + 2302 | | 2303 + Address[2] = I2 + 2304 | | 2305 + + 2306 | | 2307 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2309 The next bit of the Strict/Loose Bit Map contains the value f1. 2310 cmsg_len is incremented by 16, the Hdr Ext Len field is incremented 2311 by 2, and the Segments Left field is incremented by 1. 2313 The last call to inet6_rthdr_add() adds I3 to the list. 2315 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2316 | cmsg_len = 68 | 2317 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2318 | cmsg_level = IPPROTO_IPV6 | 2319 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2320 | cmsg_type = IPV6_RTHDR | 2321 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2322 | Next Header | Hdr Ext Len=6 | Routing Type=0| Seg Left=3 | 2323 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2324 | Reserved |X|X|X| Strict/Loose Bit Map | 2325 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2326 | | 2327 + + 2328 | | 2329 + Address[1] = I1 + 2330 | | 2331 + + 2332 | | 2333 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2334 | | 2335 + + 2336 | | 2337 + Address[2] = I2 + 2338 | | 2339 + + 2340 | | 2341 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2342 | | 2343 + + 2344 | | 2345 + Address[3] = I3 + 2346 | | 2347 + + 2348 | | 2349 +-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+-+ 2351 The next bit of the Strict/Loose Bit Map contains the value f2. 2352 cmsg_len is incremented by 16, the Hdr Ext Len field is incremented 2353 by 2, and the Segments Left field is incremented by 1. 2355 Finally, the call to inet6_rthdr_lasthop() sets the next bit of the 2356 Strict/Loose Bit Map to the value specified by f3. All the lengths 2357 remain unchanged. 2359 9. Ordering of Ancillary Data and IPv6 Extension Headers 2360 Three IPv6 extension headers can be specified by the application and 2361 returned to the application using ancillary data with sendmsg() and 2362 recvmsg(): Hop-by-Hop options, Destination options, and the Routing 2363 header. When multiple ancillary data objects are transferred via 2364 sendmsg() or recvmsg() and these objects represent any of these three 2365 extension headers, their placement in the control buffer is directly 2366 tied to their location in the corresponding IPv6 datagram. This API 2367 imposes some ordering constraints when using multiple ancillary data 2368 objects with sendmsg(). 2370 When multiple IPv6 Hop-by-Hop options having the same option type are 2371 specified, these options will be inserted into the Hop-by-Hop options 2372 header in the same order as they appear in the control buffer. But 2373 when multiple Hop-by-Hop options having different option types are 2374 specified, these options may be reordered by the kernel to reduce 2375 padding in the Hop-by-Hop options header. Hop-by-Hop options may 2376 appear anywhere in the control buffer and will always be collected by 2377 the kernel and placed into a single Hop-by-Hop options header that 2378 immediately follows the IPv6 header. 2380 Similar rules apply to the Destination options: (1) those of the same 2381 type will appear in the same order as they are specified, and (2) 2382 those of differing types may be reordered. But the kernel will build 2383 up to two Destination options headers: one to precede the Routing 2384 header and one to follow the Routing header. If the application 2385 specifies a Routing header then all Destination options that appear 2386 in the control buffer before the Routing header will appear in a 2387 Destination options header before the Routing header and these 2388 options might be reordered, subject to the two rules that we just 2389 stated. Similarly all Destination options that appear in the control 2390 buffer after the Routing header will appear in a Destination options 2391 header after the Routing header, and these options might be 2392 reordered, subject to the two rules that we just stated. 2394 As an example, assume that an application specifies control 2395 information to sendmsg() containing six ancillary data objects: the 2396 first containing two Hop-by-Hop options, the second containing one 2397 Destination option, the third containing two Destination options, the 2398 fourth containing a Routing header, the fifth containing a Hop-by-Hop 2399 option, and the sixth containing two Destination options. We also 2400 assume that all the Hop-by-Hop options are of different types, as are 2401 all the Destination options. We number these options 1-9, 2402 corresponding to their order in the control buffer, and show them on 2403 the left below. 2405 In the middle we show the final arrangement of the options in the 2406 extension headers built by the kernel. On the right we show the four 2407 ancillary data objects returned to the receiving application. 2409 Sender's Receiver's 2410 Ancillary Data --> IPv6 Extension --> Ancillary Data 2411 Objects Headers Objects 2412 ------------------ --------------- -------------- 2413 HOPOPT-1,2 (first) HOPHDR(J,7,1,2) HOPOPT-7,1,2 2414 DSTOPT-3 DSTHDR(4,5,3) DSTOPT-4,5,3 2415 DSTOPT-4,5 RTHDR(6) RTHDR-6 2416 RTHDR-6 DSTHDR(8,9) DSTOPT-8,9 2417 HOPOPT-7 2418 DSTOPT-8,9 (last) 2420 The sender's two Hop-by-Hop ancillary data objects are reordered, as 2421 are the first two Destination ancillary data objects. We also show a 2422 Jumbo Payload option (denoted as J) inserted by the kernel before the 2423 sender's three Hop-by-Hop options. The first three Destination 2424 options must appear in a Destination header before the Routing 2425 header, and the final two Destination options must appear in a 2426 Destination header after the Routing header. 2428 If Destination options are specified in the control buffer after a 2429 Routing header, or if Destination options are specified without a 2430 Routing header, the kernel will place those Destination options after 2431 an authentication header and/or an encapsulating security payload 2432 header, if present. 2434 10. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses 2436 The various socket options and ancillary data specifications defined 2437 in this document apply only to true IPv6 sockets. It is possible to 2438 create an IPv6 socket that actually sends and receives IPv4 packets, 2439 using IPv4-mapped IPv6 addresses, but the mapping of the options 2440 defined in this document to an IPv4 datagram is beyond the scope of 2441 this document. 2443 In general, attempting to specify an IPv6-only option, such as the 2444 Hop-by-Hop options, Destination options, or Routing header on an IPv6 2445 socket that is using IPv4-mapped IPv6 addresses, will probably result 2446 in an error. Some implementations, however, may provide access to 2447 the packet information (source/destination address, send/receive 2448 interface, and hop limit) on an IPv6 socket that is using IPv4-mapped 2449 IPv6 addresses. 2451 11. rresvport_af 2453 The rresvport() function is used by the rcmd() function, and this 2454 function is in turn called by many of the "r" commands such as 2455 rlogin. While new applications are not being written to use the 2456 rcmd() function, legacy applications such as rlogin will continue to 2457 use it and these will be ported to IPv6. 2459 rresvport() creates an IPv4/TCP socket and binds a "reserved port" to 2460 the socket. Instead of defining an IPv6 version of this function we 2461 define a new function that takes an address family as its argument. 2463 #include 2465 int rresvport_af(int *port, int family); 2467 This function behaves the same as the existing rresvport() function, 2468 but instead of creating an IPv4/TCP socket, it can also create an 2469 IPv6/TCP socket. The family argument is either AF_INET or AF_INET6, 2470 and a new error return is EAFNOSUPPORT if the address family is not 2471 supported. 2473 (Note: There is little consensus on which header defines the 2474 rresvport() and rcmd() function prototypes. 4.4BSD defines it in 2475 , others in , and others don't define the function 2476 prototypes at all.) 2478 (Note: We define this function only, and do not define something like 2479 rcmd_af() or rcmd6(). The reason is that rcmd() calls 2480 gethostbyname(), which returns the type of address: AF_INET or 2481 AF_INET6. It should therefore be possible to modify rcmd() to 2482 support either IPv4 or IPv6, based on the address family returned by 2483 gethostbyname().) 2485 12. Future Items 2487 Some additional items may require standardization, but no concrete 2488 proposals have been made for the API to perform these tasks. These 2489 may be addressed in a later document. 2491 12.1. Flow Labels 2493 Earlier revisions of this document specified a set of 2494 inet6_flow_XXX() functions to assign, share, and free IPv6 flow 2495 labels. Consensus, however, indicated that it was premature to 2496 specify this part of the API. 2498 12.2. Path MTU Discovery and UDP 2499 A standard method may be desirable for a UDP application to determine 2500 the "maximum send transport-message size" (Section 5.1 of [RFC-1981]) 2501 to a given destination. This would let the UDP application send 2502 smaller datagrams to the destination, avoiding fragmentation. 2504 12.3. Neighbor Reachability and UDP 2506 A standard method may be desirable for a UDP application to tell the 2507 kernel that it is making forward progress with a given peer (Section 2508 7.3.1 of [RFC-1970]). This could save unneeded neighbor 2509 solicitations and neighbor advertisements. 2511 13. Summary of New Definitions 2513 The following list summarizes the constants and structure, 2514 definitions discussed in this memo, sorted by header. 2516 ICMP6_DST_UNREACH 2517 ICMP6_DST_UNREACH_ADDR 2518 ICMP6_DST_UNREACH_ADMIN 2519 ICMP6_DST_UNREACH_NOPORT 2520 ICMP6_DST_UNREACH_NOROUTE 2521 ICMP6_DST_UNREACH_NOTNEIGHBOR 2522 ICMP6_ECHO_REPLY 2523 ICMP6_ECHO_REQUEST 2524 ICMP6_INFOMSG_MASK 2525 ICMP6_MEMBERSHIP_QUERY 2526 ICMP6_MEMBERSHIP_REDUCTION 2527 ICMP6_MEMBERSHIP_REPORT 2528 ICMP6_PACKET_TOO_BIG 2529 ICMP6_PARAMPROB_HEADER 2530 ICMP6_PARAMPROB_NEXTHEADER 2531 ICMP6_PARAMPROB_OPTION 2532 ICMP6_PARAM_PROB 2533 ICMP6_TIME_EXCEEDED 2534 ICMP6_TIME_EXCEED_REASSEMBLY 2535 ICMP6_TIME_EXCEED_TRANSIT 2536 ND_NA_FLAG_OVERRIDE 2537 ND_NA_FLAG_ROUTER 2538 ND_NA_FLAG_SOLICITED 2539 ND_NEIGHBOR_ADVERT 2540 ND_NEIGHBOR_SOLICIT 2541 ND_OPT_MTU 2542 ND_OPT_PI_FLAG_AUTO 2543 ND_OPT_PI_FLAG_ONLINK 2544 ND_OPT_PREFIX_INFORMATION 2545 ND_OPT_REDIRECTED_HEADER 2546 ND_OPT_SOURCE_LINKADDR 2547 ND_OPT_TARGET_LINKADDR 2548 ND_RA_FLAG_MANAGED 2549 ND_RA_FLAG_OTHER 2550 ND_REDIRECT 2551 ND_ROUTER_ADVERT 2552 ND_ROUTER_SOLICIT 2554 struct icmp6_filter{}; 2555 struct icmp6_hdr{}; 2556 struct nd_neighbor_advert{}; 2557 struct nd_neighbor_solicit{}; 2558 struct nd_opt_hdr{}; 2559 struct nd_opt_mtu{}; 2560 struct nd_opt_prefix_info{}; 2561 struct nd_opt_rd_hdr{}; 2562 struct nd_redirect{}; 2563 struct nd_router_advert{}; 2564 struct nd_router_solicit{}; 2566 IPPROTO_AH 2567 IPPROTO_DSTOPTS 2568 IPPROTO_ESP 2569 IPPROTO_FRAGMENT 2570 IPPROTO_HOPOPTS 2571 IPPROTO_ICMPV6 2572 IPPROTO_IPV6 2573 IPPROTO_NONE 2574 IPPROTO_ROUTING 2575 IPV6_DSTOPTS 2576 IPV6_HOPLIMIT 2577 IPV6_HOPOPTS 2578 IPV6_NEXTHOP 2579 IPV6_PKTINFO 2580 IPV6_PKTOPTIONS 2581 IPV6_RTHDR 2582 IPV6_RTHDR_LOOSE 2583 IPV6_RTHDR_STRICT 2584 IPV6_RTHDR_TYPE_0 2585 struct in6_pktinfo{}; 2587 IP6F_OFF_MASK 2588 IP6F_RESERVED_MASK 2589 IP6F_MORE_FRAG 2590 struct ip6_dest{}; 2591 struct ip6_frag{}; 2592 struct ip6_hbh{}; 2593 struct ip6_hdr{}; 2594 struct ip6_rthdr{}; 2595 struct ip6_rthdr0{}; 2597 struct cmsghdr{}; 2598 struct msghdr{}; 2600 The following list summarizes the function and macro prototypes 2601 discussed in this memo, sorted by header. 2603 void ICMP6_FILTER_SETBLOCK(int, struct icmp6_filter *); 2604 void ICMP6_FILTER_SETBLOCKALL(struct icmp6_filter *); 2605 void ICMP6_FILTER_SETPASS(int, struct icmp6_filter *); 2606 void ICMP6_FILTER_SETPASSALL(struct icmp6_filter *); 2607 int ICMP6_FILTER_WILLBLOCK(int, 2608 const struct icmp6_filter *); 2609 int ICMP6_FILTER_WILLPASS(int, 2610 const struct icmp6_filter *); 2612 int IN6_ARE_ADDR_EQUAL(const struct in6_addr *, 2613 const struct in6_addr *); 2615 uint8_t *inet6_option_alloc(struct cmsghdr *, 2616 int, int, int); 2617 int inet6_option_append(struct cmsghdr *, 2618 const uint8_t *, int, int); 2619 int inet6_option_find(const struct cmsghdr *, 2620 uint8_t *, int); 2621 int inet6_option_init(void *, struct cmsghdr **, int); 2622 int inet6_option_next(const struct cmsghdr *, 2623 uint8_t **); 2624 int inet6_option_space(int); 2626 int inet6_rthdr_add(struct cmsghdr *, 2627 const struct in6_addr *, 2628 unsigned int); 2629 struct in6_addr inet6_rthdr_getaddr(struct cmsghdr *, 2630 int); 2631 int inet6_rthdr_getflags(const struct cmsghdr *, int); 2632 struct cmsghdr *inet6_rthdr_init(void *, int); 2633 int inet6_rthdr_lasthop(struct cmsghdr *, unsigned int); 2634 int inet6_rthdr_reverse(const struct cmsghdr *, 2635 struct cmsghdr *); 2636 int inet6_rthdr_segments(const struct cmsghdr *); 2637 size_t inet6_rthdr_space(int, int); 2639 unsigned char *CMSG_DATA(const struct cmsghdr *); 2640 struct cmsghdr *CMSG_FIRSTHDR(const struct msghdr *); 2641 unsigned int CMSG_LEN(unsigned int); 2642 struct cmsghdr *CMSG_NXTHDR(const struct msghdr *mhdr, 2643 const struct cmsghdr *); 2644 unsigned int CMSG_SPACE(unsigned int); 2646 int rresvport_af(int *, int); 2648 14. Security Considerations 2650 The setting of certain Hop-by-Hop options and Destination options may 2651 be restricted to privileged processes. Similarly some Hop-by-Hop 2652 options and Destination options may not be returned to nonprivileged 2653 applications. 2655 15. Change History 2657 Changes from the March 1997 Edition (-02 draft) 2659 - In May 1997 Draft 6.6 of Posix 1003.1g (called Posix.1g herein) 2660 passed ballot and will be forwarded to the IEEE Standards Board 2661 later in 1997 for final approval. Some changes made for this 2662 final Posix draft are incorporated into this Internet Draft, 2663 specifically the datatypes mentioned in Section 1 (and used 2664 throughout the text), and the socklen_t datatype used in Section 2665 4.1 and 4.2. 2667 - Section 1: Added the intN_t signed datatypes, changed the 2668 datatype u_intN_t to uintN_t (no underscore after the "u"), and 2669 removed the datatype u_intNm_t, as per Draft 6.6 of Posix.1g. 2671 - Name space issues for structure and constant names in Section 2: 2672 Many of the structure member names and constant names were 2673 changed so that the prefixes are the same. The following 2674 prefixes are used for structure members: "ip6_", "icmp6_", and 2675 "nd_". All constants have the prefixes "ICMP6_" and "ND_". 2677 - New definitions: Section 2.1.2: contains definitions for the IPv6 2678 extension headers, other than AH and ESP. Section 2.2.2: 2679 contains additional structures and constants for the neighbor 2680 discovery option header and redirected header. 2682 - Section 2.2.2: the enum for the neighbor discovery option field 2683 was changed to be a set of #define constants. 2685 - Changed the word "function" to "macro" for references to all the 2686 uppercase names in Sections 2.3 (IN6_ARE_ADDR_EQUAL), 3.2 2687 (ICMPV6_FILTER_xxx), and 4.3 (CMSG_xxx). 2689 - Added more protocols to the /etc/protocols file (Section 2.4) and 2690 changed the name of "icmpv6" to "ipv6-icmp". 2692 - Section 3: Made it more explicit that an application cannot read 2693 or write entire IPv6 packets, that all extension headers are 2694 passed as ancillary data. Added a sentence that the kernel 2695 fragments packets written to an IPv6 raw socket when necessary. 2696 Added a note that IPPROTO_RAW raw IPv6 sockets are not special. 2698 - Section 3.1: Explicitly stated that the checksum option applies 2699 to both outgoing packets and received packets. 2701 - Section 3.2: Changed the array name within the icmp6_filter 2702 structure from "data" to "icmp6_filt". Changes the prefix for 2703 the filter macros from "ICMPV6_" to "ICMP6_", for consistency 2704 with the names in Section 2.2. Changed the example from a ping 2705 program to a program that wants to receive only router 2706 advertisements. 2708 - Section 4.1: Changed msg_namelen and msg_controllen from size_t 2709 to the Posix.1g socklen_t datatype. Updated the Note that 2710 follows. 2712 - Section 4.2: Changed cmsg_len from size_t to the Posix.1g 2713 socklen_t datatype. Updated the Note that follows. 2715 - Section 4.4: Added a Note that the second and third arguments to 2716 getsockopt() and setsockopt() are intentionally the same as the 2717 cmsg_level and cmsg_type members. 2719 - Section 4.5: Reorganized the section into a description of the 2720 option, followed by the TCP semantics, and the UDP and raw socket 2721 semantics. Added a sentence on how to clear all the sticky 2722 options. Added a note that TCP need not save the options from 2723 the most recently received segment until the application says to 2724 do so. Added the statement that ancillary data is never passed 2725 with sendmsg() or recvmsg() on a TCP socket. Simplified the 2726 interaction of the sticky options with ancillary data for UDP or 2727 raw IP: none of the sticky options are sent if ancillary data is 2728 specified. 2730 - Final paragraph of Section 5.1: ipi6_index should be 2731 ipi6_ifindex. 2733 - Section 5.4: Added a note on the term "privileged". 2735 - Section 5.5: Noted that the errors listed are examples, and the 2736 actual errors depend on the implementation. 2738 - Removed Section 6 ("Flow Labels") as the consensus is that it is 2739 premature to try and specify an API for this feature. Access to 2740 the flow label field in the IPv6 header is still provided through 2741 the sin6_flowinfo member of the IPv6 socket address structure in 2742 [RFC-2133]. Added a subsection to Section 13 that this is a 2743 future item. 2745 All remaining changes are identified by their section number in 2746 the previous draft. With the removal of Section 6, the section 2747 numbers are decremented by one. 2749 - Section 7.3.7: the calls to malloc() in all three examples should 2750 be calls to inet6_option_space() instead. The two calls to 2751 inet6_option_append() in the third example should be calls to 2752 inet6_option_alloc(). The two calls to CMSG_SPACE() in the first 2753 and third examples should be calls to CMSG_LEN(). The second 2754 call to CMSG_SPACE() in the second example should be a call to 2755 CMSG_LEN(). 2757 - Section 7.3.7: All the opt_X_ and opt_Y_ structure member names 2758 were changed to be ip6_X_opt_ and ip6_Y_opt_. The two structure 2759 names ipv6_opt_X and ipv6_opt_Y were changed to ip6_X_opt and 2760 ip6_Y_opt. The constants beginning with IPV6_OPT_X_ and 2761 IPV6_OPT_Y_ were changed to begin with IP6_X_OPT_ and IP6_Y_OPT_. 2763 - Use the term "Routing header" throughout the draft, instead of 2764 "source routing". Changed the names of the eight 2765 inet6_srcrt_XXX() functions in Section 9 to inet6_rthdr_XXX(). 2766 Changed the name of the socket option from IPV6_SRCRT to 2767 IPV6_RTHDR, and the names of the three IPV6_SRCRT_xxx constants 2768 in Section 9 to IPV6_RTHDR_xxx. 2770 - Added a paragraph to Section 9 on how to receive and send a 2771 Routing header. 2773 - Changed inet6_rthdr_add() and inet6_rthdr_reverse() so that they 2774 return -1 upon an error, instead of an Exxx errno value. 2776 - In the description of inet6_rthdr_space() in Section 9.1, added 2777 the qualifier "For an IPv6 Type 0 Routing header" to the 2778 restriction of between 1 and 23 segments. 2780 - Refer to final function argument in Sections 9.7 and 9.8 as 2781 index, not offset. 2783 - Updated Section 14 with new names from Section 2. 2785 - Changed the References from "[n]" to "[RFC-abcd]". 2787 Changes from the February 1997 Edition (-01 draft) 2789 - Changed the name of the ip6hdr structure to ip6_hdr (Section 2.1) 2790 for consistency with the icmp6hdr structure. Also changed the 2791 name of the ip6hdrctl structure contained within the ip6_hdr 2792 structure to ip6_hdrctl (Section 2.1). Finally, changed the name 2793 of the icmp6hdr structure to icmp6_hdr (Section 2.2). All other 2794 occurrences of this structure name, within the Neighbor Discovery 2795 structures in Section 2.2.1, already contained the underscore. 2797 - The "struct nd_router_solicit" and "struct nd_router_advert" 2798 should both begin with "nd6_". (Section 2.2.2). 2800 - Changed the name of in6_are_addr_equal to IN6_ARE_ADDR_EQUAL 2801 (Section 2.3) for consistency with basic API address testing 2802 functions. The header defining this macro is . 2804 - getprotobyname("ipv6") now returns 41, not 0 (Section 2.4). 2806 - The first occurrence of "struct icmpv6_filter" in Section 3.2 2807 should be "struct icmp6_filter". 2809 - Changed the name of the CMSG_LENGTH() macro to CMSG_LEN() 2810 (Section 4.3.5), since LEN is used throughout the 2811 headers. 2813 - Corrected the argument name for the sample implementations of the 2814 CMSG_SPACE() and CMSG_LEN() macros to be "length" (Sections 4.3.4 2815 and 4.3.5). 2817 - Corrected the socket option mentioned in Section 5.1 to specify 2818 the interface for multicasting from IPV6_ADD_MEMBERSHIP to 2819 IPV6_MULTICAST_IF. 2821 - There were numerous errors in the previous draft that specified 2822 that should have been . These have 2823 all been corrected and the locations of all definitions is now 2824 summarized in the new Section 14 ("Summary of New Definitions"). 2826 Changes from the October 1996 Edition (-00 draft) 2828 - Numerous rationale added using the format (Note: ...). 2830 - Added note that not all errors may be defined. 2832 - Added note about ICMPv4, IGMPv4, and ARPv4 terminology. 2834 - Changed the name of to . 2836 - Changed some names in Section 2.2.1: ICMPV6_PKT_TOOBIG to 2837 ICMPV6_PACKET_TOOBIG, ICMPV6_TIME_EXCEED to ICMPV6_TIME_EXCEEDED, 2838 ICMPV6_ECHORQST to ICMPV6_ECHOREQUEST, ICMPV6_ECHORPLY to 2839 ICMPV6_ECHOREPLY, ICMPV6_PARAMPROB_HDR to 2840 ICMPV6_PARAMPROB_HEADER, ICMPV6_PARAMPROB_NXT_HDR to 2841 ICMPV6_PARAMPROB_NEXTHEADER, and ICMPV6_PARAMPROB_OPTS to 2842 ICMPV6_PARAMPROB_OPTION. 2844 - Prepend the prefix "icmp6_" to the three members of the 2845 icmp6_dataun union of the icmp6hdr structure (Section 2.2). 2847 - Moved the neighbor discovery definitions into the 2848 header, instead of being in their own header 2849 (Section 2.2.1). 2851 - Changed Section 2.3 ("Address Testing"). The basic macros are 2852 now in the basic API. 2854 - Added the new Section 2.4 on "Protocols File". 2856 - Added note to raw sockets description that something like BPF or 2857 DLPI must be used to read or write entire IPv6 packets. 2859 - Corrected example of IPV6_CHECKSUM socket option (Section 3.1). 2860 Also defined value of -1 to disable. 2862 - Noted that defines all the ICMPv6 filtering 2863 constants, macros, and structures (Section 3.2). 2865 - Added note on magic number 10240 for amount of ancillary data 2866 (Section 4.1). 2868 - Added possible padding to picture of ancillary data (Section 2869 4.2). 2871 - Defined header for CMSG_xxx() functions (Section 2872 4.2). 2874 - Note that the data returned by getsockopt(IPV6_PKTOPTIONS) for a 2875 TCP socket is just from the optional headers, if present, of the 2876 most recently received segment. Also note that control 2877 information is never returned by recvmsg() for a TCP socket. 2879 - Changed header for struct in6_pktinfo from to 2880 (Section 5). 2882 - Removed the old Sections 5.1 and 5.2, because the interface 2883 identification functions went into the basic API. 2885 - Redid Section 5 to support the hop limit field. 2887 - New Section 5.4 ("Next Hop Address"). 2889 - New Section 6 ("Flow Labels"). 2891 - Changed all of Sections 7 and 8 dealing with Hop-by-Hop and 2892 Destination options. We now define a set of inet6_option_XXX() 2893 functions. 2895 - Changed header for IPV6_SRCRT_xxx constants from 2896 to (Section 9). 2898 - Add inet6_rthdr_lasthop() function, and fix errors in description 2899 of Routing header (Section 9). 2901 - Reworded some of the Routing header descriptions to conform to 2902 the terminology in [RFC-1883]. 2904 - Added the example from [RFC-1883] for the Routing header (Section 2905 9.9). 2907 - Expanded the example in Section 10 to show multiple options per 2908 ancillary data object, and to show the receiver's ancillary data 2909 objects. 2911 - New Section 11 ("IPv6-Specific Options with IPv4-Mapped IPv6 2912 Addresses"). 2914 - New Section 12 ("rresvport_af"). 2916 - Redid old Section 10 ("Additional Items") into new Section 13 2917 ("Future Items"). 2919 16. References 2921 [RFC-1883] Deering, S., Hinden, R., "Internet Protocol, Version 6 2922 (IPv6), Specification", RFC 1883, Dec. 1995. 2924 [RFC-2133] Gilligan, R. E., Thomson, S., Bound, J., Stevens, W., 2925 "Basic Socket Interface Extensions for IPv6", RFC 2133, 2926 April 1997. 2928 [RFC-1981] McCann, J., Deering, S., Mogul, J, "Path MTU Discovery 2929 for IP version 6", RFC 1981, Aug. 1996. 2931 [RFC-1970] Narten, T., Nordmark, E., Simpson, W., "Neighbor 2932 Discovery for IP Version 6 (IPv6)", RFC 1970, Aug. 1996. 2934 17. Acknowledgments 2936 Matt Thomas and Jim Bound have been working on the technical details 2937 in this draft for over a year. Keith Sklower is the original 2938 implementor of ancillary data in the BSD networking code. Craig Metz 2939 provided lots of feedback, suggestions, and comments based on his 2940 implementing many of these features as the document was being 2941 written. 2943 The following provided comments on earlier drafts: Pascal Anelli, 2944 Hamid Asayesh, Ran Atkinson, Karl Auerbach, Hamid Asayesh, Matt 2945 Crawford, Sam T. Denton, Richard Draves, Francis Dupont, Bob 2946 Gilligan, Tim Hartrick, Masaki Hirabaru, Yoshinobu Inoue, Mukesh 2947 Kacker, A. N. Kuznetsov, Pedro Marques, Jack McCann, der Mouse, John 2948 Moy, Thomas Narten, Erik Nordmark, Steve Parker, Charles Perkins, Tom 2949 Pusateri, Pedro Roque, Sameer Shah, Peter Sjodin, Stephen P. 2950 Spackman, Jinmei Tatuya, Karen Tracey, Quaizar Vohra, Carl Williams, 2951 Steve Wise, and Kazu Yamamoto. 2953 18. Authors' Addresses 2955 W. Richard Stevens 2956 1202 E. Paseo del Zorro 2957 Tucson, AZ 85718 2958 Email: rstevens@kohala.com 2960 Matt Thomas 2961 AltaVista Internet Software 2962 LJO2-1/J8 2963 30 Porter Rd 2964 Littleton, MA 01460 2965 Email: matt.thomas@altavista-software.com