idnits 2.17.1 draft-chakrabarti-ipv6-addrselect-api-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 18. -- Found old boilerplate from RFC 3978, Section 5.5 on line 957. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 934. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 941. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 947. ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- == No 'Intended status' indicated for this document; assuming Proposed Standard Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The abstract seems to contain references ([RFC3493], [RFC3542], [RFC3484]), which it shouldn't. Please replace those with straight textual mentions of the documents in question. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 Copyright Line does not match the current year == Using lowercase 'not' together with uppercase 'MUST', 'SHALL', 'SHOULD', or 'RECOMMENDED' is not an accepted usage according to RFC 2119. Please use uppercase 'NOT' together with RFC 2119 keywords (if that is what you mean). Found 'MUST not' in this paragraph: Applications MUST not set contradictory flags at the same time. -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (October 20, 2006) is 6396 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) ** Obsolete normative reference: RFC 3484 (Obsoleted by RFC 6724) ** Downref: Normative reference to an Informational RFC: RFC 3493 -- Obsolete informational reference (is this intentional?): RFC 2460 (Obsoleted by RFC 8200) -- Obsolete informational reference (is this intentional?): RFC 3041 (Obsoleted by RFC 4941) -- Obsolete informational reference (is this intentional?): RFC 3775 (Obsoleted by RFC 6275) Summary: 6 errors (**), 0 flaws (~~), 3 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 Network Working Group E. Nordmark 3 Internet-Draft Sun Microsystems, Inc. 4 Expires: April 23, 2007 S. Chakrabarti 5 Azaire Networks 6 J. Laganier 7 DoCoMo Euro-Labs 8 October 20, 2006 10 IPv6 Socket API for Address Selection 11 draft-chakrabarti-ipv6-addrselect-api-04 13 Status of this Memo 15 By submitting this Internet-Draft, each author represents that any 16 applicable patent or other IPR claims of which he or she is aware 17 have been or will be disclosed, and any of which he or she becomes 18 aware will be disclosed, in accordance with Section 6 of BCP 79. 20 Internet-Drafts are working documents of the Internet Engineering 21 Task Force (IETF), its areas, and its working groups. Note that 22 other groups may also distribute working documents as Internet- 23 Drafts. 25 Internet-Drafts are draft documents valid for a maximum of six months 26 and may be updated, replaced, or obsoleted by other documents at any 27 time. It is inappropriate to use Internet-Drafts as reference 28 material or to cite them other than as "work in progress." 30 The list of current Internet-Drafts can be accessed at 31 http://www.ietf.org/ietf/1id-abstracts.txt. 33 The list of Internet-Draft Shadow Directories can be accessed at 34 http://www.ietf.org/shadow.html. 36 This Internet-Draft will expire on April 23, 2007. 38 Copyright Notice 40 Copyright (C) The Internet Society (2006). 42 Abstract 44 The IPv6 default address selection document [RFC3484] describes the 45 rules for selecting source and destination IPv6 addresses, and 46 indicates that applications should be able to reverse the sense of 47 some of the address selection rules through some unspecified API. 48 However, no such socket API exists in the basic [RFC3493] or advanced 50 [RFC3542] IPv6 socket API documents. This document fills that gap by 51 specifying new socket level options and flags for the getaddrinfo() 52 API to specify preferences for address selection that modify the 53 default address selection algorithm. The socket API described in 54 this document will be particularly useful for IPv6 applications that 55 want to choose between temporary and public addresses, and for Mobile 56 IPv6 aware applications that want to use the care-of address for 57 communication. 59 Table of Contents 61 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 62 2. Definition Of Terms . . . . . . . . . . . . . . . . . . . . . 6 63 3. Design Alternatives . . . . . . . . . . . . . . . . . . . . . 7 64 4. Example Usages . . . . . . . . . . . . . . . . . . . . . . . . 8 65 5. Additions to the Socket Interface . . . . . . . . . . . . . . 9 66 6. Additions to the protocol-independent nodename translation . . 11 67 7. Application Requirements . . . . . . . . . . . . . . . . . . . 15 68 8. Implementation Notes . . . . . . . . . . . . . . . . . . . . . 17 69 9. Mapping to Default Address Selection Rules . . . . . . . . . . 18 70 10. IPv4-mapped IPv6 Addresses . . . . . . . . . . . . . . . . . . 19 71 11. Validation function for source address . . . . . . . . . . . . 20 72 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 22 73 13. Security Considerations . . . . . . . . . . . . . . . . . . . 23 74 14. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 24 75 15. References . . . . . . . . . . . . . . . . . . . . . . . . . . 25 76 15.1. Normative references . . . . . . . . . . . . . . . . . . 25 77 15.2. Informative references . . . . . . . . . . . . . . . . . 25 78 Appendix A. Per Packet Address Selection Preference . . . . . . . 26 79 Appendix B. Changes from previous version of draft . . . . . . . 28 80 Appendix C. Intellectual Property Statement . . . . . . . . . . . 29 81 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 82 Intellectual Property and Copyright Statements . . . . . . . . . . 31 84 1. Introduction 86 [RFC3484] specifies the default address selection rules for IPv6 87 [RFC2460]. This document defines socket API extensions that allow 88 applications to override the default choice of address selection. 89 Privacy considerations [RFC3041] have introduced "public" and 90 "temporary" addresses. IPv6 Mobility [RFC3775] introduces "home 91 address" and "care-of address" definitions in the mobile systems. 93 The default address selection rules in [RFC3484] in summary are that 94 a public address is preferred over a temporary address, that a mobile 95 IPv6 home address is preferred over a care-of address, and that a 96 larger scope address is preferred over a smaller scope address. 97 Although it is desirable to have default rules for address selection, 98 an application may want to reverse certain address selection rules 99 for efficiency and other application-specific reasons. 101 Currently IPv6 socket API extensions provide mechanisms to choose a 102 specific source address through simple bind() operation or 103 IPV6_PKTINFO socket option [RFC3542]. However, in order to use 104 bind() or IPV6_PKTINFO socket option, the application itself must 105 make sure that the source address is appropriate for the destination 106 address (e.g., with respect to the interface used to send packets to 107 the destination). The application also needs to verify the 108 appropriateness of the source address scope with respect to the 109 destination address and so on. This can be quite complex for the 110 application, since in effect it needs to implement all the default 111 address selection rules in order to change its preferences with 112 respect to one of the rules. 114 The mechanism presented in this document allows the application to 115 specify attributes of the source (and destination) addresses it 116 prefers while still having the system perform the rest of the address 117 selection rules. For instance, if an application specifies that it 118 prefers to use a care-of address over a home address as the source 119 address and if the host has two care-of addresses, one public and one 120 temporary, then the host would select the public care-of address by 121 following the default address selection rule for preferring a public 122 over a temporary address. 124 A socket option has been deemed useful for this purpose, as it 125 enables an application to specify address selection preferences on a 126 per-socket basis. It can also provide the flexibility of enabling 127 and disabling address selection preferences in non-connected (UDP) 128 sockets. The socket option uses a set of flags for specifying 129 address selection preferences. Since the API should not assume a 130 particular implementation method of the address selection [RFC3484] 131 in the network layer or in getaddrinfo(), the corresponding set of 132 flags are also defined for getaddrinfo(). 134 As a result, this document introduces several flags for address 135 selection preferences that alter the default address selection 136 [RFC3484] for a number of rules. It analyzes the usefulness of 137 providing API functionality for different default address selection 138 rules; it provides API to alter only those rules that are possibly 139 used by certain classes of applications. In addition, it also 140 considers CGA [RFC3972] and non-CGA source addresses when CGA 141 addresses are available in the system. In the future, more 142 destination or source flags may be added to expand the API as the 143 needs may arise. 145 The approach in this document is to allow the application to specify 146 preferences for address selection and not to be able to specify hard 147 requirements: For instance, an application can set a flag to prefer a 148 temporary source address, but if no temporary source addresses are 149 available at the node, a public address would be chosen instead. 151 Specifying hard requirements for address selection would be 152 problematic for several reasons. The major one is that in the vast 153 majority of cases the application would like to be able to 154 communicate even if an address with the 'optimal' attributes is not 155 available. For instance, an application that performs very short, 156 e.g., UDP, transactional exchanges (e.g. DNS queries), might prefer 157 to use a care-of address when running on a mobile host which is away 158 from home since this provides a short round-trip time in many cases. 159 But if the application is running on a mobile host that is at home, 160 or running on a host which isn't providing Mobile IPv6, then it 161 doesn't make sense for the application to fail due to no care-of 162 address being available. Also, in particular when using UDP sockets 163 and the sendto() or sendmsg() primitives, the use of hard 164 requirements would have been problematic, since the set of available 165 IP addresses might very well have changed from when the application 166 called getaddrinfo() until it called sendto() or sendmsg(), which 167 would introduce new failure modes. 169 For the few applications that have hard requirements on the 170 attributes of the IP addresses they use, this document defines a 171 verification function which allows such applications to properly fail 172 to communicate when their address selection requirements are not met. 174 Furthermore, the approach is to define two flags for each rule that 175 can be modified, so that an application can specify its preference 176 for addresses selected as per the rule, the opposite preference (i.e. 177 an address selected as per the rule reverted), or choose not to set 178 either of the flags relating to that rule and leave it up to the 179 system default (see section 3.1). This approach allows different 180 implementations to have different system defaults, and works with 181 getaddrinfo() as well as setsockopt(). (For setsockopt a different 182 approach could have been chosen, but that would still require this 183 approach for getaddrinfo.) 185 This document specifies extensions only to the Basic IPv6 socket API 186 specified in [RFC3493]. The intent is that this document serves as a 187 model for expressing preferences for attributes of IP addresses, that 188 also need to be expressible in other networking API such as those 189 found in middleware systems and the Java environment. 191 2. Definition Of Terms 193 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 194 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 195 document are to be interpreted as described in [RFC2119]. 197 Opposite flags: 199 Each flag expressing an address preference has a so called "opposite 200 flag" expressing the opposite preference: 202 home address preference flag is the opposite of the care-of 203 address preference flag. 205 temporary address preference flag is the opposite of the public 206 address preference flag. 208 CGA address preference flag is the opposite of the non-CGA address 209 preference flag. 211 Contradictory flags: 213 Any combination of flags including both a flag expressing a given 214 address preference and a flag expressing the opposite preference 215 constitutes Such flags are contradictory by definition of their 216 usefulness with respect to source address selection. For example, 217 consider a set of flags including both the home address preference 218 flag and the care-of address preference flag. When considering 219 source address selection, the selected address can be a home address, 220 or a care-of address, but it cannot be both at the same time. Hence, 221 to prefer an address which is both a home address, and a care-of 222 address, is contradictory. 224 3. Design Alternatives 226 Some suggested to have per-application flags instead of per-socket 227 and per-packet flags. However, this design stays with per-socket and 228 per-packet flags for the following reasons: 230 o While some systems have per environment/application flags (such as 231 environment variables in Unix systems) this might not be available 232 in all systems which implement the socket API. 234 o When an application links with some standard library, that library 235 might use the socket API, while the application is unaware of that 236 fact. Mechanisms that would provide per application flags may 237 affect not only the application itself but also the libraries, 238 hence creating risks of unintended consequences. 240 Instead of the pair of 'flag' and 'opposite flag' for each rule that 241 can be modified, the socket option could have been defined to use a 242 single 'flag' value for each rule. This would still have allowed 243 different implementations to have different default settings as long 244 as the applications were coded to first retrieve the default setting 245 (using getsockopt()), and then clear or set the 'flag' according to 246 their preferences, and finally set the new value with setsockopt(). 248 But such an approach would not be possible for getaddrinfo() because 249 all the preferences would need to be expressible in the parameters 250 that are passed with a single getaddrinfo() call. Hence, for 251 consistency, the 'flag' and 'opposite flag' approach is used for both 252 getaddrinfo() and setsockopt(). 254 4. Example Usages 256 The examples discussed here are limited to applications supporting 257 Mobile IPv6, IPv6 Privacy Extensions and Cryptographically Generated 258 Addresses. Address selection document [RFC3484] recommends that home 259 addresses should be preferred over care-of address when both are 260 configured. However, a mobile node may want to prefer care-of 261 address as source address for DNS query in the foreign network as it 262 normally means a shorter and local return path compared to the route 263 via the mobile node's home-agent when the query contains home address 264 as source address. Another example is IKE application which requires 265 care-of address as its source address for the initial security 266 association pair with Home Agent [RFC3775] while the mobile node 267 boots up at the foreign network and wants to do the key exchange 268 before a successful home-registration. Also a Mobile IPv6 aware 269 application may want to toggle between home address and care-of 270 address depending on its location and state of the application. It 271 may also want to open different sockets and use home address as 272 source address for one socket and care-of address for the others. 274 In a non-mobile environment, similarly an application may prefer to 275 use temporary address as source address for certain cases. By 276 default, the source address selection rule selects "public" address 277 when both are available. For example, an application supporting web 278 browser and mail-server may want to use "temporary" address for the 279 former and "public" address for the mail-server as a mail-server may 280 require reverse path for DNS records for anti-spam rules. 282 Similarly, a node may be configured to use Cryptographically 283 Generated Addresses [RFC3972] by default, as in Secure Neighbor 284 Discovery [RFC3971], but an application may prefer not to use it. 285 For instance, fping [FPING], a debugging tool which tests basic 286 reachability of multiple destinations by sending packets in parallel, 287 may find that the cost and time incurred in proof-of-ownership by CGA 288 verification is not justified. On the other hand, when a node is not 289 configured for CGA as default, an application may prefer using CGA by 290 setting the corresponding preference. 292 5. Additions to the Socket Interface 294 The IPv6 Basic Socket API [RFC3493] defines socket options for IPv6. 295 To allow applications to influence address selection mechanisms this 296 document adds a new socket option at the IPPROTO_IPV6 level. This 297 socket option is called IPV6_ADDR_PREFERENCES. It can be used with 298 setsockopt() and getsockopt() calls to set and get the address 299 selection preferences affecting all packets sent via a given socket. 300 The socket option value (optval) is a 32-bits unsigned integer 301 argument. The argument consists of a number of flags where each flag 302 indicates an address selection preference which modifies one of the 303 rules in the default address selection specification. 305 The following flags are defined to alter or set the default rule of 306 source and destination address selection rules discussed in default 307 address selection specification [RFC3484]. 309 #include 311 IPV6_PREFER_SRC_HOME /* Prefer Home address as source */ 312 IPV6_PREFER_SRC_COA /* Prefer Care-of address as source */ 313 IPV6_PREFER_SRC_TMP /* Prefer Temporary address as source */ 314 IPV6_PREFER_SRC_PUBLIC /* Prefer Public address as source */ 315 IPV6_PREFER_SRC_CGA /* Prefer CGA address as source */ 316 IPV6_PREFER_SRC_NONCGA /* Prefer a non-CGA address as source */ 318 NOTE: No source preference flag for longest matching prefix is 319 defined here because it is believed to be handled by the policy table 320 defined in the default address selection specification. 322 The following example illustrates usage on an AF_INET6 socket: 324 uint32_t flags = IPV6_PREFER_SRC_COA; 326 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 327 (const void *) &flags, sizeof (flags)) == -1) { 328 perror("setsockopt IPV6_ADDR_PREFERENCES"); 329 } 331 When the IPV6_ADDR_PREFERENCES is successfully set with setsockopt(), 332 the option value given is used to specify address preference for any 333 connection initiation through the socket and all subsequent packets 334 sent via that socket. If no option is set, the system selects a 335 default value as per default address selection algorithm or by some 336 other equivalent means. 338 Setting contradictory flags at the same time results in the error 339 EINVAL. For example, contradictory combinations of flags are: 341 IPV6_PREFER_SRC_PUBLIC | IPV6_PREFER_SRC_TMP 342 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_COA 343 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_COA | IPV6_PREFER_SRC_TMP 344 IPV6_PREFER_SRC_CGA | IPV6_PREFER_SRC_NONCGA 345 etc. 347 If a flag set includes a combination of 'X' and 'Y', and if 'Y' is 348 not applicable or available in the system, then the selected address 349 has attribute 'X' and system default for the attribute 'Y'. For 350 example, a possible valid combination of flags can be: 352 IPV6_PREFER_SRC_PUBLIC | IPV6_PREFER_SRC_HOME 354 6. Additions to the protocol-independent nodename translation 356 Section 8 of Default Address Selection [RFC3484] document indicates 357 possible implementation strategies for getaddrinfo() [RFC3493]. One 358 of them suggests that getaddrinfo() collects available source/ 359 destination pair from the network layer after being sorted at the 360 network layer with full knowledge of source address selection. 361 Another strategy is to call down to the network layer to retrieve 362 source address information and then sort the list in the context of 363 getaddrinfo(). 365 This implies that getaddrinfo() should be aware of the address 366 selection preferences of the application, since getaddrinfo() is 367 independent of any socket the application might be using. 369 Thus if an application alters the default address selection rules by 370 using setsockopt() with the IPV6_ADDR_PREFERENCES option, the 371 application should also use the corresponding flags with its 372 getaddrinfo() call. A new ai_flag is introduced (AI_PREFERENCE) to 373 indicate the system to look for source address selection hints 374 specified in the ai_eflags. If AI_PREFERENCES is set, ai_eflags MUST 375 be set to the IPV6_PREFER_SRC_* values defined in this document. 376 Note that the additional field for extended flags are added at the 377 bottom of the addrinfo structure in order to preserve binary 378 compatibility of the new functionality with the old applications 379 which use the existing addrinfo data structure. Addition of extended 380 flags field provides the designers freedom of adding more flags as 381 necessary without crowding the valuable bit space in the ai_flags 382 field. 384 There is no corresponding destination address selection rule for 385 source address selection rule #7, in default address selection 386 document. However, this API provides a way for an application to 387 make sure that the source address preference set in setsockopt() is 388 taken into account by the getaddrinfo() function. Let's consider an 389 example to understand this scenario. DA and DB are two global 390 destination addresses and the node has two global source addresses SA 391 and SB through interface A and B respectively. SA is a temporary 392 address while SB is a public address. The application has set 393 IPV6_PREFER_SRC_TMP in the setsockopt() flag. The route to DA points 394 to interface A and route to DB points to interface B. Thus when 395 AI_PREFERENCES in ai_flags and IPV6_PREFER_SRC_TMP in ai_eflags are 396 set, getaddrinfo() returns DA before DB in the list of destination 397 addresses and thus SA will be used to communicate with the 398 destination DA. Similarly, getaddrinfo() returns DB before DA when 399 AI_PREFERENCES and ai_eflags are set to IPV6_PREFER_SRC_PUBLIC. Thus 400 the source address preference is taking effect into destination 401 address selection and as well as source address selection by the 402 getaddrinfo() function. 404 struct addrinfo { 405 int ai_flags; /* input flags */ 406 int ai_family; /* protocol family for socket */ 407 int ai_socktype; /* socket type */ 408 int ai_protocol; /* protocol for socket */ 409 socklen_t ai_addrlen; /* length of socket address */ 410 char *ai_canonname; /* canonical name for hostname */ 411 struct sockaddr *ai_addr; /* socket address for socket */ 412 struct addrinfo *ai_next; /* pointer to next in list */ 413 int ai_eflags; /* Extended flags for special usage */ 414 }; 416 Example of usage: 418 struct addrinfo hints, *ai; 419 uint32_t preferences; 421 preferences = IPV6_PREFER_SRC_TMP; 423 hints.ai_flags |= AI_PREFERENCES; 424 hints.ai_eflags = preferences; /* Chosen address preference flag */ 425 /* Fill in other hints fields */ 427 getaddrinfo(....,&hints,. &ai..); 429 /* Loop over all returned addresses and do connect */ 430 while (ai != NULL) { 431 s = socket(ai->ai_family, ...); 432 setsockopt(s, IPV6_ADDR_PREFERENCES, (void *) &preferences, 433 sizeof (preferences)); 434 if (connect(s, ai->ai_addr, ai->ai_addrlen) == -1){ 435 close (s); 436 ai = ai->ai_next; 437 continue; 438 } 439 break; 440 } 442 freeaddrinfo(ai); 444 The following numerical example clarifies the above further. 446 Imagine a host with two addresses: 448 1234::1:1 public 450 9876::1:2 temporary 452 The destination has the following two addresses: 454 1234::9:3 456 9876::9:4 458 By default getaddrinfo() will return the destination addresses in the 459 order 461 1234::9:3 463 9876::9:4 465 because the public source is preferred and 1234 matches more bits 466 with the public source address. On the other hand, if ai_flags is 467 set to AI_PREFERENCES and ai_eflags to IPV6_PREFER_SRC_TMP, 468 getaddrinfo will return the addresses in the reverse order since the 469 temporary source address will be preferred. 471 The following new flag is added for the ai_flags in addrinfo data 472 structure defined in Basic IPV6 Socket API Extension [RFC3493]. 474 AI_PREFERENCES /* address preference flag */ 476 If AI_PREFERENCE flag is set in ai_flags, then the getaddrinfo() 477 implementation MUST look for ai_eflags values. AI_PREFERENCE flag is 478 only meaningful if the extended flag sets (ai_eflags) are properly 479 set. This document defines IPV6 source address preference values 480 (IPV6_PREFER_SRC_*), so that getaddrinfo() can return matching 481 destination addresses corresponding to the source address 482 preferences. By default, AI_PREFERENCES are not set. If 483 AI_PREFERENCES are set in ai_flags and ai_eflags are 0 or undefined, 484 then AI_PREFERENCES is ignored. 486 Currently AI_PREFERENCES is defined for AF_INET6 sockets only. But 487 its usage should be extendable to other socket families as 488 appropriate. 490 If contradictory flags such as IPV6_PREFER_SRC_HOME and 491 IPV6_PREFER_SRC_COA are set in ai_eflags, the getaddrinfo() fails 492 with an error EAI_BADFLAGS [RFC3493]. 494 Valid combination of address selection flags are defined below: 496 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_PUBLIC 498 IPV6_PREFER_SRC_COA | IPV6_PREFER_SRC_PUBLIC 500 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_CGA 502 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_NONCGA 504 IPV6_PREFER_SRC_COA | IPV6_PREFER_SRC_CGA 506 IPV6_PREFER_SRC_COA | IPV6_PREFER_SRC_NONCGA 508 7. Application Requirements 510 An application should call getsockopt() prior calling setsockopt() if 511 the application needs to be able to restore the socket back to the 512 system default preferences. Note, this is suggested for portability. 513 An application which does not have this requirement can just use 514 getaddrinfo() while specifying its preferences, followed by: 516 uint32_t flags = IPV6_PREFER_SRC_TMP; 518 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 519 (void *) &flags, sizeof (flags)) == -1) { 520 perror("setsockopt IPV6_ADDR_REFERENCES"); 521 } 523 An application which needs to be able to restore the default settings 524 on the socket would instead do this: 526 uint32_t save_flags, flags; 527 int optlen = sizeof (save_flags); 529 /* Save the existing IPv6_ADDR_PREFERENCE flags now */ 531 if (getsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 532 (void *) &save_flags, &optlen) == -1 { 533 perror("getsockopt IPV6_ADDR_REFERENCES"); 534 } 536 /* Set the new flags */ 537 flags = IPV6_PREFER_SRC_TMP; 538 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 539 (void *) &flags, sizeof (flags)) == -1) { 540 perror("setsockopt IPV6_ADDR_REFERENCES"); 541 } 543 /* 544 * 545 * Do some work with the socket here. 546 * 547 */ 549 /* Restore the flags */ 551 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 552 (void *) &save_flags, sizeof (save_flags)) == -1) { 553 perror("setsockopt IPV6_ADDR_REFERENCES"); 554 } 556 Applications MUST not set contradictory flags at the same time. 558 Example of contradictory flags: 560 IPV6_PREFER_SRC_TMP | IPV6_PREFER_SRC_PUBLIC. 562 In order to allow different implementations to do different parts of 563 address selection in getaddrinfo() and in the protocol stack, this 564 specification requires that applications set the semantically 565 equivalent flags when calling getaddrinfo() and when calling 566 setsockopt(). For example, if the application sets the 567 IPV6_PREFER_SRC_COA flag, it MUST use the same for ai_eflag when 568 calling getaddrinfo(). If applications are not setting the 569 semantically equivalent flags the behavior of the implementation is 570 undefined. 572 8. Implementation Notes 574 o Within the same application, if a specific source address is set 575 by either bind() or IPV6_PKTINFO socket option, while at the same 576 time an address selection preference is expressed with the 577 IPV6_ADDR_PREFERENCES socket option, then the source address 578 setting carried by bind() or IPV6_PKTINFO takes precedence over 579 the address selection setting. 581 o setsockopt() and getaddrinfo() should silently ignore any address 582 preference flags that are not supported in the system. For 583 example, a host which does not implement Mobile IPv6, should not 584 fail setsockopt() or getaddrinfo() that specify preferences for 585 home or care-of addresses. The socket option calls should return 586 error (-1) and set errno to EINVAL when contradictory flags values 587 are passed to them. 589 o If an implementation supports both stream and datagram sockets, it 590 should implement the address preference mechanism API described in 591 this document on both types of sockets. 593 o An implementation supporting this API MUST implement both 594 getaddrinfo() extension flags and socket option flags processing 595 for portability of applications. 597 o The following flags are set as default values on a system (which 598 is consistent with [RFC3484] defaults): 600 IPV6_PREFER_SRC_HOME 602 IPV6_PREFER_SRC_PUBLIC 604 IPV6_PREFER_SRC_CGA 606 9. Mapping to Default Address Selection Rules 608 This API defines only those flags that are deemed to be useful by the 609 applications to alter default address selection rules. Thus we 610 discuss the mapping of each set of flags to the corresponding rule 611 number in the address selection document [RFC3484]. 613 Source address selection rule #4 (prefer home address): 615 IPV6_PREFER_SRC_HOME (default) 617 IPV6_PREFER_SRC_COA 619 Source address selection rule #7 (prefer public address) : 621 IPV6_PREFER_SRC_PUBLIC (default) 623 IPV6_PREFER_SRC_TMP 625 At this time, this document does not define flags to alter source 626 address selection rule #2 (prefer appropriate scope for destination) 627 and destination address selection rule #8 (prefer smaller scope) as 628 the implementers felt that there were no practical applications that 629 can take advantage of reverting the scoping rules of IPv6 default 630 address selection. Flags altering other destination address 631 selection rules (#4, prefer home address and #7, prefer native 632 transport) could have applications, but the problem is that the local 633 system cannot systematically determine whether a destination address 634 is a tunnel address for destination rule #7 (although it can when the 635 destination address is one of its own, or can be syntactically 636 recognized as a tunnel address, e.g., a 6to4 address.) The flags 637 defined for source address selection rule #4 (prefer home address) 638 should also take care of destination address selection rule #4. Thus 639 at this point, it was decided not to define flags for these 640 destination rules. 642 Other source address rules (that are not mentioned here) were also 643 deemed not applicable for changing its default on a per-application 644 basis. 646 10. IPv4-mapped IPv6 Addresses 648 IPv4-mapped IPv6 addresses for AF_INET6 sockets are supported in this 649 API. In some cases the application of IPv4-mapped addresses are 650 limited because the API attributes are IPv6 specific. For example, 651 IPv6 temporary addresses and cryptographically generated addresses 652 have no IPv4 counterparts. Thus the IPV6_PREFER_SRC_TMP or 653 IPV6_PREFER_SRC_CGA are not directly applicable to an IPv4-mapped 654 IPv6 address. However, the IPv4-mapped address support may be useful 655 for mobile-IPv4 applications shifting source address between the home 656 address and the care-of address. Thus the IPV6_PREFER_SRC_COA and 657 IPV6_PREFER_SRC_HOME are applicable to an IPv4-mapped IPv6 address. 658 At this point it is not understood whether this API has any value to 659 IPv4 addresses or AF_INET family of sockets. 661 11. Validation function for source address 663 Sometimes an application may have a requirement to only use addresses 664 with some particular attribute, and if no such address is available 665 the application should fail to communicate instead of communicating 666 using the 'wrong' address. In that situation, address selection 667 preferences do not guarantee that the application requirements are 668 met. Instead, the application has to explicitly verify that the 669 chosen address satisfies its requirements using a validation 670 function. Such an application would go through the following steps: 672 1. The application specifies one or more IPV6_PREFER_SRC_* flags and 673 AI_PREFERENCE ai_flags with getaddrinfo(). 675 2. The application specifies the same IPV6_PREFER_SRC_* flags with 676 setsockopt() 678 3. The application calls connect(). This applies even for datagram 679 (UDP) sockets, as the connect call results in the stack selecting 680 a source address, for TCP as well as UDP. 682 4. Retrieve the selected source address using the getsockname() API 683 call. 685 5. Verify with the validation function that the retrieved address is 686 satisfactory as specified below. If not, abort the communication 687 e.g., by closing the socket. 689 The verification of temporary vs. public, home vs. care-of, CGA vs. 690 not, are performed by a new validation function defined for this 691 purpose: 693 #include 695 short inet6_is_srcaddr(struct sockaddr_in6 *srcaddr, 696 uint32_t flags); 698 Where the flags contains the specified IPV6_PREFER_SRC_* source 699 preference flags, and the srcaddr is a non-NULL pointer to a 700 sockaddr_in6 structure initialized as follows: 702 o sin6_addr is a 128-bit IPv6 address of the local node. 704 o sin6_family MUST be set to AF_INET6. 706 o sin6_scope_id MUST be set if the address is link-local. 708 inet6_is_srcaddr() is defined to return three possible values (0, 1, 709 -1): The function returns true (1) when the IPv6 address corresponds 710 to a valid address in the node and satisfies the given preference 711 flags. If the IPv6 address input value does not correspond to any 712 address in the node or if the flags are not one of the valid 713 preference flags, it returns a failure (-1). If the input address 714 does not match an address which satisfies the preference flags 715 indicated, the function returns false (0.) 717 This function can handle multiple valid preference flags combination 718 as its second parameter, for example IPV6_PREFER_SRC_COA | 719 IPV6_PREFER_SRC_TMP, which means that all flags MUST be satisfied for 720 the result to be true. Contradictory flag values result in a false 721 return value. 723 The function will return true for IPV6_PREFER_SRC_HOME even if the 724 host is not implementing mobile IPv6, as well as for a mobile node 725 which is at home (i.e., does not have any care-of address). 727 12. IANA Considerations 729 This document has no IANA considerations. 731 13. Security Considerations 733 This document conforms to the same security implications as specified 734 in the Basic IPv6 socket API [RFC3493]. Allowing applications to 735 specify a preference for temporary addresses provides per-application 736 (and per-socket) ability to use the privacy benefits of the temporary 737 addresses. The setting of certain address preferences (e.g. not 738 using a CGA address, or not using a temporary address) may be 739 restricted to privileged processes because of security implications. 741 14. Acknowledgments 743 The authors like to thank members of mobile-ip and ipv6 working 744 groups for useful discussion on this topic. Richard Draves and Dave 745 Thaler suggested that getaddrinfo also needs to be considered along 746 with the new socket option. Gabriel Montenegro suggested that CGAs 747 may also be considered in this document. Thanks to Alain Durand, 748 Renee Danson, Alper Yegin, Francis Dupont, Keiichi Shima, Michael 749 Hunter, Sebastien Roy, Robert Elz, Pekka Savola, Itojun, Jim Bound, 750 Steve Cipoli, Jeff Boote, Steve Cipolli, Vlad Yasevich and Mika 751 Liljeberg for useful discussions and suggestions. Thanks to Brian 752 Haberman, Brian Haley, Bob Gilligan, Jack McCann, Jim Bound and 753 Jinmei Tatuya for the review of the document and the suggestions for 754 improvement. 756 15. References 758 15.1. Normative references 760 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 761 Requirement Levels", BCP 14, RFC 2119, March 1997. 763 [RFC3484] Draves, R., "Default Address Selection for Internet 764 Protocol version 6 (IPv6)", RFC 3484, February 2003. 766 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 767 Stevens, "Basic Socket Interface Extensions for IPv6", 768 RFC 3493, February 2003. 770 15.2. Informative references 772 [FPING] "Fping - a program to ping hosts in parallel", Online web 773 site http://www.fping.com. 775 [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 776 (IPv6) Specification", RFC 2460, December 1998. 778 [RFC3041] Narten, T. and R. Draves, "Privacy Extensions for 779 Stateless Address Autoconfiguration in IPv6", RFC 3041, 780 January 2001. 782 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 783 "Advanced Sockets Application Program Interface (API) for 784 IPv6", RFC 3542, May 2003. 786 [RFC3775] Johnson, D., Perkins, C., and J. Arkko, "Mobility Support 787 in IPv6", RFC 3775, June 2004. 789 [RFC3971] Arkko, J., Kempf, J., Zill, B., and P. Nikander, "SEcure 790 Neighbor Discovery (SEND)", RFC 3971, March 2005. 792 [RFC3972] Aura, T., "Cryptographically Generated Addresses (CGA)", 793 RFC 3972, March 2005. 795 Appendix A. Per Packet Address Selection Preference 797 This document discusses setting source address selection preferences 798 on a per socket basis with the new IPV6_ADDR_PREFERENCES socket 799 option used in setsockopt(). The document does not encourage setting 800 the source address selection preference on a per packet basis through 801 the use of ancillary data objects with sendmsg(), or setsockopt() 802 with unconnected datagram sockets. 804 Per-packet source address selection is expensive as the system will 805 have to determine the source address indicated by the application 806 preference before sending each packet, while setsockopt() address 807 preference on a connected socket makes the selection once and uses 808 that source address for all packets transmitted through that socket 809 end-point, as long as the socket option is set. 811 However, this document provides guidelines for those implementations 812 which like to have an option on implementing transmit-side ancillary 813 data object support for altering default source address selection. 814 Therefore, if an application chooses to use the per-packet source 815 address selection, then the implementation should process at the 816 IPPROTO_IPV6 level (cmsg_level) ancillary data object of type 817 (cmsg_type) IPV6_ADDR_PREFERENCES containing as data (cmsg_data[]) a 818 32-bits unsigned integer encoding the source address selection 819 preference flags (e.g. IPV6_PREFER_SRC_COA | 820 IPV6_PREFER_SRC_PUBLIC), in a fashion similar to the advanced IPV6 821 Socket API [RFC3542]. This address selection preference ancillary 822 data object may be present along with other ancillary data objects. 824 The implementation processing the ancillary data object is 825 responsible for selection of preferred source address as indicated in 826 the ancillary data object. Thus, an application can use sendmsg() to 827 pass an address selection preference ancillary data object to the 828 IPv6 layer. The following example shows usage of the ancillary data 829 API for setting address preferences: 831 void *extptr; 832 socklen_t extlen; 833 struct msghdr msg; 834 struct cmsghdr *cmsgptr; 835 int cmsglen; 836 struct sockaddr_in6 dest; 837 uint32_t flags; 839 extlen = sizeof(flags); 840 cmsglen = CMSG_SPACE(extlen); 841 cmsgptr = malloc(cmsglen); 842 cmsgptr->cmsg_len = CMSG_LEN(extlen); 843 cmsgptr->cmsg_level = IPPROTO_IPV6; 844 cmsgptr->cmsg_type = IPV6_ADDR_PREFERENCES; 846 extptr = CMSG_DATA(cmsgptr); 848 flags = IPV6_PREFER_SRC_COA; 849 memcpy(extptr, &flags, extlen); 851 msg.msg_control = cmsgptr; 852 msg.msg_controllen = cmsglen; 854 /* finish filling in msg{} */ 856 msg.msg_name = dest; 858 sendmsg(s, &msg, 0); 860 Thus when an IPV6_ADDR_PREFERENCES ancillary data object is passed to 861 sendmsg(), the value included in the object is used to specify 862 address preference for the packet being sent by sendmsg(). 864 Appendix B. Changes from previous version of draft 866 o Added an appendix discussing setting source address selection 867 preferences on a per packet basis, including via passing a 868 transmit-side ancillary data object. 870 o Changed getaddrinfo()usage and removed the AI_PREFER flags. Added 871 one extended flag field in addrinfo structure and added one 872 AI_flag in order to save bits. 874 o Removed scope address preferences as some questioned about 875 applicability of IPV6_PREFER_SRC and DST scope rules alterations. 877 o Added -1 return value for inet6_is_srcaddr() for failure 878 situation. 880 o Addressed comments by the working group and reviewers of this 881 draft. 883 o Added a definition of term for X and not-X flags. 885 o Changed "not-X flag" by "opposite flag", and "X and not-X flags" 886 by by "contradictory flags" 888 o updated rationale why not to deal with native transport 889 destination address selection rule. 891 Appendix C. Intellectual Property Statement 893 This document only defines a source preference flag to choose 894 Cryptographically Generated Address (CGA) as source address when 895 applicable. CGA are obtained using public keys and hashes to prove 896 address ownership. Several IPR claims have been made about such 897 methods. 899 Authors' Addresses 901 Erik Nordmark 902 Sun Microsystems, Inc. 903 4150 Network Circle, UMPK17-308 904 Santa Clara, CA 95054 905 USA 907 Email: Erik.Nordmark@Sun.COM 909 Samita Chakrabarti 910 Azaire Networks 911 4800 Great America Parkway 912 Santa Clara, CA 95054 913 USA 915 Email: samitac2@gmail.com 917 Julien Laganier 918 DoCoMo Euro-Labs 919 Landsbergerstrasse 312 920 D-80687 Muenchen 921 Germany 923 Email: julien.IETF@laposte.net 925 Intellectual Property Statement 927 The IETF takes no position regarding the validity or scope of any 928 Intellectual Property Rights or other rights that might be claimed to 929 pertain to the implementation or use of the technology described in 930 this document or the extent to which any license under such rights 931 might or might not be available; nor does it represent that it has 932 made any independent effort to identify any such rights. Information 933 on the procedures with respect to rights in RFC documents can be 934 found in BCP 78 and BCP 79. 936 Copies of IPR disclosures made to the IETF Secretariat and any 937 assurances of licenses to be made available, or the result of an 938 attempt made to obtain a general license or permission for the use of 939 such proprietary rights by implementers or users of this 940 specification can be obtained from the IETF on-line IPR repository at 941 http://www.ietf.org/ipr. 943 The IETF invites any interested party to bring to its attention any 944 copyrights, patents or patent applications, or other proprietary 945 rights that may cover technology that may be required to implement 946 this standard. Please address the information to the IETF at 947 ietf-ipr@ietf.org. 949 Disclaimer of Validity 951 This document and the information contained herein are provided on an 952 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 953 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET 954 ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, 955 INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE 956 INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 957 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 959 Copyright Statement 961 Copyright (C) The Internet Society (2006). This document is subject 962 to the rights, licenses and restrictions contained in BCP 78, and 963 except as set forth therein, the authors retain all their rights. 965 Acknowledgment 967 Funding for the RFC Editor function is currently provided by the 968 Internet Society.