draft-ietf-ipngwg-rfc2292bis-02.txt   draft-ietf-ipngwg-rfc2292bis-03.txt 
INTERNET-DRAFT W. Richard Stevens (Consultant)
Expires: May 7, 2001 Matt Thomas (Consultant) INTERNET-DRAFT W. Richard Stevens
Expires: May 21, 2002 Matt Thomas (Consultant)
Obsoletes RFC 2292 Erik Nordmark (Sun) Obsoletes RFC 2292 Erik Nordmark (Sun)
November 7, 2000 Tatuya Jinmei (Toshiba)
November 21, 2001
Advanced Sockets API for IPv6 Advanced Sockets API for IPv6
<draft-ietf-ipngwg-rfc2292bis-02.txt> <draft-ietf-ipngwg-rfc2292bis-03.txt>
Abstract Abstract
A separate specification [RFC-2553] contain changes to the sockets A separate specification [RFC-2553] contain changes to the sockets
API to support IP version 6. Those changes are for TCP and UDP-based API to support IP version 6. Those changes are for TCP and UDP-based
applications and will support most end-user applications in use applications and will support most end-user applications in use
today: Telnet and FTP clients and servers, HTTP clients and servers, today: Telnet and FTP clients and servers, HTTP clients and servers,
and the like. and the like.
But another class of applications exists that will also be run under But another class of applications exists that will also be run under
skipping to change at page 2, line 13 skipping to change at page 2, line 14
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt http://www.ietf.org/ietf/1id-abstracts.txt
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet Draft expires May 7, 2001. This Internet Draft expires May 21, 2002.
Table of Contents Table of Contents
1. Introduction ..................................................... 6 1. Introduction ..................................................... 6
2. Common Structures and Definitions ................................ 7 2. Common Structures and Definitions ................................ 7
2.1. The ip6_hdr Structure .......................................... 8 2.1. The ip6_hdr Structure .......................................... 8
2.1.1. IPv6 Next Header Values ...................................... 8 2.1.1. IPv6 Next Header Values ...................................... 8
2.1.2. IPv6 Extension Headers ....................................... 9 2.1.2. IPv6 Extension Headers ....................................... 9
2.1.3. IPv6 Options ................................................. 10 2.1.3. IPv6 Options ................................................. 10
2.2. The icmp6_hdr Structure ........................................ 13 2.2. The icmp6_hdr Structure ........................................ 11
2.2.1. ICMPv6 Type and Code Values .................................. 13 2.2.1. ICMPv6 Type and Code Values .................................. 12
2.2.2. ICMPv6 Neighbor Discovery Definitions ........................ 14 2.2.2. ICMPv6 Neighbor Discovery Definitions ........................ 13
2.2.3. Multicast Listener Discovery Definitions ..................... 17 2.2.3. Multicast Listener Discovery Definitions ..................... 15
2.2.4. ICMPv6 Router Renumbering Definitions ........................ 18 2.2.4. ICMPv6 Router Renumbering Definitions ........................ 16
2.3. Address Testing Macros ......................................... 19 2.3. Address Testing Macros ......................................... 18
2.4. Protocols File ................................................. 20 2.4. Protocols File ................................................. 18
3. IPv6 Raw Sockets ................................................. 20 3. IPv6 Raw Sockets ................................................. 19
3.1. Checksums ...................................................... 22 3.1. Checksums ...................................................... 20
3.2. ICMPv6 Type Filtering .......................................... 22 3.2. ICMPv6 Type Filtering .......................................... 21
3.3. ICMPv6 Verification of Received Packets ........................ 25 3.3. ICMPv6 Verification of Received Packets ........................ 23
4. Access to IPv6 and Extension Headers ............................. 25 4. Access to IPv6 and Extension Headers ............................. 23
4.1. TCP Implications ............................................... 27 4.1. TCP Implications ............................................... 26
4.2. UDP and Raw Socket Implications ................................ 28 4.2. UDP and Raw Socket Implications ................................ 27
5. Extensions to Socket Ancillary Data .............................. 28 5. Extensions to Socket Ancillary Data .............................. 28
6. Packet Information ............................................... 29 6. Packet Information ............................................... 28
6.1. Specifying/Receiving the Interface ............................. 30 6.1. Specifying/Receiving the Interface ............................. 29
6.2. Specifying/Receiving Source/Destination Address ................ 30 6.2. Specifying/Receiving Source/Destination Address ................ 30
6.3. Specifying/Receiving the Hop Limit ............................. 31 6.3. Specifying/Receiving the Hop Limit ............................. 31
6.4. Specifying the Next Hop Address ................................ 32 6.4. Specifying the Next Hop Address ................................ 32
6.5. Additional Errors with sendmsg() and setsockopt() .............. 32 6.5. Specifying/Receiving the Traffic Class value ................... 32
6.6. Additional Errors with sendmsg() and setsockopt() .............. 33
7. Routing Header Option ............................................ 33 6.7. Summary of outgoing interface selection ........................ 34
7.1. inet6_rth_space ................................................ 34
7.2. inet6_rth_init ................................................. 35
7.3. inet6_rth_add .................................................. 35
7.4. inet6_rth_reverse .............................................. 35
7.5. inet6_rth_segments ............................................. 36
7.6. inet6_rth_getaddr .............................................. 36
8. Hop-By-Hop Options ............................................... 36 7. Routing Header Option ............................................ 34
8.1. Receiving Hop-by-Hop Options ................................... 38 7.1. inet6_rth_space ................................................ 36
8.2. Sending Hop-by-Hop Options ..................................... 38 7.2. inet6_rth_init ................................................. 36
7.3. inet6_rth_add .................................................. 37
7.4. inet6_rth_reverse .............................................. 37
7.5. inet6_rth_segments ............................................. 37
7.6. inet6_rth_getaddr .............................................. 38
9. Destination Options .............................................. 38 8. Hop-By-Hop Options ............................................... 38
9.1. Receiving Destination Options .................................. 39 8.1. Receiving Hop-by-Hop Options ................................... 39
9.2. Sending Destination Options .................................... 39 8.2. Sending Hop-by-Hop Options ..................................... 40
9. Destination Options .............................................. 40
9.1. Receiving Destination Options .................................. 40
9.2. Sending Destination Options .................................... 41
10. Hop-by-Hop and Destination Options Processing ................... 40 10. Hop-by-Hop and Destination Options Processing ................... 41
10.1. inet6_opt_init ................................................ 40 10.1. inet6_opt_init ................................................ 42
10.2. inet6_opt_append .............................................. 41 10.2. inet6_opt_append .............................................. 42
10.3. inet6_opt_finish .............................................. 41 10.3. inet6_opt_finish .............................................. 43
10.4. inet6_opt_set_val ............................................. 42 10.4. inet6_opt_set_val ............................................. 43
10.5. inet6_opt_next ................................................ 42 10.5. inet6_opt_next ................................................ 44
10.6. inet6_opt_find ................................................ 42 10.6. inet6_opt_find ................................................ 44
10.7. inet6_opt_get_val ............................................. 43 10.7. inet6_opt_get_val ............................................. 45
11. Additional Advanced API Functions ............................... 43 11. Additional Advanced API Functions ............................... 45
11.1. Sending with the Minimum MTU .................................. 43 11.1. Sending with the Minimum MTU .................................. 45
11.2. Path MTU Discovery and UDP .................................... 44 11.2. Sending without fragmentation ................................. 46
11.3. Neighbor Reachability and UDP ................................. 44 11.3. Path MTU Discovery and UDP .................................... 46
11.4. Determining the current path MTU .............................. 47
11.5. Neighbor Reachability and UDP ................................. 48
12. Ordering of Ancillary Data and IPv6 Extension Headers ........... 45 12. Ordering of Ancillary Data and IPv6 Extension Headers ........... 49
13. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses ........... 46 13. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses ........... 51
14. Extended interfaces for rresvport, rcmd and rexec ............... 46 14. Extended interfaces for rresvport, rcmd and rexec ............... 51
14.1. rresvport_af .................................................. 46 14.1. rresvport_af .................................................. 51
14.2. rcmd_af ....................................................... 47 14.2. rcmd_af ....................................................... 52
14.3. rexec_af ...................................................... 47 14.3. rexec_af ...................................................... 52
15. Summary of New Definitions ...................................... 47 15. Summary of New Definitions ...................................... 52
16. Security Considerations ......................................... 52 16. Security Considerations ......................................... 56
17. Change History .................................................. 52 17. Change History .................................................. 57
18. TODO and Open Issues ............................................ 54 18. Open Issues ..................................................... 61
19. References ...................................................... 56 19. References ...................................................... 61
20. Acknowledgments ................................................. 56 20. Acknowledgments ................................................. 61
21. Authors' Addresses .............................................. 57 21. Authors' Addresses .............................................. 62
22. Appendix A: Ancillary Data Overview ............................. 57 22. Appendix A: Ancillary Data Overview ............................. 63
22.1. The msghdr Structure .......................................... 58 22.1. The msghdr Structure .......................................... 63
22.2. The cmsghdr Structure ......................................... 59 22.2. The cmsghdr Structure ......................................... 64
22.3. Ancillary Data Object Macros .................................. 60 22.3. Ancillary Data Object Macros .................................. 65
22.3.1. CMSG_FIRSTHDR ............................................... 61 22.3.1. CMSG_FIRSTHDR ............................................... 66
22.3.2. CMSG_NXTHDR ................................................. 62 22.3.2. CMSG_NXTHDR ................................................. 67
22.3.3. CMSG_DATA ................................................... 63 22.3.3. CMSG_DATA ................................................... 68
22.3.4. CMSG_SPACE .................................................. 63 22.3.4. CMSG_SPACE .................................................. 68
22.3.5. CMSG_LEN .................................................... 64 22.3.5. CMSG_LEN .................................................... 69
23. Appendix B: Examples using the inet6_rth_XXX() functions ........ 64 23. Appendix B: Examples using the inet6_rth_XXX() functions ........ 69
23.1. Sending a Routing Header ...................................... 64 23.1. Sending a Routing Header ...................................... 69
23.2. Receiving Routing Headers ..................................... 69 23.2. Receiving Routing Headers ..................................... 74
24. Appendix C: Examples using the inet6_opt_XXX() functions ........ 71 24. Appendix C: Examples using the inet6_opt_XXX() functions ........ 76
24.1. Building options .............................................. 71 24.1. Building options .............................................. 76
24.2. Parsing received options ...................................... 73 24.2. Parsing received options ...................................... 78
1. Introduction 1. Introduction
A separate specification [RFC-2553] contain changes to the sockets A separate specification [RFC-2553] contain changes to the sockets
API to support IP version 6. Those changes are for TCP and UDP-based API to support IP version 6. Those changes are for TCP and UDP-based
applications. This document defines some the "advanced" features of applications. This document defines some of the "advanced" features
the sockets API that are required for applications to take advantage of the sockets API that are required for applications to take
of additional features of IPv6. advantage of additional features of IPv6.
Today, the portability of applications using IPv4 raw sockets is Today, the portability of applications using IPv4 raw sockets is
quite high, but this is mainly because most IPv4 implementations quite high, but this is mainly because most IPv4 implementations
started from a common base (the Berkeley source code) or at least started from a common base (the Berkeley source code) or at least
started with the Berkeley header files. This allows programs such as started with the Berkeley header files. This allows programs such as
Ping and Traceroute, for example, to compile with minimal effort on Ping and Traceroute, for example, to compile with minimal effort on
many hosts that support the sockets API. With IPv6, however, there many hosts that support the sockets API. With IPv6, however, there
is no common source code base that implementors are starting from, is no common source code base that implementors are starting from,
and the possibility for divergence at this level between different and the possibility for divergence at this level between different
implementations is high. To avoid a complete lack of portability implementations is high. To avoid a complete lack of portability
skipping to change at page 6, line 52 skipping to change at page 6, line 52
that ICMPv6 now uses for its checksum computation. It should be that ICMPv6 now uses for its checksum computation. It should be
defined that with a raw ICMPv6 socket the kernel always defined that with a raw ICMPv6 socket the kernel always
calculates and stores the ICMPv6 header checksum. calculates and stores the ICMPv6 header checksum.
3. Packet information: how applications can obtain the received 3. Packet information: how applications can obtain the received
interface, destination address, and received hop limit, along interface, destination address, and received hop limit, along
with specifying these values on a per-packet basis. There are a with specifying these values on a per-packet basis. There are a
class of applications that need this capability and the technique class of applications that need this capability and the technique
should be portable. should be portable.
4. Access to the optional Routing header, Hop-by-Hop, and 4. Access to the optional Routing header, Hop-by-Hop options, and
Destination extension headers. Destination options extension headers.
5. Additional features required for improved IPv6 application 5. Additional features required for improved IPv6 application
portability. portability.
The packet information along with access to the extension headers The packet information along with access to the extension headers
(Routing header, Hop-by-Hop options, and Destination options) are (Routing header, Hop-by-Hop options, and Destination options) are
specified using the "ancillary data" fields that were added to the specified using the "ancillary data" fields that were added to the
4.3BSD Reno sockets API in 1990. The reason is that these ancillary 4.3BSD Reno sockets API in 1990. The reason is that these ancillary
data fields are part of the Posix.1g standard and should therefore be data fields are part of the Posix.1g standard and should therefore be
adopted by most vendors. adopted by most vendors.
skipping to change at page 9, line 16 skipping to change at page 9, line 16
sockets and IPPROTO_HOPOPTS only with IPv6 sockets. sockets and IPPROTO_HOPOPTS only with IPv6 sockets.
2.1.2. IPv6 Extension Headers 2.1.2. IPv6 Extension Headers
Six extension headers are defined for IPv6. We define structures for Six extension headers are defined for IPv6. We define structures for
all except the Authentication header and Encapsulating Security all except the Authentication header and Encapsulating Security
Payload header, both of which are beyond the scope of this document. Payload header, both of which are beyond the scope of this document.
The following structures are defined as a result of including The following structures are defined as a result of including
<netinet/ip6.h>. <netinet/ip6.h>.
/*
* Generic extension header structure used by many extension headers.
* Note that not all headers have this format. E.g. the fragmentation
* header is different.
*/
struct ip6_ext {
uint8_t ip6e_nxt; /* next header */
uint8_t ip6e_len; /* length in units of 8 octets */
};
/* Hop-by-Hop options header */ /* Hop-by-Hop options header */
struct ip6_hbh { struct ip6_hbh {
uint8_t ip6h_nxt; /* next header */ uint8_t ip6h_nxt; /* next header */
uint8_t ip6h_len; /* length in units of 8 octets */ uint8_t ip6h_len; /* length in units of 8 octets */
/* followed by options */ /* followed by options */
}; };
/* Destination options header */ /* Destination options header */
struct ip6_dest { struct ip6_dest {
uint8_t ip6d_nxt; /* next header */ uint8_t ip6d_nxt; /* next header */
skipping to change at page 10, line 31 skipping to change at page 10, line 21
#define IP6F_RESERVED_MASK 0x0006 /* reserved bits in ip6f_offlg */ #define IP6F_RESERVED_MASK 0x0006 /* reserved bits in ip6f_offlg */
#define IP6F_MORE_FRAG 0x0001 /* more-fragments flag */ #define IP6F_MORE_FRAG 0x0001 /* more-fragments flag */
#else /* BYTE_ORDER == LITTLE_ENDIAN */ #else /* BYTE_ORDER == LITTLE_ENDIAN */
#define IP6F_OFF_MASK 0xf8ff /* mask out offset from _offlg */ #define IP6F_OFF_MASK 0xf8ff /* mask out offset from _offlg */
#define IP6F_RESERVED_MASK 0x0600 /* reserved bits in ip6f_offlg */ #define IP6F_RESERVED_MASK 0x0600 /* reserved bits in ip6f_offlg */
#define IP6F_MORE_FRAG 0x0100 /* more-fragments flag */ #define IP6F_MORE_FRAG 0x0100 /* more-fragments flag */
#endif #endif
2.1.3. IPv6 Options 2.1.3. IPv6 Options
Eleven options are defined for IPv6 at the time of writing this Several options are defined for IPv6, and we define structures and
document. We define structures for all except the unspecified EID macro definitions for some of them below. The following structures
option. The following structures are defined as a result of are defined as a result of including <netinet/ip6.h>.
including <netinet/ip6.h>.
/* IPv6 options */ /* IPv6 options */
struct ip6_opt { struct ip6_opt {
uint8_t ip6o_type; uint8_t ip6o_type;
uint8_t ip6o_len; uint8_t ip6o_len;
}; };
/* /*
* The high-order 3 bits of the option type define the behavior * The high-order 3 bits of the option type define the behavior
* when processing an unknown option and whether or not the option * when processing an unknown option and whether or not the option
skipping to change at page 11, line 10 skipping to change at page 10, line 45
*/ */
#define IP6OPT_TYPE(o) ((o) & 0xc0) #define IP6OPT_TYPE(o) ((o) & 0xc0)
#define IP6OPT_TYPE_SKIP 0x00 #define IP6OPT_TYPE_SKIP 0x00
#define IP6OPT_TYPE_DISCARD 0x40 #define IP6OPT_TYPE_DISCARD 0x40
#define IP6OPT_TYPE_FORCEICMP 0x80 #define IP6OPT_TYPE_FORCEICMP 0x80
#define IP6OPT_TYPE_ICMP 0xc0 #define IP6OPT_TYPE_ICMP 0xc0
#define IP6OPT_MUTABLE 0x20 #define IP6OPT_MUTABLE 0x20
#define IP6OPT_PAD1 0x00 /* 00 0 00000 */ #define IP6OPT_PAD1 0x00 /* 00 0 00000 */
#define IP6OPT_PADN 0x01 /* 00 0 00001 */ #define IP6OPT_PADN 0x01 /* 00 0 00001 */
#define IP6OPT_JUMBO 0xc2 /* 11 0 00010 = 194 */ #define IP6OPT_JUMBO 0xc2 /* 11 0 00010 */
#define IP6OPT_NSAP_ADDR 0xc3 /* 11 0 00011 */ #define IP6OPT_NSAP_ADDR 0xc3 /* 11 0 00011 */
#define IP6OPT_TUNNEL_LIMIT 0x04 /* 00 0 00100 */ #define IP6OPT_TUNNEL_LIMIT 0x04 /* 00 0 00100 */
#define IP6OPT_ROUTER_ALERT 0x05 /* 00 0 00101 */ #define IP6OPT_ROUTER_ALERT 0x05 /* 00 0 00101 */
#define IP6OPT_BINDING_UPDATE 0xc6 /* 11 0 00110 */
#define IP6OPT_BINDING_ACK 0x07 /* 00 0 00111 */
#define IP6OPT_BINDING_REQ 0x08 /* 00 0 01000 */
#define IP6OPT_HOME_ADDRESS 0xc9 /* 11 0 01001 */
#define IP6OPT_EID 0x8a /* 10 0 01010 */
/* Jumbo Payload Option */ /* Jumbo Payload Option */
struct ip6_opt_jumbo { struct ip6_opt_jumbo {
uint8_t ip6oj_type; uint8_t ip6oj_type;
uint8_t ip6oj_len; uint8_t ip6oj_len;
uint8_t ip6oj_jumbo_len[4]; uint8_t ip6oj_jumbo_len[4];
}; };
#define IP6OPT_JUMBO_LEN 6 #define IP6OPT_JUMBO_LEN 6
/* NSAP Address Option */ /* NSAP Address Option */
struct ip6_opt_nsap { struct ip6_opt_nsap {
skipping to change at page 12, line 15 skipping to change at page 11, line 47
#ifdef _BIG_ENDIAN #ifdef _BIG_ENDIAN
#define IP6_ALERT_MLD 0x0000 #define IP6_ALERT_MLD 0x0000
#define IP6_ALERT_RSVP 0x0001 #define IP6_ALERT_RSVP 0x0001
#define IP6_ALERT_AN 0x0002 #define IP6_ALERT_AN 0x0002
#else #else
#define IP6_ALERT_MLD 0x0000 #define IP6_ALERT_MLD 0x0000
#define IP6_ALERT_RSVP 0x0100 #define IP6_ALERT_RSVP 0x0100
#define IP6_ALERT_AN 0x0200 #define IP6_ALERT_AN 0x0200
#endif #endif
/* Binding Update Option */
struct ip6_opt_binding_update {
uint8_t ip6ou_type;
uint8_t ip6ou_len;
uint8_t ip6ou_flags;
uint8_t ip6ou_prefixlen;
uint8_t ip6ou_seqno[2];
uint8_t ip6ou_lifetime[4];
uint8_t ip6ou_coa[16]; /* Optional based on flags */
/* followed by sub-options */
};
/* Binding Update Flags */
#define IP6_BUF_ACK 0x80 /* Request a binding ack */
#define IP6_BUF_HOME 0x40 /* Home Registration */
#define IP6_BUF_COA 0x20 /* Care-of-address present in option */
#define IP6_BUF_ROUTER 0x10 /* Sending mobile node is a router */
/* Binding Ack Option */
struct ip6_opt_binding_ack {
uint8_t ip6oa_type;
uint8_t ip6oa_len;
uint8_t ip6oa_status;
uint8_t ip6oa_seqno[2];
uint8_t ip6oa_lifetime[4];
uint8_t ip6oa_refresh[4];
/* followed by sub-options */
};
/* Binding Request Option */
struct ip6_opt_binding_request {
uint8_t ip6or_type;
uint8_t ip6or_len;
/* followed by sub-options */
};
/* Home Address Option */
struct ip6_opt_home_address {
uint8_t ip6oh_type;
uint8_t ip6oh_len;
uint8_t ip6oh_addr[16]; /* Home Address */
/* followed by sub-options */
};
2.2. The icmp6_hdr Structure 2.2. The icmp6_hdr Structure
The ICMPv6 header is needed by numerous IPv6 applications including The ICMPv6 header is needed by numerous IPv6 applications including
Ping, Traceroute, router discovery daemons, and neighbor discovery Ping, Traceroute, router discovery daemons, and neighbor discovery
daemons. The following structure is defined as a result of including daemons. The following structure is defined as a result of including
<netinet/icmp6.h>. Note that this is a new header. <netinet/icmp6.h>. Note that this is a new header.
struct icmp6_hdr { struct icmp6_hdr {
uint8_t icmp6_type; /* type field */ uint8_t icmp6_type; /* type field */
uint8_t icmp6_code; /* code field */ uint8_t icmp6_code; /* code field */
skipping to change at page 15, line 17 skipping to change at page 14, line 5
/* could be followed by options */ /* could be followed by options */
}; };
#define nd_ra_type nd_ra_hdr.icmp6_type #define nd_ra_type nd_ra_hdr.icmp6_type
#define nd_ra_code nd_ra_hdr.icmp6_code #define nd_ra_code nd_ra_hdr.icmp6_code
#define nd_ra_cksum nd_ra_hdr.icmp6_cksum #define nd_ra_cksum nd_ra_hdr.icmp6_cksum
#define nd_ra_curhoplimit nd_ra_hdr.icmp6_data8[0] #define nd_ra_curhoplimit nd_ra_hdr.icmp6_data8[0]
#define nd_ra_flags_reserved nd_ra_hdr.icmp6_data8[1] #define nd_ra_flags_reserved nd_ra_hdr.icmp6_data8[1]
#define ND_RA_FLAG_MANAGED 0x80 #define ND_RA_FLAG_MANAGED 0x80
#define ND_RA_FLAG_OTHER 0x40 #define ND_RA_FLAG_OTHER 0x40
#define ND_RA_FLAG_HOME_AGENT 0x20
#define nd_ra_router_lifetime nd_ra_hdr.icmp6_data16[1] #define nd_ra_router_lifetime nd_ra_hdr.icmp6_data16[1]
struct nd_neighbor_solicit { /* neighbor solicitation */ struct nd_neighbor_solicit { /* neighbor solicitation */
struct icmp6_hdr nd_ns_hdr; struct icmp6_hdr nd_ns_hdr;
struct in6_addr nd_ns_target; /* target address */ struct in6_addr nd_ns_target; /* target address */
/* could be followed by options */ /* could be followed by options */
}; };
#define nd_ns_type nd_ns_hdr.icmp6_type #define nd_ns_type nd_ns_hdr.icmp6_type
#define nd_ns_code nd_ns_hdr.icmp6_code #define nd_ns_code nd_ns_hdr.icmp6_code
skipping to change at page 16, line 26 skipping to change at page 15, line 13
uint8_t nd_opt_type; uint8_t nd_opt_type;
uint8_t nd_opt_len; /* in units of 8 octets */ uint8_t nd_opt_len; /* in units of 8 octets */
/* followed by option specific data */ /* followed by option specific data */
}; };
#define ND_OPT_SOURCE_LINKADDR 1 #define ND_OPT_SOURCE_LINKADDR 1
#define ND_OPT_TARGET_LINKADDR 2 #define ND_OPT_TARGET_LINKADDR 2
#define ND_OPT_PREFIX_INFORMATION 3 #define ND_OPT_PREFIX_INFORMATION 3
#define ND_OPT_REDIRECTED_HEADER 4 #define ND_OPT_REDIRECTED_HEADER 4
#define ND_OPT_MTU 5 #define ND_OPT_MTU 5
#define ND_OPT_ADVINTERVAL 7
#define ND_OPT_HOMEAGENT_INFO 8
struct nd_opt_prefix_info { /* prefix information */ struct nd_opt_prefix_info { /* prefix information */
uint8_t nd_opt_pi_type; uint8_t nd_opt_pi_type;
uint8_t nd_opt_pi_len; uint8_t nd_opt_pi_len;
uint8_t nd_opt_pi_prefix_len; uint8_t nd_opt_pi_prefix_len;
uint8_t nd_opt_pi_flags_reserved; uint8_t nd_opt_pi_flags_reserved;
uint32_t nd_opt_pi_valid_time; uint32_t nd_opt_pi_valid_time;
uint32_t nd_opt_pi_preferred_time; uint32_t nd_opt_pi_preferred_time;
uint32_t nd_opt_pi_reserved2; uint32_t nd_opt_pi_reserved2;
/* XXX uint8_t nd_opt_pi_reserved2[3]; */
/* XXX uint8_t nd_opt_pi_sitelen; */
struct in6_addr nd_opt_pi_prefix; struct in6_addr nd_opt_pi_prefix;
}; };
#define ND_OPT_PI_FLAG_ONLINK 0x80 #define ND_OPT_PI_FLAG_ONLINK 0x80
#define ND_OPT_PI_FLAG_AUTO 0x40 #define ND_OPT_PI_FLAG_AUTO 0x40
#define ND_OPT_PI_FLAG_ROUTER 0x20 /* Added my Mobile IPv6 */
#define ND_OPT_PI_FLAG_SITEPREF 0x10 /* XXX sitelen is valid */
struct nd_opt_rd_hdr { /* redirected header */ struct nd_opt_rd_hdr { /* redirected header */
uint8_t nd_opt_rh_type; uint8_t nd_opt_rh_type;
uint8_t nd_opt_rh_len; uint8_t nd_opt_rh_len;
uint16_t nd_opt_rh_reserved1; uint16_t nd_opt_rh_reserved1;
uint32_t nd_opt_rh_reserved2; uint32_t nd_opt_rh_reserved2;
/* followed by IP header and data */ /* followed by IP header and data */
}; };
struct nd_opt_mtu { /* MTU option */ struct nd_opt_mtu { /* MTU option */
uint8_t nd_opt_mtu_type; uint8_t nd_opt_mtu_type;
uint8_t nd_opt_mtu_len; uint8_t nd_opt_mtu_len;
uint16_t nd_opt_mtu_reserved; uint16_t nd_opt_mtu_reserved;
uint32_t nd_opt_mtu_mtu; uint32_t nd_opt_mtu_mtu;
}; };
struct nd_opt_advinterval { /* Advertisement Interval */
uint8_t nd_opt_adv_type;
uint8_t nd_opt_adv_len;
uint16_t nd_opt_adv_reserved;
uint32_t nd_opt_adv_interval; /* In milliseconds */
};
struct nd_opt_homeagent_info { /* Home Agent info */
uint8_t nd_opt_hai_type;
uint8_t nd_opt_hai_len;
uint16_t nd_opt_hai_reserved;
int16_t nd_opt_hai_preference;
uint16_t nd_opt_hai_lifetime;
};
We note that the nd_na_flags_reserved flags have the same byte We note that the nd_na_flags_reserved flags have the same byte
ordering problems as we discussed with ip6f_offlg. ordering problems as we discussed with ip6f_offlg.
2.2.3. Multicast Listener Discovery Definitions 2.2.3. Multicast Listener Discovery Definitions
The following structures and definitions are defined as a result of The following structures and definitions are defined as a result of
including <netinet/icmp6.h>. including <netinet/icmp6.h>.
#define MLD_LISTENER_QUERY 130 #define MLD_LISTENER_QUERY 130
#define MLD_LISTENER_REPORT 131 #define MLD_LISTENER_REPORT 131
skipping to change at page 18, line 14 skipping to change at page 16, line 28
2.2.4. ICMPv6 Router Renumbering Definitions 2.2.4. ICMPv6 Router Renumbering Definitions
The following structures and definitions are defined as a result of The following structures and definitions are defined as a result of
including <netinet/icmp6.h>. including <netinet/icmp6.h>.
#define ICMP6_ROUTER_RENUMBERING 138 /* router renumbering */ #define ICMP6_ROUTER_RENUMBERING 138 /* router renumbering */
struct icmp6_router_renum { /* router renumbering header */ struct icmp6_router_renum { /* router renumbering header */
struct icmp6_hdr rr_hdr; struct icmp6_hdr rr_hdr;
u_int8_t rr_segnum; uint8_t rr_segnum;
u_int8_t rr_flags; uint8_t rr_flags;
u_int16_t rr_maxdelay; uint16_t rr_maxdelay;
u_int32_t rr_reserved; uint32_t rr_reserved;
}; };
#define rr_type rr_hdr.icmp6_type #define rr_type rr_hdr.icmp6_type
#define rr_code rr_hdr.icmp6_code #define rr_code rr_hdr.icmp6_code
#define rr_cksum rr_hdr.icmp6_cksum #define rr_cksum rr_hdr.icmp6_cksum
#define rr_seqnum rr_hdr.icmp6_data32[0] #define rr_seqnum rr_hdr.icmp6_data32[0]
/* Router renumbering flags */ /* Router renumbering flags */
#define ICMP6_RR_FLAGS_TEST 0x80 #define ICMP6_RR_FLAGS_TEST 0x80
#define ICMP6_RR_FLAGS_REQRESULT 0x40 #define ICMP6_RR_FLAGS_REQRESULT 0x40
#define ICMP6_RR_FLAGS_FORCEAPPLY 0x20 #define ICMP6_RR_FLAGS_FORCEAPPLY 0x20
#define ICMP6_RR_FLAGS_SPECSITE 0x10 #define ICMP6_RR_FLAGS_SPECSITE 0x10
#define ICMP6_RR_FLAGS_PREVDONE 0x08 #define ICMP6_RR_FLAGS_PREVDONE 0x08
struct rr_pco_match { /* match prefix part */ struct rr_pco_match { /* match prefix part */
u_int8_t rpm_code; uint8_t rpm_code;
u_int8_t rpm_len; uint8_t rpm_len;
u_int8_t rpm_ordinal; uint8_t rpm_ordinal;
u_int8_t rpm_matchlen; uint8_t rpm_matchlen;
u_int8_t rpm_minlen; uint8_t rpm_minlen;
u_int8_t rpm_maxlen; uint8_t rpm_maxlen;
u_int16_t rpm_reserved; uint16_t rpm_reserved;
struct in6_addr rpm_prefix; struct in6_addr rpm_prefix;
}; };
/* PCO code values */ /* PCO code values */
#define RPM_PCO_ADD 1 #define RPM_PCO_ADD 1
#define RPM_PCO_CHANGE 2 #define RPM_PCO_CHANGE 2
#define RPM_PCO_SETGLOBAL 3 #define RPM_PCO_SETGLOBAL 3
struct rr_pco_use { /* use prefix part */ struct rr_pco_use { /* use prefix part */
u_int8_t rpu_uselen; uint8_t rpu_uselen;
u_int8_t rpu_keeplen; uint8_t rpu_keeplen;
u_int8_t rpu_ramask; uint8_t rpu_ramask;
u_int8_t rpu_raflags; uint8_t rpu_raflags;
u_int32_t rpu_vltime; uint32_t rpu_vltime;
u_int32_t rpu_pltime; uint32_t rpu_pltime;
u_int32_t rpu_flags; uint32_t rpu_flags;
struct in6_addr rpu_prefix; struct in6_addr rpu_prefix;
}; };
#define ICMP6_RR_PCOUSE_RAFLAGS_ONLINK 0x20 #define ICMP6_RR_PCOUSE_RAFLAGS_ONLINK 0x20
#define ICMP6_RR_PCOUSE_RAFLAGS_AUTO 0x10 #define ICMP6_RR_PCOUSE_RAFLAGS_AUTO 0x10
#if BYTE_ORDER == BIG_ENDIAN #if BYTE_ORDER == BIG_ENDIAN
#define ICMP6_RR_PCOUSE_FLAGS_DECRVLTIME 0x80000000 #define ICMP6_RR_PCOUSE_FLAGS_DECRVLTIME 0x80000000
#define ICMP6_RR_PCOUSE_FLAGS_DECRPLTIME 0x40000000 #define ICMP6_RR_PCOUSE_FLAGS_DECRPLTIME 0x40000000
#elif BYTE_ORDER == LITTLE_ENDIAN #elif BYTE_ORDER == LITTLE_ENDIAN
#define ICMP6_RR_PCOUSE_FLAGS_DECRVLTIME 0x80 #define ICMP6_RR_PCOUSE_FLAGS_DECRVLTIME 0x80
#define ICMP6_RR_PCOUSE_FLAGS_DECRPLTIME 0x40 #define ICMP6_RR_PCOUSE_FLAGS_DECRPLTIME 0x40
#endif #endif
struct rr_result { /* router renumbering result message */ struct rr_result { /* router renumbering result message */
u_int16_t rrr_flags; uint16_t rrr_flags;
u_int8_t rrr_ordinal; uint8_t rrr_ordinal;
u_int8_t rrr_matchedlen; uint8_t rrr_matchedlen;
u_int32_t rrr_ifid; uint32_t rrr_ifid;
struct in6_addr rrr_prefix; struct in6_addr rrr_prefix;
}; };
#if BYTE_ORDER == BIG_ENDIAN #if BYTE_ORDER == BIG_ENDIAN
#define ICMP6_RR_RESULT_FLAGS_OOB 0x0002 #define ICMP6_RR_RESULT_FLAGS_OOB 0x0002
#define ICMP6_RR_RESULT_FLAGS_FORBIDDEN 0x0001 #define ICMP6_RR_RESULT_FLAGS_FORBIDDEN 0x0001
#elif BYTE_ORDER == LITTLE_ENDIAN #elif BYTE_ORDER == LITTLE_ENDIAN
#define ICMP6_RR_RESULT_FLAGS_OOB 0x0200 #define ICMP6_RR_RESULT_FLAGS_OOB 0x0200
#define ICMP6_RR_RESULT_FLAGS_FORBIDDEN 0x0100 #define ICMP6_RR_RESULT_FLAGS_FORBIDDEN 0x0100
#endif #endif
skipping to change at page 20, line 27 skipping to change at page 18, line 39
proto = getprotobyname("icmp"); proto = getprotobyname("icmp");
s = socket(PF_INET, SOCK_RAW, proto->p_proto); s = socket(PF_INET, SOCK_RAW, proto->p_proto);
Common names are required for the new IPv6 protocols in this file, to Common names are required for the new IPv6 protocols in this file, to
provide portability of applications that call the getprotoXXX() provide portability of applications that call the getprotoXXX()
functions. functions.
We define the following protocol names with the values shown. These We define the following protocol names with the values shown. These
are taken from ftp://ftp.isi.edu/in-notes/iana/assignments/protocol- are taken from http://www.iana.org/assignments/protocol-numbers.
numbers.
hopopt 0 # hop-by-hop options for ipv6 hopopt 0 # hop-by-hop options for ipv6
ipv6 41 # ipv6 ipv6 41 # ipv6
ipv6-route 43 # routing header for ipv6 ipv6-route 43 # routing header for ipv6
ipv6-frag 44 # fragment header for ipv6 ipv6-frag 44 # fragment header for ipv6
esp 50 # encapsulating security payload for ipv6 esp 50 # encapsulating security payload for ipv6
ah 51 # authentication header for ipv6 ah 51 # authentication header for ipv6
ipv6-icmp 58 # icmp for ipv6 ipv6-icmp 58 # icmp for ipv6
ipv6-nonxt 59 # no next header for ipv6 ipv6-nonxt 59 # no next header for ipv6
ipv6-opts 60 # destination options for ipv6 ipv6-opts 60 # destination options for ipv6
skipping to change at page 21, line 20 skipping to change at page 19, line 30
ordering and used the host's byte order for certain IP header fields. ordering and used the host's byte order for certain IP header fields.
Another difference from IPv4 raw sockets is that complete packets Another difference from IPv4 raw sockets is that complete packets
(that is, IPv6 packets with extension headers) cannot be sent or (that is, IPv6 packets with extension headers) cannot be sent or
received using the IPv6 raw sockets API. Instead, ancillary data received using the IPv6 raw sockets API. Instead, ancillary data
objects are used to transfer the extension headers and hoplimit objects are used to transfer the extension headers and hoplimit
information, as described in Section 6. Should an application need information, as described in Section 6. Should an application need
access to the complete IPv6 packet, some other technique, such as the access to the complete IPv6 packet, some other technique, such as the
datalink interfaces BPF or DLPI, must be used. datalink interfaces BPF or DLPI, must be used.
All fields in the IPv6 header that an application might want to All fields except the flow label field in the IPv6 header that an
change (i.e., everything other than the version number) can be application might want to change (i.e., everything other than the
modified using ancillary data and/or socket options by the version number) can be modified using ancillary data and/or socket
application for output. All fields in a received IPv6 header (other options by the application for output. All fields except the flow
than the version number and Next Header fields) and all extension label field in a received IPv6 header (other than the version number
headers are also made available to the application as ancillary data and Next Header fields) and all extension headers that an application
on input. Hence there is no need for a socket option similar to the might want to specify are also made available to the application as
IPv4 IP_HDRINCL socket option and on receipt the application will ancillary data on input. Hence there is no need for a socket option
only receive the payload i.e. the data after the IPv6 header and all similar to the IPv4 IP_HDRINCL socket option and on receipt the
the extension headers. application will only receive the payload i.e. the data after the
IPv6 header and all the extension headers.
This API does not define access to the flow label field, because
today there is no standard usage of the field.
When writing to a raw socket the kernel will automatically fragment When writing to a raw socket the kernel will automatically fragment
the packet if its size exceeds the path MTU, inserting the required the packet if its size exceeds the path MTU, inserting the required
fragmentation headers. On input the kernel reassembles received fragmentation headers. On input the kernel reassembles received
fragments, so the reader of a raw socket never sees any fragment fragments, so the reader of a raw socket never sees any fragment
headers. headers.
When we say "an ICMPv6 raw socket" we mean a socket created by When we say "an ICMPv6 raw socket" we mean a socket created by
calling the socket function with the three arguments PF_INET6, calling the socket function with the three arguments PF_INET6,
SOCK_RAW, and IPPROTO_ICMPV6. SOCK_RAW, and IPPROTO_ICMPV6.
skipping to change at page 22, line 30 skipping to change at page 20, line 40
the user data of where the checksum is located. the user data of where the checksum is located.
int offset = 2; int offset = 2;
setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, sizeof(offset)); setsockopt(fd, IPPROTO_IPV6, IPV6_CHECKSUM, &offset, sizeof(offset));
By default, this socket option is disabled. Setting the offset to -1 By default, this socket option is disabled. Setting the offset to -1
also disables the option. By disabled we mean (1) the kernel will also disables the option. By disabled we mean (1) the kernel will
not calculate and store a checksum for outgoing packets, and (2) the not calculate and store a checksum for outgoing packets, and (2) the
kernel will not verify a checksum for received packets. kernel will not verify a checksum for received packets.
This option assumes the use of the 16-bit one's complement of the
one's complement sum as the checksum algorithm and that the checksum
field is aligned on a 16-bit boundary. Thus, specifying a positive
odd value as offset is invalid, and setsockopt() will fail for odd
offset values.
An attempt to set IPV6_CHECKSUM for an ICMPv6 socket will fail. An attempt to set IPV6_CHECKSUM for an ICMPv6 socket will fail.
(Note: Since the checksum is always calculated by the kernel for an (Note: Since the checksum is always calculated by the kernel for an
ICMPv6 socket, applications are not able to generate ICMPv6 packets ICMPv6 socket, applications are not able to generate ICMPv6 packets
with incorrect checksums (presumably for testing purposes) using this with incorrect checksums (presumably for testing purposes) using this
API.) API.)
3.2. ICMPv6 Type Filtering 3.2. ICMPv6 Type Filtering
ICMPv4 raw sockets receive most ICMPv4 messages received by the ICMPv4 raw sockets receive most ICMPv4 messages received by the
skipping to change at page 24, line 25 skipping to change at page 22, line 41
ICMP6_FILTER_SETBLOCKALL(&myfilt); ICMP6_FILTER_SETBLOCKALL(&myfilt);
ICMP6_FILTER_SETPASS(ND_ROUTER_ADVERT, &myfilt); ICMP6_FILTER_SETPASS(ND_ROUTER_ADVERT, &myfilt);
setsockopt(fd, IPPROTO_ICMPV6, ICMP6_FILTER, &myfilt, sizeof(myfilt)); setsockopt(fd, IPPROTO_ICMPV6, ICMP6_FILTER, &myfilt, sizeof(myfilt));
The filter structure is declared and then initialized to block all The filter structure is declared and then initialized to block all
messages types. The filter structure is then changed to allow router messages types. The filter structure is then changed to allow router
advertisement messages to be passed to the application and the filter advertisement messages to be passed to the application and the filter
is installed using setsockopt(). is installed using setsockopt().
In order to clear an installed filter the application can issue a
setsockopt for ICMP6_FILTER with a zero length. When no such filter
has been installed corresponding getsockopt() will return the kernel
default filter.
The icmp6_filter structure is similar to the fd_set datatype used The icmp6_filter structure is similar to the fd_set datatype used
with the select() function in the sockets API. The icmp6_filter with the select() function in the sockets API. The icmp6_filter
structure is an opaque datatype and the application should not care structure is an opaque datatype and the application should not care
how it is implemented. All the application does with this datatype how it is implemented. All the application does with this datatype
is allocate a variable of this type, pass a pointer to a variable of is allocate a variable of this type, pass a pointer to a variable of
this type to getsockopt() and setsockopt(), and operate on a variable this type to getsockopt() and setsockopt(), and operate on a variable
of this type using the six macros that we just defined. of this type using the six macros that we just defined.
Nevertheless, it is worth showing a simple implementation of this Nevertheless, it is worth showing a simple implementation of this
datatype and the six macros. datatype and the six macros.
skipping to change at page 25, line 15 skipping to change at page 23, line 37
implementation may want to change. The first four macros evaluate implementation may want to change. The first four macros evaluate
their first argument two times. The second two macros require the their first argument two times. The second two macros require the
inclusion of the <string.h> header for the memset() function.) inclusion of the <string.h> header for the memset() function.)
3.3. ICMPv6 Verification of Received Packets 3.3. ICMPv6 Verification of Received Packets
The protocol stack will verify the ICMPv6 checksum and discard any The protocol stack will verify the ICMPv6 checksum and discard any
packets with invalid checksums. packets with invalid checksums.
An implementation might perform additional validity checks on the An implementation might perform additional validity checks on the
ICMP message content and discard malformed packets. However, a ICMPv6 message content and discard malformed packets. However, a
portable application must not assume that such validity checks have portable application must not assume that such validity checks have
been performed. been performed.
The protocol stack should not automatically discard packets if the The protocol stack should not automatically discard packets if the
ICMP type is unknown to the stack. For extensibility reasons received ICMP type is unknown to the stack. For extensibility reasons received
ICMP packets with any type (informational or error) must be passed to ICMP packets with any type (informational or error) must be passed to
the applications (subject to ICMP6_FILTER filtering on the type value the applications (subject to ICMP6_FILTER filtering on the type value
and the checksum verification). and the checksum verification).
4. Access to IPv6 and Extension Headers 4. Access to IPv6 and Extension Headers
skipping to change at page 25, line 37 skipping to change at page 24, line 13
Applications need to be able to control IPv6 header and extension Applications need to be able to control IPv6 header and extension
header content when sending as well as being able to receive the header content when sending as well as being able to receive the
content of these headers. This is done by defining socket option content of these headers. This is done by defining socket option
types which can be used both with setsockopt and with ancillary data. types which can be used both with setsockopt and with ancillary data.
Ancillary data is discussed in Appendix A. The following optional Ancillary data is discussed in Appendix A. The following optional
information can be exchanged between the application and the kernel: information can be exchanged between the application and the kernel:
1. The send/receive interface and source/destination address, 1. The send/receive interface and source/destination address,
2. The hop limit, 2. The hop limit,
3. Next hop address, 3. Next hop address,
4. Routing header. 4. The traffic class,
5. Hop-by-Hop options, and 4. Routing header,
6. Destination options (both before and after a Routing header). 5. Hop-by-Hop options header, and
6. Destination options header (both before and after a Routing header).
First, to receive any of this optional information (other than the First, to receive any of this optional information (other than the
next hop address, which can only be set), the application must call next hop address, which can only be set), the application must call
setsockopt() to turn on the corresponding flag: setsockopt() to turn on the corresponding flag:
int on = 1; int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVPKTINFO, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVPKTINFO, &on, sizeof(on));
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVHOPLIMIT, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVHOPLIMIT, &on, sizeof(on));
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on));
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVHOPOPTS, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVHOPOPTS, &on, sizeof(on));
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on));
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDRDSTOPTS, setsockopt(fd, IPPROTO_IPV6, IPV6_RECVTCLASS, &on, sizeof(on));
&on, sizeof(on));
When any of these options are enabled, the corresponding data is When any of these options are enabled, the corresponding data is
returned as control information by recvmsg(), as one or more returned as control information by recvmsg(), as one or more
ancillary data objects. ancillary data objects.
Two different mechanisms exist for sending this optional information: Two different mechanisms exist for sending this optional information:
1. Using setsockopt to specify the option content for a socket. 1. Using setsockopt to specify the option content for a socket.
These are known an "sticky" options since they affect all These are known "sticky" options since they affect all
transmitted packets on the socket until either the a new transmitted packets on the socket until either a new setsockopt
setsockopt is done or the options are overridden using ancillary is done or the options are overridden using ancillary data.
data.
2. Using ancillary data to specify the option content for a single 2. Using ancillary data to specify the option content for a single
datagram. This only applies to datagram and raw sockets; not to datagram. This only applies to datagram and raw sockets; not to
TCP sockets. TCP sockets.
The three socket option parameters and the three cmsghdr fields that The three socket option parameters and the three cmsghdr fields that
describe the options/ancillary data objects are summarized as: describe the options/ancillary data objects are summarized as:
opt level/ optname/ optval/ opt level/ optname/ optval/
cmsg_level cmsg_type cmsg_data[] cmsg_level cmsg_type cmsg_data[]
------------ ------------ ------------------------ ------------ ------------ ------------------------
IPPROTO_IPV6 IPV6_PKTINFO in6_pktinfo structure IPPROTO_IPV6 IPV6_PKTINFO in6_pktinfo structure
IPPROTO_IPV6 IPV6_HOPLIMIT int IPPROTO_IPV6 IPV6_HOPLIMIT int
IPPROTO_IPV6 IPV6_NEXTHOP socket address structure IPPROTO_IPV6 IPV6_NEXTHOP socket address structure
IPPROTO_IPV6 IPV6_RTHDR ip6_rthdr structure IPPROTO_IPV6 IPV6_RTHDR ip6_rthdr structure
IPPROTO_IPV6 IPV6_HOPOPTS ip6_hbh structure IPPROTO_IPV6 IPV6_HOPOPTS ip6_hbh structure
IPPROTO_IPV6 IPV6_DSTOPTS ip6_dest structure IPPROTO_IPV6 IPV6_DSTOPTS ip6_dest structure
IPPROTO_IPV6 IPV6_RTHDRDSTOPTS ip6_dest structure IPPROTO_IPV6 IPV6_RTHDRDSTOPTS ip6_dest structure
IPPROTO_IPV6 IPV6_TCLASS int
(Note: IPV6_HOPLIMIT can be used as ancillary data items only)
All these options are described in detail in Section 6, 7, 8 and 9. All these options are described in detail in Section 6, 7, 8 and 9.
All the constants beginning with IPV6_ are defined as a result of All the constants beginning with IPV6_ are defined as a result of
including the <netinet/in.h>. including the <netinet/in.h>.
Issuing getsockopt() for the above options will return the sticky
option value i.e. the value set with setsockopt(). If no sticky
option value has been set getsockopt() will return the default value.
Note: We intentionally use the same constant for the cmsg_level Note: We intentionally use the same constant for the cmsg_level
member as is used as the second argument to getsockopt() and member as is used as the second argument to getsockopt() and
setsockopt() (what is called the "level"), and the same constant for setsockopt() (what is called the "level"), and the same constant for
the cmsg_type member as is used as the third argument to getsockopt() the cmsg_type member as is used as the third argument to getsockopt()
and setsockopt() (what is called the "option name"). and setsockopt() (what is called the "option name").
Issuing getsockopt() for the above options will return the sticky
option value i.e. the value set with setsockopt(). If no sticky
option value has been set getsockopt() will return the following
values:
- For the IPV6_PKTINFO option, it will return an in6_pktinfo
structure with ipi6_addr being in6addr_any and ipi6_ifindex being
zero.
- For the IPV6_TCLASS option, it will return the kernel default
value.
- For other options, it will indicate the lack of the option value
with optlen being zero.
The application does not explicitly need to access the data The application does not explicitly need to access the data
structures for the Routing header option, Hop-by-Hop option, and structures for the Routing header, Hop-by-Hop options header, and
Destination options, since the API to these features is through a set Destination options header, since the API to these features is
of inet6_rth_XXX() and inet6_opt_XXX() functions that we define in through a set of inet6_rth_XXX() and inet6_opt_XXX() functions that
Section 8 and Section 10. Those functions simplify the interface to we define in Section 7 and Section 10. Those functions simplify the
these features instead of requiring the application to know the interface to these features instead of requiring the application to
intimate details of the extension header formats. know the intimate details of the extension header formats.
4.1. TCP Implications 4.1. TCP Implications
It is not possible to use ancillary data to transmit the above It is not possible to use ancillary data to transmit the above
options for TCP since there is not a one-to-one mapping between send options for TCP since there is not a one-to-one mapping between send
operations and the TCP segments being transmitted. Instead an operations and the TCP segments being transmitted. Instead an
application can use setsockopt to specify them as sticky options. application can use setsockopt to specify them as sticky options.
When the application uses setsockopt to specify the above options it When the application uses setsockopt to specify the above options it
is expected that TCP will start using the new information when is expected that TCP will start using the new information when
sending segments. However, TCP may or may not use the new sending segments. However, TCP may or may not use the new
information when retransmitting segments that were originally sent information when retransmitting segments that were originally sent
when the old sticky options were in effect. when the old sticky options were in effect.
Applications using TCP can use ancillary data (after enabling the Applications using TCP could use ancillary data to receive the IPv6
desired IPV6_RECVxxx options) to receive the IPv6 and extension and extension header information by enabling the desired IPV6_RECVxxx
header information. However, since there is not a one-to-one mapping options and using recvmsg(). However, this is not feasible due to
between received TCP segments and recv operations seen by the the lack of mapping between received TCP segments and recv
application, when different TCP segments have different IPv6 and operations. Also, since most TCP applications do not use recvmsg(),
extension headers the application might not be able to observe all this type of approach would introduce an additional cost to
received headers. For efficiency reasons it is recommended that a application programmers. This specification thus provides a
TCP implementation not send ancillary data items with every received different method for access to optional information by the
segment but instead try to detect the points in the data stream when IPV6_PKTOPTIONS socket option.
the requested IPv6 and extension header content changes and only send
a single ancillary data item at the time of the change. Also, TCP
should send ancillary data items at the start of the connection and
when the application enables a new IPV6_RECVxxx option.
For example, assume an application has enabled IPV6_RECVHOPLIMIT getsockopt(fd, IPPROTO_IPV6, IPV6_PKTOPTIONS, buf, &len);
before a connection is established. Then the first recvmsg() would
have an IPV6_HOPLIMIT item indicating the hop limit in the first data
segment. Should the hoplimit in the received data segment change a
subsequent recvmsg() will also have an IPV6_HOPLIMIT item. However,
the application must be prepared to handle ancillary data items even
though the hop limit did not change. Note that should the hop limit
in received ACK-only segments be different than the hop limit in data
segments the application might only be able to observe the hop limit
in the received data segments.
The above example was for hop limit but the application should be returns a buffer with one or more ancillary data objects for all the
prepared to handle the corresponding behavior for the other option optional receive information that the application has previously
specified that it wants to receive. The fourth argument points to
the buffer that is filled in by the call. The fifth argument is a
pointer to a value-result integer: when the function is called the
integer specifies the size of the buffer pointed to by the fourth
argument, and on return this integer contains the actual number of
bytes that were returned. The application processes this buffer
exactly as if the buffer were returned by recvmsg() as control
information. information.
The above recvmsg() behavior allows the application to detect changes When a TCP application requires the kernel to pass optional
in the received IPv6 and extension headers without resorting to information by IPV6_RECVxxx options, the kernel stores the
periodic getsockopt() calls. corresponding information of the last-received segment. That is, the
stored information will be overridden when the kernel receives a
segment before the application calls getsockopt() for
IPV6_PKTOPTIONS. This means that applications usually cannot follow
all changes on the optional information. Thus, applications should
not use the optional information for authentication or qualification
purposes. The information can only be used as some hints about the
received packets. For the same reason, it is not meaningful to poll
the socket periodically in order to see if there have been some
changes on the received packets.
The IPV6_PKTOPTIONS socket option is a get-only option, and can only
be used by a TCP socket.
4.2. UDP and Raw Socket Implications 4.2. UDP and Raw Socket Implications
The receive behavior for UDP and raw sockets is quite The receive behavior for UDP and raw sockets is quite
straightforward. After the application has enabled an IPV6_RECVxxx straightforward. After the application has enabled an IPV6_RECVxxx
socket option it will receive ancillary data items for every socket option it will receive ancillary data items for every
recvmsg() call containing the requested information. However, if the recvmsg() call containing the requested information. However, if the
information is not present in the packet the ancillary data item will information is not present in the packet the ancillary data item will
not be included. For example, if the application enables not be included. For example, if the application enables
IPV6_RECVRTHDR and a received datagram does not contain a Routing IPV6_RECVRTHDR and a received datagram does not contain a Routing
header there will not be an IPV6_RTHDR ancillary data item. Note header there will not be an IPV6_RTHDR ancillary data item. Note
that due to buffering in the socket implementation there might be that due to buffering in the socket implementation there might be
some packets queued when an IPV6_RECVxxx option is enabled and they some packets queued when an IPV6_RECVxxx option is enabled and they
might not have the ancillary data information. might not have the ancillary data information.
For sending the application has the choice between using sticky For sending the application has the choice between using sticky
options and ancillary data. The application can also use both having options and ancillary data. The application can also use both having
the sticky options specify the "default" and using ancillary data to the sticky options specify the "default" and using ancillary data to
override the default options. Note that if any ancillary data is override the default options.
specified in a call to sendmsg(), all of the sticky options are
overridden for that datagram. For example, if the application has When an ancillary data item is specified in a call to sendmsg(), the
set IPV6_RTHDR using a sticky option and later passes IPV6_HOPLIMIT item will override an existing sticky option of the same name (if
as ancillary data this will override the IPV6_RTHDR sticky option and previously specified). For example, if the application has set
no Routing header will be sent with that datagram. IPV6_RTHDR using a sticky option and later passes IPV6_RTHDR as
ancillary data this will override the IPV6_RTHDR sticky option and
the routing header of the outgoing packet will be from the ancillary
data item, not from the sticky option. Note, however, that other
sticky options than IPV6_RTHDR will not be affected by the IPV6_RTHDR
ancillary data item; the overriding mechanism only works for the same
type of sticky options and ancillary data items.
(Note: the overriding rule is different from the one in RFC 2292. In
RFC 2292, an ancillary data item overrode all sticky options
previously defined. This was reasonable, because sticky options
could only be specified as a set by a single socket option. However,
in this API, each option is separated so that it can be specified as
a single sticky option. Additionally, there are much more ancillary
data items and sticky options than in RFC 2292, including ancillary-
only one. Thus, it should be natural for application programmers to
separate the overriding rule as well.)
An application can also temporarily disable a particular sticky
option by specifying a corresponding ancillary data item that could
disable the sticky option when being used as an argument for a socket
option. For example, if the application has set IPV6_HOPOPTS as a
sticky option and later passes IPV6_HOPOPTS with a zero length as an
ancillary data item, the packet will not have a Hop-by-Hop options
header.
5. Extensions to Socket Ancillary Data 5. Extensions to Socket Ancillary Data
This specification uses ancillary data as defined in Posix.1g which This specification uses ancillary data as defined in Posix.1g with
the following compatible extensions: the following compatible extensions:
- CMSG_NXTHDR has been extended to handle a NULL 2nd argument to - CMSG_NXTHDR has been extended to handle a NULL 2nd argument to
mean "get the first header". See Section 22.3.2. mean "get the first header". See Section 22.3.2.
- A new CMSG_SPACE macro is defined. It is used to determine how - A new CMSG_SPACE macro is defined. It is used to determine how
much space need to be allocated for an ancillary data item. See much space need to be allocated for an ancillary data item. See
Section 22.3.4. Section 22.3.4.
- A new CMSG_LEN macro is defined. It returns the value to store - A new CMSG_LEN macro is defined. It returns the value to store
in the cmsg_len member of the cmsghdr structure, taking into in the cmsg_len member of the cmsghdr structure, taking into
account any padding needed to satisfy alignment requirements. account any padding needed to satisfy alignment requirements.
See Section 22.3.5. See Section 22.3.5.
6. Packet Information 6. Packet Information
There are four pieces of information that an application can specify There are five pieces of information that an application can specify
for an outgoing packet using ancillary data: for an outgoing packet using ancillary data:
1. the source IPv6 address, 1. the source IPv6 address,
2. the outgoing interface index, 2. the outgoing interface index,
3. the outgoing hop limit, and 3. the outgoing hop limit,
4. the next hop address. 4. the next hop address, and
5. the outgoing traffic class value.
Three similar pieces of information can be returned for a received Four similar pieces of information can be returned for a received
packet as ancillary data: packet as ancillary data:
1. the destination IPv6 address, 1. the destination IPv6 address,
2. the arriving interface index, and 2. the arriving interface index,
3. the arriving hop limit. 3. the arriving hop limit, and
4. the arriving traffic class value.
The first two pieces of information are contained in an in6_pktinfo The first two pieces of information are contained in an in6_pktinfo
structure that is set with setsockopt() or sent as ancillary data structure that is set with setsockopt() or sent as ancillary data
with sendmsg() and received as ancillary data with recvmsg(). This with sendmsg() and received as ancillary data with recvmsg(). This
structure is defined as a result of including the <netinet/in.h>. structure is defined as a result of including the <netinet/in.h>.
struct in6_pktinfo { struct in6_pktinfo {
struct in6_addr ipi6_addr; /* src/dst IPv6 address */ struct in6_addr ipi6_addr; /* src/dst IPv6 address */
unsigned int ipi6_ifindex; /* send/recv interface index */ unsigned int ipi6_ifindex; /* send/recv interface index */
}; };
In the socket option and cmsghdr level will be IPPROTO_IPV6, the type In the socket option and cmsghdr level will be IPPROTO_IPV6, the type
will be IPV6_PKTINFO, and the first byte of the option value and will be IPV6_PKTINFO, and the first byte of the option value and
cmsg_data[] will be the first byte of the in6_pktinfo structure. An cmsg_data[] will be the first byte of the in6_pktinfo structure. An
application can clear any sticky IPV6_PKTINFO option by either doing application can clear any sticky IPV6_PKTINFO option by doing a
a setsockopt for option with optlen being zero, or by doing a
"regular" setsockopt with ipi6_addr being in6addr_any and "regular" setsockopt with ipi6_addr being in6addr_any and
ipi6_ifindex being zero. ipi6_ifindex being zero.
This information is returned as ancillary data by recvmsg() only if This information is returned as ancillary data by recvmsg() only if
the application has enabled the IPV6_RECVPKTINFO socket option: the application has enabled the IPV6_RECVPKTINFO socket option:
int on = 1; int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVPKTINFO, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVPKTINFO, &on, sizeof(on));
(Note: The hop limit is not contained in the in6_pktinfo structure (Note: The hop limit is not contained in the in6_pktinfo structure
skipping to change at page 30, line 36 skipping to change at page 30, line 7
describes a function to map an interface name to its interface index, describes a function to map an interface name to its interface index,
a function to map an interface index to its interface name, and a a function to map an interface index to its interface name, and a
function to return all the interface names and indexes. Notice from function to return all the interface names and indexes. Notice from
this document that no interface is ever assigned an index of 0. this document that no interface is ever assigned an index of 0.
When specifying the outgoing interface, if the ipi6_ifindex value is When specifying the outgoing interface, if the ipi6_ifindex value is
0, the kernel will choose the outgoing interface. If the application 0, the kernel will choose the outgoing interface. If the application
specifies an outgoing interface for a multicast packet, the interface specifies an outgoing interface for a multicast packet, the interface
specified by the ancillary data overrides any interface specified by specified by the ancillary data overrides any interface specified by
the IPV6_MULTICAST_IF socket option (described in [RFC-2553]), for the IPV6_MULTICAST_IF socket option (described in [RFC-2553]), for
that call to sendmsg() only. that call to sendmsg() only. Also, if the application specifies an
outgoing interface for a multicast packet as well as specifying a
generic outgoing interface by the IPV6_PKTINFO sticky option, the
latter will override the former for every multicast packet on the
corresponding socket. The reason for the ordering comes from
expectation that the source address is specified as well and that the
pair of the address and the outgoing interface should be desired.
When the IPV6_RECVPKTINFO socket option is enabled, the received When the IPV6_RECVPKTINFO socket option is enabled, the received
interface index is always returned as the ipi6_ifindex member of the interface index is always returned as the ipi6_ifindex member of the
in6_pktinfo structure. in6_pktinfo structure.
6.2. Specifying/Receiving Source/Destination Address 6.2. Specifying/Receiving Source/Destination Address
The source IPv6 address can be specified by calling bind() before The source IPv6 address can be specified by calling bind() before
each output operation, but supplying the source address together with each output operation, but supplying the source address together with
the data requires less overhead (i.e., fewer system calls) and the data requires less overhead (i.e., fewer system calls) and
skipping to change at page 31, line 16 skipping to change at page 30, line 38
ipi6_addr member of the in6_pktinfo structure is the unspecified ipi6_addr member of the in6_pktinfo structure is the unspecified
address (IN6ADDR_ANY_INIT or in6addr_any), then (a) if an address is address (IN6ADDR_ANY_INIT or in6addr_any), then (a) if an address is
currently bound to the socket, it is used as the source address, or currently bound to the socket, it is used as the source address, or
(b) if no address is currently bound to the socket, the kernel will (b) if no address is currently bound to the socket, the kernel will
choose the source address. If the ipi6_addr member is not the choose the source address. If the ipi6_addr member is not the
unspecified address, but the socket has already bound a source unspecified address, but the socket has already bound a source
address, then the ipi6_addr value overrides the already-bound source address, then the ipi6_addr value overrides the already-bound source
address for this output operation only. address for this output operation only.
The kernel must verify that the requested source address is indeed a The kernel must verify that the requested source address is indeed a
unicast address assigned to the node. unicast address assigned to the node. When the address is a scoped
one, there may be ambiguity about its scope zone. This is
particularly the case for link-local addresses. In such a case, the
kernel must first determine the appropriate scope zone based on the
zone of the destination address or the outgoing interface (if known),
then qualify the address. This also means that it is not feasible to
specify the source address for a non-binding socket by the
IPV6_PKTINFO sticky option, unless the outgoing interface is also
specified. The application should simply use bind() for such
purposes.
IPV6_PKTINFO can also be used as a sticky option for specifying the
socket's default source address. However, the ipi6_addr member
should be ignored when the option is specified for a TCP socket,
because it is not possible to dynamically change the source address
of a TCP connection. This restriction should be applied even before
the socket binds a specific address.
When the in6_pktinfo structure is returned as ancillary data by When the in6_pktinfo structure is returned as ancillary data by
recvmsg(), the ipi6_addr member contains the destination IPv6 address recvmsg(), the ipi6_addr member contains the destination IPv6 address
from the received packet. from the received packet. For TCP sockets, the destination address
will be trivial; the local address of the connection.
6.3. Specifying/Receiving the Hop Limit 6.3. Specifying/Receiving the Hop Limit
The outgoing hop limit is normally specified with either the The outgoing hop limit is normally specified with either the
IPV6_UNICAST_HOPS socket option or the IPV6_MULTICAST_HOPS socket IPV6_UNICAST_HOPS socket option or the IPV6_MULTICAST_HOPS socket
option, both of which are described in [RFC-2553]. Specifying the option, both of which are described in [RFC-2553]. Specifying the
hop limit as ancillary data lets the application override either the hop limit as ancillary data lets the application override either the
kernel's default or a previously specified value, for either a kernel's default or a previously specified value, for either a
unicast destination or a multicast destination, for a single output unicast destination or a multicast destination, for a single output
operation. Returning the received hop limit is useful for programs operation. Returning the received hop limit is useful for programs
skipping to change at page 31, line 48 skipping to change at page 31, line 40
int on = 1; int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVHOPLIMIT, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVHOPLIMIT, &on, sizeof(on));
In the cmsghdr structure containing this ancillary data, the In the cmsghdr structure containing this ancillary data, the
cmsg_level member will be IPPROTO_IPV6, the cmsg_type member will be cmsg_level member will be IPPROTO_IPV6, the cmsg_type member will be
IPV6_HOPLIMIT, and the first byte of cmsg_data[] will be the first IPV6_HOPLIMIT, and the first byte of cmsg_data[] will be the first
byte of the integer hop limit. byte of the integer hop limit.
Nothing special need be done to specify the outgoing hop limit: just Nothing special need be done to specify the outgoing hop limit: just
specify the control information as ancillary data for sendmsg() or specify the control information as ancillary data for sendmsg(). As
using setsockopt(). As specified in [RFC-2553], the interpretation specified in [RFC-2553], the interpretation of the integer hop limit
of the integer hop limit value is value is
x < -1: return an error of EINVAL x < -1: return an error of EINVAL
x == -1: use kernel default x == -1: use kernel default
0 <= x <= 255: use x 0 <= x <= 255: use x
x >= 256: return an error of EINVAL x >= 256: return an error of EINVAL
In order to clear a sticky IPV6_HOPLIMIT option the application can This API defines IPV6_HOPLIMIT as an ancillary-only option, that is,
specify -1 as the value. Alternatively, the application can specify the option name cannot be used as a socket option. This is because
an IPV6_HOPLIMIT socket option with a zero length. the basic API has more fine-grained socket options; IPV6_UNICAST_HOPS
and IPV6_MULTICAST_HOPS.
6.4. Specifying the Next Hop Address 6.4. Specifying the Next Hop Address
The IPV6_NEXTHOP ancillary data object specifies the next hop for the The IPV6_NEXTHOP ancillary data object specifies the next hop for the
datagram as a socket address structure. In the cmsghdr structure datagram as a socket address structure. In the cmsghdr structure
containing this ancillary data, the cmsg_level member will be containing this ancillary data, the cmsg_level member will be
IPPROTO_IPV6, the cmsg_type member will be IPV6_NEXTHOP, and the IPPROTO_IPV6, the cmsg_type member will be IPV6_NEXTHOP, and the
first byte of cmsg_data[] will be the first byte of the socket first byte of cmsg_data[] will be the first byte of the socket
address structure. address structure.
This is a privileged option. (Note: It is implementation defined and This is a privileged option. (Note: It is implementation defined and
beyond the scope of this document to define what "privileged" means. beyond the scope of this document to define what "privileged" means.
Unix systems use this term to mean the process must have an effective Unix systems use this term to mean the process must have an effective
user ID of 0.) user ID of 0.)
If the socket address structure contains an IPv6 address (e.g., the This API only defines the case where the socket address contains an
sin6_family member is AF_INET6), then the node identified by that IPv6 address (i.e., the sa_family member is AF_INET6). And, in this
address must be a neighbor of the sending host. If that address case, the node identified by that address must be a neighbor of the
equals the destination IPv6 address of the datagram, then this is sending host. If that address equals the destination IPv6 address of
equivalent to the existing SO_DONTROUTE socket option. the datagram, then this is equivalent to the existing SO_DONTROUTE
socket option.
This option does not have any meaning for multicast destinations. In
such a case, the specified next hop will be ignored.
When the outgoing interface is specified by IPV6_PKTINFO as well, the
next hop specified by this option must be reachable via the specified
interface.
In order to clear a sticky IPV6_NEXTHOP option the application must In order to clear a sticky IPV6_NEXTHOP option the application must
issue a setsockopt for IPv6_NEXTHOP with a zero length. issue a setsockopt for IPV6_NEXTHOP with a zero length.
6.5. Additional Errors with sendmsg() and setsockopt() 6.5. Specifying/Receiving the Traffic Class value
The outgoing traffic class is normally set to 0. Specifying the
traffic class as ancillary data lets the application override either
the kernel's default or a previously specified value, for either a
unicast destination or a multicast destination, for a single output
operation. Returning the received traffic class is useful for
programs such as a diffserv debugging tool and for user level ECN
(explicit congestion notification) implementation.
The received traffic class is returned as ancillary data by recvmsg()
only if the application has enabled the IPV6_RECVTCLASS socket
option:
int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVTCLASS, &on, sizeof(on));
In the cmsghdr structure containing this ancillary data, the
cmsg_level member will be IPPROTO_IPV6, the cmsg_type member will be
IPV6_TCLASS, and the first byte of cmsg_data[] will be the first byte
of the integer traffic class.
To specify the outgoing traffic class value, just specify the control
information as ancillary data for sendmsg() or using setsockopt().
Just like the hop limit value, the interpretation of the integer
traffic class value is
x < -1: return an error of EINVAL
x == -1: use kernel default
0 <= x <= 255: use x
x >= 256: return an error of EINVAL
In order to clear a sticky IPV6_TCLASS option the application can
specify -1 as the value.
There are cases where the kernel needs to control the traffic class
value and conflicts with the user-specified value on the outgoing
traffic. An example is an implementation of ECN in the kernel,
setting 2 bits of the traffic class value. In such cases, the kernel
should override the user-specified value. On the incoming traffic,
the kernel may mask some of the bits in the traffic class field.
6.6. Additional Errors with sendmsg() and setsockopt()
With the IPV6_PKTINFO socket option there are no additional errors With the IPV6_PKTINFO socket option there are no additional errors
possible with the call to recvmsg(). But when specifying the possible with the call to recvmsg(). But when specifying the
outgoing interface or the source address, additional errors are outgoing interface or the source address, additional errors are
possible from sendmsg() or setsockopt(). Note that some possible from sendmsg() or setsockopt(). Note that some
implementations might only be able to return this type of errors for implementations might only be able to return this type of errors for
setsockopt(). The following are examples, but some of these may not setsockopt(). The following are examples, but some of these may not
be provided by some implementations, and some implementations may be provided by some implementations, and some implementations may
define additional errors: define additional errors:
skipping to change at page 33, line 16 skipping to change at page 34, line 11
ENETDOWN The interface specified by ipi6_ifindex is not enabled ENETDOWN The interface specified by ipi6_ifindex is not enabled
for IPv6 use. for IPv6 use.
EADDRNOTAVAIL ipi6_ifindex specifies an interface but the address EADDRNOTAVAIL ipi6_ifindex specifies an interface but the address
ipi6_addr is not available for use on that interface. ipi6_addr is not available for use on that interface.
EHOSTUNREACH No route to the destination exists over the interface EHOSTUNREACH No route to the destination exists over the interface
specified by ifi6_ifindex. specified by ifi6_ifindex.
6.7. Summary of outgoing interface selection
This document and [RFC-2553] specify various methods that affect the
selection of the packet's outgoing interface. This subsection
summarizes the ordering among those in order to ensure determined
behavior.
For a given outgoing packet on a given socket, the outgoing interface
is determined in the following order:
1. if an interface is specified in an IPV6_PKTINFO ancillary data
item, the interface is used.
2. otherwise, if an interface is specified in an IPV6_PKTINFO sticky
option, the interface is used.
3. otherwise, if the destination address is a multicast address and
the IPV6_MULTICAST_IF socket option is specified for the socket,
the interface is used.
4. otherwise, if an IPV6_NEXTHOP ancillary data item is specified,
the interface to the next hop is used.
5. otherwise, if an IPV6_NEXTHOP sticky option is specified,
the interface to the next hop is used.
6. otherwise, the outgoing interface should be determined in an
implementation dependent manner.
In any case, the kernel must also verify that the source and
destination addresses do not break their scope zones with regard to
the outgoing interface.
7. Routing Header Option 7. Routing Header Option
Source routing in IPv6 is accomplished by specifying a Routing header Source routing in IPv6 is accomplished by specifying a Routing header
as an extension header. There can be different types of Routing as an extension header. There can be different types of Routing
headers, but IPv6 currently defines only the Type 0 Routing header headers, but IPv6 currently defines only the Type 0 Routing header
[RFC-2460]. This type supports up to 127 intermediate nodes (limited [RFC-2460]. This type supports up to 127 intermediate nodes (limited
by the length field in the extension header). With this maximum by the length field in the extension header). With this maximum
number of intermediate nodes, a source, and a destination, there are number of intermediate nodes, a source, and a destination, there are
128 hops. 128 hops.
skipping to change at page 34, line 8 skipping to change at page 35, line 32
The function prototypes for these functions are defined as a result The function prototypes for these functions are defined as a result
of including the <netinet/in.h>. of including the <netinet/in.h>.
To receive a Routing header the application must enable the To receive a Routing header the application must enable the
IPV6_RECVRTHDR socket option: IPV6_RECVRTHDR socket option:
int on = 1; int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on));
Each received Routing header is returned as one ancillary data object
described by a cmsghdr structure with cmsg_type set to IPV6_RTHDR.
When multiple Routing headers are received, multiple ancillary data
objects (with cmsg_type set to IPV6_RTHDR) will be returned to the
application.
To send a Routing header the application specifies it either as To send a Routing header the application specifies it either as
ancillary data in a call to sendmsg() or using setsockopt(). ancillary data in a call to sendmsg() or using setsockopt(). For the
sending side, this API assumes the recommended order about extension
headers described in [RFC-2460]. Thus, applications can only specify
at most one outgoing Routing header.
The application can remove any sticky Routing header by calling The application can remove any sticky Routing header by calling
setsockopt() for IPV6_RTHDR with a zero option length. setsockopt() for IPV6_RTHDR with a zero option length.
When using ancillary data a Routing header is passed between the When using ancillary data a Routing header is passed between the
application and the kernel as follows: The cmsg_level member has a application and the kernel as follows: The cmsg_level member has a
value of IPPROTO_IPV6 and the cmsg_type member has a value of value of IPPROTO_IPV6 and the cmsg_type member has a value of
IPV6_RTHDR. The contents of the cmsg_data[] member is implementation IPV6_RTHDR. The contents of the cmsg_data[] member is implementation
dependent and should not be accessed directly by the application, but dependent and should not be accessed directly by the application, but
should be accessed using the six functions that we are about to should be accessed using the six functions that we are about to
skipping to change at page 36, line 38 skipping to change at page 38, line 25
returned by inet6_rth_segments()) in the Routing header described by returned by inet6_rth_segments()) in the Routing header described by
bp. An application should first call inet6_rth_segments() to obtain bp. An application should first call inet6_rth_segments() to obtain
the number of segments in the Routing header. the number of segments in the Routing header.
Upon an error the return value of the function is NULL. Upon an error the return value of the function is NULL.
8. Hop-By-Hop Options 8. Hop-By-Hop Options
A variable number of Hop-by-Hop options can appear in a single Hop- A variable number of Hop-by-Hop options can appear in a single Hop-
by-Hop options header. Each option in the header is TLV-encoded with by-Hop options header. Each option in the header is TLV-encoded with
a type, length, and value. a type, length, and value. This IPv6 API defines seven functions
that the application calls to build and examine a Hop-by_Hop options
Today only four Hop-by-Hop options are defined for IPv6 [RFC-2460]:
Jumbo Payload, Pad1, PadN, and router-alert. The two pad options are
for alignment purposes and are automatically inserted by the
inet6_opt_XXX() routines and ignored by the inet6_opt_XXX() routines
on the receive side.
This section of the API is therefore defined for future Hop-by-Hop
options (as well as destination options) that an application may need
to specify and receive. This IPv6 API defines seven functions that
the application calls to build and examine a Hop-by_Hop options
header, and the ability to use sticky options or ancillary data to header, and the ability to use sticky options or ancillary data to
communicate this information between the application and the kernel. communicate this information between the application and the kernel.
This uses the IPV6_HOPOPTS for hob-by-hop options. This uses the IPV6_HOPOPTS for a Hob-by-Hop options header.
Four functions build a options header: Today several Hop-by-Hop options are defined for IPv6. Two pad
options, Pad1 and PadN, are for alignment purposes and are
automatically inserted by the inet6_opt_XXX() routines and ignored by
the inet6_opt_XXX() routines on the receive side. This section of
the API is therefore defined for other (and future) Hop-by-Hop
options that an application may need to specify and receive.
Four functions build an options header:
inet6_opt_init() - initialize buffer data for options header inet6_opt_init() - initialize buffer data for options header
inet6_opt_append() - add one TLV option to the options header inet6_opt_append() - add one TLV option to the options header
inet6_opt_finish() - finish adding TLV options to the options header inet6_opt_finish() - finish adding TLV options to the options header
inet6_opt_set_val() - add one component of the option content to the option inet6_opt_set_val() - add one component of the option content to the option
Three functions deal with a returned options header: Three functions deal with a returned options header:
inet6_opt_next() - extract the next option from the options header inet6_opt_next() - extract the next option from the options header
inet6_opt_find() - extract an option of a specified type from the header inet6_opt_find() - extract an option of a specified type from the header
skipping to change at page 38, line 8 skipping to change at page 39, line 38
placing them in a single extension header. placing them in a single extension header.
Finally, we note that use of some Hop-by-Hop options or some Finally, we note that use of some Hop-by-Hop options or some
Destination options, might require special privilege. That is, Destination options, might require special privilege. That is,
normal applications (without special privilege) might be forbidden normal applications (without special privilege) might be forbidden
from setting certain options in outgoing packets, and might never see from setting certain options in outgoing packets, and might never see
certain options in received packets. certain options in received packets.
8.1. Receiving Hop-by-Hop Options 8.1. Receiving Hop-by-Hop Options
To receive Hop-by-Hop options the application must enable the To receive a Hop-by-Hop options header the application must enable
IPV6_RECVHOPOPTS socket option: the IPV6_RECVHOPOPTS socket option:
int on = 1; int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVHOPOPTS, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVHOPOPTS, &on, sizeof(on));
When using ancillary data a Hop-by-hop options is passed between the When using ancillary data a Hop-by-hop options header is passed
application and the kernel as follows: The cmsg_level member will be between the application and the kernel as follows: The cmsg_level
IPPROTO_IPV6 and the cmsg_type member will be IPV6_HOPOPTS. These member will be IPPROTO_IPV6 and the cmsg_type member will be
options are then processed by calling the inet6_opt_next(), IPV6_HOPOPTS. These options are then processed by calling the
inet6_opt_find(), and inet6_opt_get_val() functions, described in inet6_opt_next(), inet6_opt_find(), and inet6_opt_get_val()
Section 10.6. functions, described in Section 10.
8.2. Sending Hop-by-Hop Options 8.2. Sending Hop-by-Hop Options
To send a Hop-by-Hop options header, the application specifies the To send a Hop-by-Hop options header, the application specifies the
header either as ancillary data in a call to sendmsg() or using header either as ancillary data in a call to sendmsg() or using
setsockopt(). setsockopt().
The application can remove any sticky Hop-by-Hop extension header by The application can remove any sticky Hop-by-Hop options header by
calling setsockopt() for IPV6_HOPOPTS with a zero option length. calling setsockopt() for IPV6_HOPOPTS with a zero option length.
All the Hop-by-Hop options must specified by a single ancillary data All the Hop-by-Hop options must be specified by a single ancillary
object. The cmsg_level member is set to IPPROTO_IPV6 and the data object. The cmsg_level member is set to IPPROTO_IPV6 and the
cmsg_type member is set to IPV6_HOPOPTS. The option is normally cmsg_type member is set to IPV6_HOPOPTS. The option is normally
constructed using the inet6_opt_init(), inet6_opt_append(), constructed using the inet6_opt_init(), inet6_opt_append(),
inet6_opt_finish(), and inet6_set_val() functions, described in inet6_opt_finish(), and inet6_opt_set_val() functions, described in
Section 10. Section 10.
Additional errors may be possible from sendmsg() and setsockopt() if Additional errors may be possible from sendmsg() and setsockopt() if
the specified option is in error. the specified option is in error.
9. Destination Options 9. Destination Options
A variable number of Destination options can appear in one or more A variable number of Destination options can appear in one or more
Destination option headers. As defined in [RFC-2460], a Destination Destination options headers. As defined in [RFC-2460], a Destination
options header appearing before a Routing header is processed by the options header appearing before a Routing header is processed by the
first destination plus any subsequent destinations specified in the first destination plus any subsequent destinations specified in the
Routing header, while a Destination options header appearing after a Routing header, while a Destination options header that is not
Routing header is processed only by the final destination. As with followed by a Routing header is processed only by the final
the Hop-by-Hop options, each option in a Destination options header destination. As with the Hop-by-Hop options, each option in a
is TLV-encoded with a type, length, and value. Destination options header is TLV-encoded with a type, length, and
value.
Today no Destination options are defined for IPv6 [RFC-2460],
although proposals exist to use Destination options with Mobile IPv6.
9.1. Receiving Destination Options 9.1. Receiving Destination Options
To receive Destination options appearing after a Routing header (or To receive Destination options header the application must enable the
in a packet without a Routing header) the application must enable the
IPV6_RECVDSTOPTS socket option: IPV6_RECVDSTOPTS socket option:
int on = 1; int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVDSTOPTS, &on, sizeof(on));
To receive Destination options appearing before a Routing header the Each Destination options header is returned as one ancillary data
application must enable the IPV6_RECVRTHDRDSTOPTS socket option: object described by a cmsghdr structure with cmsg_level set to
IPPROTO_IPV6 and cmsg_type set to IPV6_DSTOPTS.
int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDRDSTOPTS,
&on, sizeof(on));
All the Destination options appearing before a Routing header are
returned as one ancillary data object described by a cmsghdr
structure (with cmsg_type set to IPV6_RTHDRDSTOPTS) and all the
Destination options appearing after a Routing header (or in a packet
without a Routing header) are returned as another ancillary data
object described by a cmsghdr structure (with cmsg_type set to
IPV6_DSTOPTS). For all these ancillary data objects, the cmsg_level
member will be IPPROTO_IPV6.
These options are then processed by calling the inet6_opt_next(), These options are then processed by calling the inet6_opt_next(),
inet6_opt_find(), and inet6_opt_get_value() functions. inet6_opt_find(), and inet6_opt_get_value() functions.
9.2. Sending Destination Options 9.2. Sending Destination Options
To send a Destination options header, the application specifies it To send a Destination options header, the application specifies it
either as ancillary data in a call to sendmsg() or using either as ancillary data in a call to sendmsg() or using
setsockopt(). setsockopt().
The application can remove any sticky Destination extension header by The application can remove any sticky Destination options header by
calling setsockopt() for IPV6_RTHDRDSTOPTS/IPV6_DSTOPTS with a zero calling setsockopt() for IPV6_RTHDRDSTOPTS/IPV6_DSTOPTS with a zero
option length. option length.
As described in Section 6 one set of Destination options can appear This API assumes the recommended ordering about extension headers
before a Routing header, and one set can appear after a Routing described in [RFC-2460]. Thus, one set of Destination options can
header (or in a packet with no Routing header). Each set can consist only appear before a Routing header, and one set can only appear
of one or more options but each set is a single extension header. after a Routing header (or in a packet with no Routing header). Each
set can consist of one or more options but each set is a single
extension header.
When using ancillary data a Destination options header is passed When using ancillary data a Destination options header is passed
between the application and the kernel as follows: The set preceding between the application and the kernel as follows: The set preceding
a Routing header are specified with the cmsg_level member is set to a Routing header are specified with the cmsg_level member set to
IPPROTO_IPV6 and the cmsg_type member is set to IPV6_RTHDRDSTOPTS. IPPROTO_IPV6 and the cmsg_type member set to IPV6_RTHDRDSTOPTS. Any
Any setsockopt or ancillary data for IPV6_RTHDRDSTOPTS is silently setsockopt or ancillary data for IPV6_RTHDRDSTOPTS is silently
ignored when sending packets unless a Routing header is also ignored when sending packets unless a Routing header is also
specified. specified. Note that the "Routing header" here means the one
specified by this API. Even when the kernel inserts a routing header
in its internal routine (e.g. in a mobile IPv6 stack), the
Destination options header specified by IPV6_RTHDRDSTOPTS will still
be ignored unless the application explicitly specifies its own
Routing header.
The set of Destination options after a Routing header, which are also The set of Destination options after a Routing header, which are also
used when no Routing header is present, are specified with the used when no Routing header is present, are specified with the
cmsg_level member is set to IPPROTO_IPV6 and the cmsg_type member is cmsg_level member is set to IPPROTO_IPV6 and the cmsg_type member is
set to IPV6_DSTOPTS. set to IPV6_DSTOPTS.
The Destination options are normally constructed using the The Destination options are normally constructed using the
inet6_opt_init(), inet6_opt_append(), inet6_opt_finish(), and inet6_opt_init(), inet6_opt_append(), inet6_opt_finish(), and
inet6_set_val() functions, described in Section 10. inet6_opt_set_val() functions, described in Section 10.
Additional errors may be possible from sendmsg() and setsockopt() if Additional errors may be possible from sendmsg() and setsockopt() if
the specified option is in error. the specified option is in error.
10. Hop-by-Hop and Destination Options Processing 10. Hop-by-Hop and Destination Options Processing
Building and parsing the Hop-by-Hop and Destination options is Building and parsing the Hop-by-Hop and Destination options is
complicated for the reasons given earlier. We therefore define a set complicated for the reasons given earlier. We therefore define a set
of functions to help the application. These functions assume the of functions to help the application. These functions assume the
formatting rules specified in Appendix B in [RFC-2460] i.e. that the formatting rules specified in Appendix B in [RFC-2460] i.e. that the
largest field is placed last in the option. largest field is placed last in the option.
The function prototypes for these functions are defined as a result The function prototypes for these functions are defined as a result
of including the <netinet/in.h>. of including the <netinet/in.h>.
The first 3 functions (init, append, and finish) are used both to The first 3 functions (init, append, and finish) are used both to
skipping to change at page 42, line 16 skipping to change at page 43, line 38
If the necessary pad does not fit in the extension header buffer the If the necessary pad does not fit in the extension header buffer the
function returns -1. function returns -1.
10.4. inet6_opt_set_val 10.4. inet6_opt_set_val
int inet6_opt_set_val(void *databuf, size_t offset, void *val, int inet6_opt_set_val(void *databuf, size_t offset, void *val,
int vallen); int vallen);
Databuf should be a pointer returned by inet6_opt_append(). This Databuf should be a pointer returned by inet6_opt_append(). This
function inserts data items of various sizes (1, 2, 4, or 8 bytes) in function inserts data items of various sizes in the data portion of
the data portion of the option. Val should point to the data to be the option. Val should point to the data to be inserted. Offset
inserted. Offset specifies where in the data portion of the option specifies where in the data portion of the option the value should be
the value should be inserted; the first byte after the option type inserted; the first byte after the option type and length is accessed
and length is accessed by specifying an offset of zero. by specifying an offset of zero.
The caller should ensure that each field is aligned on its natural
boundaries as described in Appendix B of [RFC-2460], but the function
must not rely on the caller's behavior. Even when the alignment
requirement is not satisfied, inet6_opt_set_val should just copy the
data as required.
The function returns the offset for the next field (i.e., offset + The function returns the offset for the next field (i.e., offset +
vallen) which can be used when composing option content with multiple vallen) which can be used when composing option content with multiple
fields. fields.
10.5. inet6_opt_next 10.5. inet6_opt_next
int inet6_opt_next(void *extbuf, size_t extlen, int prevlen, int inet6_opt_next(void *extbuf, size_t extlen, int prevlen,
uint8_t *typep, size_t *lenp, uint8_t *typep, size_t *lenp,
void **databufp); void **databufp);
skipping to change at page 43, line 31 skipping to change at page 45, line 13
is -1. If the option extension header is malformed, the return value is -1. If the option extension header is malformed, the return value
is -1. is -1.
10.7. inet6_opt_get_val 10.7. inet6_opt_get_val
int inet6_opt_get_val(void *databuf, size_t offset, void *val, int inet6_opt_get_val(void *databuf, size_t offset, void *val,
int vallen); int vallen);
Databuf should be a pointer returned by inet6_opt_next() or Databuf should be a pointer returned by inet6_opt_next() or
inet6_opt_find(). This function extracts data items of various sizes inet6_opt_find(). This function extracts data items of various sizes
(1, 2, 4, or 8 bytes) in the data portion of the option. Val should in the data portion of the option. Val should point to the
point to the destination for the extracted data. Offset specifies destination for the extracted data. Offset specifies from where in
from where in the data portion of the option the value should be the data portion of the option the value should be extracted; the
extracted; the first byte after the option type and length is first byte after the option type and length is accessed by specifying
accessed by specifying an offset of zero. an offset of zero.
It is expected that each field is aligned on its natural boundaries
as described in Appendix B of [RFC-2460], but the function must not
rely on the alignment.
The function returns the offset for the next field (i.e., offset + The function returns the offset for the next field (i.e., offset +
vallen) which can be used when extracting option content with vallen) which can be used when extracting option content with
multiple fields. multiple fields.
11. Additional Advanced API Functions 11. Additional Advanced API Functions
11.1. Sending with the Minimum MTU 11.1. Sending with the Minimum MTU
Some applications might not want to incur the overhead of path MTU Some applications might not want to incur the overhead of path MTU
skipping to change at page 44, line 18 skipping to change at page 45, line 46
sending at the minimum IPv6 MTU [RFC-2460]. If the packet is larger sending at the minimum IPv6 MTU [RFC-2460]. If the packet is larger
than the minimum MTU and this feature has been enabled the IP layer than the minimum MTU and this feature has been enabled the IP layer
will fragment to the minimum MTU. This can be enabled using the will fragment to the minimum MTU. This can be enabled using the
IPV6_USE_MIN_MTU socket option. IPV6_USE_MIN_MTU socket option.
int on = 1; int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_USE_MIN_MTU, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_USE_MIN_MTU, &on, sizeof(on));
By default, this socket option is disabled. Setting the value to 0 By default, this socket option is disabled. Setting the value to 0
also disables the option. This option can also be sent as ancillary also disables the option. This option can also be sent as ancillary
data. data. In the cmsghdr structure containing this ancillary data, the
cmsg_level member will be IPPROTO_IPV6, the cmsg_type member will be
IPV6_USE_MIN_MTU, and the first byte of cmsg_data[] will be the first
byte of the integer.
11.2. Path MTU Discovery and UDP 11.2. Sending without fragmentation
In order to provide for easy porting of existing UDP and raw socket
applications IPv6 implementations will, when originating packets,
automatically insert a fragment header in the packet if the packet is
too big for the path MTU.
Some applications might not want this behavior. An example is
traceroute which might want to discover the actual path MTU.
This specification defines a mechanism to turn off the automatic
inserting of a fragment header for UDP and raw sockets. This can be
enabled using the IPV6_DONTFRAG socket option.
int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_DONTFRAG, &on, sizeof(&on));
By default, this socket option is disabled. Setting the value to 0
also disables the option i.e. reverts to the default behavior of
automatic inserting. This option can also be sent as ancillary data.
In the cmsghdr structure containing this ancillary data, the
cmsg_level member will be IPPROTO_IPV6, the cmsg_type member will be
IPV6_DONTFRAG, and the first byte of cmsg_data[] will be the first
byte of the integer. This API only specifies the use of this option
for UDP and raw sockets, and does not define the usage for TCP
sockets.
When the data size is larger than the MTU of the outgoing interface,
the packet will be discarded. Applications can know the result by
enabling the IPV6_RECVPATHMTU option described below and receiving
the corresponding ancillary data items.
11.3. Path MTU Discovery and UDP
UDP and raw socket applications need to be able to determine the UDP and raw socket applications need to be able to determine the
"maximum send transport-message size" (Section 5.1 of [RFC-1981]) to "maximum send transport-message size" (Section 5.1 of [RFC-1981]) to
a given destination so that those applications can participate in a given destination so that those applications can participate in
path MTU discovery. This lets those applications send smaller path MTU discovery. This lets those applications send smaller
datagrams to the destination, avoiding fragmentation. datagrams to the destination, avoiding fragmentation.
This is accomplished using a new ancillary data item (IPV6_PATHMTU) This is accomplished using a new ancillary data item (IPV6_PATHMTU)
which is delivered to recvmsg() without any actual data. The which is delivered to recvmsg() without any actual data. The
application enable the receipt of IPV6_PATHMTU ancillary data items application can enable the receipt of IPV6_PATHMTU ancillary data
by enabing IPV6_RECVPATHMTU. items by setting the IPV6_RECVPATHMTU socket option.
int on = 1; int on = 1;
setsockopt(fd, IPPROTO_IPV6, IPV6_RECVPATHMTU, &on, sizeof(on)); setsockopt(fd, IPPROTO_IPV6, IPV6_RECVPATHMTU, &on, sizeof(on));
By default, this socket option is disabled. Setting the value to 0 By default, this socket option is disabled. Setting the value to 0
also disables the option. also disables the option. This API only specifies the use of this
option for UDP and raw sockets, and does not define the usage for TCP
sockets.
When the application is sending packets too big for the path MTU When the application is sending packets too big for the path MTU
recvmsg will return zero (indicating no data) but there will be a recvmsg will return zero (indicating no data) but there will be a
cmsghdr with cmsg_type set to IPV6_PATHMTU, and cmsg_len will cmsghdr with cmsg_type set to IPV6_PATHMTU, and cmsg_len will
indicate that cmsg_data is 4 bytes long. CMSG_DATA will point to an indicate that cmsg_data is sizeof(struct ip6_mtuinfo) bytes long.
integer carrying the path MTU to use. This can happen when the sending node receives a corresponding ICMPv6
packet too big error, or when the packet is sent from a socket with
the IPV6_DONTFRAG option being on and the packet size is larger than
the MTU of the outgoing interface. The first byte of cmsg_data[]
will point to a struct ip6_mtuinfo carrying the path MTU to use
together with the IPv6 destination address.
11.3. Neighbor Reachability and UDP struct ip6_mtuinfo {
struct sockaddr_in6 ip6m_addr; /* dst address including zone ID */
uint32_t ip6m_mtu; /* path MTU in host byte order */
};
UDP and raw socket application might know that communication is This cmsghdr will be passed to every socket that sets the
IPV6_RECVPATHMTU socket option, even if the socket is non-connected.
Note that this also means an application that sets the option may get
the ancillary data upon a too big message sent from other
applications to the same destination. An implementation may choose
not to delivery data to a connected socket that has a foreign address
that is different than the address specified in the ip6m_addr
structure.
When an application sends a packet with a routing header, the final
destination stored in the ip6m_addr member does not necessarily
contain complete information of the entire path.
11.4. Determining the current path MTU
Some applications might need to determine the current path MTU e.g.
applications using IPV6_RECVPATHMTU might want to pick a good
starting value.
This specification defines a get-only socket option to retrieve the
current path MTU value for the destination of a given connected
socket. If the IP layer does not have a cached path MTU value it
will return the interface MTU for the interface that will be used
when sending to the destination address.
This information is retrieved using the IPV6_PATHMTU socket option.
This option takes a pointer to the ip6_mtuinfo structure as the
fourth argument, and the size of the structure should be passed as a
value-result parameter in the fifth argument.
struct ip6_mtuinfo mtuinfo;
size_t infolen = sizeof(mtuinfo);
getsockopt(fd, IPPROTO_IPV6, IPV6_PATHMTU, &mtuinfo, &infolen);
When the call succeeds, the path MTU value is stored in the ip6m_mtu
member of the ip6_mtuinfo structure. Since the socket is connected,
the ip6m_addr member is meaningless and should not be referred to by
the application.
This option can only be used for a connected socket, because a non-
connected socket does not have the information of the destination and
there is no way to pass the destination via getsockopt(). When
getsockopt() for this option is issued on a non-connected socket, the
call will fail.
11.5. Neighbor Reachability and UDP
UDP and raw socket applications might know that communication is
making forward progress i.e. that the path from the node to the next making forward progress i.e. that the path from the node to the next
hop is working. In such a case the applications, similarly to TCP as hop is working. In such a case the applications, similarly to TCP as
specified in [RFC-2461], has the option indicate to the internet specified in [RFC-2461], has the option indicate to the internet
layer that the neighbor is reachable. See section 7.3.1 of [RFC- layer that the neighbor is reachable. See section 7.3.1 of [RFC-
2461]. This could save unneeded neighbor solicitation and neighbor 2461]. This could save unneeded neighbor solicitation and neighbor
advertisement messages. advertisement messages.
This is done by including an ancilary data item with cmsg_type being This is done by including an ancillary data item with cmsg_type being
IPV6_REACHCONF and with no attached CMSG_DATA. IPV6_REACHCONF and with no attached CMSG_DATA. IPV6_REACHCONF can
only be used as an ancillary data item. This also means that this
cannot be used for TCP sockets.
If implementations honor the IPV6_REACHCONF from any application If implementations honor the IPV6_REACHCONF from any application
there is a possibility that, when there is an unreachability there is a possibility that, when there is an unreachability
situation, one application can cause a denial of service attack on situation, one application can cause a denial of service attack on
anogther application running on the same node by periodically issuing anogther application running on the same node by periodically issuing
sendmsg() with an IPV6_REACHCONF ancillary data item to prevent the sendmsg() with an IPV6_REACHCONF ancillary data item to prevent the
Neighbor Unreachability Detection algoritm to send probe messages and Neighbor Unreachability Detection algoritm to send probe messages and
declare the neighbor unreachable. It is unclear whether declare the neighbor unreachable. It is unclear whether
implementations need to mitigate this very minor threat by e.g. implementations need to mitigate this very minor threat by e.g.
restricting IPV6_REACHCONF to priviledged applications. restricting IPV6_REACHCONF to priviledged applications.
12. Ordering of Ancillary Data and IPv6 Extension Headers 12. Ordering of Ancillary Data and IPv6 Extension Headers
Three IPv6 extension headers can be specified by the application and Three IPv6 extension headers can be specified by the application and
returned to the application using ancillary data with sendmsg() and returned to the application using ancillary data with sendmsg() and
recvmsg(): the Routing header, Hop-by-Hop options, and Destination recvmsg(): the Routing header, Hop-by-Hop options header, and
options. When multiple ancillary data objects are transferred via Destination options header. When multiple ancillary data objects are
recvmsg() and these objects represent any of these three extension transferred via recvmsg() and these objects represent any of these
headers, their placement in the control buffer is directly tied to three extension headers, their placement in the control buffer is
their location in the corresponding IPv6 datagram. This API imposes directly tied to their location in the corresponding IPv6 datagram.
some ordering constraints for using these ancillary data objects with For example, when the application has enabled the IPV6_RECVRTHDR and
sendmsg(). IPV6_RECVDSTOPTS options and later receives an IPv6 packet with
extension headers in the following order:
All Hop-by-Hop options must be specified in a single ancillary data The IPv6 header
object. Should multiple hop-by-hop ancillary data objects be A Hop-by-Hop options header
specified the implementation might choose an arbitrary one or drop A Destination options header (1)
the packet. A Routing header
An Authentication header
A Destination options header (2)
A UDP header and UDP data
All Destination options that precede a Routing header must be then the application will receive three ancillary data objects in the
specified in a single ancillary data object. If there is no Routing following order:
header ancillary data object the IPV6_RTHDRDSTOPTS object will be
silently ignored.
All Destination options that follow a Routing header (or are used an object with cmsg_type set to IPV6_DSTOPTS, which represents
without a Routing header) must be specified in a single ancillary the destination options header (1)
data object. an object with cmsg_type set to IPV6_DSTOPTS, which represents the
Routing header
an object with cmsg_type set to IPV6_DSTOPTS, which represents the
destination options header (2)
If Destination options are specified in the control buffer after a This example follows the recommended order described in [RFC-2460],
Routing header, or if Destination options are specified without a but the receiving side of this specification does not assume the
Routing header, the kernel will place those Destination options after recommended order. Applications may receive any numbers of objects
an authentication header and/or an encapsulating security payload in any order according to the ordering of the received IPv6 datagram.
header, if present.
For the sending side, however, this API imposes some ordering
constraints according to the recommendation. Applications using this
API cannot make a packet with extension headers that do not follow
the recommended ordering. Should an application need to make an
outgoing packet in an arbitrary order about the extension headers,
some other technique, such as the datalink interfaces BPF or DLPI,
must be used.
The followings are more details about the constraints:
- Each IPV6_xxx ancillary data object for a particular type of
extension header can be specified at most once in a single
control buffer.
- IPV6_xxx ancillary data objects can appear in any order in a
control buffer, because there is no ambiguity of the ordering.
- Each set of IPV6_xxx ancillary data objects and sticky options
will be put in the outgoing packet along with the recommended
header ordering described in [RFC-2460].
- An ancillary data object or a sticky option of IPV6_RTHDRDSTOPTS
will affect the outgoing packet only when a Routing header is
specified as an ancillary data object or a sticky option.
Otherwise, the specified value for IPV6_RTHDRDSTOPTS will be
ignored.
For example, when an application sends a UDP datagram with a control
data buffer containing ancillary data objects in the following order:
an object with cmsg_type set to IPV6_DSTOPTS
an object with cmsg_type set to IPV6_RTHDRDSTOPTS
an object with cmsg_type set to IPV6_HOPOPTS
and the sending socket does not have any sticky options, then the
outgoing packet would be constructed as follows:
The IPv6 header
A Hop-by-Hop options header
A Destination options header
A UDP header and UDP data
where the destination options header corresponds to the ancillary
data object with the type IPV6_DSTOPTS.
Note that the constraints above do not necessarily mean that the
outgoing packet sent on the wire always follows the recommended
header ordering. The kernel may insert additional headers that break
the recommended order as a result. For example, if the kernel
supports Mobile IPv6, an additional destination options header may be
inserted before an authentication header, even without a routing
header.
This API does not provide access to any other extension headers than
the supported three types of headers. In particular, no information
is provided about the IP security headers on an incoming packet, nor
can be specified for an outgoing packet. This API is for
applications that do not care about the existence of IP security
headers.
13. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses 13. IPv6-Specific Options with IPv4-Mapped IPv6 Addresses
The various socket options and ancillary data specifications defined The various socket options and ancillary data specifications defined
in this document apply only to true IPv6 sockets. It is possible to in this document apply only to true IPv6 sockets. It is possible to
create an IPv6 socket that actually sends and receives IPv4 packets, create an IPv6 socket that actually sends and receives IPv4 packets,
using IPv4-mapped IPv6 addresses, but the mapping of the options using IPv4-mapped IPv6 addresses, but the mapping of the options
defined in this document to an IPv4 datagram is beyond the scope of defined in this document to an IPv4 datagram is beyond the scope of
this document. this document.
skipping to change at page 47, line 14 skipping to change at page 52, line 14
family is not supported. family is not supported.
(Note: There is little consensus on which header defines the (Note: There is little consensus on which header defines the
rresvport() and rcmd() function prototypes. 4.4BSD defines it in rresvport() and rcmd() function prototypes. 4.4BSD defines it in
<unistd.h>, others in <netdb.h>, and others don't define the function <unistd.h>, others in <netdb.h>, and others don't define the function
prototypes at all.) prototypes at all.)
14.2. rcmd_af 14.2. rcmd_af
The existing rcmd() function can not transparently use AF_INET6 The existing rcmd() function can not transparently use AF_INET6
sockets since the an application would not be prepared to handle sockets since an application would not be prepared to handle AF_INET6
AF_INET6 addresses returned by e.g. getpeername on the file addresses returned by e.g. getpeername on the file descriptor created
descriptor created by rcmd. Thus a new function is needed. by rcmd. Thus a new function is needed.
int rcmd_af(char **ahost, unsigned short rport, const char *locuser, int rcmd_af(char **ahost, unsigned short rport, const char *locuser,
const char *remuser, const char *cmd, int *fd2p, int af) const char *remuser, const char *cmd, int *fd2p, int af)
This function behaves the same as the existing rcmd() function, but This function behaves the same as the existing rcmd() function, but
instead of creating an AF_INET TCP socket, it can also create an instead of creating an AF_INET TCP socket, it can also create an
AF_INET6 TCP socket. The family argument is either AF_INET or AF_INET6 TCP socket. The family argument is either AF_INET or
AF_INET6, and a new error return is EAFNOSUPPORT if the address AF_INET6, and a new error return is EAFNOSUPPORT if the address
family is not supported. family is not supported.
skipping to change at page 48, line 24 skipping to change at page 53, line 24
<netinet/icmp6.h> ICMP6_PARAMPROB_NEXTHEADER <netinet/icmp6.h> ICMP6_PARAMPROB_NEXTHEADER
<netinet/icmp6.h> ICMP6_PARAMPROB_OPTION <netinet/icmp6.h> ICMP6_PARAMPROB_OPTION
<netinet/icmp6.h> ICMP6_PARAM_PROB <netinet/icmp6.h> ICMP6_PARAM_PROB
<netinet/icmp6.h> ICMP6_ROUTER_RENUMBERING <netinet/icmp6.h> ICMP6_ROUTER_RENUMBERING
<netinet/icmp6.h> ICMP6_RR_FLAGS_FORCEAPPLY <netinet/icmp6.h> ICMP6_RR_FLAGS_FORCEAPPLY
<netinet/icmp6.h> ICMP6_RR_FLAGS_PREVDONE <netinet/icmp6.h> ICMP6_RR_FLAGS_PREVDONE
<netinet/icmp6.h> ICMP6_RR_FLAGS_REQRESULT <netinet/icmp6.h> ICMP6_RR_FLAGS_REQRESULT
<netinet/icmp6.h> ICMP6_RR_FLAGS_SPECSITE <netinet/icmp6.h> ICMP6_RR_FLAGS_SPECSITE
<netinet/icmp6.h> ICMP6_RR_FLAGS_TEST <netinet/icmp6.h> ICMP6_RR_FLAGS_TEST
<netinet/icmp6.h> ICMP6_RR_PCOUSE_FLAGS_DECRPLTIME <netinet/icmp6.h> ICMP6_RR_PCOUSE_FLAGS_DECRPLTIME
<netinet/icmp6.h> ICMP6_RR_PCOUSE_FLAGS_DECRPLTIME
<netinet/icmp6.h> ICMP6_RR_PCOUSE_FLAGS_DECRVLTIME
<netinet/icmp6.h> ICMP6_RR_PCOUSE_FLAGS_DECRVLTIME <netinet/icmp6.h> ICMP6_RR_PCOUSE_FLAGS_DECRVLTIME
<netinet/icmp6.h> ICMP6_RR_PCOUSE_RAFLAGS_AUTO <netinet/icmp6.h> ICMP6_RR_PCOUSE_RAFLAGS_AUTO
<netinet/icmp6.h> ICMP6_RR_PCOUSE_RAFLAGS_ONLINK <netinet/icmp6.h> ICMP6_RR_PCOUSE_RAFLAGS_ONLINK
<netinet/icmp6.h> ICMP6_RR_RESULT_FLAGS_FORBIDDEN <netinet/icmp6.h> ICMP6_RR_RESULT_FLAGS_FORBIDDEN
<netinet/icmp6.h> ICMP6_RR_RESULT_FLAGS_FORBIDDEN
<netinet/icmp6.h> ICMP6_RR_RESULT_FLAGS_OOB
<netinet/icmp6.h> ICMP6_RR_RESULT_FLAGS_OOB <netinet/icmp6.h> ICMP6_RR_RESULT_FLAGS_OOB
<netinet/icmp6.h> ICMP6_TIME_EXCEEDED <netinet/icmp6.h> ICMP6_TIME_EXCEEDED
<netinet/icmp6.h> ICMP6_TIME_EXCEED_REASSEMBLY <netinet/icmp6.h> ICMP6_TIME_EXCEED_REASSEMBLY
<netinet/icmp6.h> ICMP6_TIME_EXCEED_TRANSIT <netinet/icmp6.h> ICMP6_TIME_EXCEED_TRANSIT
<netinet/icmp6.h> MLD_LISTENER_QUERY <netinet/icmp6.h> MLD_LISTENER_QUERY
<netinet/icmp6.h> MLD_LISTENER_REDUCTION <netinet/icmp6.h> MLD_LISTENER_REDUCTION
<netinet/icmp6.h> MLD_LISTENER_REPORT <netinet/icmp6.h> MLD_LISTENER_REPORT
<netinet/icmp6.h> ND_NA_FLAG_OVERRIDE <netinet/icmp6.h> ND_NA_FLAG_OVERRIDE
<netinet/icmp6.h> ND_NA_FLAG_ROUTER <netinet/icmp6.h> ND_NA_FLAG_ROUTER
<netinet/icmp6.h> ND_NA_FLAG_SOLICITED <netinet/icmp6.h> ND_NA_FLAG_SOLICITED
<netinet/icmp6.h> ND_NEIGHBOR_ADVERT <netinet/icmp6.h> ND_NEIGHBOR_ADVERT
<netinet/icmp6.h> ND_NEIGHBOR_SOLICIT <netinet/icmp6.h> ND_NEIGHBOR_SOLICIT
<netinet/icmp6.h> ND_OPT_MTU <netinet/icmp6.h> ND_OPT_MTU
<netinet/icmp6.h> ND_OPT_PI_FLAG_AUTO <netinet/icmp6.h> ND_OPT_PI_FLAG_AUTO
<netinet/icmp6.h> ND_OPT_PI_FLAG_ONLINK <netinet/icmp6.h> ND_OPT_PI_FLAG_ONLINK
<netinet/icmp6.h> ND_OPT_PI_FLAG_ROUTER <netinet/icmp6.h> ND_OPT_PI_FLAG_ROUTER
<netinet/icmp6.h> ND_OPT_PI_FLAG_SITEPREF
<netinet/icmp6.h> ND_OPT_PREFIX_INFORMATION <netinet/icmp6.h> ND_OPT_PREFIX_INFORMATION
<netinet/icmp6.h> ND_OPT_REDIRECTED_HEADER <netinet/icmp6.h> ND_OPT_REDIRECTED_HEADER
<netinet/icmp6.h> ND_OPT_SOURCE_LINKADDR <netinet/icmp6.h> ND_OPT_SOURCE_LINKADDR
<netinet/icmp6.h> ND_OPT_TARGET_LINKADDR <netinet/icmp6.h> ND_OPT_TARGET_LINKADDR
<netinet/icmp6.h> ND_RA_FLAG_HOME_AGENT
<netinet/icmp6.h> ND_RA_FLAG_MANAGED <netinet/icmp6.h> ND_RA_FLAG_MANAGED
<netinet/icmp6.h> ND_RA_FLAG_OTHER <netinet/icmp6.h> ND_RA_FLAG_OTHER
<netinet/icmp6.h> ND_REDIRECT <netinet/icmp6.h> ND_REDIRECT
<netinet/icmp6.h> ND_ROUTER_ADVERT <netinet/icmp6.h> ND_ROUTER_ADVERT
<netinet/icmp6.h> ND_ROUTER_SOLICIT <netinet/icmp6.h> ND_ROUTER_SOLICIT
<netinet/icmp6.h> struct icmp6_filter{}; <netinet/icmp6.h> struct icmp6_filter{};
<netinet/icmp6.h> struct icmp6_hdr{}; <netinet/icmp6.h> struct icmp6_hdr{};
<netinet/icmp6.h> struct icmp6_router_renum{}; <netinet/icmp6.h> struct icmp6_router_renum{};
<netinet/icmp6.h> struct mld_hdr{}; <netinet/icmp6.h> struct mld_hdr{};
skipping to change at page 49, line 39 skipping to change at page 54, line 33
<netinet/in.h> IPPROTO_AH <netinet/in.h> IPPROTO_AH
<netinet/in.h> IPPROTO_DSTOPTS <netinet/in.h> IPPROTO_DSTOPTS
<netinet/in.h> IPPROTO_ESP <netinet/in.h> IPPROTO_ESP
<netinet/in.h> IPPROTO_FRAGMENT <netinet/in.h> IPPROTO_FRAGMENT
<netinet/in.h> IPPROTO_HOPOPTS <netinet/in.h> IPPROTO_HOPOPTS
<netinet/in.h> IPPROTO_ICMPV6 <netinet/in.h> IPPROTO_ICMPV6
<netinet/in.h> IPPROTO_IPV6 <netinet/in.h> IPPROTO_IPV6
<netinet/in.h> IPPROTO_NONE <netinet/in.h> IPPROTO_NONE
<netinet/in.h> IPPROTO_ROUTING <netinet/in.h> IPPROTO_ROUTING
<netinet/in.h> IPV6_CHECKSUM <netinet/in.h> IPV6_CHECKSUM
<netinet/in.h> IPV6_DONTFRAG
<netinet/in.h> IPV6_DSTOPTS <netinet/in.h> IPV6_DSTOPTS
<netinet/in.h> IPV6_HOPLIMIT <netinet/in.h> IPV6_HOPLIMIT
<netinet/in.h> IPV6_HOPOPTS <netinet/in.h> IPV6_HOPOPTS
<netinet/in.h> IPV6_NEXTHOP <netinet/in.h> IPV6_NEXTHOP
<netinet/in.h> IPV6_PATHMTU <netinet/in.h> IPV6_PATHMTU
<netinet/in.h> IPV6_PKTOPTIONS
<netinet/in.h> IPV6_PKTINFO <netinet/in.h> IPV6_PKTINFO
<netinet/in.h> IPV6_RECVDSTOPTS <netinet/in.h> IPV6_RECVDSTOPTS
<netinet/in.h> IPV6_RECVHOPLIMIT <netinet/in.h> IPV6_RECVHOPLIMIT
<netinet/in.h> IPV6_RECVHOPOPTS <netinet/in.h> IPV6_RECVHOPOPTS
<netinet/in.h> IPV6_RECVPKTINFO <netinet/in.h> IPV6_RECVPKTINFO
<netinet/in.h> IPV6_RECVRTHDR <netinet/in.h> IPV6_RECVRTHDR
<netinet/in.h> IPV6_RECVRTHDRDSTOPTS <netinet/in.h> IPV6_RECVTCLASS
<netinet/in.h> IPV6_RTHDR <netinet/in.h> IPV6_RTHDR
<netinet/in.h> IPV6_RTHDRDSTOPTS <netinet/in.h> IPV6_RTHDRDSTOPTS
<netinet/in.h> IPV6_RTHDR_TYPE_0 <netinet/in.h> IPV6_RTHDR_TYPE_0
<netinet/in.h> IPV6_RECVPATHMTU <netinet/in.h> IPV6_RECVPATHMTU
<netinet/in.h> IPV6_REACHCONF <netinet/in.h> IPV6_REACHCONF
<netinet/in.h> IPV6_TCLASS
<netinet/in.h> IPV6_USE_MIN_MTU <netinet/in.h> IPV6_USE_MIN_MTU
<netinet/in.h> struct in6_pktinfo{}; <netinet/in.h> struct in6_pktinfo{};
<netinet/in.h> struct ip6_mtuinfo{};
<netinet/ip6.h> IP6F_MORE_FRAG <netinet/ip6.h> IP6F_MORE_FRAG
<netinet/ip6.h> IP6F_OFF_MASK <netinet/ip6.h> IP6F_OFF_MASK
<netinet/ip6.h> IP6F_RESERVED_MASK <netinet/ip6.h> IP6F_RESERVED_MASK
<netinet/ip6.h> IP6OPT_BINDING_ACK
<netinet/ip6.h> IP6OPT_BINDING_REQ
<netinet/ip6.h> IP6OPT_BINDING_UPDATE
<netinet/ip6.h> IP6OPT_EID
<netinet/ip6.h> IP6OPT_HOME_ADDRESS
<netinet/ip6.h> IP6OPT_JUMBO <netinet/ip6.h> IP6OPT_JUMBO
<netinet/ip6.h> IP6OPT_JUMBO_LEN <netinet/ip6.h> IP6OPT_JUMBO_LEN
<netinet/ip6.h> IP6OPT_MUTABLE <netinet/ip6.h> IP6OPT_MUTABLE
<netinet/ip6.h> IP6OPT_NSAP_ADDR <netinet/ip6.h> IP6OPT_NSAP_ADDR
<netinet/ip6.h> IP6OPT_PAD1 <netinet/ip6.h> IP6OPT_PAD1
<netinet/ip6.h> IP6OPT_PADN <netinet/ip6.h> IP6OPT_PADN
<netinet/ip6.h> IP6OPT_ROUTER_ALERT <netinet/ip6.h> IP6OPT_ROUTER_ALERT
<netinet/ip6.h> IP6OPT_TUNNEL_LIMIT <netinet/ip6.h> IP6OPT_TUNNEL_LIMIT
<netinet/ip6.h> IP6OPT_TYPE_DISCARD <netinet/ip6.h> IP6OPT_TYPE_DISCARD
<netinet/ip6.h> IP6OPT_TYPE_FORCEICMP <netinet/ip6.h> IP6OPT_TYPE_FORCEICMP
<netinet/ip6.h> IP6OPT_TYPE_ICMP <netinet/ip6.h> IP6OPT_TYPE_ICMP
<netinet/ip6.h> IP6OPT_TYPE_SKIP <netinet/ip6.h> IP6OPT_TYPE_SKIP
<netinet/ip6.h> IP6_ALERT_AN <netinet/ip6.h> IP6_ALERT_AN
<netinet/ip6.h> IP6_ALERT_AN
<netinet/ip6.h> IP6_ALERT_MLD <netinet/ip6.h> IP6_ALERT_MLD
<netinet/ip6.h> IP6_ALERT_MLD
<netinet/ip6.h> IP6_ALERT_RSVP
<netinet/ip6.h> IP6_ALERT_RSVP <netinet/ip6.h> IP6_ALERT_RSVP
<netinet/ip6.h> IP6_BUF_ACK
<netinet/ip6.h> IP6_BUF_COA
<netinet/ip6.h> IP6_BUF_HOME
<netinet/ip6.h> IP6_BUF_ROUTER
<netinet/ip6.h> struct ip6_dest{}; <netinet/ip6.h> struct ip6_dest{};
<netinet/ip6.h> struct ip6_ext{}; <netinet/ip6.h> struct ip6_ext{};
<netinet/ip6.h> struct ip6_frag{}; <netinet/ip6.h> struct ip6_frag{};
<netinet/ip6.h> struct ip6_hbh{}; <netinet/ip6.h> struct ip6_hbh{};
<netinet/ip6.h> struct ip6_hdr{}; <netinet/ip6.h> struct ip6_hdr{};
<netinet/ip6.h> struct ip6_opt{}; <netinet/ip6.h> struct ip6_opt{};
<netinet/ip6.h> struct ip6_opt_binding_ack{};
<netinet/ip6.h> struct ip6_opt_binding_request{};
<netinet/ip6.h> struct ip6_opt_binding_update{};
<netinet/ip6.h> struct ip6_opt_home_address{};
<netinet/ip6.h> struct ip6_opt_jumbo{}; <netinet/ip6.h> struct ip6_opt_jumbo{};
<netinet/ip6.h> struct ip6_opt_nsap{}; <netinet/ip6.h> struct ip6_opt_nsap{};
<netinet/ip6.h> struct ip6_opt_router{}; <netinet/ip6.h> struct ip6_opt_router{};
<netinet/ip6.h> struct ip6_opt_tunnel{}; <netinet/ip6.h> struct ip6_opt_tunnel{};
<netinet/ip6.h> struct ip6_rthdr{}; <netinet/ip6.h> struct ip6_rthdr{};
<netinet/ip6.h> struct ip6_rthdr0{}; <netinet/ip6.h> struct ip6_rthdr0{};
The following list summarizes the function and macro prototypes The following list summarizes the function and macro prototypes
discussed in this memo, sorted by header. discussed in this memo, sorted by header.
skipping to change at page 52, line 19 skipping to change at page 56, line 48
16. Security Considerations 16. Security Considerations
The setting of certain Hop-by-Hop options and Destination options may The setting of certain Hop-by-Hop options and Destination options may
be restricted to privileged processes. Similarly some Hop-by-Hop be restricted to privileged processes. Similarly some Hop-by-Hop
options and Destination options may not be returned to nonprivileged options and Destination options may not be returned to nonprivileged
applications. applications.
The ability to specify an arbitrary source address using IPV6_PKTINFO The ability to specify an arbitrary source address using IPV6_PKTINFO
must be prevented; at least for non-privileged processes. must be prevented; at least for non-privileged processes.
The use of IPV6_REACHCONF ancillary data item may cause a denial of
service attack from a local application.
17. Change History 17. Change History
Changes from RFC 2292: Changes from RFC 2292:
- Removed the IPV6_PKTOPTIONS socket option by allowing sticky - Removed the IPV6_PKTOPTIONS socket option by allowing sticky
options to be set with individual setsockopt calls. This options to be set with individual setsockopt calls. This
simplifies the protocol stack implementation by not having to simplifies the protocol stack implementation by not having to
handle options within options and also clarifies the failure handle options within options and also clarifies the failure
semantics when some option is incorrectly formatted. semantics when some option is incorrectly formatted.
skipping to change at page 54, line 24 skipping to change at page 59, line 9
applications. applications.
- Clarified that if the application asks for e.g., IPV6_RTHDR and a - Clarified that if the application asks for e.g., IPV6_RTHDR and a
received datagram does not contain a Routing header an received datagram does not contain a Routing header an
implementation will exclude the IPV6_RTHDR ancillary data item. implementation will exclude the IPV6_RTHDR ancillary data item.
- Removed the constraints for jumbo option. - Removed the constraints for jumbo option.
- Moved the new CMSG macros and changes from the appendix. - Moved the new CMSG macros and changes from the appendix.
- Add text about inet6_opt_ depending on 2260 appendix B formatting - Add text about inet6_opt_ depending on 2460 appendix B formatting
rules i.e. largest field last in the option. rules i.e. largest field last in the option.
- Specified that getsockopt() of a sticky option returns what was - Specified that getsockopt() of a sticky option returns what was
set with setsockopt(). set with setsockopt().
- Updated the summary of new definitions to make it current. - Updated the summary of new definitions to make it current.
Changes since -01: Changes since -01:
- Added a note about the minor threat for DoS attacks using - Added a note about the minor threat for DoS attacks using
IPV6_REACHCONF IPV6_REACHCONF
- Clarified checksum and other receive side verification for RAW - Clarified checksum and other receive side verification for RAW
ICMP sockets. ICMP sockets.
- Editorial clarifications. - Editorial clarifications.
18. TODO and Open Issues Changes since -02:
Items left to do: - Changed IPV6_PATHMTU to carry a ip6_mtuinfo data structure.
- Add macros for ip6_hdr to access the traffic class and flow label - Added the ability to do a getsockopt with IPV6_PATHMTU.
fields.
- Should we remove the 1, 2, 4, 8 byte restriction for - Added IPV6_DONTFRAG socket option.
inet6_opt_set_val and inet6_opt_get_val? Option values can be
any size even though there alignment must be a power of two.
Issue of how natural alignment is defined for sizes that are not
a power of two.
- Perhaps we should add a note to point out that robust receivers - Incorporated IPV6_TCLASS and friends, from draft-itojun-ipv6-
should verify alignment before calling inet6_opt_get_val(). Or tclass-api-03.txt.
require that inet6_opt_get_val() should check the alignment and
fail by returning -1?
- Should we change IPV6_USE_MIN_MTU to IPV6_USEMTU taking a - Removed definitions and descriptions about ongoing stuff,
uint32_t Should we add IPV6_DONTFRAG option for traceroute?? including ones for mobile IPv6 and site prefixes.
- Add credits for UDP MTU stuff - Revised the overriding mechanism of sticky options so that a
sticky option can only be overridden by an ancillary data item of
the same option name.
- Move information about mapping from inet6_opt to setsockopt and - Loosened requirements on the size of option fields in
cmsg. inet6_opt_get_val() and inet6_opt_set_val().
- Clarify IPV6_RTHDRDSTOPTS's interaction with IPV6_RTHDR. - Added credits for the original idea of IPV6_USE_MIN_MTU.
- Make the new inet6_opt_set_val() and inet6_opt_get_val() check - Clarified how to clear sticky options and the ICMPv6 filter.
the length of the data item.
- Add sending and receiving sections for routing header text just - Clarified alignment issues on inet6_opt_set_val().
like destination options?
- Include sample implementation of inet6_opt_XXX. - Clarified that IPV6_CHECKSUM assumes an even positive offset and
that the checksum field is aligned on a 16-bit boundary.
- Fix Authors address wrt Rich. - Removed the ip6_ext structure, which was intended to be used as a
"generic" extension header prototype. But the working group
consensus was that we should NOT include such stuff.
Open issues: - Revised the "TCP implications" section; for the receiving side,
reverted to a RFC2292-style getsockopt instead of using recvmsg()
and ancillary data.
- Add ICMP name lookups definitions? - Disabled the use of the IPV6_HOPLIMIT sticky option.
- Add site-prefixes definitions? - Clarified the ordering between IPV6_MULTICAST_IF and the
IPV6_PKTINFO sticky option for mutlcast packets.
- Add flow label allocation API as requested in draft-berson-rsvp- - Added considerations on Specifying/Receiving Source/Destination
ipv6-fl-00.txt? Draft has expired! Address, mainly about TCP implications.
- Anything special for mobility options? Restrict setting at API? - Clarified the scoped-address case of the source address
Filter out on receipt? If received what does the home address specification; the kernel must first determine the appropriate
option contain? scope zone.
- Specify "change" for TCP especially when there are multiple HBH - Added a summary about the interface selection rule.
option headers etc.
- Specify binding to scope-id => implies filtering of addresses - Clarified that IPV6_NEXTHOP should be ignored for a multicast
with that scope if the address you are bound to is link-local destination and that it should not contradict with the specified
etc. What about conflicts with bound scope-id and sendto/connect outgoing interface.
scope-id?
- Specify order for ifindex selection. Put in separate section. - Added clarifications on exten headers ordering; for the sending
Different cases for sending to link-local (scope_id including side, assume the recommended ordering described in RFC2460. For
nexthop scope_id) and global. Is multicast different? the receiving side, do not assume any ordering and pass all
headers to the application in the received order.
- bind() and sin6_scope_id. Should have been in Basic API. Error - Clarified return values of getsockopt() for IPV6_xxx sticky
checks when bind/sendto sin6_scope_id does not match? options when no sticky option value has been set by setsockopt().
- Specify notion of default multicast interface? In Basic API? - Described TCP implications about "additional advanced API
functions."
- What about site names and site ids? Need for interfaces to map? - Updated text about Hop-by-Hop and Destination options headers
Requires that site-prefixes pass name - does name need to use DNS that was based on the old RFC version of this API document.
format to handle character sets?
- If the home address option passed out in IPV6_RECVDSTOPTS? If so - Updated the URL for protocol numbers.
what address value does it contain?
- Clarified that access to the flow label field was not provided.
- Removed IPV6_RECVRTHDRDSTOPTS. Since we have loosened the
ordering restriction for the receiving side, it is not meaningful
to separate the two cases.
- Clearly stated that this API only handles the case where
IPV6_NEXTHOP takes sockaddr_in6.
18. Open Issues
Open issues:
- Do we really need to standardize rcmd functions here?
- Is this a good idea to revive the IPV6_PKTOPTIONS option to get
the optional information on a TCP socket? Or should we keep the
previous usage using recvmsg() and ancillary data? The latter
approach has a merit of less overhead and the ability to provide
applications with more chances to follow changes on the optional
information. However, it still does not provide complete
information of the changes, and, thus, it cannot be used for
security purposes (such as the filtering based on the receiving
hop limit). Also, since the optional information always comes
with a data segment, a TCP application that do not receive a data
segment (i.e. an application only receiving SYN, FIN, and ACK-
only segments) cannot get any optional information. Those issues
are the reason for the specification change in this revision, but
it may be controversial.
19. References 19. References
[RFC-2460] Deering, S., Hinden, R., "Internet Protocol, Version 6 [RFC-2460] Deering, S., Hinden, R., "Internet Protocol, Version 6
(IPv6), Specification", RFC 2460, Dec. 1998. (IPv6), Specification", RFC 2460, Dec. 1998.
[RFC-2553] Gilligan, R. E., Thomson, S., Bound, J., Stevens, W., [RFC-2553] Gilligan, R. E., Thomson, S., Bound, J., Stevens, W.,
"Basic Socket Interface Extensions for IPv6", RFC 2553, "Basic Socket Interface Extensions for IPv6", RFC 2553,
March 1999. March 1999.
skipping to change at page 56, line 38 skipping to change at page 62, line 4
"Basic Socket Interface Extensions for IPv6", RFC 2553, "Basic Socket Interface Extensions for IPv6", RFC 2553,
March 1999. March 1999.
[RFC-1981] McCann, J., Deering, S., Mogul, J, "Path MTU Discovery [RFC-1981] McCann, J., Deering, S., Mogul, J, "Path MTU Discovery
for IP version 6", RFC 1981, Aug. 1996. for IP version 6", RFC 1981, Aug. 1996.
[RFC-2461] Narten, T., Nordmark, E., Simpson, W., "Neighbor [RFC-2461] Narten, T., Nordmark, E., Simpson, W., "Neighbor
Discovery for IP Version 6 (IPv6)", RFC 2461, Dec. 1998. Discovery for IP Version 6 (IPv6)", RFC 2461, Dec. 1998.
20. Acknowledgments 20. Acknowledgments
Matt Thomas and Jim Bound have been working on the technical details Matt Thomas and Jim Bound have been working on the technical details
in this draft for over a year. Keith Sklower is the original in this draft for over a year. Keith Sklower is the original
implementor of ancillary data in the BSD networking code. Craig Metz implementor of ancillary data in the BSD networking code. Craig Metz
provided lots of feedback, suggestions, and comments based on his provided lots of feedback, suggestions, and comments based on his
implementing many of these features as the document was being implementing many of these features as the document was being
written. written. Mark Andrews first proposed the idea of the
IPV6_USE_MIN_MTU option. Jun-ichiro Hagino contributed text for the
traffic class API from a draft of his own.
The following provided comments on earlier drafts: Pascal Anelli, The following provided comments on earlier drafts: Pascal Anelli,
Hamid Asayesh, Ran Atkinson, Karl Auerbach, Hamid Asayesh, Jim Bound, Hamid Asayesh, Ran Atkinson, Karl Auerbach, Hamid Asayesh, Don
Don Coolidge, Matt Crawford, Sam T. Denton, Richard Draves, Francis Coolidge, Matt Crawford, Sam T. Denton, Richard Draves, Francis
Dupont, Bob Gilligan, Jun-ichiro Hagino, Gerri Harter, Tim Hartrick, Dupont, Lilian Fernandes, Bob Gilligan, Gerri Harter, Tim Hartrick,
Bob Halley, Masaki Hirabaru, Yoshinobu Inoue, Mukesh Kacker, A. N. Bob Halley, Masaki Hirabaru, Yoshinobu Inoue, Mukesh Kacker, A. N.
Kuznetsov, Sam Manthorpe, Pedro Marques, Jack McCann, der Mouse, John Kuznetsov, Sam Manthorpe, Pedro Marques, Jack McCann, der Mouse, John
Moy, Thomas Narten, Steve Parker, Charles Perkins, Ken Powell, Tom Moy, Lori Napoli, Thomas Narten, Atsushi Onoe, Steve Parker, Charles
Pusateri, Pedro Roque, Sameer Shah, Peter Sjodin, Stephen P. Perkins, Ken Powell, Tom Pusateri, Pedro Roque, Sameer Shah, Peter
Spackman, Jinmei Tatuya, Karen Tracey, Sowmini Varadhan, Quaizar Sjodin, Stephen P. Spackman, Jinmei Tatuya, Karen Tracey, Sowmini
Vohra, Carl Williams, Steve Wise, Eric Wong, Farrell Woods, Kazu Varadhan, Quaizar Vohra, Carl Williams, Steve Wise, Eric Wong,
Yamamoto, and Vlad Yasevich. Farrell Woods, Kazu Yamamoto, Vlad Yasevich, and YOSHIFUJI Hideaki.
21. Authors' Addresses 21. Authors' Addresses
W. Richard Stevens W. Richard Stevens (deceased)
1202 E. Paseo del Zorro
Tucson, AZ 85718
Email: rstevens@kohala.com
Matt Thomas Matt Thomas
3am Software Foundry 3am Software Foundry
8053 Park Villa Circle 8053 Park Villa Circle
Cupertino, CA 95014 Cupertino, CA 95014
Email: matt@3am-software.com Email: matt@3am-software.com
Erik Nordmark Erik Nordmark
Sun Microsystems, Inc. Sun Microsystems Laboratories, Europe
901 San Antonio Road 29 Chemin du Vieux Chene
Palo Alto, CA 94303, USA 38240 Meylan, France
Email: erik.nordmark@eng.sun.com Email: Erik.Nordmark@sun.com
Tatuya JINMEI
Corporate Research & Development Center, Toshiba Corporation
1 Komukai Toshiba-cho, Kawasaki-shi
Kanagawa 212-8582, Japan
Email: jinmei@isl.rdc.toshiba.co.jp
22. Appendix A: Ancillary Data Overview 22. Appendix A: Ancillary Data Overview
4.2BSD allowed file descriptors to be transferred between separate 4.2BSD allowed file descriptors to be transferred between separate
processes across a UNIX domain socket using the sendmsg() and processes across a UNIX domain socket using the sendmsg() and
recvmsg() functions. Two members of the msghdr structure, recvmsg() functions. Two members of the msghdr structure,
msg_accrights and msg_accrightslen, were used to send and receive the msg_accrights and msg_accrightslen, were used to send and receive the
descriptors. When the OSI protocols were added to 4.3BSD Reno in descriptors. When the OSI protocols were added to 4.3BSD Reno in
1990 the names of these two fields in the msghdr structure were 1990 the names of these two fields in the msghdr structure were
changed to msg_control and msg_controllen, because they were used by changed to msg_control and msg_controllen, because they were used by
skipping to change at page 58, line 40 skipping to change at page 64, line 9
(Note: Before Posix.1g the two "void *" pointers were typically "char (Note: Before Posix.1g the two "void *" pointers were typically "char
*", and the two socklen_t members and the size_t member were *", and the two socklen_t members and the size_t member were
typically integers. Earlier drafts of Posix.1g had the two socklen_t typically integers. Earlier drafts of Posix.1g had the two socklen_t
members as size_t, but Draft 6.6 of Posix.1g, apparently the final members as size_t, but Draft 6.6 of Posix.1g, apparently the final
draft, changed these to socklen_t to simplify binary portability for draft, changed these to socklen_t to simplify binary portability for
64-bit implementations and to align Posix.1g with X/Open's Networking 64-bit implementations and to align Posix.1g with X/Open's Networking
Services, Issue 5. The change in msg_control to a "void *" pointer Services, Issue 5. The change in msg_control to a "void *" pointer
affects any code that increments this pointer.) affects any code that increments this pointer.)
(Note: Before Posix.1g the cmsg_len member was an integer, and not a
socklen_t. See the Note in the previous section for why socklen_t is
used here.)
Most Berkeley-derived implementations limit the amount of ancillary Most Berkeley-derived implementations limit the amount of ancillary
data in a call to sendmsg() to no more than 108 bytes (an mbuf). data in a call to sendmsg() to no more than 108 bytes (an mbuf).
This API requires a minimum of 10240 bytes of ancillary data, but it This API requires a minimum of 10240 bytes of ancillary data, but it
is recommended that the amount be limited only by the buffer space is recommended that the amount be limited only by the buffer space
reserved by the socket (which can be modified by the SO_SNDBUF socket reserved by the socket (which can be modified by the SO_SNDBUF socket
option). (Note: This magic number 10240 was picked as a value that option). (Note: This magic number 10240 was picked as a value that
should always be large enough. 108 bytes is clearly too small as the should always be large enough. 108 bytes is clearly too small as the
maximum size of a Routing header is 2048 bytes.) maximum size of a Routing header is 2048 bytes.)
22.2. The cmsghdr Structure 22.2. The cmsghdr Structure
skipping to change at page 59, line 21 skipping to change at page 64, line 32
struct cmsghdr { struct cmsghdr {
socklen_t cmsg_len; /* #bytes, including this header */ socklen_t cmsg_len; /* #bytes, including this header */
int cmsg_level; /* originating protocol */ int cmsg_level; /* originating protocol */
int cmsg_type; /* protocol-specific type */ int cmsg_type; /* protocol-specific type */
/* followed by unsigned char cmsg_data[]; */ /* followed by unsigned char cmsg_data[]; */
}; };
This structure is declared as a result of including <sys/socket.h>. This structure is declared as a result of including <sys/socket.h>.
(Note: Before Posix.1g the cmsg_len member was an integer, and not a
socklen_t. See the Note in the previous section for why socklen_t is
used here.)
As shown in this definition, normally there is no member with the As shown in this definition, normally there is no member with the
name cmsg_data[]. Instead, the data portion is accessed using the name cmsg_data[]. Instead, the data portion is accessed using the
CMSG_xxx() macros, as described in Section 22.3. Nevertheless, it is CMSG_xxx() macros, as described in Section 22.3. Nevertheless, it is
common to refer to the cmsg_data[] member. common to refer to the cmsg_data[] member.
When ancillary data is sent or received, any number of ancillary data When ancillary data is sent or received, any number of ancillary data
objects can be specified by the msg_control and msg_controllen objects can be specified by the msg_control and msg_controllen
members of the msghdr structure, because each object is preceded by a members of the msghdr structure, because each object is preceded by a
cmsghdr structure defining the object's length (the cmsg_len member). cmsghdr structure defining the object's length (the cmsg_len member).
Historically Berkeley-derived implementations have passed only one Historically Berkeley-derived implementations have passed only one
 End of changes. 159 change blocks. 
487 lines changed or deleted 752 lines changed or added

This html diff was produced by rfcdiff 1.33. The latest version is available from http://tools.ietf.org/tools/rfcdiff/