idnits 2.17.1 draft-chakrabarti-ipv6-addrselect-api-05.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, updated by RFC 4748 on line 1015. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1026. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1033. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1039. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. 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 IETF Trust 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 (March 5, 2007) is 6262 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: Informational ---------------------------------------------------------------------------- ** Obsolete normative reference: RFC 3484 (Obsoleted by RFC 6724) -- 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: 3 errors (**), 0 flaws (~~), 2 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: September 6, 2007 S. Chakrabarti 5 Azaire Networks 6 J. Laganier 7 DoCoMo Euro-Labs 8 March 5, 2007 10 IPv6 Socket API for Address Selection 11 draft-chakrabarti-ipv6-addrselect-api-05 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 September 6, 2007. 38 Copyright Notice 40 Copyright (C) The IETF Trust (2007). 42 Intended Status 44 Intended status: Informational 46 Abstract 48 The IPv6 default address selection document [RFC3484] describes the 49 rules for selecting source and destination IPv6 addresses, and 50 indicates that applications should be able to reverse the sense of 51 some of the address selection rules through some unspecified API. 52 However, no such socket API exists in the basic [RFC3493] or advanced 53 [RFC3542] IPv6 socket API documents. This document fills that gap by 54 specifying new socket level options and flags for the getaddrinfo() 55 API to specify preferences for address selection that modify the 56 default address selection algorithm. The socket API described in 57 this document will be particularly useful for IPv6 applications that 58 want to choose between temporary and public addresses, and for Mobile 59 IPv6 aware applications that want to use the care-of address for 60 communication. 62 Table of Contents 64 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 65 2. Definition Of Terms . . . . . . . . . . . . . . . . . . . . . 7 66 3. Usage Scenario . . . . . . . . . . . . . . . . . . . . . . . . 8 67 4. Design Alternatives . . . . . . . . . . . . . . . . . . . . . 9 68 5. Address Preference Flags . . . . . . . . . . . . . . . . . . . 10 69 6. Additions to the Socket Interface . . . . . . . . . . . . . . 12 70 7. Additions to the protocol-independent nodename translation . . 13 71 8. Application Requirements . . . . . . . . . . . . . . . . . . . 15 72 9. Usage Example . . . . . . . . . . . . . . . . . . . . . . . . 17 73 10. Implementation Notes . . . . . . . . . . . . . . . . . . . . . 18 74 11. Mapping to Default Address Selection Rules . . . . . . . . . . 19 75 12. IPv4-mapped IPv6 Addresses . . . . . . . . . . . . . . . . . . 21 76 13. Validation function for source address . . . . . . . . . . . . 22 77 14. Summary of New Definitions . . . . . . . . . . . . . . . . . . 24 78 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 25 79 16. Security Considerations . . . . . . . . . . . . . . . . . . . 26 80 17. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 27 81 18. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 82 18.1. Normative references . . . . . . . . . . . . . . . . . . 28 83 18.2. Informative references . . . . . . . . . . . . . . . . . 28 84 Appendix A. Per Packet Address Selection Preference . . . . . . . 29 85 Appendix B. Changes from previous version of draft . . . . . . . 31 86 Appendix C. Intellectual Property Statement . . . . . . . . . . . 32 87 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 33 88 Intellectual Property and Copyright Statements . . . . . . . . . . 34 90 1. Introduction 92 [RFC3484] specifies the default address selection rules for IPv6 93 [RFC2460]. This document defines socket API extensions that allow 94 applications to override the default choice of address selection. 95 Privacy considerations [RFC3041] have introduced "public" and 96 "temporary" addresses. IPv6 Mobility [RFC3775] introduces "home 97 address" and "care-of address" definitions in the mobile systems. 99 The default address selection rules in [RFC3484] in summary are that 100 a public address is preferred over a temporary address, that a mobile 101 IPv6 home address is preferred over a care-of address, and that a 102 larger scope address is preferred over a smaller scope address. 103 Although it is desirable to have default rules for address selection, 104 an application may want to reverse certain address selection rules 105 for efficiency and other application-specific reasons. 107 Currently IPv6 socket API extensions provide mechanisms to choose a 108 specific source address through simple bind() operation or 109 IPV6_PKTINFO socket option [RFC3542]. However, in order to use 110 bind() or IPV6_PKTINFO socket option, the application itself must 111 make sure that the source address is appropriate for the destination 112 address (e.g., with respect to the interface used to send packets to 113 the destination). The application also needs to verify the 114 appropriateness of the source address scope with respect to the 115 destination address and so on. This can be quite complex for the 116 application, since in effect it needs to implement all the default 117 address selection rules in order to change its preferences with 118 respect to one of the rules. 120 The mechanism presented in this document allows the application to 121 specify attributes of the source (and destination) addresses it 122 prefers while still having the system perform the rest of the address 123 selection rules. For instance, if an application specifies that it 124 prefers to use a care-of address over a home address as the source 125 address and if the host has two care-of addresses, one public and one 126 temporary, then the host would select the public care-of address by 127 following the default address selection rule for preferring a public 128 over a temporary address. 130 A socket option has been deemed useful for this purpose, as it 131 enables an application to specify address selection preferences on a 132 per-socket basis. It can also provide the flexibility of enabling 133 and disabling address selection preferences in non-connected (UDP) 134 sockets. The socket option uses a set of flags for specifying 135 address selection preferences. Since the API should not assume a 136 particular implementation method of the address selection [RFC3484] 137 in the network layer or in getaddrinfo(), the corresponding set of 138 flags are also defined for getaddrinfo(). 140 As a result, this document introduces several flags for address 141 selection preferences that alter the default address selection 142 [RFC3484] for a number of rules. It analyzes the usefulness of 143 providing API functionality for different default address selection 144 rules; it provides API to alter only those rules that are possibly 145 used by certain classes of applications. In addition, it also 146 considers CGA [RFC3972] and non-CGA source addresses when CGA 147 addresses are available in the system. In the future, more 148 destination or source flags may be added to expand the API as the 149 needs may arise. 151 The approach in this document is to allow the application to specify 152 preferences for address selection and not to be able to specify hard 153 requirements: For instance, an application can set a flag to prefer a 154 temporary source address, but if no temporary source addresses are 155 available at the node, a public address would be chosen instead. 157 Specifying hard requirements for address selection would be 158 problematic for several reasons. The major one is that in the vast 159 majority of cases the application would like to be able to 160 communicate even if an address with the 'optimal' attributes is not 161 available. For instance, an application that performs very short, 162 e.g., UDP, transactional exchanges (e.g. DNS queries), might prefer 163 to use a care-of address when running on a mobile host which is away 164 from home since this provides a short round-trip time in many cases. 165 But if the application is running on a mobile host that is at home, 166 or running on a host which isn't providing Mobile IPv6, then it 167 doesn't make sense for the application to fail due to no care-of 168 address being available. Also, in particular when using UDP sockets 169 and the sendto() or sendmsg() primitives, the use of hard 170 requirements would have been problematic, since the set of available 171 IP addresses might very well have changed from when the application 172 called getaddrinfo() until it called sendto() or sendmsg(), which 173 would introduce new failure modes. 175 For the few applications that have hard requirements on the 176 attributes of the IP addresses they use, this document defines a 177 verification function which allows such applications to properly fail 178 to communicate when their address selection requirements are not met. 180 Furthermore, the approach is to define two flags for each rule that 181 can be modified, so that an application can specify its preference 182 for addresses selected as per the rule, the opposite preference (i.e. 183 an address selected as per the rule reverted), or choose not to set 184 either of the flags relating to that rule and leave it up to the 185 system default (see section 3.1). This approach allows different 186 implementations to have different system defaults, and works with 187 getaddrinfo() as well as setsockopt(). (For setsockopt a different 188 approach could have been chosen, but that would still require this 189 approach for getaddrinfo.) 191 This document specifies extensions only to the Basic IPv6 socket API 192 specified in [RFC3493]. The intent is that this document serves as a 193 model for expressing preferences for attributes of IP addresses, that 194 also need to be expressible in other networking API such as those 195 found in middleware systems and the Java environment. 197 2. Definition Of Terms 199 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 200 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 201 document are to be interpreted as described in [RFC2119]. 203 Address preference flag: 204 A flag expressing a preference for a particular type of address 205 (e.g. temporary, public). 207 Opposite flags: 208 Each flag expressing an address preference has a so called 209 "opposite flag" expressing the opposite preference: 211 * home address preference flag is the opposite of the care-of 212 address preference flag. 214 * temporary address preference flag is the opposite of the public 215 address preference flag. 217 * CGA address preference flag is the opposite of the non-CGA 218 address preference flag. 220 Contradictory flags: 221 Any combination of flags including both a flag expressing a given 222 address preference and a flag expressing the opposite preference 223 constitutes Such flags are contradictory by definition of their 224 usefulness with respect to source address selection. For example, 225 consider a set of flags including both the home address preference 226 flag and the care-of address preference flag. When considering 227 source address selection, the selected address can be a home 228 address, or a care-of address, but it cannot be both at the same 229 time. Hence, to prefer an address which is both a home address, 230 and a care-of address, is contradictory. 232 3. Usage Scenario 234 The examples discussed here are limited to applications supporting 235 Mobile IPv6, IPv6 Privacy Extensions and Cryptographically Generated 236 Addresses. Address selection document [RFC3484] recommends that home 237 addresses should be preferred over care-of address when both are 238 configured. However, a mobile node may want to prefer care-of 239 address as source address for DNS query in the foreign network as it 240 normally means a shorter and local return path compared to the route 241 via the mobile node's home-agent when the query contains home address 242 as source address. Another example is IKE application which requires 243 care-of address as its source address for the initial security 244 association pair with Home Agent [RFC3775] while the mobile node 245 boots up at the foreign network and wants to do the key exchange 246 before a successful home-registration. Also a Mobile IPv6 aware 247 application may want to toggle between home address and care-of 248 address depending on its location and state of the application. It 249 may also want to open different sockets and use home address as 250 source address for one socket and care-of address for the others. 252 In a non-mobile environment, an application may similarly prefer to 253 use temporary address as source address for certain cases. By 254 default, the source address selection rule selects "public" address 255 when both are available. For example, an application supporting web 256 browser and mail-server may want to use "temporary" address for the 257 former and "public" address for the mail-server as a mail-server may 258 require reverse path for DNS records for anti-spam rules. 260 Similarly, a node may be configured to use Cryptographically 261 Generated Addresses [RFC3972] by default, as in Secure Neighbor 262 Discovery [RFC3971], but an application may prefer not to use it. 263 For instance, fping [FPING], a debugging tool which tests basic 264 reachability of multiple destinations by sending packets in parallel, 265 may find that the cost and time incurred in proof-of-ownership by CGA 266 verification is not justified. On the other hand, when a node is not 267 configured for CGA as default, an application may prefer using CGA by 268 setting the corresponding preference. 270 4. Design Alternatives 272 Some suggested to have per-application flags instead of per-socket 273 and per-packet flags. However, this design stays with per-socket and 274 per-packet flags for the following reasons: 276 o While some systems have per environment/application flags (such as 277 environment variables in Unix systems) this might not be available 278 in all systems which implement the socket API. 280 o When an application links with some standard library, that library 281 might use the socket API, while the application is unaware of that 282 fact. Mechanisms that would provide per application flags may 283 affect not only the application itself but also the libraries, 284 hence creating risks of unintended consequences. 286 Instead of the pair of 'flag' and 'opposite flag' for each rule that 287 can be modified, the socket option could have been defined to use a 288 single 'flag' value for each rule. This would still have allowed 289 different implementations to have different default settings as long 290 as the applications were coded to first retrieve the default setting 291 (using getsockopt()), and then clear or set the 'flag' according to 292 their preferences, and finally set the new value with setsockopt(). 294 But such an approach would not be possible for getaddrinfo() because 295 all the preferences would need to be expressible in the parameters 296 that are passed with a single getaddrinfo() call. Hence, for 297 consistency, the 'flag' and 'opposite flag' approach is used for both 298 getaddrinfo() and setsockopt(). 300 5. Address Preference Flags 302 The following flags are defined to alter or set the default rule of 303 source and destination address selection rules discussed in default 304 address selection specification [RFC3484]. 306 IPV6_PREFER_SRC_HOME /* Prefer Home address as source */ 308 IPV6_PREFER_SRC_COA /* Prefer Care-of address as source */ 310 IPV6_PREFER_SRC_TMP /* Prefer Temporary address as source */ 312 IPV6_PREFER_SRC_PUBLIC /* Prefer Public address as source */ 314 IPV6_PREFER_SRC_CGA /* Prefer CGA address as source */ 316 IPV6_PREFER_SRC_NONCGA /* Prefer a non-CGA address as source */ 318 These flags can be combined together in a flag-set to express more 319 complex address preferences. However such combinations can result in 320 a contradictory flag-set, for example: 322 IPV6_PREFER_SRC_PUBLIC | IPV6_PREFER_SRC_TMP 324 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_COA 326 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_COA | IPV6_PREFER_SRC_TMP 328 IPV6_PREFER_SRC_CGA | IPV6_PREFER_SRC_NONCGA 330 Etc. 332 Example of valid combination of address selection flags are given 333 below: 335 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_PUBLIC 337 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_CGA 339 IPV6_PREFER_SRC_COA | IPV6_PREFER_SRC_PUBLIC | IPV6_PREFER_SRC_CGA 341 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_NONCGA 343 If a flag-set includes a combination of 'X' and 'Y', and if 'Y' is 344 not applicable or available in the system, then the selected address 345 has attribute 'X' and system default for the attribute 'Y'. For 346 example, on a system that has only public addresses, the valid 347 combination of flags: 349 IPV6_PREFER_SRC_TMP | IPV6_PREFER_SRC_HOME 351 would result in the selected address being a public home address, 352 since no temporary addresses are available. 354 6. Additions to the Socket Interface 356 The IPv6 Basic Socket API [RFC3493] defines socket options for IPv6. 357 To allow applications to influence address selection mechanisms this 358 document adds a new socket option at the IPPROTO_IPV6 level. This 359 socket option is called IPV6_ADDR_PREFERENCES. It can be used with 360 setsockopt() and getsockopt() calls to set and get the address 361 selection preferences affecting all packets sent via a given socket. 362 The socket option value (optval) is a 32-bits unsigned integer 363 argument. The argument consists of a number of flags where each flag 364 indicates an address selection preference which modifies one of the 365 rules in the default address selection specification. 367 The following flags are defined to alter or set the default rule of 368 source and destination address selection rules discussed in default 369 address selection specification [RFC3484]. They are defined as a 370 result of including the header: 372 IPV6_PREFER_SRC_HOME /* Prefer Home address as source */ 374 IPV6_PREFER_SRC_COA /* Prefer Care-of address as source */ 376 IPV6_PREFER_SRC_TMP /* Prefer Temporary address as source */ 378 IPV6_PREFER_SRC_PUBLIC /* Prefer Public address as source */ 380 IPV6_PREFER_SRC_CGA /* Prefer CGA address as source */ 382 IPV6_PREFER_SRC_NONCGA /* Prefer a non-CGA address as source */ 384 NOTE: No source preference flag for longest matching prefix is 385 defined here because it is believed to be handled by the policy table 386 defined in the default address selection specification. 388 When the IPV6_ADDR_PREFERENCES is successfully set with setsockopt(), 389 the option value given is used to specify address preference for any 390 connection initiation through the socket and all subsequent packets 391 sent via that socket. If no option is set, the system selects a 392 default value as per default address selection algorithm or by some 393 other equivalent means. 395 Setting contradictory flags at the same time results in the error 396 EINVAL. 398 7. Additions to the protocol-independent nodename translation 400 Section 8 of Default Address Selection [RFC3484] document indicates 401 possible implementation strategies for getaddrinfo() [RFC3493]. One 402 of them suggests that getaddrinfo() collects available source/ 403 destination pair from the network layer after being sorted at the 404 network layer with full knowledge of source address selection. 405 Another strategy is to call down to the network layer to retrieve 406 source address information and then sort the list in the context of 407 getaddrinfo(). 409 This implies that getaddrinfo() should be aware of the address 410 selection preferences of the application, since getaddrinfo() is 411 independent of any socket the application might be using. 413 Thus if an application alters the default address selection rules by 414 using setsockopt() with the IPV6_ADDR_PREFERENCES option, the 415 application should also use the corresponding address selection 416 preference flags with its getaddrinfo() call. 418 For that purpose, the addrinfo data structure defined in Basic IPV6 419 Socket API Extension [RFC3493] has been extended with an extended 420 "ai_eflags" flag-set field to provides the designers freedom of 421 adding more flags as necessary without crowding the valuable bit 422 space in the "ai_flags" flag-set field. The extended addrinfo data 423 structre is defined as a result of including the header: 425 struct addrinfo { 426 int ai_flags; /* input flags */ 427 int ai_family; /* protocol family for socket */ 428 int ai_socktype; /* socket type */ 429 int ai_protocol; /* protocol for socket */ 430 socklen_t ai_addrlen; /* length of socket address */ 431 char *ai_canonname; /* canonical name for hostname */ 432 struct sockaddr *ai_addr; /* socket address for socket */ 433 struct addrinfo *ai_next; /* pointer to next in list */ 434 int ai_eflags; /* Extended flags for special usage */ 435 }; 437 Note that the additional field for extended flags are added at the 438 bottom of the addrinfo structure to preserve binary compatibility of 439 the new functionality with the old applications which use the 440 existing addrinfo data structure. 442 A new flag (AI_EXTFLAGS) is defined for the "ai_flags" flag-set field 443 of the addrinfo data structure to tell the system to look for the 444 "ai_eflags" extended flag-set field in the addrinfo structure. It is 445 defined in the header: 447 AI_EXTFLAGS /* extended flag-set present */ 449 If AI_EXTFLAGS flag is set in "ai_flags" flag-set field of the 450 addrinfo data structure, then the getaddrinfo() implementation MUST 451 look for the "ai_eflags" values stored in the extended flag-set field 452 "ai_eflags" of the addrinfo data structure. The flags stored in the 453 extended flags set "ai_eflags" field are only meaningful if the 454 AI_EXTFLAGS flag is set in the "ai_flags" flag-set field of the 455 addrinfo data structure. By default, AI_EXTFLAGS is not set in the 456 "ai_flags" flag-set field. If AI_EXTFLAGS is set in the "ai_flags" 457 flag-set field, and the "ai_eflags" extended flag-set field is 0 458 (zero) or undefined, then AI_EXTFLAGS is ignored. 460 The IPV6 source address preference values (IPV6_PREFER_SRC_*) defined 461 for the IPV6_ADDR_PREFERENCES socket option are also defined as 462 address selection preference flags for the "ai_eflags" extended flag- 463 set field of the addrinfo data structure, so that getaddrinfo() can 464 return matching destination addresses corresponding to the source 465 address preferences expressed by the caller application. 467 Thus, an application passes source address selection hints to 468 getaddrinfo by setting AI_EXTFLAGS in the "ai_flags" field of the 469 addrinfo structure, and the corresponding address selection 470 preference flags (IPV6_PREFER_SRC_*) in the "ai_eflags" field. 472 Currently AI_EXTFLAGS is defined for the AF_INET6 socket protocol 473 family only. But its usage should be extendable to other socket 474 protocol families as appropriate. 476 If contradictory flags such as IPV6_PREFER_SRC_HOME and 477 IPV6_PREFER_SRC_COA are set in ai_eflags, the getaddrinfo() fails and 478 return the value EAI_BADEXTFLAGS defined as a result of including the 479 header. This error value MUST be interpreted into a 480 descriptive text string when passed to the gai_strerror() function 481 [RFC3493]. 483 8. Application Requirements 485 An application should call getsockopt() prior calling setsockopt() if 486 the application needs to be able to restore the socket back to the 487 system default preferences. Note, this is suggested for portability. 488 An application which does not have this requirement can just use 489 getaddrinfo() while specifying its preferences, followed by: 491 uint32_t flags = IPV6_PREFER_SRC_TMP; 493 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 494 (void *) &flags, sizeof (flags)) == -1) { 495 perror("setsockopt IPV6_ADDR_REFERENCES"); 496 } 498 An application which needs to be able to restore the default settings 499 on the socket would instead do this: 501 uint32_t save_flags, flags; 502 int optlen = sizeof (save_flags); 504 /* Save the existing IPv6_ADDR_PREFERENCE flags now */ 506 if (getsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 507 (void *) &save_flags, &optlen) == -1 { 508 perror("getsockopt IPV6_ADDR_REFERENCES"); 509 } 511 /* Set the new flags */ 512 flags = IPV6_PREFER_SRC_TMP; 513 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 514 (void *) &flags, sizeof (flags)) == -1) { 515 perror("setsockopt IPV6_ADDR_REFERENCES"); 516 } 518 /* 519 * 520 * Do some work with the socket here. 521 * 522 */ 524 /* Restore the flags */ 526 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 527 (void *) &save_flags, sizeof (save_flags)) == -1) { 528 perror("setsockopt IPV6_ADDR_REFERENCES"); 529 } 531 Applications MUST not set contradictory flags at the same time. 533 In order to allow different implementations to do different parts of 534 address selection in getaddrinfo() and in the protocol stack, this 535 specification requires that applications set the semantically 536 equivalent flags when calling getaddrinfo() and setsockopt(). For 537 example, if the application sets the IPV6_PREFER_SRC_COA flag, it 538 MUST use the same for the "ai_eflag" field of the addrinfo data 539 structure when calling getaddrinfo(). If applications are not 540 setting the semantically equivalent flags the behavior of the 541 implementation is undefined. 543 9. Usage Example 545 An example of usage of this API is given below: 547 struct addrinfo hints, *ai, *ai0; 548 uint32_t preferences; 550 preferences = IPV6_PREFER_SRC_TMP; 552 hints.ai_flags |= AI_EXTFLAGS; 553 hints.ai_eflags = preferences; /* Chosen address preference flag */ 554 /* Fill in other hints fields */ 556 getaddrinfo(....,&hints,. &ai0..); 558 /* Loop over all returned addresses and do connect */ 559 for (ai = ai0; ai; ai = ai->ai_next) { 560 s = socket(ai->ai_family, ...); 562 setsockopt(s, IPV6_ADDR_PREFERENCES, (void *) &preferences, 563 sizeof (preferences)); 565 if (connect(s, ai->ai_addr, ai->ai_addrlen) == -1){ 566 close (s); 567 s = -1; 568 continue; 569 } 571 break; 572 } 574 freeaddrinfo(ai0); 576 10. Implementation Notes 578 o Within the same application, if a specific source address is set 579 by either bind() or IPV6_PKTINFO socket option, while at the same 580 time an address selection preference is expressed with the 581 IPV6_ADDR_PREFERENCES socket option, then the source address 582 setting carried by bind() or IPV6_PKTINFO takes precedence over 583 the address selection setting. 585 o setsockopt() and getaddrinfo() should silently ignore any address 586 preference flags that are not supported in the system. For 587 example, a host which does not implement Mobile IPv6, should not 588 fail setsockopt() or getaddrinfo() that specify preferences for 589 home or care-of addresses. The socket option calls should return 590 error (-1) and set errno to EINVAL when contradictory flags values 591 are passed to them. 593 o If an implementation supports both stream and datagram sockets, it 594 should implement the address preference mechanism API described in 595 this document on both types of sockets. 597 o An implementation supporting this API MUST implement both 598 getaddrinfo() extension flags and socket option flags processing 599 for portability of applications. 601 o The following flags are set as default values on a system (which 602 is consistent with [RFC3484] defaults): 604 IPV6_PREFER_SRC_HOME 606 IPV6_PREFER_SRC_PUBLIC 608 IPV6_PREFER_SRC_CGA 610 11. Mapping to Default Address Selection Rules 612 This API defines only those flags that are deemed to be useful by the 613 applications to alter default address selection rules. Thus we 614 discuss the mapping of each set of flags to the corresponding rule 615 number in the address selection document [RFC3484]. 617 Source address selection rule #4 (prefer home address): 619 IPV6_PREFER_SRC_HOME (default) 621 IPV6_PREFER_SRC_COA 623 Source address selection rule #7 (prefer public address) : 625 IPV6_PREFER_SRC_PUBLIC (default) 627 IPV6_PREFER_SRC_TMP 629 At this time, this document does not define flags to alter source 630 address selection rule #2 (prefer appropriate scope for destination) 631 and destination address selection rule #8 (prefer smaller scope) as 632 the implementers felt that there were no practical applications that 633 can take advantage of reverting the scoping rules of IPv6 default 634 address selection. Flags altering other destination address 635 selection rules (#4, prefer home address and #7, prefer native 636 transport) could have applications, but the problem is that the local 637 system cannot systematically determine whether a destination address 638 is a tunnel address for destination rule #7 (although it can when the 639 destination address is one of its own, or can be syntactically 640 recognized as a tunnel address, e.g., a 6to4 address.) The flags 641 defined for source address selection rule #4 (prefer home address) 642 should also take care of destination address selection rule #4. Thus 643 at this point, it was decided not to define flags for these 644 destination rules. 646 Also, note that there is no corresponding destination address 647 selection rule for source address selection rule #7 (prefer public 648 addresses) of default address selection document [RFC3484]. However, 649 this API provides a way for an application to make sure that the 650 source address preference set in setsockopt() is taken into account 651 by the getaddrinfo() function. Let's consider an example to 652 understand this scenario. DA and DB are two global destination 653 addresses and the node has two global source addresses SA and SB 654 through interface A and B respectively. SA is a temporary address 655 while SB is a public address. The application has set 656 IPV6_PREFER_SRC_TMP in the setsockopt() flag. The route to DA points 657 to interface A and route to DB points to interface B. Thus when 658 AI_EXTFLAGS in ai_flags and IPV6_PREFER_SRC_TMP in ai_eflags are set, 659 getaddrinfo() returns DA before DB in the list of destination 660 addresses and thus SA will be used to communicate with the 661 destination DA. Similarly, getaddrinfo() returns DB before DA when 662 AI_EXTFLAGS and ai_eflags are set to IPV6_PREFER_SRC_PUBLIC. Thus 663 the source address preference is taking effect into destination 664 address selection and as well as source address selection by the 665 getaddrinfo() function. 667 The following numerical example clarifies the above further. 669 Imagine a host with two addresses: 671 1234::1:1 public 673 9876::1:2 temporary 675 The destination has the following two addresses: 677 1234::9:3 679 9876::9:4 681 By default getaddrinfo() will return the destination addresses in the 682 order 684 1234::9:3 686 9876::9:4 688 because the public source is preferred and 1234 matches more bits 689 with the public source address. On the other hand, if ai_flags is 690 set to AI_EXTFLAGS and ai_eflags to IPV6_PREFER_SRC_TMP, getaddrinfo 691 will return the addresses in the reverse order since the temporary 692 source address will be preferred. 694 Other source address rules (that are not mentioned here) were also 695 deemed not applicable for changing its default on a per-application 696 basis. 698 12. IPv4-mapped IPv6 Addresses 700 IPv4-mapped IPv6 addresses for AF_INET6 sockets are supported in this 701 API. In some cases the application of IPv4-mapped addresses are 702 limited because the API attributes are IPv6 specific. For example, 703 IPv6 temporary addresses and cryptographically generated addresses 704 have no IPv4 counterparts. Thus the IPV6_PREFER_SRC_TMP or 705 IPV6_PREFER_SRC_CGA are not directly applicable to an IPv4-mapped 706 IPv6 address. However, the IPv4-mapped address support may be useful 707 for mobile-IPv4 applications shifting source address between the home 708 address and the care-of address. Thus the IPV6_PREFER_SRC_COA and 709 IPV6_PREFER_SRC_HOME are applicable to an IPv4-mapped IPv6 address. 710 At this point it is not understood whether this API has any value to 711 IPv4 addresses or AF_INET family of sockets. 713 13. Validation function for source address 715 Sometimes an application may have a requirement to only use addresses 716 with some particular attribute, and if no such address is available 717 the application should fail to communicate instead of communicating 718 using the 'wrong' address. In that situation, address selection 719 preferences do not guarantee that the application requirements are 720 met. Instead, the application has to explicitly verify that the 721 chosen address satisfies its requirements using a validation 722 function. Such an application would go through the following steps: 724 1. The application specifies one or more IPV6_PREFER_SRC_* flags and 725 AI_EXTFLAGS ai_flags with getaddrinfo(). 727 2. The application specifies the same IPV6_PREFER_SRC_* flags with 728 setsockopt() 730 3. The application calls connect(). This applies even for datagram 731 (UDP) sockets, as the connect call results in the stack selecting 732 a source address, for TCP as well as UDP. 734 4. Retrieve the selected source address using the getsockname() API 735 call. 737 5. Verify with the validation function that the retrieved address is 738 satisfactory as specified below. If not, abort the communication 739 e.g., by closing the socket. 741 The verification of temporary vs. public, home vs. care-of, CGA vs. 742 not, are performed by a new validation function defined for this 743 purpose: 745 #include 747 short inet6_is_srcaddr(struct sockaddr_in6 *srcaddr, 748 uint32_t flags); 750 Where the flags contains the specified IPV6_PREFER_SRC_* source 751 preference flags, and the srcaddr is a non-NULL pointer to a 752 sockaddr_in6 structure initialized as follows: 754 o sin6_addr is a 128-bit IPv6 address of the local node. 756 o sin6_family MUST be set to AF_INET6. 758 o sin6_scope_id MUST be set if the address is link-local. 760 inet6_is_srcaddr() is defined to return three possible values (0, 1, 761 -1): The function returns true (1) when the IPv6 address corresponds 762 to a valid address in the node and satisfies the given preference 763 flags. If the IPv6 address input value does not correspond to any 764 address in the node or if the flags are not one of the valid 765 preference flags, it returns a failure (-1). If the input address 766 does not match an address which satisfies the preference flags 767 indicated, the function returns false (0.) 769 This function can handle multiple valid preference flags combination 770 as its second parameter, for example IPV6_PREFER_SRC_COA | 771 IPV6_PREFER_SRC_TMP, which means that all flags MUST be satisfied for 772 the result to be true. Contradictory flag values result in a false 773 return value. 775 The function will return true for IPV6_PREFER_SRC_HOME even if the 776 host is not implementing mobile IPv6, as well as for a mobile node 777 which is at home (i.e., does not have any care-of address). 779 14. Summary of New Definitions 781 The following list summarizes the constants, structure, and extern 782 definitions discussed in this memo, sorted by header. 784 AI_EXTFLAGS 785 IPV6_PREFER_SRC_HOME 786 IPV6_PREFER_SRC_COA 787 IPV6_PREFER_SRC_TMP 788 IPV6_PREFER_SRC_PUBLIC 789 IPV6_PREFER_SRC_CGA 790 IPV6_PREFER_SRC_NONCGA 791 EAI_BADEXTFLAGS 792 struct addrinfo{}; 794 IPV6_PREFER_SRC_HOME 795 IPV6_PREFER_SRC_COA 796 IPV6_PREFER_SRC_TMP 797 IPV6_PREFER_SRC_PUBLIC 798 IPV6_PREFER_SRC_CGA 799 IPV6_PREFER_SRC_NONCGA 800 short inet6_is_srcaddr(struct sockaddr_in6 *, 801 uint32_t); 803 15. IANA Considerations 805 This document has no IANA considerations. 807 16. Security Considerations 809 This document conforms to the same security implications as specified 810 in the Basic IPv6 socket API [RFC3493]. Allowing applications to 811 specify a preference for temporary addresses provides per-application 812 (and per-socket) ability to use the privacy benefits of the temporary 813 addresses. The setting of certain address preferences (e.g. not 814 using a CGA address, or not using a temporary address) may be 815 restricted to privileged processes because of security implications. 817 17. Acknowledgments 819 The authors like to thank members of mobile-ip and ipv6 working 820 groups for useful discussion on this topic. Richard Draves and Dave 821 Thaler suggested that getaddrinfo also needs to be considered along 822 with the new socket option. Gabriel Montenegro suggested that CGAs 823 may also be considered in this document. Thanks to Alain Durand, 824 Renee Danson, Alper Yegin, Francis Dupont, Keiichi Shima, Michael 825 Hunter, Sebastien Roy, Robert Elz, Pekka Savola, Itojun, Jim Bound, 826 Steve Cipoli, Jeff Boote, Steve Cipolli, Vlad Yasevich and Mika 827 Liljeberg for useful discussions and suggestions. Thanks to Remi 828 Denis-Courmont, Brian Haberman, Brian Haley, Bob Gilligan, Jack 829 McCann, Jim Bound and Jinmei Tatuya for the review of the document 830 and the suggestions for improvement. 832 18. References 834 18.1. Normative references 836 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 837 Requirement Levels", BCP 14, RFC 2119, March 1997. 839 [RFC3484] Draves, R., "Default Address Selection for Internet 840 Protocol version 6 (IPv6)", RFC 3484, February 2003. 842 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 843 Stevens, "Basic Socket Interface Extensions for IPv6", 844 RFC 3493, February 2003. 846 18.2. Informative references 848 [FPING] "Fping - a program to ping hosts in parallel", Online web 849 site http://www.fping.com. 851 [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 852 (IPv6) Specification", RFC 2460, December 1998. 854 [RFC3041] Narten, T. and R. Draves, "Privacy Extensions for 855 Stateless Address Autoconfiguration in IPv6", RFC 3041, 856 January 2001. 858 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 859 "Advanced Sockets Application Program Interface (API) for 860 IPv6", RFC 3542, May 2003. 862 [RFC3775] Johnson, D., Perkins, C., and J. Arkko, "Mobility Support 863 in IPv6", RFC 3775, June 2004. 865 [RFC3971] Arkko, J., Kempf, J., Zill, B., and P. Nikander, "SEcure 866 Neighbor Discovery (SEND)", RFC 3971, March 2005. 868 [RFC3972] Aura, T., "Cryptographically Generated Addresses (CGA)", 869 RFC 3972, March 2005. 871 Appendix A. Per Packet Address Selection Preference 873 This document discusses setting source address selection preferences 874 on a per socket basis with the new IPV6_ADDR_PREFERENCES socket 875 option used in setsockopt(). The document does not encourage setting 876 the source address selection preference on a per packet basis through 877 the use of ancillary data objects with sendmsg(), or setsockopt() 878 with unconnected datagram sockets. 880 Per-packet source address selection is expensive as the system will 881 have to determine the source address indicated by the application 882 preference before sending each packet, while setsockopt() address 883 preference on a connected socket makes the selection once and uses 884 that source address for all packets transmitted through that socket 885 end-point, as long as the socket option is set. 887 However, this document provides guidelines for those implementations 888 which like to have an option on implementing transmit-side ancillary 889 data object support for altering default source address selection. 890 Therefore, if an application chooses to use the per-packet source 891 address selection, then the implementation should process at the 892 IPPROTO_IPV6 level (cmsg_level) ancillary data object of type 893 (cmsg_type) IPV6_ADDR_PREFERENCES containing as data (cmsg_data[]) a 894 32-bits unsigned integer encoding the source address selection 895 preference flags (e.g. IPV6_PREFER_SRC_COA | 896 IPV6_PREFER_SRC_PUBLIC), in a fashion similar to the advanced IPV6 897 Socket API [RFC3542]. This address selection preference ancillary 898 data object may be present along with other ancillary data objects. 900 The implementation processing the ancillary data object is 901 responsible for selection of preferred source address as indicated in 902 the ancillary data object. Thus, an application can use sendmsg() to 903 pass an address selection preference ancillary data object to the 904 IPv6 layer. The following example shows usage of the ancillary data 905 API for setting address preferences: 907 void *extptr; 908 socklen_t extlen; 909 struct msghdr msg; 910 struct cmsghdr *cmsgptr; 911 int cmsglen; 912 struct sockaddr_in6 dest; 913 uint32_t flags; 915 extlen = sizeof(flags); 916 cmsglen = CMSG_SPACE(extlen); 917 cmsgptr = malloc(cmsglen); 918 cmsgptr->cmsg_len = CMSG_LEN(extlen); 919 cmsgptr->cmsg_level = IPPROTO_IPV6; 920 cmsgptr->cmsg_type = IPV6_ADDR_PREFERENCES; 922 extptr = CMSG_DATA(cmsgptr); 924 flags = IPV6_PREFER_SRC_COA; 925 memcpy(extptr, &flags, extlen); 927 msg.msg_control = cmsgptr; 928 msg.msg_controllen = cmsglen; 930 /* finish filling in msg{} */ 932 msg.msg_name = dest; 934 sendmsg(s, &msg, 0); 936 Thus when an IPV6_ADDR_PREFERENCES ancillary data object is passed to 937 sendmsg(), the value included in the object is used to specify 938 address preference for the packet being sent by sendmsg(). 940 Appendix B. Changes from previous version of draft 942 o Added an appendix discussing setting source address selection 943 preferences on a per packet basis, including via passing a 944 transmit-side ancillary data object. 946 o Changed getaddrinfo()usage and removed the AI_PREFER flags. Added 947 one extended flag field in addrinfo structure and added one 948 AI_flag in order to save bits. 950 o Removed scope address preferences as some questioned about 951 applicability of IPV6_PREFER_SRC and DST scope rules alterations. 953 o Added -1 return value for inet6_is_srcaddr() for failure 954 situation. 956 o Addressed comments by the working group and reviewers of this 957 draft. 959 o Added a definition of term for X and not-X flags. 961 o Changed "not-X flag" by "opposite flag", and "X and not-X flags" 962 by by "contradictory flags" 964 o updated rationale why not to deal with native transport 965 destination address selection rule. 967 Appendix C. Intellectual Property Statement 969 This document only defines a source preference flag to choose 970 Cryptographically Generated Address (CGA) as source address when 971 applicable. CGA are obtained using public keys and hashes to prove 972 address ownership. Several IPR claims have been made about such 973 methods. 975 Authors' Addresses 977 Erik Nordmark 978 Sun Microsystems, Inc. 979 4150 Network Circle, UMPK17-308 980 Santa Clara, CA 95054 981 USA 983 Email: Erik.Nordmark@Sun.COM 985 Samita Chakrabarti 986 Azaire Networks 987 4800 Great America Parkway 988 Santa Clara, CA 95054 989 USA 991 Email: samitac2@gmail.com 993 Julien Laganier 994 DoCoMo Euro-Labs 995 Landsbergerstrasse 312 996 D-80687 Muenchen 997 Germany 999 Email: julien.IETF@laposte.net 1001 Full Copyright Statement 1003 Copyright (C) The IETF Trust (2007). 1005 This document is subject to the rights, licenses and restrictions 1006 contained in BCP 78, and except as set forth therein, the authors 1007 retain all their rights. 1009 This document and the information contained herein are provided on an 1010 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1011 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1012 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1013 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1014 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1015 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1017 Intellectual Property 1019 The IETF takes no position regarding the validity or scope of any 1020 Intellectual Property Rights or other rights that might be claimed to 1021 pertain to the implementation or use of the technology described in 1022 this document or the extent to which any license under such rights 1023 might or might not be available; nor does it represent that it has 1024 made any independent effort to identify any such rights. Information 1025 on the procedures with respect to rights in RFC documents can be 1026 found in BCP 78 and BCP 79. 1028 Copies of IPR disclosures made to the IETF Secretariat and any 1029 assurances of licenses to be made available, or the result of an 1030 attempt made to obtain a general license or permission for the use of 1031 such proprietary rights by implementers or users of this 1032 specification can be obtained from the IETF on-line IPR repository at 1033 http://www.ietf.org/ipr. 1035 The IETF invites any interested party to bring to its attention any 1036 copyrights, patents or patent applications, or other proprietary 1037 rights that may cover technology that may be required to implement 1038 this standard. Please address the information to the IETF at 1039 ietf-ipr@ietf.org. 1041 Acknowledgment 1043 Funding for the RFC Editor function is provided by the IETF 1044 Administrative Support Activity (IASA).