idnits 2.17.1 draft-chakrabarti-ipv6-addrselect-api-07.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 1108. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1119. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1126. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1132. 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 -- 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 (June 14, 2007) is 6161 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Proposed Standard ---------------------------------------------------------------------------- (See RFCs 3967 and 4897 for information about using normative references to lower-maturity documents in RFCs) == Missing Reference: 'Section 11' is mentioned on line 210, but not defined ** Obsolete normative reference: RFC 3484 (Obsoleted by RFC 6724) ** Downref: Normative reference to an Informational RFC: RFC 3493 -- Obsolete informational reference (is this intentional?): RFC 2460 (Obsoleted by RFC 8200) -- Obsolete informational reference (is this intentional?): RFC 3041 (Obsoleted by RFC 4941) -- Obsolete informational reference (is this intentional?): RFC 3775 (Obsoleted by RFC 6275) Summary: 4 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 Intended status: Standards Track S. Chakrabarti 5 Expires: December 16, 2007 Azaire Networks 6 J. Laganier 7 DoCoMo Euro-Labs 8 June 14, 2007 10 IPv6 Socket API for Source Address Selection 11 draft-chakrabarti-ipv6-addrselect-api-07 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 December 16, 2007. 38 Copyright Notice 40 Copyright (C) The IETF Trust (2007). 42 Abstract 44 The IPv6 default address selection document [RFC3484] describes the 45 rules for selecting source and destination IPv6 addresses, and 46 indicates that applications should be able to reverse the sense of 47 some of the address selection rules through some unspecified API. 48 However, no such socket API exists in the basic [RFC3493] or advanced 49 [RFC3542] IPv6 socket API documents. This document fills that gap 50 partially by specifying new socket-level options for source address 51 selection and flags for the getaddrinfo() API to specify address 52 selection based on the the source address preference in accordance 53 with the socket-level options that modify the default source address 54 selection algorithm. The socket API described in this document will 55 be particularly useful for IPv6 applications that want to choose 56 between temporary and public addresses, and for Mobile IPv6 aware 57 applications that want to use the care-of address for communication. 58 It also specifies socket options and flags for selecting CGA or non- 59 CGA source addresses. 61 Table of Contents 63 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 64 2. Definition Of Terms . . . . . . . . . . . . . . . . . . . . . 7 65 3. Usage Scenario . . . . . . . . . . . . . . . . . . . . . . . . 8 66 4. Design Alternatives . . . . . . . . . . . . . . . . . . . . . 9 67 5. Address Preference Flags . . . . . . . . . . . . . . . . . . . 10 68 6. Additions to the Socket Interface . . . . . . . . . . . . . . 12 69 7. Additions to the protocol-independent nodename translation . . 13 70 8. Application Requirements . . . . . . . . . . . . . . . . . . . 15 71 9. Usage Example . . . . . . . . . . . . . . . . . . . . . . . . 17 72 10. Implementation Notes . . . . . . . . . . . . . . . . . . . . . 18 73 11. Mapping to Default Address Selection Rules . . . . . . . . . . 19 74 12. IPv4-mapped IPv6 Addresses . . . . . . . . . . . . . . . . . . 21 75 13. Validating source address preferences . . . . . . . . . . . . 22 76 14. Summary of New Definitions . . . . . . . . . . . . . . . . . . 25 77 15. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 26 78 16. Security Considerations . . . . . . . . . . . . . . . . . . . 27 79 17. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 28 80 18. References . . . . . . . . . . . . . . . . . . . . . . . . . . 29 81 18.1. Normative references . . . . . . . . . . . . . . . . . . 29 82 18.2. Informative references . . . . . . . . . . . . . . . . . 29 83 Appendix A. Per Packet Address Selection Preference . . . . . . . 30 84 Appendix B. Changes from previous version of draft . . . . . . . 32 85 Appendix C. Intellectual Property Statement . . . . . . . . . . . 33 86 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 34 87 Intellectual Property and Copyright Statements . . . . . . . . . . 35 89 1. Introduction 91 [RFC3484] specifies the default address selection rules for IPv6 92 [RFC2460]. This document defines socket API extensions that allow 93 applications to override the default choice of source address 94 selection. It therefore indirectly affects the destination address 95 selection through getaddrinfo(). Privacy considerations [RFC3041] 96 have introduced "public" and "temporary" addresses. IPv6 Mobility 97 [RFC3775] introduces "home address" and "care-of address" definitions 98 in the mobile systems. 100 The default address selection rules in [RFC3484] in summary are that 101 a public address is preferred over a temporary address, that a mobile 102 IPv6 home address is preferred over a care-of address, and that a 103 larger scope address is preferred over a smaller scope address. 104 Although it is desirable to have default rules for address selection, 105 an application may want to reverse certain address selection rules 106 for efficiency and other application-specific reasons. 108 Currently IPv6 socket API extensions provide mechanisms to choose a 109 specific source address through simple bind() operation or 110 IPV6_PKTINFO socket option [RFC3542]. However, in order to use 111 bind() or IPV6_PKTINFO socket option, the application itself must 112 make sure that the source address is appropriate for the destination 113 address (e.g., with respect to the interface used to send packets to 114 the destination). The application also needs to verify the 115 appropriateness of the source address scope with respect to the 116 destination address and so on. This can be quite complex for the 117 application, since in effect it needs to implement all the default 118 address selection rules in order to change its preferences with 119 respect to one of the rules. 121 The mechanism presented in this document allows the application to 122 specify attributes of the source addresses it prefers while still 123 having the system perform the rest of the address selection rules. 124 For instance, if an application specifies that it prefers to use a 125 care-of address over a home address as the source address and if the 126 host has two care-of addresses, one public and one temporary, then 127 the host would select the public care-of address by following the 128 default address selection rule for preferring a public over a 129 temporary address. 131 A socket option has been deemed useful for this purpose, as it 132 enables an application to specify address selection preferences on a 133 per-socket basis. It can also provide the flexibility of enabling 134 and disabling address selection preferences in non-connected (UDP) 135 sockets. The socket option uses a set of flags for specifying 136 address selection preferences. Since the API should not assume a 137 particular implementation method of the address selection [RFC3484] 138 in the network layer or in getaddrinfo(), the corresponding set of 139 flags are also defined for getaddrinfo() as it depends on the source 140 address selection. 142 As a result, this document introduces several flags for address 143 selection preferences that alter the default address selection 144 [RFC3484] for a number of rules. It analyzes the usefulness of 145 providing API functionality for different default address selection 146 rules; it provides API to alter only those rules that are possibly 147 used by certain classes of applications. In addition, it also 148 considers CGA [RFC3972] and non-CGA source addresses when CGA 149 addresses are available in the system. In the future, more source 150 flags may be added to expand the API as the needs may arise. 152 The approach in this document is to allow the application to specify 153 preferences for address selection and not to be able to specify hard 154 requirements: For instance, an application can set a flag to prefer a 155 temporary source address, but if no temporary source addresses are 156 available at the node, a public address would be chosen instead. 158 Specifying hard requirements for address selection would be 159 problematic for several reasons. The major one is that in the vast 160 majority of cases the application would like to be able to 161 communicate even if an address with the 'optimal' attributes is not 162 available. For instance, an application that performs very short, 163 e.g., UDP, transactional exchanges (e.g. DNS queries), might prefer 164 to use a care-of address when running on a mobile host which is away 165 from home since this provides a short round-trip time in many cases. 166 But if the application is running on a mobile host that is at home, 167 or running on a host which isn't providing Mobile IPv6, then it 168 doesn't make sense for the application to fail due to no care-of 169 address being available. Also, in particular when using UDP sockets 170 and the sendto() or sendmsg() primitives, the use of hard 171 requirements would have been problematic, since the set of available 172 IP addresses might very well have changed from when the application 173 called getaddrinfo() until it called sendto() or sendmsg(), which 174 would introduce new failure modes. 176 For the few applications that have hard requirements on the 177 attributes of the IP addresses they use, this document defines a 178 verification function which allows such applications to properly fail 179 to communicate when their address selection requirements are not met. 181 Furthermore, the approach is to define two flags for each rule that 182 can be modified, so that an application can specify its preference 183 for addresses selected as per the rule, the opposite preference (i.e. 184 an address selected as per the rule reverted), or choose not to set 185 either of the flags relating to that rule and leave it up to the 186 system default (section 4). This approach allows different 187 implementations to have different system defaults, and works with 188 getaddrinfo() as well as setsockopt(). (For setsockopt a different 189 approach could have been chosen, but that would still require the 190 same approach for getaddrinfo.) 192 Note that this document does not directly modify the destination 193 address selection rules described in [RFC3484]. An analysis has been 194 done to see which destination address rules may be altered by the 195 applications. Rule number 4(prefer home address), 8(prefer smaller 196 scope), 7(prefer native interfaces) of default address selection 197 document [RFC3484] were taken into consideration for destination 198 address alteration. But, as of this writing there was not enough 199 practical usage for applications to alter destination address 200 selection rules directly by applying the setsockopt() with a 201 preferred destination type of address flag. However, this document 202 does not rule out any possibility of adding flags for preferred 203 destination address selection. However, [RFC3484] destination 204 address selection rules are dependent on source address selections, 205 thus by altering the default source address selection by using the 206 methods described in this document, one indirectly influences the 207 choice of destination address selection. Hence this document 208 explains how getaddrinfo() can be used to select the destination 209 address while taking the preferred source addresses into 210 consideration [Section 11]. 212 This document specifies extensions only to the Basic IPv6 socket API 213 specified in [RFC3493]. The intent is that this document serves as a 214 model for expressing preferences for attributes of IP addresses, that 215 also need to be expressible in other networking API such as those 216 found in middleware systems and the Java environment. Similar model 217 is also applicable for other socket families. 219 2. Definition Of Terms 221 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 222 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 223 document are to be interpreted as described in [RFC2119]. 225 Address preference flag: 226 A flag expressing a preference for a particular type of address 227 (e.g. temporary, public). 229 Opposite flags: 230 Each flag expressing an address preference has a so called 231 "opposite flag" expressing the opposite preference: 233 * home address preference flag is the opposite of the care-of 234 address preference flag. 236 * temporary address preference flag is the opposite of the public 237 address preference flag. 239 * CGA address preference flag is the opposite of the non-CGA 240 address preference flag. 242 Contradictory flags: 243 Any combination of flags including both a flag expressing a given 244 address preference and a flag expressing the opposite preference 245 constitutes Such flags are contradictory by definition of their 246 usefulness with respect to source address selection. For example, 247 consider a set of flags including both the home address preference 248 flag and the care-of address preference flag. When considering 249 source address selection, the selected address can be a home 250 address, or a care-of address, but it cannot be both at the same 251 time. Hence, to prefer an address which is both a home address, 252 and a care-of address, is contradictory. 254 3. Usage Scenario 256 The examples discussed here are limited to applications supporting 257 Mobile IPv6, IPv6 Privacy Extensions and Cryptographically Generated 258 Addresses. Address selection document [RFC3484] recommends that home 259 addresses should be preferred over care-of address when both are 260 configured. However, a mobile node may want to prefer care-of 261 address as source address for DNS query in the foreign network as it 262 normally means a shorter and local return path compared to the route 263 via the mobile node's home-agent when the query contains home address 264 as source address. Another example is IKE application which requires 265 care-of address as its source address for the initial security 266 association pair with Home Agent [RFC3775] while the mobile node 267 boots up at the foreign network and wants to do the key exchange 268 before a successful home-registration. Also a Mobile IPv6 aware 269 application may want to toggle between home address and care-of 270 address depending on its location and state of the application. It 271 may also want to open different sockets and use home address as 272 source address for one socket and care-of address for the others. 274 In a non-mobile environment, an application may similarly prefer to 275 use temporary address as source address for certain cases. By 276 default, the source address selection rule selects "public" address 277 when both are available. For example, an application supporting web 278 browser and mail-server may want to use "temporary" address for the 279 former and "public" address for the mail-server as a mail-server may 280 require reverse path for DNS records for anti-spam rules. 282 Similarly, a node may be configured to use Cryptographically 283 Generated Addresses [RFC3972] by default, as in Secure Neighbor 284 Discovery [RFC3971], but an application may prefer not to use it. 285 For instance, fping [FPING], a debugging tool which tests basic 286 reachability of multiple destinations by sending packets in parallel. 287 These packets may end up initiating neighbor discovery signaling that 288 uses SEND if used with a CGA source address. SEND performs some 289 cryptographic operations to prove ownership of the said CGA address. 290 If the application does not require this feature, it would like to 291 use a non-CGA address to avoid potentially expensive computations 292 performed by SEND. On the other hand, when a node is not configured 293 for CGA as default, an application may prefer using CGA by setting 294 the corresponding preference. 296 4. Design Alternatives 298 Some suggested to have per-application flags instead of per-socket 299 and per-packet flags. However, this design stays with per-socket and 300 per-packet flags for the following reasons: 302 o While some systems have per environment/application flags (such as 303 environment variables in Unix systems) this might not be available 304 in all systems which implement the socket API. 306 o When an application links with some standard library, that library 307 might use the socket API, while the application is unaware of that 308 fact. Mechanisms that would provide per application flags may 309 affect not only the application itself but also the libraries, 310 hence creating risks of unintended consequences. 312 Instead of the pair of 'flag' and 'opposite flag' for each rule that 313 can be modified, the socket option could have been defined to use a 314 single 'flag' value for each rule. This would still have allowed 315 different implementations to have different default settings as long 316 as the applications were coded to first retrieve the default setting 317 (using getsockopt()), and then clear or set the 'flag' according to 318 their preferences, and finally set the new value with setsockopt(). 320 But such an approach would not be possible for getaddrinfo() because 321 all the preferences would need to be expressible in the parameters 322 that are passed with a single getaddrinfo() call. Hence, for 323 consistency, the 'flag' and 'opposite flag' approach is used for both 324 getaddrinfo() and setsockopt(). 326 Thus in this API document, an application has three choices on source 327 address selection: 329 a) Application wants to use an address with flag X : Set flag X; 330 unset opposite/contradictory flags of X if they are set before. 332 b) Application wants to use an address with 'opposite' or 333 contradictory flag of X: Set opposite or contradictory flag of X; 334 unset flag X, if already set. 336 c) Application does not care about the presence of flag X and 337 would like to use default : No need to set any address preference 338 flags through setsockopt() or getaddrinfo() ; unset any address 339 preference flags if they are set before by the same socket. 341 5. Address Preference Flags 343 The following flags are defined to alter or set the default rule of 344 source address selection rules discussed in default address selection 345 specification [RFC3484]. 347 IPV6_PREFER_SRC_HOME /* Prefer Home address as source */ 349 IPV6_PREFER_SRC_COA /* Prefer Care-of address as source */ 351 IPV6_PREFER_SRC_TMP /* Prefer Temporary address as source */ 353 IPV6_PREFER_SRC_PUBLIC /* Prefer Public address as source */ 355 IPV6_PREFER_SRC_CGA /* Prefer CGA address as source */ 357 IPV6_PREFER_SRC_NONCGA /* Prefer a non-CGA address as source */ 359 These flags can be combined together in a flag-set to express more 360 complex address preferences. However such combinations can result in 361 a contradictory flag-set, for example: 363 IPV6_PREFER_SRC_PUBLIC | IPV6_PREFER_SRC_TMP 365 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_COA 367 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_COA | IPV6_PREFER_SRC_TMP 369 IPV6_PREFER_SRC_CGA | IPV6_PREFER_SRC_NONCGA 371 Etc. 373 Example of valid combination of address selection flags are given 374 below: 376 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_PUBLIC 378 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_CGA 380 IPV6_PREFER_SRC_COA | IPV6_PREFER_SRC_PUBLIC | IPV6_PREFER_SRC_CGA 382 IPV6_PREFER_SRC_HOME | IPV6_PREFER_SRC_NONCGA 384 If a flag-set includes a combination of 'X' and 'Y', and if 'Y' is 385 not applicable or available in the system, then the selected address 386 has attribute 'X' and system default for the attribute 'Y'. For 387 example, on a system that has only public addresses, the valid 388 combination of flags: 390 IPV6_PREFER_SRC_TMP | IPV6_PREFER_SRC_HOME 392 would result in the selected address being a public home address, 393 since no temporary addresses are available. 395 6. Additions to the Socket Interface 397 The IPv6 Basic Socket API [RFC3493] defines socket options for IPv6. 398 To allow applications to influence address selection mechanisms this 399 document adds a new socket option at the IPPROTO_IPV6 level. This 400 socket option is called IPV6_ADDR_PREFERENCES. It can be used with 401 setsockopt() and getsockopt() calls to set and get the address 402 selection preferences affecting all packets sent via a given socket. 403 The socket option value (optval) is a 32-bits unsigned integer 404 argument. The argument consists of a number of flags where each flag 405 indicates an address selection preference which modifies one of the 406 rules in the default address selection specification. 408 The following flags are defined to alter or set the default rule of 409 source address selection rules discussed in default address selection 410 specification [RFC3484]. They are defined as a result of including 411 the header: 413 IPV6_PREFER_SRC_HOME /* Prefer Home address as source */ 415 IPV6_PREFER_SRC_COA /* Prefer Care-of address as source */ 417 IPV6_PREFER_SRC_TMP /* Prefer Temporary address as source */ 419 IPV6_PREFER_SRC_PUBLIC /* Prefer Public address as source */ 421 IPV6_PREFER_SRC_CGA /* Prefer CGA address as source */ 423 IPV6_PREFER_SRC_NONCGA /* Prefer a non-CGA address as source */ 425 NOTE: No source preference flag for longest matching prefix is 426 defined here because it is believed to be handled by the policy table 427 defined in the default address selection specification. 429 When the IPV6_ADDR_PREFERENCES is successfully set with setsockopt(), 430 the option value given is used to specify address preference for any 431 connection initiation through the socket and all subsequent packets 432 sent via that socket. If no option is set, the system selects a 433 default value as per default address selection algorithm or by some 434 other equivalent means. 436 Setting contradictory flags at the same time results in the error 437 EINVAL. 439 7. Additions to the protocol-independent nodename translation 441 Section 8 of Default Address Selection [RFC3484] document indicates 442 possible implementation strategies for getaddrinfo() [RFC3493]. One 443 of them suggests that getaddrinfo() collects available source/ 444 destination pair from the network layer after being sorted at the 445 network layer with full knowledge of source address selection. 446 Another strategy is to call down to the network layer to retrieve 447 source address information and then sort the list in the context of 448 getaddrinfo(). 450 This implies that getaddrinfo() should be aware of the address 451 selection preferences of the application, since getaddrinfo() is 452 independent of any socket the application might be using. 454 Thus if an application alters the default address selection rules by 455 using setsockopt() with the IPV6_ADDR_PREFERENCES option, the 456 application should also use the corresponding address selection 457 preference flags with its getaddrinfo() call. 459 For that purpose, the addrinfo data structure defined in Basic IPV6 460 Socket API Extension [RFC3493] has been extended with an extended 461 "ai_eflags" flag-set field to provide the designers freedom of adding 462 more flags as necessary without crowding the valuable bit space in 463 the "ai_flags" flag-set field. The extended addrinfo data structre 464 is defined as a result of including the header: 466 struct addrinfo { 467 int ai_flags; /* input flags */ 468 int ai_family; /* protocol family for socket */ 469 int ai_socktype; /* socket type */ 470 int ai_protocol; /* protocol for socket */ 471 socklen_t ai_addrlen; /* length of socket address */ 472 char *ai_canonname; /* canonical name for hostname */ 473 struct sockaddr *ai_addr; /* socket address for socket */ 474 struct addrinfo *ai_next; /* pointer to next in list */ 475 int ai_eflags; /* Extended flags for special usage */ 476 }; 478 Note that the additional field for extended flags are added at the 479 bottom of the addrinfo structure to preserve binary compatibility of 480 the new functionality with the old applications which use the 481 existing addrinfo data structure. 483 A new flag (AI_EXTFLAGS) is defined for the "ai_flags" flag-set field 484 of the addrinfo data structure to tell the system to look for the 485 "ai_eflags" extended flag-set field in the addrinfo structure. It is 486 defined in the header: 488 AI_EXTFLAGS /* extended flag-set present */ 490 If AI_EXTFLAGS flag is set in "ai_flags" flag-set field of the 491 addrinfo data structure, then the getaddrinfo() implementation MUST 492 look for the "ai_eflags" values stored in the extended flag-set field 493 "ai_eflags" of the addrinfo data structure. The flags stored in the 494 "ai_eflags" field are only meaningful if the AI_EXTFLAGS flag is set 495 in the "ai_flags" flag-set field of the addrinfo data structure. By 496 default, AI_EXTFLAGS is not set in the "ai_flags" flag-set field. If 497 AI_EXTFLAGS is set in the "ai_flags" flag-set field, and the 498 "ai_eflags" extended flag-set field is 0 (zero) or undefined, then 499 AI_EXTFLAGS is ignored. 501 The IPV6 source address preference values (IPV6_PREFER_SRC_*) defined 502 for the IPV6_ADDR_PREFERENCES socket option are also defined as 503 address selection preference flags for the "ai_eflags" extended flag- 504 set field of the addrinfo data structure, so that getaddrinfo() can 505 return matching destination addresses corresponding to the source 506 address preferences expressed by the caller application. 508 Thus, an application passes source address selection hints to 509 getaddrinfo by setting AI_EXTFLAGS in the "ai_flags" field of the 510 addrinfo structure, and the corresponding address selection 511 preference flags (IPV6_PREFER_SRC_*) in the "ai_eflags" field. 513 Currently AI_EXTFLAGS is defined for the AF_INET6 socket protocol 514 family only. But its usage should be extendable to other socket 515 protocol families - such as AF_INET or as appropriate. 517 If contradictory flags such as IPV6_PREFER_SRC_HOME and 518 IPV6_PREFER_SRC_COA are set in ai_eflags, the getaddrinfo() fails and 519 return the value EAI_BADEXTFLAGS defined as a result of including the 520 header. This error value MUST be interpreted into a 521 descriptive text string when passed to the gai_strerror() function 522 [RFC3493]. 524 8. Application Requirements 526 An application should call getsockopt() prior calling setsockopt() if 527 the application needs to be able to restore the socket back to the 528 system default preferences. Note, this is suggested for portability. 529 An application which does not have this requirement can just use 530 getaddrinfo() while specifying its preferences, followed by: 532 uint32_t flags = IPV6_PREFER_SRC_TMP; 534 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 535 (void *) &flags, sizeof (flags)) == -1) { 536 perror("setsockopt IPV6_ADDR_REFERENCES"); 537 } 539 An application which needs to be able to restore the default settings 540 on the socket would instead do this: 542 uint32_t save_flags, flags; 543 int optlen = sizeof (save_flags); 545 /* Save the existing IPv6_ADDR_PREFERENCE flags now */ 547 if (getsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 548 (void *) &save_flags, &optlen) == -1 { 549 perror("getsockopt IPV6_ADDR_REFERENCES"); 550 } 552 /* Set the new flags */ 553 flags = IPV6_PREFER_SRC_TMP; 554 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 555 (void *) &flags, sizeof (flags)) == -1) { 556 perror("setsockopt IPV6_ADDR_REFERENCES"); 557 } 559 /* 560 * 561 * Do some work with the socket here. 562 * 563 */ 565 /* Restore the flags */ 567 if (setsockopt(s, IPPROTO_IPV6, IPV6_ADDR_PREFERENCES, 568 (void *) &save_flags, sizeof (save_flags)) == -1) { 569 perror("setsockopt IPV6_ADDR_REFERENCES"); 570 } 572 Applications should not set contradictory flags at the same time. 574 In order to allow different implementations to do different parts of 575 address selection in getaddrinfo() and in the protocol stack, this 576 specification requires that applications set the semantically 577 equivalent flags when calling getaddrinfo() and setsockopt(). For 578 example, if the application sets the IPV6_PREFER_SRC_COA flag, it 579 MUST use the same for the "ai_eflag" field of the addrinfo data 580 structure when calling getaddrinfo(). If applications are not 581 setting the semantically equivalent flags the behavior of the 582 implementation is undefined. 584 9. Usage Example 586 An example of usage of this API is given below: 588 struct addrinfo hints, *ai, *ai0; 589 uint32_t preferences; 591 preferences = IPV6_PREFER_SRC_TMP; 593 hints.ai_flags |= AI_EXTFLAGS; 594 hints.ai_eflags = preferences; /* Chosen address preference flag */ 595 /* Fill in other hints fields */ 597 getaddrinfo(....,&hints,. &ai0..); 599 /* Loop over all returned addresses and do connect */ 600 for (ai = ai0; ai; ai = ai->ai_next) { 601 s = socket(ai->ai_family, ...); 603 setsockopt(s, IPV6_ADDR_PREFERENCES, (void *) &preferences, 604 sizeof (preferences)); 606 if (connect(s, ai->ai_addr, ai->ai_addrlen) == -1){ 607 close (s); 608 s = -1; 609 continue; 610 } 612 break; 613 } 615 freeaddrinfo(ai0); 617 10. Implementation Notes 619 o Within the same application, if a specific source address is set 620 by either bind() or IPV6_PKTINFO socket option, while at the same 621 time an address selection preference is expressed with the 622 IPV6_ADDR_PREFERENCES socket option, then the source address 623 setting carried by bind() or IPV6_PKTINFO takes precedence over 624 the address selection setting. 626 o setsockopt() and getaddrinfo() should silently ignore any address 627 preference flags that are not supported in the system. For 628 example, a host which does not implement Mobile IPv6, should not 629 fail setsockopt() or getaddrinfo() that specify preferences for 630 home or care-of addresses. The socket option calls should return 631 error (-1) and set errno to EINVAL when contradictory flags values 632 are passed to them. 634 o If an implementation supports both stream and datagram sockets, it 635 should implement the address preference mechanism API described in 636 this document on both types of sockets. 638 o An implementation supporting this API MUST implement both 639 getaddrinfo() extension flags and socket option flags processing 640 for portability of applications. 642 o The following flags are set as default values on a system (which 643 is consistent with [RFC3484] defaults): 645 IPV6_PREFER_SRC_HOME 647 IPV6_PREFER_SRC_PUBLIC 649 IPV6_PREFER_SRC_CGA 651 11. Mapping to Default Address Selection Rules 653 This API defines only those flags that are deemed to be useful by the 654 applications to alter default address selection rules. Thus we 655 discuss the mapping of each set of flags to the corresponding rule 656 number in the address selection document [RFC3484]. 658 Source address selection rule #4 (prefer home address): 660 IPV6_PREFER_SRC_HOME (default) 662 IPV6_PREFER_SRC_COA 664 Source address selection rule #7 (prefer public address) : 666 IPV6_PREFER_SRC_PUBLIC (default) 668 IPV6_PREFER_SRC_TMP 670 At this time, this document does not define flags to alter source 671 address selection rule #2 (prefer appropriate scope for destination) 672 and destination address selection rule #8 (prefer smaller scope) as 673 the implementers felt that there were no practical applications that 674 can take advantage of reverting the scoping rules of IPv6 default 675 address selection. Flags altering other destination address 676 selection rules (#4, prefer home address and #7, prefer native 677 transport) could have applications, but the problem is that the local 678 system cannot systematically determine whether a destination address 679 is a tunnel address for destination rule #7 (although it can when the 680 destination address is one of its own, or can be syntactically 681 recognized as a tunnel address, e.g., a 6to4 address.) The flags 682 defined for source address selection rule #4 (prefer home address) 683 should also take care of destination address selection rule #4. Thus 684 at this point, it was decided not to define flags for these 685 destination rules. 687 Also, note that there is no corresponding destination address 688 selection rule for source address selection rule #7 (prefer public 689 addresses) of default address selection document [RFC3484]. However, 690 this API provides a way for an application to make sure that the 691 source address preference set in setsockopt() is taken into account 692 by the getaddrinfo() function. Let's consider an example to 693 understand this scenario. DA and DB are two global destination 694 addresses and the node has two global source addresses SA and SB 695 through interface A and B respectively. SA is a temporary address 696 while SB is a public address. The application has set 697 IPV6_PREFER_SRC_TMP in the setsockopt() flag. The route to DA points 698 to interface A and route to DB points to interface B. Thus when 699 AI_EXTFLAGS in ai_flags and IPV6_PREFER_SRC_TMP in ai_eflags are set, 700 getaddrinfo() returns DA before DB in the list of destination 701 addresses and thus SA will be used to communicate with the 702 destination DA. Similarly, getaddrinfo() returns DB before DA when 703 AI_EXTFLAGS and ai_eflags are set to IPV6_PREFER_SRC_PUBLIC. Thus 704 the source address preference is taking effect into destination 705 address selection and as well as source address selection by the 706 getaddrinfo() function. 708 The following numerical example clarifies the above further. 710 Imagine a host with two addresses: 712 1234::1:1 public 714 9876::1:2 temporary 716 The destination has the following two addresses: 718 1234::9:3 720 9876::9:4 722 By default getaddrinfo() will return the destination addresses in the 723 order 725 1234::9:3 727 9876::9:4 729 because the public source is preferred and 1234 matches more bits 730 with the public source address. On the other hand, if ai_flags is 731 set to AI_EXTFLAGS and ai_eflags to IPV6_PREFER_SRC_TMP, getaddrinfo 732 will return the addresses in the reverse order since the temporary 733 source address will be preferred. 735 Other source address rules (that are not mentioned here) were also 736 deemed not applicable for changing its default on a per-application 737 basis. 739 12. IPv4-mapped IPv6 Addresses 741 IPv4-mapped IPv6 addresses for AF_INET6 sockets are supported in this 742 API. In some cases the application of IPv4-mapped addresses are 743 limited because the API attributes are IPv6 specific. For example, 744 IPv6 temporary addresses and cryptographically generated addresses 745 have no IPv4 counterparts. Thus the IPV6_PREFER_SRC_TMP or 746 IPV6_PREFER_SRC_CGA are not directly applicable to an IPv4-mapped 747 IPv6 address. However, the IPv4-mapped address support may be useful 748 for mobile-IPv4 applications shifting source address between the home 749 address and the care-of address. Thus the IPV6_PREFER_SRC_COA and 750 IPV6_PREFER_SRC_HOME are applicable to an IPv4-mapped IPv6 address. 751 At this point it is not well understood whether this particular API 752 has any value to IPv4 addresses or AF_INET family of sockets, but 753 similar model still applies to AF_INET socket family if corresponding 754 address flags are defined. 756 13. Validating source address preferences 758 Sometimes an application may have a requirement to only use addresses 759 with some particular attribute, and if no such address is available 760 the application should fail to communicate instead of communicating 761 using the 'wrong' address. In that situation, address selection 762 preferences do not guarantee that the application requirements are 763 met. Instead, the application has to use a new call that binds a 764 socket to the source address that would be selected to communicate 765 with a given destination address, according to its preferences, and 766 then explicitly verify that the chosen address satisfies its 767 requirements using a validation function. Such an application would 768 go through the following steps: 770 1. The application specifies one or more IPV6_PREFER_SRC_* flags and 771 AI_EXTFLAGS ai_flags with getaddrinfo(). 773 2. The application specifies the same IPV6_PREFER_SRC_* flags with 774 setsockopt() 776 3. The application calls the stack to select a source address to 777 communicate with the specified destination address, according to 778 the expressed address selection preferences. This is achieved 779 with a connect() call, or a bind2addrsel() call as specified 780 below. The connect() function must not be used when the 781 application uses connexion-oriented communication (e.g. TCP) and 782 want to ensure that no single packet (e.g. TCP SYN) is sent 783 before the application could verify that its requirements were 784 fulfilled. Instead, the application must use the newly 785 introduced bind2addrsel() call, which binds a socket to the 786 source address that would be selected to communicate with a given 787 destination address according to the application's preferences. 788 For datagram-oriented communications (e.g. UDP), the connect() 789 call can be used since it results in the stack selecting a source 790 address without sending any packet. 792 4. Retrieve the selected source address using the getsockname() API 793 call. 795 5. Verify with the validation function that the retrieved address is 796 satisfactory as specified below. If not, abort the communication 797 e.g., by closing the socket. 799 The binding of the socket to the address that would be selected to 800 communicate with a given destination address according to the 801 application preferences is accomplished via a new binding function 802 defined for this purpose: 804 #include 806 int bind2addrsel(int s, const struct sockaddr *dstaddr, 807 socklen_t dstaddrlen); 809 Where s is the socket which source address selection preferences have 810 been expressed by the application, the dstaddr is a non-NULL pointer 811 to a sockaddr_in6 structure initialized as follows: 813 o sin6_addr is a 128-bit IPv6 destination address with which the 814 local node wants to communicate. 816 o sin6_family MUST be set to AF_INET6. 818 o sin6_scope_id MUST be set if the address is link-local. 820 and dstaddrlen is the size of the sockaddr structure passed as 821 argument, 823 The bind2addrsel() call is defined to return the same values as the 824 bind() call, i.e. 0 if successful, -1 otherwise while the global 825 variable errno is set to indicate the error. The bind2addrsel() call 826 fails for the same reasons that the bind() call. 828 The verification of temporary vs. public, home vs. care-of, CGA vs. 829 not, are performed by a new validation function defined for this 830 purpose: 832 #include 834 short inet6_is_srcaddr(struct sockaddr_in6 *srcaddr, 835 uint32_t flags); 837 Where the flags contains the specified IPV6_PREFER_SRC_* source 838 preference flags, and the srcaddr is a non-NULL pointer to a 839 sockaddr_in6 structure initialized as follows: 841 o sin6_addr is a 128-bit IPv6 address of the local node. 843 o sin6_family MUST be set to AF_INET6. 845 o sin6_scope_id MUST be set if the address is link-local. 847 inet6_is_srcaddr() is defined to return three possible values (0, 1, 848 -1): The function returns true (1) when the IPv6 address corresponds 849 to a valid address in the node and satisfies the given preference 850 flags. If the IPv6 address input value does not correspond to any 851 address in the node or if the flags are not one of the valid 852 preference flags, it returns a failure (-1). If the input address 853 does not match an address which satisfies the preference flags 854 indicated, the function returns false (0.) 856 This function can handle multiple valid preference flags combination 857 as its second parameter, for example IPV6_PREFER_SRC_COA | 858 IPV6_PREFER_SRC_TMP, which means that all flags MUST be satisfied for 859 the result to be true. Contradictory flag values result in a false 860 return value. 862 The function will return true for IPV6_PREFER_SRC_HOME even if the 863 host is not implementing mobile IPv6, as well as for a mobile node 864 which is at home (i.e., does not have any care-of address). 866 14. Summary of New Definitions 868 The following list summarizes the constants, structure, and extern 869 definitions discussed in this memo, sorted by header. 871 AI_EXTFLAGS 872 IPV6_PREFER_SRC_HOME 873 IPV6_PREFER_SRC_COA 874 IPV6_PREFER_SRC_TMP 875 IPV6_PREFER_SRC_PUBLIC 876 IPV6_PREFER_SRC_CGA 877 IPV6_PREFER_SRC_NONCGA 878 EAI_BADEXTFLAGS 879 struct addrinfo{}; 881 IPV6_PREFER_SRC_HOME 882 IPV6_PREFER_SRC_COA 883 IPV6_PREFER_SRC_TMP 884 IPV6_PREFER_SRC_PUBLIC 885 IPV6_PREFER_SRC_CGA 886 IPV6_PREFER_SRC_NONCGA 887 short inet6_is_srcaddr(struct sockaddr_in6 *, 888 uint32_t); 889 int bind2addrsel(int, const struct sockaddr *, 890 socklen_t); 892 15. IANA Considerations 894 This document has no IANA considerations. 896 16. Security Considerations 898 This document conforms to the same security implications as specified 899 in the Basic IPv6 socket API [RFC3493]. Allowing applications to 900 specify a preference for temporary addresses provides per-application 901 (and per-socket) ability to use the privacy benefits of the temporary 902 addresses. The setting of certain address preferences (e.g. not 903 using a CGA address, or not using a temporary address) may be 904 restricted to privileged processes because of security implications. 906 17. Acknowledgments 908 The authors like to thank members of mobile-ip and ipv6 working 909 groups for useful discussion on this topic. Richard Draves and Dave 910 Thaler suggested that getaddrinfo also needs to be considered along 911 with the new socket option. Gabriel Montenegro suggested that CGAs 912 may also be considered in this document. Thanks to Alain Durand, 913 Renee Danson, Alper Yegin, Francis Dupont, Keiichi Shima, Michael 914 Hunter, Sebastien Roy, Robert Elz, Pekka Savola, Itojun, Jim Bound, 915 Jeff Boote, Steve Cipolli, Vlad Yasevich, Mika Liljeberg, Ted Hardie, 916 Vidya Narayanan and Lars Eggert for useful discussions and 917 suggestions. Thanks to Remi Denis-Courmont, Brian Haberman, Brian 918 Haley, Bob Gilligan, Jack McCann, Jim Bound, Jinmei Tatuya, Suresh 919 Krishnan, Hilarie Orman, Geoff Houston, Marcelo Bungulo and Jari 920 Arkko for the review of the document and suggestions for improvement. 922 18. References 924 18.1. Normative references 926 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 927 Requirement Levels", BCP 14, RFC 2119, March 1997. 929 [RFC3484] Draves, R., "Default Address Selection for Internet 930 Protocol version 6 (IPv6)", RFC 3484, February 2003. 932 [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. 933 Stevens, "Basic Socket Interface Extensions for IPv6", 934 RFC 3493, February 2003. 936 18.2. Informative references 938 [FPING] "Fping - a program to ping hosts in parallel", Online web 939 site http://www.fping.com. 941 [RFC2460] Deering, S. and R. Hinden, "Internet Protocol, Version 6 942 (IPv6) Specification", RFC 2460, December 1998. 944 [RFC3041] Narten, T. and R. Draves, "Privacy Extensions for 945 Stateless Address Autoconfiguration in IPv6", RFC 3041, 946 January 2001. 948 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 949 "Advanced Sockets Application Program Interface (API) for 950 IPv6", RFC 3542, May 2003. 952 [RFC3775] Johnson, D., Perkins, C., and J. Arkko, "Mobility Support 953 in IPv6", RFC 3775, June 2004. 955 [RFC3971] Arkko, J., Kempf, J., Zill, B., and P. Nikander, "SEcure 956 Neighbor Discovery (SEND)", RFC 3971, March 2005. 958 [RFC3972] Aura, T., "Cryptographically Generated Addresses (CGA)", 959 RFC 3972, March 2005. 961 Appendix A. Per Packet Address Selection Preference 963 This document discusses setting source address selection preferences 964 on a per socket basis with the new IPV6_ADDR_PREFERENCES socket 965 option used in setsockopt(). The document does not encourage setting 966 the source address selection preference on a per packet basis through 967 the use of ancillary data objects with sendmsg(), or setsockopt() 968 with unconnected datagram sockets. 970 Per-packet source address selection is expensive as the system will 971 have to determine the source address indicated by the application 972 preference before sending each packet, while setsockopt() address 973 preference on a connected socket makes the selection once and uses 974 that source address for all packets transmitted through that socket 975 end-point, as long as the socket option is set. 977 However, this document provides guidelines for those implementations 978 which like to have an option on implementing transmit-side ancillary 979 data object support for altering default source address selection. 980 Therefore, if an application chooses to use the per-packet source 981 address selection, then the implementation should process at the 982 IPPROTO_IPV6 level (cmsg_level) ancillary data object of type 983 (cmsg_type) IPV6_ADDR_PREFERENCES containing as data (cmsg_data[]) a 984 32-bits unsigned integer encoding the source address selection 985 preference flags (e.g. IPV6_PREFER_SRC_COA | 986 IPV6_PREFER_SRC_PUBLIC), in a fashion similar to the advanced IPV6 987 Socket API [RFC3542]. This address selection preference ancillary 988 data object may be present along with other ancillary data objects. 990 The implementation processing the ancillary data object is 991 responsible for selection of preferred source address as indicated in 992 the ancillary data object. Thus, an application can use sendmsg() to 993 pass an address selection preference ancillary data object to the 994 IPv6 layer. The following example shows usage of the ancillary data 995 API for setting address preferences: 997 void *extptr; 998 socklen_t extlen; 999 struct msghdr msg; 1000 struct cmsghdr *cmsgptr; 1001 int cmsglen; 1002 struct sockaddr_in6 dest; 1003 uint32_t flags; 1005 extlen = sizeof(flags); 1006 cmsglen = CMSG_SPACE(extlen); 1007 cmsgptr = malloc(cmsglen); 1008 cmsgptr->cmsg_len = CMSG_LEN(extlen); 1009 cmsgptr->cmsg_level = IPPROTO_IPV6; 1010 cmsgptr->cmsg_type = IPV6_ADDR_PREFERENCES; 1012 extptr = CMSG_DATA(cmsgptr); 1014 flags = IPV6_PREFER_SRC_COA; 1015 memcpy(extptr, &flags, extlen); 1017 msg.msg_control = cmsgptr; 1018 msg.msg_controllen = cmsglen; 1020 /* finish filling in msg{} */ 1022 msg.msg_name = dest; 1024 sendmsg(s, &msg, 0); 1026 Thus when an IPV6_ADDR_PREFERENCES ancillary data object is passed to 1027 sendmsg(), the value included in the object is used to specify 1028 address preference for the packet being sent by sendmsg(). 1030 Appendix B. Changes from previous version of draft 1032 o Note to RFC Editor: This section is to be removed upon publication 1033 as an RFC. 1035 o Added an appendix discussing setting source address selection 1036 preferences on a per packet basis, including via passing a 1037 transmit-side ancillary data object. 1039 o Changed getaddrinfo()usage and removed the AI_PREFER flags. Added 1040 one extended flag field in addrinfo structure and added one 1041 AI_flag in order to save bits. 1043 o Removed scope address preferences as some questioned about 1044 applicability of IPV6_PREFER_SRC and DST scope rules alterations. 1046 o Added -1 return value for inet6_is_srcaddr() for failure 1047 situation. 1049 o Addressed comments by the working group and reviewers of this 1050 draft. 1052 o Added a definition of term for X and not-X flags. 1054 o Changed "not-X flag" by "opposite flag", and "X and not-X flags" 1055 by by "contradictory flags" 1057 o updated rationale why not to deal with native transport 1058 destination address selection rule. 1060 Appendix C. Intellectual Property Statement 1062 This document only defines a source preference flag to choose 1063 Cryptographically Generated Address (CGA) as source address when 1064 applicable. CGA are obtained using public keys and hashes to prove 1065 address ownership. Several IPR claims have been made about such 1066 methods. 1068 Authors' Addresses 1070 Erik Nordmark 1071 Sun Microsystems, Inc. 1072 4150 Network Circle, UMPK17-308 1073 Santa Clara, CA 95054 1074 USA 1076 Email: Erik.Nordmark@Sun.COM 1078 Samita Chakrabarti 1079 Azaire Networks 1080 3121 Jay Street, Suite 210 1081 Santa Clara, CA 95054 1082 USA 1084 Email: samitac2@gmail.com 1086 Julien Laganier 1087 DoCoMo Euro-Labs 1088 Landsbergerstrasse 312 1089 D-80687 Muenchen 1090 Germany 1092 Email: julien.IETF@laposte.net 1094 Full Copyright Statement 1096 Copyright (C) The IETF Trust (2007). 1098 This document is subject to the rights, licenses and restrictions 1099 contained in BCP 78, and except as set forth therein, the authors 1100 retain all their rights. 1102 This document and the information contained herein are provided on an 1103 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1104 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1105 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1106 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1107 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1108 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1110 Intellectual Property 1112 The IETF takes no position regarding the validity or scope of any 1113 Intellectual Property Rights or other rights that might be claimed to 1114 pertain to the implementation or use of the technology described in 1115 this document or the extent to which any license under such rights 1116 might or might not be available; nor does it represent that it has 1117 made any independent effort to identify any such rights. Information 1118 on the procedures with respect to rights in RFC documents can be 1119 found in BCP 78 and BCP 79. 1121 Copies of IPR disclosures made to the IETF Secretariat and any 1122 assurances of licenses to be made available, or the result of an 1123 attempt made to obtain a general license or permission for the use of 1124 such proprietary rights by implementers or users of this 1125 specification can be obtained from the IETF on-line IPR repository at 1126 http://www.ietf.org/ipr. 1128 The IETF invites any interested party to bring to its attention any 1129 copyrights, patents or patent applications, or other proprietary 1130 rights that may cover technology that may be required to implement 1131 this standard. Please address the information to the IETF at 1132 ietf-ipr@ietf.org. 1134 Acknowledgment 1136 Funding for the RFC Editor function is provided by the IETF 1137 Administrative Support Activity (IASA).