Network Working Group W. Stevens Request for Comments: 3542 M. Thomas Obsoletes: 2292 Consultant Category: Informational E. Nordmark Sun T. Jinmei Toshiba May 2003 Advanced Sockets Application Program Interface (API) for IPv6 Status of this Memo This memo provides information for the Internet community. It does not specify an Internet standard of any kind. Distribution of this memo is unlimited. Copyright Notice Copyright (C) The Internet Society (2003). All Rights Reserved. Abstract This document provides sockets Application Program Interface (API) to support "advanced" IPv6 applications, as a supplement to a separate specification, RFC 3493. The expected applications include Ping, Traceroute, routing daemons and the like, which typically use raw sockets to access IPv6 or ICMPv6 header fields. This document proposes some portable interfaces for applications that use raw sockets under IPv6. There are other features of IPv6 that some applications will need to access: interface identification (specifying the outgoing interface and determining the incoming interface), IPv6 extension headers, and path Maximum Transmission Unit (MTU) information. This document provides API access to these features too. Additionally, some extended interfaces to libraries for the "r" commands are defined. The extension will provide better backward compatibility to existing implementations that are not IPv6-capable. Stevens, et al. Informational [Page 1] RFC 3542 Advanced Sockets API for IPv6 May 2003 Table of Contents 1. Introduction .............................................. 3 2. Common Structures and Definitions ......................... 5 2.1 The ip6_hdr Structure ................................ 6 2.1.1 IPv6 Next Header Values ....................... 6 2.1.2 IPv6 Extension Headers ........................ 7 2.1.3 IPv6 Options .................................. 8 2.2 The icmp6_hdr Structure .............................. 10 2.2.1 ICMPv6 Type and Code Values ................... 10 2.2.2 ICMPv6 Neighbor Discovery Definitions ......... 11 2.2.3 Multicast Listener Discovery Definitions ...... 14 2.2.4 ICMPv6 Router Renumbering Definitions ......... 14 2.3 Address Testing Macros ............................... 16 2.4 Protocols File ....................................... 16 3. IPv6 Raw Sockets .......................................... 17 3.1 Checksums ............................................ 18 3.2 ICMPv6 Type Filtering ................................ 19 3.3 ICMPv6 Verification of Received Packets .............. 22 4. Access to IPv6 and Extension Headers ...................... 22 4.1 TCP Implications ..................................... 24 4.2 UDP and Raw Socket Implications ...................... 25 5. Extensions to Socket Ancillary Data ....................... 26 5.1 CMSG_NXTHDR .......................................... 26 5.2 CMSG_SPACE ........................................... 26 5.3 CMSG_LEN ............................................. 27 6. Packet Information ........................................ 27 6.1 Specifying/Receiving the Interface ................... 28 6.2 Specifying/Receiving Source/Destination Address ...... 29 6.3 Specifying/Receiving the Hop Limit ................... 29 6.4 Specifying the Next Hop Address ...................... 30 6.5 Specifying/Receiving the Traffic Class value ......... 31 6.6 Additional Errors with sendmsg() and setsockopt() .... 32 6.7 Summary of Outgoing Interface Selection .............. 32 7. Routing Header Option ..................................... 33 7.1 inet6_rth_space ...................................... 35 7.2 inet6_rth_init ....................................... 35 7.3 inet6_rth_add ........................................ 36 7.4 inet6_rth_reverse .................................... 36 7.5 inet6_rth_segments ................................... 36 7.6 inet6_rth_getaddr .................................... 36 8. Hop-By-Hop Options ........................................ 37 8.1 Receiving Hop-by-Hop Options ......................... 38 8.2 Sending Hop-by-Hop Options ........................... 38 9. Destination Options ....................................... 39 9.1 Receiving Destination Options ........................ 39 9.2 Sending Destination Options .......................... 39 10. Hop-by-Hop and Destination Options Processing ............. 40 Stevens, et al. Informational [Page 2] RFC 3542 Advanced Sockets API for IPv6 May 2003 10.1 inet6_opt_init ...................................... 41 10.2 inet6_opt_append .................................... 41 10.3 inet6_opt_finish .................................... 42 10.4 inet6_opt_set_val ................................... 42 10.5 inet6_opt_next ...................................... 42 10.6 inet6_opt_find ...................................... 43 10.7 inet6_opt_get_val ................................... 43 11. Additional Advanced API Functions ......................... 44 11.1 Sending with the Minimum MTU ........................ 44 11.2 Sending without Fragmentation ....................... 45 11.3 Path MTU Discovery and UDP .......................... 46 11.4 Determining the Current Path MTU .................... 47 12. Ordering of Ancillary Data and IPv6 Extension Headers ..... 48 13. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses ..... 50 14. Extended interfaces for rresvport, rcmd and rexec ......... 51 14.1 rresvport_af ........................................ 51 14.2 rcmd_af ............................................. 51 14.3 rexec_af ............................................ 52 15. Summary of New Definitions ................................ 52 16. Security Considerations ................................... 56 17. Changes from RFC 2292 ..................................... 57 18. References ................................................ 59 19. Acknowledgments ........................................... 59 20. Appendix A: Ancillary Data Overview ....................... 60 20.1 The msghdr Structure ................................ 60 20.2 The cmsghdr Structure ............................... 61 20.3 Ancillary Data Object Macros ........................ 62 20.3.1 CMSG_FIRSTHDR ............................... 63 20.3.2 CMSG_NXTHDR ................................. 64 20.3.3 CMSG_DATA ................................... 65 20.3.4 CMSG_SPACE .................................. 65 20.3.5 CMSG_LEN .................................... 65 21. Appendix B: Examples Using the inet6_rth_XXX() Functions .. 65 21.1 Sending a Routing Header ............................ 65 21.2 Receiving Routing Headers ........................... 70 22. Appendix C: Examples Using the inet6_opt_XXX() Functions .. 72 22.1 Building Options .................................... 72 22.2 Parsing Received Options ............................ 74 23. Authors' Addresses ........................................ 76 24. Full Copyright Statement .................................. 77 1. Introduction A separate specification [RFC-3493] contains changes to the sockets API to support IP version 6. Those changes are for TCP and UDP-based applications. This document defines some of the "advanced" features of the sockets API that are required for applications to take advantage of additional features of IPv6. Stevens, et al. Informational [Page 3] RFC 3542 Advanced Sockets API for IPv6 May 2003 Today, the portability of applications using IPv4 raw sockets is quite high, but this is mainly because most IPv4 implementations started from a common base (the Berkeley source code) or at least started with the Berkeley header files. This allows programs such as Ping and Traceroute, for example, to compile with minimal effort on many hosts that support the sockets API. With IPv6, however, there is no common source code base that implementors are starting from, and the possibility for divergence at this level between different implementations is high. To avoid a complete lack of portability amongst applications that use raw IPv6 sockets, some standardization is necessary. There are also features from the basic IPv6 specification that are not addressed in [RFC-3493]: sending and receiving Routing headers, Hop-by-Hop options, and Destination options, specifying the outgoing interface, being told of the receiving interface, and control of path MTU information. This document updates and replaces RFC 2292. This revision is based on implementation experience of RFC 2292, as well as some additional extensions that have been found to be useful through the IPv6 deployment. Note, however, that further work on this document may still be needed. Once the API specification becomes mature and is deployed among implementations, it may be formally standardized by a more appropriate body, such as has been done with the Basic API [RFC-3493]. This document can be divided into the following main sections. 1. Definitions of the basic constants and structures required for applications to use raw IPv6 sockets. This includes structure definitions for the IPv6 and ICMPv6 headers and all associated constants (e.g., values for the Next Header field). 2. Some basic semantic definitions for IPv6 raw sockets. For example, a raw ICMPv4 socket requires the application to calculate and store the ICMPv4 header checksum. But with IPv6 this would require the application to choose the source IPv6 address because the source address is part of the pseudo header that ICMPv6 now uses for its checksum computation. It should be defined that with a raw ICMPv6 socket the kernel always calculates and stores the ICMPv6 header checksum. 3. Packet information: how applications can obtain the received interface, destination address, and received hop limit, along with specifying these values on a per-packet basis. There are a class of applications that need this capability and the technique should be portable. Stevens, et al. Informational [Page 4] RFC 3542 Advanced Sockets API for IPv6 May 2003 4. Access to the optional Routing header, Hop-by-Hop options, and Destination options extension headers. 5. Additional features required for improved IPv6 application portability. The packet information along with access to the extension headers (Routing header, Hop-by-Hop options, and Destination options) are specified using the "ancillary data" fields that were added to the 4.3BSD Reno sockets API in 1990. The reason is that these ancillary data fields are part of the Posix standard [POSIX] and should therefore be adopted by most vendors. This document does not address application access to either the authentication header or the encapsulating security payload header. Many examples in this document omit error checking in favor of brevity and clarity. We note that some of the functions and socket options defined in this document may have error returns that are not defined in this document. Some of these possible error returns will be recognized only as implementations proceed. Datatypes in this document follow the Posix format: intN_t means a signed integer of exactly N bits (e.g., int16_t) and uintN_t means an unsigned integer of exactly N bits (e.g., uint32_t). Note that we use the (unofficial) terminology ICMPv4, IGMPv4, and ARPv4 to avoid any confusion with the newer ICMPv6 protocol. 2. Common Structures and Definitions Many advanced applications examine fields in the IPv6 header and set and examine fields in the various ICMPv6 headers. Common structure definitions for these protocol headers are required, along with common constant definitions for the structure members. This API assumes that the fields in the protocol headers are left in the network byte order, which is big-endian for the Internet protocols. If not, then either these constants or the fields being tested must be converted at run-time, using something like htons() or htonl(). Two new header files are defined: and . Stevens, et al. Informational [Page 5] RFC 3542 Advanced Sockets API for IPv6 May 2003 When an include file is specified, that include file is allowed to include other files that do the actual declaration or definition. 2.1. The ip6_hdr Structure The following structure is defined as a result of including . Note that this is a new header. struct ip6_hdr { union { struct ip6_hdrctl { uint32_t ip6_un1_flow; /* 4 bits version, 8 bits TC, 20 bits flow-ID */ uint16_t ip6_un1_plen; /* payload length */ uint8_t ip6_un1_nxt; /* next header */ uint8_t ip6_un1_hlim; /* hop limit */ } ip6_un1; uint8_t ip6_un2_vfc; /* 4 bits version, top 4 bits tclass */ } ip6_ctlun; struct in6_addr ip6_src; /* source address */ struct in6_addr ip6_dst; /* destination address */ }; #define ip6_vfc ip6_ctlun.ip6_un2_vfc #define ip6_flow ip6_ctlun.ip6_un1.ip6_un1_flow #define ip6_plen ip6_ctlun.ip6_un1.ip6_un1_plen #define ip6_nxt ip6_ctlun.ip6_un1.ip6_un1_nxt #define ip6_hlim ip6_ctlun.ip6_un1.ip6_un1_hlim #define ip6_hops ip6_ctlun.ip6_un1.ip6_un1_hlim 2.1.1. IPv6 Next Header Values IPv6 defines many new values for the Next Header field. The following constants are defined as a result of including . #define IPPROTO_HOPOPTS 0 /* IPv6 Hop-by-Hop options */ #define IPPROTO_IPV6 41 /* IPv6 header */ #define IPPROTO_ROUTING 43 /* IPv6 Routing header */ #define IPPROTO_FRAGMENT 44 /* IPv6 fragment header */ #define IPPROTO_ESP 50 /* encapsulating security payload */ #define IPPROTO_AH 51 /* authentication header */ #define IPPROTO_ICMPV6 58 /* ICMPv6 */ #define IPPROTO_NONE 59 /* IPv6 no next header */ #define IPPROTO_DSTOPTS 60 /* IPv6 Destination options */ Stevens, et al. Informational [Page 6] RFC 3542 Advanced Sockets API for IPv6 May 2003 Berkeley-derived IPv4 implementations also define IPPROTO_IP to be 0. This should not be a problem since IPPROTO_IP is used only with IPv4 sockets and IPPROTO_HOPOPTS only with IPv6 sockets. 2.1.2. IPv6 Extension Headers Six extension headers are defined for IPv6. We define structures for all except the Authentication header and Encapsulating Security Payload header, both of which are beyond the scope of this document. The following structures are defined as a result of including . /* Hop-by-Hop options header */ struct ip6_hbh { uint8_t ip6h_nxt; /* next header */ uint8_t ip6h_len; /* length in units of 8 octets */ /* followed by options */ }; /* Destination options header */ struct ip6_dest { uint8_t ip6d_nxt; /* next header */ uint8_t ip6d_len; /* length in units of 8 octets */ /* followed by options */ }; /* Routing header */ struct ip6_rthdr { uint8_t ip6r_nxt; /* next header */ uint8_t ip6r_len; /* length in units of 8 octets */ uint8_t ip6r_type; /* routing type */ uint8_t ip6r_segleft; /* segments left */ /* followed by routing type specific data */ }; /* Type 0 Routing header */ struct ip6_rthdr0 { uint8_t ip6r0_nxt; /* next header */ uint8_t ip6r0_len; /* length in units of 8 octets */ uint8_t ip6r0_type; /* always zero */ uint8_t ip6r0_segleft; /* segments left */ uint32_t ip6r0_reserved; /* reserved field */ /* followed by up to 127 struct in6_addr */ }; Stevens, et al. Informational [Page 7] RFC 3542 Advanced Sockets API for IPv6 May 2003 /* Fragment header */ struct ip6_frag { uint8_t ip6f_nxt; /* next header */ uint8_t ip6f_reserved; /* reserved field */ uint16_t ip6f_offlg; /* offset, reserved, and flag */ uint32_t ip6f_ident; /* identification */ }; #if BYTE_ORDER == BIG_ENDIAN #define IP6F_OFF_MASK 0xfff8 /* mask out offset from ip6f_offlg */ #define IP6F_RESERVED_MASK 0x0006 /* reserved bits in ip6f_offlg */ #define IP6F_MORE_FRAG 0x0001 /* more-fragments flag */ #else /* BYTE_OR