idnits 2.17.1 draft-chakrabarti-ipv6-addrselect-api-06.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 1029. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1040. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1047. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1053. 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 : ---------------------------------------------------------------------------- ** There are 14 instances of too long lines in the document, the longest one being 7 characters in excess of 72. ** 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 (May 9, 2007) is 6196 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 ---------------------------------------------------------------------------- == Missing Reference: 'Section 11' is mentioned on line 205, but not defined ** 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: 4 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: November 10, 2007 S. Chakrabarti 5 Azaire Networks 6 J. Laganier 7 DoCoMo Euro-Labs 8 May 9, 2007 10 IPv6 Socket API for Address Selection 11 draft-chakrabarti-ipv6-addrselect-api-06 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 November 10, 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 addresses it prefers while still 122 having the system perform the rest of the address selection rules. 123 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 Note that this document does not directly modify the destination address 192 selection rules described in [RFC3484]. An analysis has been done to see 193 which destination address rules may be required to be altered by the 194 applications. Rule number 4(prefer home address), 8(prefer smaller scope), 195 7(prefer native interfaces) of default address selection document [RFC3484] 196 were taken into consideration for destination address alteration. But, at 197 this point, there was not enough practical usage for applications to alter 198 destination address selection rules directly by applying the setsockopt() 199 with a preferred destination type of address flag. 200 Moreover, [RFC3484] destination address selection rules are dependent on 201 source address selections, thus by altering the default source address 202 selection by using the methods described in this document, one indirectly 203 influences the choice of destination address selection. Hence this document 204 explains how getaddrinfo() can be used to select the destination address 205 while taking the preferred source addresses into consideration [Section 11]. 207 This document specifies extensions only to the Basic IPv6 socket API 208 specified in [RFC3493]. The intent is that this document serves as a 209 model for expressing preferences for attributes of IP addresses, that 210 also need to be expressible in other networking API such as those 211 found in middleware systems and the Java environment. 213 2. Definition Of Terms 215 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 216 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 217 document are to be interpreted as described in [RFC2119]. 219 Address preference flag: 220 A flag expressing a preference for a particular type of 221 (e.g. temporary, public) source or destination addresses. 223 Opposite flags: 224 Each flag expressing an address preference has a so called 225 "opposite flag" expressing the opposite preference: 227 * home address preference flag is the opposite of the care-of 228 address preference flag. 230 * temporary address preference flag is the opposite of the public 231 address preference flag. 233 * CGA address preference flag is the opposite of the non-CGA 234 address preference flag. 236 Contradictory flags: 237 Any combination of flags including both a flag expressing a given 238 address preference and a flag expressing the opposite preference 239 constitutes Such flags are contradictory by definition of their 240 usefulness with respect to source address selection. For example, 241 consider a set of flags including both the home address preference 242 flag and the care-of address preference flag. When considering 243 source address selection, the selected address can be a home 244 address, or a care-of address, but it cannot be both at the same 245 time. Hence, to prefer an address which is both a home address, 246 and a care-of address, is contradictory. 248 3. Usage Scenario 250 The examples discussed here are limited to applications supporting 251 Mobile IPv6, IPv6 Privacy Extensions and Cryptographically Generated 252 Addresses. Address selection document [RFC3484] recommends that home 253 addresses should be preferred over care-of address when both are 254 configured. However, a mobile node may want to prefer care-of 255 address as source address for DNS query in the foreign network as it 256 normally means a shorter and local return path compared to the route 257 via the mobile node's home-agent when the query contains home address 258 as source address. Another example is IKE application which requires 259 care-of address as its source address for the initial security 260 association pair with Home Agent [RFC3775] while the mobile node 261 boots up at the foreign network and wants to do the key exchange 262 before a successful home-registration. Also a Mobile IPv6 aware 263 application may want to toggle between home address and care-of 264 address depending on its location and state of the application. It 265 may also want to open different sockets and use home address as 266 source address for one socket and care-of address for the others. 268 In a non-mobile environment, an application may similarly prefer to 269 use temporary address as source address for certain cases. By 270 default, the source address selection rule selects "public" address 271 when both are available. For example, an application supporting web 272 browser and mail-server may want to use "temporary" address for the 273 former and "public" address for the mail-server as a mail-server may 274 require reverse path for DNS records for anti-spam rules. 276 Similarly, a node may be configured to use Cryptographically 277 Generated Addresses [RFC3972] by default, as in Secure Neighbor 278 Discovery [RFC3971], but an application may prefer not to use it. 279 For instance, fping [FPING], a debugging tool which tests basic 280 reachability of multiple destinations by sending packets in parallel, 281 may find that the cost and time incurred in proof-of-ownership by CGA 282 verification is not justified. On the other hand, when a node is not 283 configured for CGA as default, an application may prefer using CGA by 284 setting the corresponding preference. 286 4. Design Alternatives 288 Some suggested to have per-application flags instead of per-socket 289 and per-packet flags. However, this design stays with per-socket and 290 per-packet flags for the following reasons: 292 o While some systems have per environment/application flags (such as 293 environment variables in Unix systems) this might not be available 294 in all systems which implement the socket API. 296 o When an application links with some standard library, that library 297 might use the socket API, while the application is unaware of that 298 fact. Mechanisms that would provide per application flags may 299 affect not only the application itself but also the libraries, 300 hence creating risks of unintended consequences. 302 Instead of the pair of 'flag' and 'opposite flag' for each rule that 303 can be modified, the socket option could have been defined to use a 304 single 'flag' value for each rule. This would still have allowed 305 different implementations to have different default settings as long 306 as the applications were coded to first retrieve the default setting 307 (using getsockopt()), and then clear or set the 'flag' according to 308 their preferences, and finally set the new value with setsockopt(). 310 But such an approach would not be possible for getaddrinfo() because 311 all the preferences would need to be expressible in the parameters 312 that are passed with a single getaddrinfo() call. Hence, for 313 consistency, the 'flag' and 'opposite flag' approach is used for both 314 getaddrinfo() and setsockopt(). 316 5. Address Preference Flags 318 The following flags are defined to alter or set the default rule of 319 source and destination address selection rules discussed in default 320 address selection specification [RFC3484]. 322 IPV6_PREFER_SRC_HOME /* Prefer Home address as source */ 324 IPV6_PREFER_SRC_COA /* Prefer Care-of address as source */ 326 IPV6_PREFER_SRC_TMP /* Prefer Temporary address as source */ 328 IPV6_PREFER_SRC_PUBLIC /* Prefer Public address as source */ 330 IPV6_PREFER_SRC_CGA /* Prefer CGA address as source */ 332 IPV6_PREFER_SRC_NONCGA /* Prefer a non-CGA address as source */ 334 These flags can be combined together in a flag-set to express more 335 complex address preferences. However such combinations can result in 336 a contradictory flag-set, for example: 338 IPV6_PREFER_SRC_PUBLIC | IPV6_PREFER_SRC_TMP 340 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_COA 342 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_COA | IPV6_PREFER_SRC_TMP 344 IPV6_PREFER_SRC_CGA | IPV6_PREFER_SRC_NONCGA 346 Etc. 348 Example of valid combination of address selection flags are given 349 below: 351 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_PUBLIC 353 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_CGA 355 IPV6_PREFER_SRC_COA | IPV6_PREFER_SRC_PUBLIC | IPV6_PREFER_SRC_CGA 357 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_NONCGA 359 If a flag-set includes a combination of 'X' and 'Y', and if 'Y' is 360 not applicable or available in the system, then the selected address 361 has attribute 'X' and system default for the attribute 'Y'. For 362 example, on a system that has only public addresses, the valid 363 combination of flags: 365 IPV6_PREFER_SRC_TMP | IPV6_PREFER_SRC_HOME 367 would result in the selected address being a public home address, 368 since no temporary addresses are available. 370 6. Additions to the Socket Interface 372 The IPv6 Basic Socket API [RFC3493] defines socket options for IPv6. 373 To allow applications to influence address selection mechanisms this 374 document adds a new socket option at the IPPROTO_IPV6 level. This 375 socket option is called IPV6_ADDR_PREFERENCES. It can be used with 376 setsockopt() and getsockopt() calls to set and get the address 377 selection preferences affecting all packets sent via a given socket. 378 The socket option value (optval) is a 32-bits unsigned integer 379 argument. The argument consists of a number of flags where each flag 380 indicates an address selection preference which modifies one of the 381 rules in the default address selection specification. 383 The following flags are defined to alter or set the default rule of 384 source and destination address selection rules discussed in default 385 address selection specification [RFC3484]. They are defined as a 386 result of including the header: 388 IPV6_PREFER_SRC_HOME /* Prefer Home address as source */ 390 IPV6_PREFER_SRC_COA /* Prefer Care-of address as source */ 392 IPV6_PREFER_SRC_TMP /* Prefer Temporary address as source */ 394 IPV6_PREFER_SRC_PUBLIC /* Prefer Public address as source */ 396 IPV6_PREFER_SRC_CGA /* Prefer CGA address as source */ 398 IPV6_PREFER_SRC_NONCGA /* Prefer a non-CGA address as source */ 400 NOTE: No source preference flag for longest matching prefix is 401 defined here because it is believed to be handled by the policy table 402 defined in the default address selection specification. 404 When the IPV6_ADDR_PREFERENCES is successfully set with setsockopt(), 405 the option value given is used to specify address preference for any 406 connection initiation through the socket and all subsequent packets 407 sent via that socket. If no option is set, the system selects a 408 default value as per default address selection algorithm or by some 409 other equivalent means. 411 Setting contradictory flags at the same time results in the error 412 EINVAL. 414 7. Additions to the protocol-independent nodename translation 416 Section 8 of Default Address Selection [RFC3484] document indicates 417 possible implementation strategies for getaddrinfo() [RFC3493]. One 418 of them suggests that getaddrinfo() collects available source/ 419 destination pair from the network layer after being sorted at the 420 network layer with full knowledge of source address selection. 421 Another strategy is to call down to the network layer to retrieve 422 source address information and then sort the list in the context of 423 getaddrinfo(). 425 This implies that getaddrinfo() should be aware of the address 426 selection preferences of the application, since getaddrinfo() is 427 independent of any socket the application might be using. 429 Thus if an application alters the default address selection rules by 430 using setsockopt() with the IPV6_ADDR_PREFERENCES option, the 431 application should also use the corresponding address selection 432 preference flags with its getaddrinfo() call. 434 For that purpose, the addrinfo data structure defined in Basic IPV6 435 Socket API Extension [RFC3493] has been extended with an extended 436 "ai_eflags" flag-set field to provides the designers freedom of 437 adding more flags as necessary without crowding the valuable bit 438 space in the "ai_flags" flag-set field. The extended addrinfo data 439 structre is defined as a result of including the header: 441 struct addrinfo { 442 int ai_flags; /* input flags */ 443 int ai_family; /* protocol family for socket */ 444 int ai_socktype; /* socket type */ 445 int ai_protocol; /* protocol for socket */ 446 socklen_t ai_addrlen; /* length of socket address */ 447 char *ai_canonname; /* canonical name for hostname */ 448 struct sockaddr *ai_addr; /* socket address for socket */ 449 struct addrinfo *ai_next; /* pointer to next in list */ 450 int ai_eflags; /* Extended flags for special usage */ 451 }; 453 Note that the additional field for extended flags are added at the 454 bottom of the addrinfo structure to preserve binary compatibility of 455 the new functionality with the old applications which use the 456 existing addrinfo data structure. 458 A new flag (AI_EXTFLAGS) is defined for the "ai_flags" flag-set field 459 of the addrinfo data structure to tell the system to look for the 460 "ai_eflags" extended flag-set field in the addrinfo structure. It is 461 defined in the header: 463 AI_EXTFLAGS /* extended flag-set present */ 465 If AI_EXTFLAGS flag is set in "ai_flags" flag-set field of the 466 addrinfo data structure, then the getaddrinfo() implementation MUST 467 look for the "ai_eflags" values stored in the extended flag-set field 468 "ai_eflags" of the addrinfo data structure. The flags stored in the 469 extended flags set "ai_eflags" field are only meaningful if the 470 AI_EXTFLAGS flag is set in the "ai_flags" flag-set field of the 471 addrinfo data structure. By default, AI_EXTFLAGS is not set. 472 If AI_EXTFLAGS is set in the "ai_flags" flag-set field, and the 473 "ai_eflags" field is 0(zero), then AI_EXTFLAGS is ignored. 475 The IPV6 source address preference values (IPV6_PREFER_SRC_*) defined 476 for the IPV6_ADDR_PREFERENCES socket option are also used as 477 address selection preference flags for the extended flag-set (ai_eflags) 478 field of the addrinfo data structure, so that getaddrinfo() can 479 return matching destination addresses corresponding to the source 480 address preferences expressed by the caller application. 482 Thus, an application passes source address selection hints to 483 getaddrinfo by setting AI_EXTFLAGS in the "ai_flags" field of the 484 addrinfo structure, and the corresponding address selection 485 preference flags (IPV6_PREFER_SRC_*) in the "ai_eflags" field. 487 Currently AI_EXTFLAGS is defined for the AF_INET6 socket protocol 488 family only. But its usage should be extendable to other socket 489 protocol families as appropriate. 491 If contradictory flags such as IPV6_PREFER_SRC_HOME and 492 IPV6_PREFER_SRC_COA are set in ai_eflags, the getaddrinfo() fails and 493 return the value EAI_BADEXTFLAGS which is defined in . 494 This error value MUST be interpreted into a descriptive text string 495 when passed to the gai_strerror() function [RFC3493]. 497 8. Application Requirements 499 An application should call getsockopt() prior calling setsockopt() if 500 the application needs to be able to restore the socket back to the 501 system default preferences. Note, this is suggested for portability. 502 An application which does not have this requirement can just use 503 getaddrinfo() while specifying its preferences, followed by: 505 uint32_t flags = IPV6_PREFER_SRC_TMP; 507 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 508 (void *) &flags, sizeof (flags)) == -1) { 509 perror("setsockopt IPV6_ADDR_REFERENCES"); 510 } 512 An application which needs to be able to restore the default settings 513 on the socket would instead do this: 515 uint32_t save_flags, flags; 516 int optlen = sizeof (save_flags); 518 /* Save the existing IPv6_ADDR_PREFERENCE flags now */ 520 if (getsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 521 (void *) &save_flags, &optlen) == -1 { 522 perror("getsockopt IPV6_ADDR_REFERENCES"); 523 } 525 /* Set the new flags */ 526 flags = IPV6_PREFER_SRC_TMP; 527 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 528 (void *) &flags, sizeof (flags)) == -1) { 529 perror("setsockopt IPV6_ADDR_REFERENCES"); 530 } 532 /* 533 * 534 * Do some work with the socket here. 535 * 536 */ 538 /* Restore the flags */ 540 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 541 (void *) &save_flags, sizeof (save_flags)) == -1) { 542 perror("setsockopt IPV6_ADDR_REFERENCES"); 543 } 545 Applications MUST not set contradictory flags at the same time. 547 In order to allow different implementations to do different parts of 548 address selection in getaddrinfo() and in the protocol stack, this 549 specification requires that applications set the semantically 550 equivalent flags when calling getaddrinfo() and setsockopt(). For 551 example, if the application sets the IPV6_PREFER_SRC_COA flag, it 552 MUST use the same for the "ai_eflag" field of the addrinfo data 553 structure when calling getaddrinfo(). If applications are not 554 setting the semantically equivalent flags the behavior of the 555 implementation is undefined. 557 9. Usage Example 559 An example of usage of this API is given below: 561 struct addrinfo hints, *ai, *ai0; 562 uint32_t preferences; 564 preferences = IPV6_PREFER_SRC_TMP; 566 hints.ai_flags |= AI_EXTFLAGS; 567 hints.ai_eflags = preferences; /* Chosen address preference flag */ 568 /* Fill in other hints fields */ 570 getaddrinfo(....,&hints,. &ai0..); 572 /* Loop over all returned addresses and do connect */ 573 for (ai = ai0; ai; ai = ai->ai_next) { 574 s = socket(ai->ai_family, ...); 576 setsockopt(s, IPV6_ADDR_PREFERENCES, (void *) &preferences, 577 sizeof (preferences)); 579 if (connect(s, ai->ai_addr, ai->ai_addrlen) == -1){ 580 close (s); 581 s = -1; 582 continue; 583 } 585 break; 586 } 588 freeaddrinfo(ai0); 590 10. Implementation Notes 592 o Within the same application, if a specific source address is set 593 by either bind() or IPV6_PKTINFO socket option, while at the same 594 time an address selection preference is expressed with the 595 IPV6_ADDR_PREFERENCES socket option, then the source address 596 setting carried by bind() or IPV6_PKTINFO takes precedence over 597 the address selection setting. 599 o setsockopt() and getaddrinfo() should silently ignore any address 600 preference flags that are not supported in the system. For 601 example, a host which does not implement Mobile IPv6, should not 602 fail setsockopt() or getaddrinfo() that specify preferences for 603 home or care-of addresses. The socket option calls should return 604 error (-1) and set errno to EINVAL when contradictory flags values 605 are passed to them. 607 o If an implementation supports both stream and datagram sockets, it 608 should implement the address preference mechanism API described in 609 this document on both types of sockets. 611 o An implementation supporting this API MUST implement both 612 getaddrinfo() extension flags and socket option flags processing 613 for portability of applications. 615 o The following flags are set as default values on a system (which 616 is consistent with [RFC3484] defaults): 618 IPV6_PREFER_SRC_HOME 620 IPV6_PREFER_SRC_PUBLIC 622 IPV6_PREFER_SRC_CGA 624 11. Mapping to Default Address Selection Rules 626 This API defines only those flags that are deemed to be useful by the 627 applications to alter default address selection rules. Thus we 628 discuss the mapping of each set of flags to the corresponding rule 629 number in the address selection document [RFC3484]. 631 Source address selection rule #4 (prefer home address): 633 IPV6_PREFER_SRC_HOME (default) 635 IPV6_PREFER_SRC_COA 637 Source address selection rule #7 (prefer public address) : 639 IPV6_PREFER_SRC_PUBLIC (default) 641 IPV6_PREFER_SRC_TMP 643 At this time, this document does not define flags to alter source 644 address selection rule #2 (prefer appropriate scope for destination) 645 and destination address selection rule #8 (prefer smaller scope) as 646 the implementers felt that there were no practical applications that 647 can take advantage of reverting the scoping rules of IPv6 default 648 address selection. Flags altering other destination address 649 selection rules (#4, prefer home address and #7, prefer native 650 transport) could have applications, but the problem is that the local 651 system cannot systematically determine whether a destination address 652 is a tunnel address for destination rule #7 (although it can when the 653 destination address is one of its own, or can be syntactically 654 recognized as a tunnel address, e.g., a 6to4 address.) The flags 655 defined for source address selection rule #4 (prefer home address) 656 should also take care of destination address selection rule #4. Thus 657 at this point, it was decided not to define flags for these 658 destination rules. 660 Also, note that there is no corresponding destination address 661 selection rule for source address selection rule #7 (prefer public 662 addresses) of default address selection document [RFC3484]. However, 663 this API provides a way for an application to make sure that the 664 source address preference set in setsockopt() is taken into account 665 by the getaddrinfo() function. Let's consider an example to 666 understand this scenario. DA and DB are two global destination 667 addresses and the node has two global source addresses SA and SB 668 through interface A and B respectively. SA is a temporary address 669 while SB is a public address. The application has set 670 IPV6_PREFER_SRC_TMP in the setsockopt() flag. The route to DA points 671 to interface A and route to DB points to interface B. Thus when 672 AI_EXTFLAGS in ai_flags and IPV6_PREFER_SRC_TMP in ai_eflags are set, 673 getaddrinfo() returns DA before DB in the list of destination 674 addresses and thus SA will be used to communicate with the 675 destination DA. Similarly, getaddrinfo() returns DB before DA when 676 AI_EXTFLAGS and ai_eflags are set to IPV6_PREFER_SRC_PUBLIC. Thus 677 the source address preference is taking effect into destination 678 address selection and as well as source address selection by the 679 getaddrinfo() function. 681 The following numerical example clarifies the above further. 683 Imagine a host with two addresses: 685 1234::1:1 public 687 9876::1:2 temporary 689 The destination has the following two addresses: 691 1234::9:3 693 9876::9:4 695 By default getaddrinfo() will return the destination addresses in the 696 order 698 1234::9:3 700 9876::9:4 702 because the public source is preferred and 1234 matches more bits 703 with the public source address. On the other hand, if ai_flags is 704 set to AI_EXTFLAGS and ai_eflags to IPV6_PREFER_SRC_TMP, getaddrinfo 705 will return the addresses in the reverse order since the temporary 706 source address will be preferred. 708 Other source address rules (that are not mentioned here) were also 709 deemed not applicable for changing its default on a per-application 710 basis. 712 12. IPv4-mapped IPv6 Addresses 714 IPv4-mapped IPv6 addresses for AF_INET6 sockets are supported in this 715 API. In some cases the application of IPv4-mapped addresses are 716 limited because the API attributes are IPv6 specific. For example, 717 IPv6 temporary addresses and cryptographically generated addresses 718 have no IPv4 counterparts. Thus the IPV6_PREFER_SRC_TMP or 719 IPV6_PREFER_SRC_CGA are not directly applicable to an IPv4-mapped 720 IPv6 address. However, the IPv4-mapped address support may be useful 721 for mobile-IPv4 applications shifting source address between the home 722 address and the care-of address. Thus the IPV6_PREFER_SRC_COA and 723 IPV6_PREFER_SRC_HOME are applicable to an IPv4-mapped IPv6 address. 724 At this point it is not understood whether this API has any value to 725 IPv4 addresses or AF_INET family of sockets. 727 13. Validation function for source address 729 Sometimes an application may have a requirement to only use addresses 730 with some particular attribute, and if no such address is available 731 the application should fail to communicate instead of communicating 732 using the 'wrong' address. In that situation, address selection 733 preferences do not guarantee that the application requirements are 734 met. Instead, the application has to explicitly verify that the 735 chosen address satisfies its requirements using a validation 736 function. Such an application would go through the following steps: 738 1. The application specifies one or more IPV6_PREFER_SRC_* flags and 739 AI_EXTFLAGS ai_flags with getaddrinfo(). 741 2. The application specifies the same IPV6_PREFER_SRC_* flags with 742 setsockopt() 744 3. The application calls connect(). This applies even for datagram 745 (UDP) sockets, as the connect call results in the stack selecting 746 a source address, for TCP as well as UDP. 748 4. Retrieve the selected source address using the getsockname() API 749 call. 751 5. Verify with the validation function that the retrieved address is 752 satisfactory as specified below. If not, abort the communication 753 e.g., by closing the socket. 755 The verification of temporary vs. public, home vs. care-of, CGA vs. 756 not, are performed by a new validation function defined for this 757 purpose: 759 #include 761 short inet6_is_srcaddr(struct sockaddr_in6 *srcaddr, 762 uint32_t flags); 764 Where the flags contains the specified IPV6_PREFER_SRC_* source 765 preference flags, and the srcaddr is a non-NULL pointer to a 766 sockaddr_in6 structure initialized as follows: 768 o sin6_addr is a 128-bit IPv6 address of the local node. 770 o sin6_family MUST be set to AF_INET6. 772 o sin6_scope_id MUST be set if the address is link-local. 774 inet6_is_srcaddr() is defined to return three possible values (0, 1, 775 -1): The function returns true (1) when the IPv6 address corresponds 776 to a valid address in the node and satisfies the given preference 777 flags. If the IPv6 address input value does not correspond to any 778 address in the node or if the flags are not one of the valid 779 preference flags, it returns a failure (-1). If the input address 780 does not match an address which satisfies the preference flags 781 indicated, the function returns false (0.) 783 This function can handle multiple valid preference flags combination 784 as its second parameter, for example IPV6_PREFER_SRC_COA | 785 IPV6_PREFER_SRC_TMP, which means that all flags MUST be satisfied for 786 the result to be true. Contradictory flag values result in a false 787 return value. 789 The function will return true for IPV6_PREFER_SRC_HOME even if the 790 host is not implementing mobile IPv6, as well as for a mobile node 791 which is at home (i.e., does not have any care-of address). 793 14. Summary of New Definitions 795 The following list summarizes the constants, structure, and extern 796 definitions discussed in this memo, sorted by header. 798 AI_EXTFLAGS 799 IPV6_PREFER_SRC_HOME 800 IPV6_PREFER_SRC_COA 801 IPV6_PREFER_SRC_TMP 802 IPV6_PREFER_SRC_PUBLIC 803 IPV6_PREFER_SRC_CGA 804 IPV6_PREFER_SRC_NONCGA 805 EAI_BADEXTFLAGS 806 struct addrinfo{}; 808 IPV6_PREFER_SRC_HOME 809 IPV6_PREFER_SRC_COA 810 IPV6_PREFER_SRC_TMP 811 IPV6_PREFER_SRC_PUBLIC 812 IPV6_PREFER_SRC_CGA 813 IPV6_PREFER_SRC_NONCGA 814 short inet6_is_srcaddr(struct sockaddr_in6 *, 815 uint32_t); 817 15. IANA Considerations 819 This document has no IANA considerations. 821 16. Security Considerations 823 This document conforms to the same security implications as specified 824 in the Basic IPv6 socket API [RFC3493]. Allowing applications to 825 specify a preference for temporary addresses provides per-application 826 (and per-socket) ability to use the privacy benefits of the temporary 827 addresses. The setting of certain address preferences (e.g. not 828 using a CGA address, or not using a temporary address) may be 829 restricted to privileged processes because of security implications. 831 17. Acknowledgments 833 The authors like to thank members of mobile-ip and ipv6 working 834 groups for useful discussion on this topic. Richard Draves and Dave 835 Thaler suggested that getaddrinfo also needs to be considered along 836 with the new socket option. Gabriel Montenegro suggested that CGAs 837 may also be considered in this document. Thanks to Alain Durand, 838 Renee Danson, Alper Yegin, Francis Dupont, Keiichi Shima, Michael 839 Hunter, Sebastien Roy, Robert Elz, Pekka Savola, Itojun, Jim Bound, 840 Steve Cipoli, Jeff Boote, Steve Cipolli, Vlad Yasevich and Mika 841 Liljeberg for useful discussions and suggestions. Thanks to Remi 842 Denis-Courmont, Brian Haberman, Brian Haley, Bob Gilligan, Jack 843 McCann, Jim Bound and Jinmei Tatuya for the review of the document 844 and the suggestions for improvement. 846 18. References 848 18.1. Normative references 850 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 851 Requirement Levels", BCP 14, RFC 2119, March 1997. 853 [RFC3484] Draves, R., "Default Address Selection for Internet 854 Protocol version 6 (IPv6)", RFC 3484, February 2003. 856 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 857 Stevens, "Basic Socket Interface Extensions for IPv6", 858 RFC 3493, February 2003. 860 18.2. Informative references 862 [FPING] "Fping - a program to ping hosts in parallel", Online web 863 site http://www.fping.com. 865 [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 866 (IPv6) Specification", RFC 2460, December 1998. 868 [RFC3041] Narten, T. and R. Draves, "Privacy Extensions for 869 Stateless Address Autoconfiguration in IPv6", RFC 3041, 870 January 2001. 872 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 873 "Advanced Sockets Application Program Interface (API) for 874 IPv6", RFC 3542, May 2003. 876 [RFC3775] Johnson, D., Perkins, C., and J. Arkko, "Mobility Support 877 in IPv6", RFC 3775, June 2004. 879 [RFC3971] Arkko, J., Kempf, J., Zill, B., and P. Nikander, "SEcure 880 Neighbor Discovery (SEND)", RFC 3971, March 2005. 882 [RFC3972] Aura, T., "Cryptographically Generated Addresses (CGA)", 883 RFC 3972, March 2005. 885 Appendix A. Per Packet Address Selection Preference 887 This document discusses setting source address selection preferences 888 on a per socket basis with the new IPV6_ADDR_PREFERENCES socket 889 option used in setsockopt(). The document does not encourage setting 890 the source address selection preference on a per packet basis through 891 the use of ancillary data objects with sendmsg(), or setsockopt() 892 with unconnected datagram sockets. 894 Per-packet source address selection is expensive as the system will 895 have to determine the source address indicated by the application 896 preference before sending each packet, while setsockopt() address 897 preference on a connected socket makes the selection once and uses 898 that source address for all packets transmitted through that socket 899 end-point, as long as the socket option is set. 901 However, this document provides guidelines for those implementations 902 which like to have an option on implementing transmit-side ancillary 903 data object support for altering default source address selection. 904 Therefore, if an application chooses to use the per-packet source 905 address selection, then the implementation should process at the 906 IPPROTO_IPV6 level (cmsg_level) ancillary data object of type 907 (cmsg_type) IPV6_ADDR_PREFERENCES containing as data (cmsg_data[]) a 908 32-bits unsigned integer encoding the source address selection 909 preference flags (e.g. IPV6_PREFER_SRC_COA | 910 IPV6_PREFER_SRC_PUBLIC), in a fashion similar to the advanced IPV6 911 Socket API [RFC3542]. This address selection preference ancillary 912 data object may be present along with other ancillary data objects. 914 The implementation processing the ancillary data object is 915 responsible for selection of preferred source address as indicated in 916 the ancillary data object. Thus, an application can use sendmsg() to 917 pass an address selection preference ancillary data object to the 918 IPv6 layer. The following example shows usage of the ancillary data 919 API for setting address preferences: 921 void *extptr; 922 socklen_t extlen; 923 struct msghdr msg; 924 struct cmsghdr *cmsgptr; 925 int cmsglen; 926 struct sockaddr_in6 dest; 927 uint32_t flags; 929 extlen = sizeof(flags); 930 cmsglen = CMSG_SPACE(extlen); 931 cmsgptr = malloc(cmsglen); 932 cmsgptr->cmsg_len = CMSG_LEN(extlen); 933 cmsgptr->cmsg_level = IPPROTO_IPV6; 934 cmsgptr->cmsg_type = IPV6_ADDR_PREFERENCES; 936 extptr = CMSG_DATA(cmsgptr); 938 flags = IPV6_PREFER_SRC_COA; 939 memcpy(extptr, &flags, extlen); 941 msg.msg_control = cmsgptr; 942 msg.msg_controllen = cmsglen; 944 /* finish filling in msg{} */ 946 msg.msg_name = dest; 948 sendmsg(s, &msg, 0); 950 Thus when an IPV6_ADDR_PREFERENCES ancillary data object is passed to 951 sendmsg(), the value included in the object is used to specify 952 address preference for the packet being sent by sendmsg(). 954 Appendix B. Changes from previous version of draft 956 o Added an appendix discussing setting source address selection 957 preferences on a per packet basis, including via passing a 958 transmit-side ancillary data object. 960 o Changed getaddrinfo()usage and removed the AI_PREFER flags. Added 961 one extended flag field in addrinfo structure and added one 962 AI_flag in order to save bits. 964 o Removed scope address preferences as some questioned about 965 applicability of IPV6_PREFER_SRC and DST scope rules alterations. 967 o Added -1 return value for inet6_is_srcaddr() for failure 968 situation. 970 o Addressed comments by the working group and reviewers of this 971 draft. 973 o Added a definition of term for X and not-X flags. 975 o Changed "not-X flag" by "opposite flag", and "X and not-X flags" 976 by by "contradictory flags" 978 o updated rationale why not to deal with native transport 979 destination address selection rule. 981 Appendix C. Intellectual Property Statement 983 This document only defines a source preference flag to choose 984 Cryptographically Generated Address (CGA) as source address when 985 applicable. CGA are obtained using public keys and hashes to prove 986 address ownership. Several IPR claims have been made about such 987 methods. 989 Authors' Addresses 991 Erik Nordmark 992 Sun Microsystems, Inc. 993 4150 Network Circle, UMPK17-308 994 Santa Clara, CA 95054 995 USA 997 Email: Erik.Nordmark@Sun.COM 999 Samita Chakrabarti 1000 Azaire Networks 1001 4800 Great America Parkway 1002 Santa Clara, CA 95054 1003 USA 1005 Email: samitac2@gmail.com 1007 Julien Laganier 1008 DoCoMo Euro-Labs 1009 Landsbergerstrasse 312 1010 D-80687 Muenchen 1011 Germany 1013 Email: julien.IETF@laposte.net 1015 Full Copyright Statement 1017 Copyright (C) The IETF Trust (2007). 1019 This document is subject to the rights, licenses and restrictions 1020 contained in BCP 78, and except as set forth therein, the authors 1021 retain all their rights. 1023 This document and the information contained herein are provided on an 1024 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1025 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1026 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1027 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1028 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1029 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1031 Intellectual Property 1033 The IETF takes no position regarding the validity or scope of any 1034 Intellectual Property Rights or other rights that might be claimed to 1035 pertain to the implementation or use of the technology described in 1036 this document or the extent to which any license under such rights 1037 might or might not be available; nor does it represent that it has 1038 made any independent effort to identify any such rights. Information 1039 on the procedures with respect to rights in RFC documents can be 1040 found in BCP 78 and BCP 79. 1042 Copies of IPR disclosures made to the IETF Secretariat and any 1043 assurances of licenses to be made available, or the result of an 1044 attempt made to obtain a general license or permission for the use of 1045 such proprietary rights by implementers or users of this 1046 specification can be obtained from the IETF on-line IPR repository at 1047 http://www.ietf.org/ipr. 1049 The IETF invites any interested party to bring to its attention any 1050 copyrights, patents or patent applications, or other proprietary 1051 rights that may cover technology that may be required to implement 1052 this standard. Please address the information to the IETF at 1053 ietf-ipr@ietf.org. 1055 Acknowledgment 1057 Funding for the RFC Editor function is provided by the IETF 1058 Administrative Support Activity (IASA).