idnits 2.17.1 draft-ietf-v6ops-application-transition-03.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 3667, Section 5.1 on line 21. -- Found old boilerplate from RFC 3978, Section 5.5 on line 1483. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1459. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1466. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1472. ** The document seems to lack an RFC 3978 Section 5.1 IPR Disclosure Acknowledgement -- however, there's a paragraph with a matching beginning. Boilerplate error? ** This document has an original RFC 3978 Section 5.4 Copyright Line, instead of the newer IETF Trust Copyright according to RFC 4748. ** This document has an original RFC 3978 Section 5.5 Disclaimer, instead of the newer disclaimer which includes the IETF Trust according to RFC 4748. ** The document uses RFC 3667 boilerplate or RFC 3978-like boilerplate instead of verbatim RFC 3978 boilerplate. After 6 May 2005, submission of drafts without verbatim RFC 3978 boilerplate is not accepted. The following non-3978 patterns matched text found in the document. That text should be removed or replaced: By submitting this Internet-Draft, I certify that any applicable patent or other IPR claims of which I am aware have been disclosed, or will be disclosed, and any of which I become aware will be disclosed, in accordance with RFC 3668. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- ** The document seems to lack a 1id_guidelines paragraph about 6 months document validity -- however, there's a paragraph with a matching beginning. Boilerplate error? == No 'Intended status' indicated for this document; assuming Proposed Standard == The page length should not exceed 58 lines per page, but there was 29 longer pages, the longest (page 2) being 61 lines Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack an IANA Considerations section. (See Section 2.2 of https://www.ietf.org/id-info/checklist for how to handle the case when there are no actions for IANA.) == There are 3 instances of lines with non-RFC6890-compliant IPv4 addresses in the document. If these are example addresses, they should be changed. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the RFC 3978 Section 5.4 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 2004) is 7248 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: 'RFC2460' is mentioned on line 742, but not defined ** Obsolete undefined reference: RFC 2460 (Obsoleted by RFC 8200) == Missing Reference: 'RFC2133' is mentioned on line 876, but not defined ** Obsolete undefined reference: RFC 2133 (Obsoleted by RFC 2553) == Missing Reference: 'MAXSOCK' is mentioned on line 1071, but not defined == Unused Reference: 'RFC 3493' is defined on line 1248, but no explicit reference was found in the text == Unused Reference: 'RFC 3542' is defined on line 1252, but no explicit reference was found in the text == Unused Reference: 'RFC 2460' is defined on line 1264, but no explicit reference was found in the text ** Downref: Normative reference to an Informational RFC: RFC 3493 ** Downref: Normative reference to an Informational RFC: RFC 3542 ** Obsolete normative reference: RFC 2767 (ref. 'BIS') (Obsoleted by RFC 6535) ** Obsolete normative reference: RFC 3338 (ref. 'BIA') (Obsoleted by RFC 6535) ** Obsolete normative reference: RFC 2460 (Obsoleted by RFC 8200) ** Obsolete normative reference: RFC 3484 (Obsoleted by RFC 6724) ** Obsolete normative reference: RFC 3513 (Obsoleted by RFC 4291) -- Obsolete informational reference (is this intentional?): RFC 2732 (Obsoleted by RFC 3986) -- Obsolete informational reference (is this intentional?): RFC 2821 (Obsoleted by RFC 5321) -- Obsolete informational reference (is this intentional?): RFC 2766 (ref. 'NAT-PT') (Obsoleted by RFC 4966) Summary: 16 errors (**), 0 flaws (~~), 10 warnings (==), 11 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 1 v6ops Working Group M-K. Shin (ed.) 2 INTERNET DRAFT ETRI/NIST 3 Expires: December 2004 Y-G. Hong 4 ETRI 5 J. Hagino 6 IIJ 7 P. Savola 8 CSC/FUNET 9 E. M. Castro 10 GSYC/URJC 11 June 2004 13 Application Aspects of IPv6 Transition 14 16 Status of this Memo 18 By submitting this Internet-Draft, I certify that any applicable 19 patent or other IPR claims of which I am aware have been disclosed, 20 and any of which I become aware will be disclosed, in accordance 21 with RFC 3668. 23 Internet-Drafts are working documents of the Internet Engineering 24 Task Force (IETF), its areas, and its working groups. Note that 25 other groups may also distribute working documents as Internet- 26 Drafts. 28 Internet-Drafts are draft documents valid for a maximum of six 29 months and may be updated, replaced, or obsoleted by other docu- 30 ments at any time. It is inappropriate to use Internet-Drafts as 31 reference material or to cite them other than as "work in 32 progress." 34 The list of current Internet-Drafts can be accessed at 35 http://www.ietf.org/ietf/1id-abstracts.txt. 37 The list of Internet-Draft Shadow Directories can be accessed at 38 http://www.ietf.org/shadow.html. 40 This Internet-Draft will expire on December 2004. 42 Abstract 44 As IPv6 networks are deployed and the network transition discussed, 45 one should also consider how to enable IPv6 support in applications 46 running on IPv6 hosts, and the best strategy to develop IP protocol 47 support in applications. This document specifies scenarios and 48 aspects of application transition. It also proposes guidelines on 49 how to develop IP version-independent applications during the 50 transition period. 52 Table of Contents: 54 1. Introduction .............................................. 3 55 2. Overview of IPv6 Application Transition ................... 3 56 3. Problems with IPv6 Application Transition ................. 5 57 3.1 IPv6 support in the OS and applications are unrelated.... 5 58 3.2 DNS does not indicate which IP version will be used ..... 5 59 3.3 Supporting many versions of an application is difficult ..6 60 4. Description of Transition Scenarios and Guidelines ........ 6 61 4.1 IPv4 Applications in a Dual-stack Node .................. 7 62 4.2 IPv6 Applications in a Dual-stack Node .................. 7 63 4.3 IPv4/IPv6 Applications in a Dual-stack Node .............10 64 4.4 IPv4/IPv6 Applications in an IPv4-only Node .............11 65 5. Application Porting Considerations ........................11 66 5.1 Presentation Format for an IP address ...................12 67 5.2 Transport Layer API .....................................13 68 5.3 Name and Address Resolution .............................14 69 5.4 Specific IP Dependencies ............................... 14 70 5.4.1 IP Address Selection .................................14 71 5.4.2 Application Framing ..................................15 72 5.4.3 Storage of IP addresses ..............................15 73 5.5 Multicast Applications ..................................16 74 6. Developing IP version-independent Applications ............17 75 6.1 IP version-independent Structures .......................17 76 6.2 IP version-independent APIs .............................18 77 6.2.1 Example of Overly Simplistic TCP Server Application ..19 78 6.2.2 Example of Overly Simplistic TCP Client Application ..20 79 6.2.3 Binary/Presentation Format Conversion ................21 80 6.3 Iterated Jobs for Finding the Working Address ...........22 81 6.3.1 Example of TCP Server Application ....................22 82 6.3.2 Example of TCP Client Application ....................23 83 7. Transition Mechanism Considerations .......................24 84 8. Security Considerations ...................................25 85 9. Acknowledgements .........................................25 86 10. References ...............................................25 87 Authors' Addresses ...........................................27 88 Appendix A. Other Binary/Presentation Format Conversions .....28 89 A.1 Binary to Presentation using inet_ntop() ................28 90 A.2 Presentation to Binary using inet_pton() ................29 92 1. Introduction 94 As IPv6 is introduced in the IPv4-based Internet, several general 95 issues arise such as routing, addressing, DNS, scenarios, etc. 97 One important key to a successful IPv6 transition is the 98 compatibility with the large installed base of IPv4 hosts and 99 routers. This issue had been already been extensively studied, and 100 the work is still in progress. In particular, [2893BIS] describes 101 the basic transition mechanisms, dual-stack deployment and 102 tunneling. In addition, various kinds of transition mechanisms 103 have been developed for the transition to an IPv6 network. 104 However, these transition mechanisms take no stance on whether 105 applications support IPv6 or not. 107 This document specifies application aspects of IPv6 transition. 108 That is, two inter-related topics are covered: 110 1. How different network transition techniques affect 111 applications, and what are the strategies for applications 112 to support IPv6 and IPv4. 114 2. How to develop IPv6-capable or protocol-independent 115 applications ("application porting guidelines"). 117 Applications will need to be modified to support IPv6 (and IPv4), 118 using one of a number of techniques described in sections 2-4. 119 Some guidelines to develop such application are then presented in 120 sections 5 and 6. 122 2. Overview of IPv6 Application Transition 124 The transition of an application can be classifed using four 125 different cases (excluding the first case when there is no IPv6 126 support either in the application or the operating system), as 127 follows: 129 +-------------------+ 130 | appv4 | (appv4 - IPv4-only applications) 131 +-------------------+ 132 | TCP / UDP / others| (transport protocols - TCP, UDP, 133 +-------------------+ SCTP, DCCP, etc.) 134 | IPv4 | IPv6 | (IP protocols supported/enabled in the OS) 135 +-------------------+ 137 Case 1. IPv4 applications in a dual-stack node 138 +-------------------+ (appv4 - IPv4-only applications) 139 | appv4 | appv6 | (appv6 - IPv6-only applications) 140 +-------------------+ 141 | TCP / UDP / others| (transport protocols - TCP, UDP, 142 +-------------------+ SCTP, DCCP, etc.) 143 | IPv4 | IPv6 | (IP protocols supported/enabled in the OS) 144 +-------------------+ 146 Case 2. IPv4-only applications and IPv6-only applications 147 in a dual-stack node 149 +-------------------+ 150 | appv4/v6 | (appv4/v6 - applications supporting 151 +-------------------+ both IPv4 and IPv6) 152 | TCP / UDP / others| (transport protocols - TCP, UDP, 153 +-------------------+ SCTP, DCCP, etc.) 154 | IPv4 | IPv6 | (IP protocols supported/enabled in the OS) 155 +-------------------+ 157 Case 3. Applications supporting both IPv4 and IPv6 158 in a dual-stack node 160 +-------------------+ 161 | appv4/v6 | (appv4/v6 - applications supporting 162 +-------------------+ both IPv4 and IPv6) 163 | TCP / UDP / others| (transport protocols - TCP, UDP, 164 +-------------------+ SCTP, DCCP, etc.) 165 | IPv4 | (IP protocols supported/enabled in the OS) 166 +-------------------+ 168 Case 4. Applications supporting both IPv4 and IPv6 169 in an IPv4-only node 171 Figure 1. Overview of Application Transition 173 Figure 1 shows the cases of application transition. 175 Case 1 : IPv4-only applications in a dual-stack node. 176 IPv6 protocol is introduced in a node, but 177 applications are not yet ported to support IPv6. 179 Case 2 : IPv4-only applications and IPv6-only applications 180 in a dual-stack node. 181 Applications are ported for IPv6-only. Therefore 182 there are two similar applications, one for each 183 protocol version (e.g., ping and ping6). 185 Case 3 : Applications supporting both IPv4 and IPv6 in a dual 186 stack node. 187 Applications are ported for both IPv4 and IPv6 support. 188 Therefore, the existing IPv4 applications can be 189 removed. 191 Case 4 : Applications supporting both IPv4 and IPv6 in an 192 IPv4-only node. 193 Applications are ported for both IPv4 and IPv6 support, 194 but the same applications may also have to work when 195 IPv6 is not being used (e.g. disabled from the OS). 197 Note that this draft does not address DCCP and SCTP considerations 198 at this phase. 200 3. Problems with IPv6 Application Transition 202 There are several reasons why the transition period between IPv4 203 and IPv6 applications may not be straightforward. These issues are 204 described in this section. 206 3.1 IPv6 support in the OS and applications are unrelated 208 Considering the cases described in the previous section, IPv4 and 209 IPv6 protocol stacks in a node is likely to co-exist for a long 210 time. 212 Similarly, most applications are expected to be able to handle both 213 IPv4 and IPv6 during another, unrelated long time period. That is, 214 the operating system being dual stack does not mean having both 215 IPv4 and IPv6 applications. Therefore, IPv6-capable application 216 transition may be independent of protocol stacks in a node. 218 It is even probable that applications capable of both IPv4 and IPv6 219 will have to work properly in IPv4-only nodes (whether the IPv6 220 protocol is completely disabled or there is no IPv6 connectivity at 221 all). 223 3.2 DNS does not indicate which IP version will be used 225 The role of the DNS name resolver in a node is to get the list of 226 destination addresses. DNS queries and responses are sent using 227 either IPv4 or IPv6 to carry the queries, regardless of the 228 protocol version of the data records [DNSTRANS]. 230 The issue of DNS name resolution related to application transition, 231 is that a client application can not be certain of the version of 232 the peer application by only doing a DNS name lookup. For example, 233 if a server application does not support IPv6 yet, but runs on a 234 dual-stack machine for other IPv6 services, and this host is listed 235 with a AAAA record in the DNS, the client application will fail to 236 connect to the server application. This is caused by a mis-match 237 between the DNS query result (i.e. IPv6 addresses) and a server 238 application version (i.e. IPv4). 240 Using SRV records would avoid these problems. Unfortunately, they 241 are not sufficiently widely used to be applicable in most cases. 242 Hence an operational technique is to use "service names" in the 243 DNS, that is, if a node is offering multiple services, but only 244 some of them over IPv6, add a DNS name for each of these services 245 (with the associated A/AAAA records), not just a single name for 246 the whole node, also including the AAAA records. However, the 247 applications cannot depend on such operational practices. 249 In consequence, the application should request all IP addresses 250 without address family constraints and try all the records returned 251 from the DNS, in some order, until a working address is found. In 252 particular, the application has to be able to handle all IP 253 versions returned from the DNS. This issue is discussed in more 254 detail in [DNSOPV6]. 256 3.3 Supporting many versions of an application is difficult 258 During the application transition period, system administrators may 259 have various versions of the same application (an IPv4-only 260 application, an IPv6-only application, or an application supporting 261 both IPv4 and IPv6). 263 Typically one cannot know which IP versions must be supported prior 264 to doing a DNS lookup *and* trying (see section 3.2) the addresses 265 returned. Therefore, the local users have a difficulty selecting 266 the right application version supporting the exact IP version 267 required if multiple versions of the same application are 268 available. 270 To avoid problems with one application not supporting the specified 271 protocol version, it is desirable to have hybrid applications 272 supporting both of the protocol versions. 274 One could argue that an alternative approach for local client 275 applications could be to have a "wrapper application" which 276 performs certain tasks (like figures out which protocol version 277 will be used) and calls the IPv4/IPv6-only applications as 278 necessary. In other words, such applications would perform 279 connection establishment (or similar), and pass the opened socket 280 to the other application. However, as these applications would 281 have to do more than just perform a DNS lookup or figure out the 282 literal IP address given, they will get complex -- likely much more 283 complex than writing a hybrid application. Furthermore, "wrapping" 284 applications which perform complex operations with IP addresses 285 (like FTP clients) might be even more challenging or even 286 impossible. In summary, wrapper applications does not look like a 287 robust approach for application transition. 289 4. Description of Transition Scenarios and Guidelines 291 Once the IPv6 network is deployed, applications supporting IPv6 can 292 use IPv6 network services and establish IPv6 connections. However, 293 upgrading every node to IPv6 at the same time is not feasible and 294 transition from IPv4 to IPv6 will be a gradual process. 296 Dual-stack nodes are one of the ways to maintain IPv4 compatibility 297 in unicast communications. In this section we will analyze 298 different application transition scenarios (as introduced in 299 section 2) and guidelines to maintain interoperability between 300 applications running in different types of nodes. 302 4.1 IPv4 Applications in a Dual-stack Node 304 This scenario happens if the IPv6 protocol is added in a node but 305 IPv6-capable applications aren't yet available or installed. 306 Although the node implements the dual stack, IPv4 applications can 307 only manage IPv4 communications. Then, IPv4 applications can only 308 accept/establish connections from/to nodes which implement an IPv4 309 stack. 311 In order to allow an application to communicate with other nodes 312 using IPv6, the first priority is to port applications to IPv6. 314 In some cases (e.g. no source code is available), existing IPv4 315 applications can work if the Bump-in-the-Stack [BIS] or Bump-in- 316 the-API [BIA] mechanism is installed in the node. We strongly 317 recommend that application developers sould not use these 318 mechanisms when application source code is available. Also, it 319 should not be used as an excuse not to port software or delay 320 porting. 322 When [BIA] or [BIS] is used, the problem described in section 3.2 323 --the IPv4 client in a [BIS]/[BIA] node trying to connect to an 324 IPv4 server in a dual stack system-- arises. However, one can rely 325 on the [BIA]/[BIS] mechanism, which should cycle through all the 326 addresses instead of applications. 328 [BIS] or [BIA] does not work with all kinds of applications. In 329 particular, the applications which exchange IP addresses as 330 application data (e.g., FTP). These mechanisms provide IPv4 331 temporary addresses to the applications and locally make a 332 translation between IPv4 and IPv6 communication. Hence, these IPv4 333 temporary addresses are only valid in the node scope." 335 4.2 IPv6 Applications in a Dual-stack Node 337 As we have seen in the previous section, applications should be 338 ported to IPv6. The easiest way to port an IPv4 application is to 339 substitute the old IPv4 API references with the new IPv6 APIs with 340 one-to-one mapping. This way the application will be IPv6-only. 341 This IPv6-only source code can not work in IPv4-only nodes, so the 342 old IPv4 application should be maintained in these nodes. Then, we 343 will get two similar applications working with different protocol 344 versions, depending on the node they are running (e.g., telnet and 345 telnet6). This case is undesirable since maintaining two versions 346 of the same source code per application could be a difficult task. 347 In addition, this approach would cause problems for the users when 348 having to select which version of the application to use, as 349 described in section 3.3. 351 Most implementations of dual stack allow IPv6-only applications to 352 interoperate with both IPv4 and IPv6 nodes. IPv4 packets going to 353 IPv6 applications on a dual-stack node reach their destination 354 because their addresses are mapped to IPv6 ones using IPv4-mapped 355 IPv6 addresses: the IPv6 address ::FFFF:x.y.z.w represents the IPv4 356 address x.y.z.w. 358 +----------------------------------------------+ 359 | +------------------------------------------+ | 360 | | | | 361 | | IPv6-only applications | | 362 | | | | 363 | +------------------------------------------+ | 364 | | | 365 | +------------------------------------------+ | 366 | | | | 367 | | TCP / UDP / others (SCTP, DCCP, etc.) | | 368 | | | | 369 | +------------------------------------------+ | 370 | IPv4-mapped | | IPv6 | 371 | IPv6 addresses | | addresses | 372 | +--------------------+ +-------------------+ | 373 | | IPv4 | | IPv6 | | 374 | +--------------------+ +-------------------+ | 375 | IPv4 | | | 376 | adresses | | | 377 +--------------|-----------------|-------------+ 378 | | 379 IPv4 packets IPv6 packets 381 We will analyze the behaviour of IPv6-applications which exchange 382 IPv4 packets with IPv4 applications using the client/server model. 383 We consider the default case when the IPV6_V6ONLY socket option has 384 not been set. This default behavior of IPv6 applications in these 385 dual-stack nodes allows a limited amount of IPv4 communication 386 using the IPv4-mapped IPv6 addresses. 388 IPv6-only server: 389 When an IPv4 client application sends data to an 390 IPv6-only server application running on a dual-stack 391 node using the wildcard address, the IPv4 client address 392 is interpreted as the IPv4-mapped IPv6 address in the 393 dual-stack node. This allows the IPv6 application to 394 manage the communication. The IPv6 server will use this 395 mapped address as if it were a regular IPv6 address, and 396 a usual IPv6 connection. However, IPv4 packets will be 397 exchanged between the nodes. Kernels with dual stack 398 properly interpret IPv4-mapped IPv6 addresses as IPv4 399 ones and vice versa. 401 IPv6-only client: 402 IPv6-only client applications in a dual-stack node will 403 not get IPv4-mapped addresses from the hostname 404 resolution API functions unless a special hint, 405 AI_V4MAPPED, is given. If given, the IPv6 client will 406 use the returned mapped address as if it were a regular 407 IPv6 address, and a usual IPv6 connection. However, again 408 IPv4 packets will be exchanged between applications. 410 Respectively, with IPV6_V6ONLY set, an IPv6-only server application 411 will only communicate with IPv6 nodes, and an IPv6-only client with 412 IPv6 servers, as the mapped addresses have been disabled. This 413 option could be useful if applications use new IPv6 features, such 414 as Flow Label. If communication with IPv4 is needed, either 415 IPV6_V6ONLY must not be used, or dual-stack applications be used, 416 as described in section 4.3. 418 There are some implementations of dual-stack which do not allow 419 IPv4-mapped IPv6 addresses to be used for interoperability between 420 IPv4 and IPv6 applications. In that case, there are two ways to 421 handle the problem: 423 1. deploy two different versions of the application (possibly 424 attached with '6' in the name), or 426 2. deploy just one application supporting both protocol versions 427 as described in the next section. 429 The first method is not recommended because of a significant amount 430 of problems associated with selecting the right applications. This 431 problems are described in sections 3.2 and 3.3. 433 Therefore, there are actually two distinct cases to consider when 434 writing one application to support both protocols: 436 1. whether the application can (or should) support both IPv4 437 and IPv6 through IPv4-mapped IPv6 addresses, or should the 438 applications support both explicitly (see section 4.3), and 440 2. whether the systems where the applications are used support 441 IPv6 at all or not (see section 4.4). 443 Note that some systems will disable (by default) support for 444 internal IPv4-mapped IPv6 addresses. The security concerns 445 regarding IPv4-mapped IPv6 addresses on the wire are legitimate but 446 disabling it internally breaks one transition mechanism for server 447 applications which were originally written to bind() and listen() 448 to a single socket using a wildcard address. This forces the 449 software developer to rewrite the daemon to create 2 separate 450 sockets, one for IPv4 only and the other for IPv6 only, and then 451 use select(). However, enabling mapping of IPv4 addresses on any 452 particular system is controlled by the OS owner and not 453 necessarilly by a developer. This complicates the developer's work 454 as he now has to rewrite the daemon network code to handle both 455 environments, even for the same OS. 457 4.3 IPv4/IPv6 Applications in a Dual-stack Node 459 Applications should be ported to support both IPv4 and IPv6; such 460 applications are sometimes called IP version-independent 461 applications. After that, the existing IPv4-only applications 462 could be removed. Since we have only one version of each 463 application, the source code will be typically easy to maintain and 464 to modify, and there are no problems managing which application to 465 select for which communication. 467 This transition case is the most advisable. During the IPv6 468 transition period applications supporting both IPv4 and IPv6 should 469 be able to communicate with other applications, irrespective of the 470 versions of the protocol stack or the application in the node. 471 Dual applications allow more interoperability between heterogeneous 472 applications and nodes. 474 If the source code is written in a protocol-independent way, 475 without dependencies on either IPv4 or IPv6, applications will be 476 able to communicate with any combination of applications and types 477 of nodes. 479 Implementations typically by-default prefer IPv6 if the remote node 480 and application support it. However, if IPv6 connections fail, 481 version-independent applications will automatically try IPv4 ones. 482 The resolver returns a list of valid addresses for the remote node 483 and applications can iterate through all of them until connection 484 succeeds. 486 Applications writers should be aware of this typical by-default 487 ordering, but the applications themselves typically need not be 488 aware of the the local protocol ordering [RFC 3484]. 490 If the source code is written in a protocol-dependent way, the 491 application will support IPv4 and IPv6 explicitly using 2 separate 492 sockets. Note that there are some differences in bind() 493 implementation, whether you can first bind to the IPv6, and then 494 IPv4, wildcard addresses. It can be a pain to write applications 495 that cope with this. If IPV6_V6ONLY is implemented, this becomes 496 simpler. The reason the IPv4 wildcard bind fails on some systems is 497 that the IPv4 address space is embedded into IPv6 address space 498 when using IPv4-mapped IPv6 addresses. 500 A more detailed porting guideline is described in section 6. 502 4.4. IPv4/IPv6 Applications in an IPv4-only Node 504 As the transition is likely to happen over a longer timeframe, 505 applications that have already been ported to support both IPv4 and 506 IPv6 may be run on IPv4-only nodes. This would typically be done to 507 avoid having to support two application versions for older and 508 newer operating systems, or to support the case that the user wants 509 to disable IPv6 for some reason. 511 The most important case is the application support on systems where 512 IPv6 support can be dynamically enabled or disabled by the users. 513 Applications on such a system should be able to handle the 514 situation where IPv6 would not be enabled. The secondary scenario 515 is when an application could be deployed on older systems which do 516 not support IPv6 at all (even the basic getaddrinfo etc. APIs). In 517 that case the application designer has to make a case-by-case 518 judgement call whether it makes sense to have compile-time toggle 519 between an older and newer API (having to support both in the 520 code), or whether to provide getaddrinfo etc. function support on 521 older platforms as part of the application libraries. 523 Depending on how application/operating system support is done, some 524 may want to ignore this case, but usually no assumptions can be 525 made and applications should also work in this scenario. 527 An example is an application that issues a socket() command, first 528 trying AF_INET6 and then AF_INET. However, if the kernel does not 529 have IPv6 support, the call will result in an EPROTONOSUPPORT or 530 EAFNOSUPPORT error. Typically, encountering errors like these leads 531 to exiting the socket loop, and AF_INET will not even be tried. 532 The application will need to handle this case or build the loop in 533 such a way that errors are ignored until the last address family. 535 So, this case is just an extension of the IPv4/IPv6 support in the 536 previous case, covering one relatively common but often ignored 537 case. 539 5. Application Porting Considerations 541 The minimum changes to IPv4 applications to work with IPv6 are 542 based on the different size and format of IPv4 and IPv6 addresses. 544 Applications have been developed with the assumption they would use 545 IPv4 as their network protocol. This assumption results in many IP 546 dependencies through source code. 548 The following list summarizes the more common IP version 549 dependencies in applications: 551 a) Presentation format for an IP address: it is an ASCII string 552 which represents the IP address, dotted-decimal string 553 for IPv4 and hexadecimal string for IPv6. 555 b) Transport layer API: functions to establish communications 556 and to exchange information. 558 c) Name and address resolution: conversion functions between 559 hostnames and IP addresses, and vice versa. 561 d) Specific IP dependencies: more specific IP version 562 dependencies, such as: IP address selection, 563 application framing, storage of IP addresses. 565 e) Multicast applications: one must find the IPv6 equivalents to 566 the IPv4 multicast addresses, and use the right socket 567 configuration options. 569 In the following subsections, the problems with the aforementioned 570 IP version dependencies are analyzed. Although application source 571 code can be ported to IPv6 with minimum changes related to IP 572 addresses, some recommendations are given to modify the source code 573 in a protocol independent way, which will allow applications to 574 work using both IPv4 and IPv6. 576 5.1 Presentation Format for an IP Address 578 Many applications use IP addresses to identify network nodes and to 579 establish connections to destination addresses. For instance, using 580 the client/server model, clients usually need an IP address as an 581 application parameter to connect to a server. This IP address is 582 usually provided in the presentation format, as a string. There 583 are two problems, when porting the presentation format for an IP 584 address: the allocated memory and the management of the 585 presentation format. 587 Usually, the allocated memory to contain an IPv4 address 588 representation as a string is unable to contain an IPv6 address. 589 Applications should be modified to prevent buffer overflows made 590 possible by the larger IPv6 address. 592 IPv4 and IPv6 do not use the same presentation format. IPv4 uses a 593 dot (.) to separate the four octets written in decimal notation and 594 IPv6 uses a colon (:) to separate each pair of octets written in 595 hexadecimal notation [RFC 3513]. In cases where it one must be 596 able to specify e.g., port numbers with the address (see below), it 597 may be desirable to require placing the address inside the square 598 brackets [TextRep]. 600 A particular problem with IP address parsers comes when the input 601 is actually a combination of IP address and port number. With IPv4 602 these are often coupled with a colon such as "192.0.2.1:80". 603 However, such an approach would be ambiguous with IPv6 as colons 604 are already used to structure the address. 606 Therefore, the IP address parsers which take the port number 607 separated with a colon should represent IPv6 addresses somehow. 608 One way is to enclose the address in brackets, as is done with 609 Uniform Resource Locators (URLs) [RFC 2732], like 610 http://[2001:db8::1]:80. 612 Some applications also need to specify IPv6 prefixes and lengths; 613 the prefix length should be inserted outside of the square 614 brackets, if used, like [2001:db8::]/64 or 2001:db8::/64 -- not for 615 example [2001:db8::/64]. Note that prefix/length notation is 616 syntactically indistinguishable from a legal URI; therefore the 617 prefix/length notation must not be used when it isn't clear from 618 the context that it's used to specify the prefix and length and 619 not e.g., a URI. 621 In some specific cases, it may be necessary to give a zone 622 identifier as part of the address, like fe80::1%eth0. In general, 623 applications should not need to parse these identifiers. 625 The IP address parsers should support enclosing the IPv6 address in 626 brackets even when it's not used in conjunction with a port number, 627 but requiring that the user always gives a literal IP address 628 enclosed in brackets is not recommended. 630 One should note that some applications may also represent IPv6 631 address literals differently; for example, SMTP [RFC 2821] uses 632 [IPv6:2001:db8::1]. 634 Note that the use of address literals is strongly discouraged for 635 general purpose direct input to the applications; host names and 636 DNS should be used instead. 638 5.2 Transport Layer API 640 Communication applications often include a transport module that 641 establishes communications. Usually this module manages everything 642 related to communications and uses a transport layer API, typically 643 as a network library. When porting an application to IPv6, most 644 changes should be made in this application transport module in 645 order to be adapted to the new IPv6 API. 647 In the general case, porting an existing application to IPv6 648 requires an examination of the following issues related to the API: 650 - Network information storage: IP address data structures. 651 The new structures must contain 128-bit IP addresses. The use of 652 generic address structures, which can store any address family, 653 is recommended. 655 Sometimes special addresses are hard-coded in the application 656 source code; developers should pay attention to them in order to 657 use the new address format. Some of these special IP addresses 658 are: wildcard local, loopback and broadcast. IPv6 does not have 659 the broadcast addresses, so applications can use multicast 660 instead. 662 - Address conversion functions. 663 The address conversion functions convert the binary address 664 representation to the presentation format and vice versa. The 665 new conversion functions are specified to the IPv6 address 666 format. 668 - Communication API functions. 669 These functions manage communications. Their signatures are 670 defined based on a generic socket address structure. The 671 same functions are valid for IPv6, however, the IP address data 672 structures used when calling these functions require the 673 updates. 675 - Network configuration options. 676 They are used when configuring different communication models 677 for Input/Output (I/O) operations (blocking/nonblocking, I/O 678 multiplexing, etc.) and should be translated to the IPv6 ones. 680 5.3 Name and Address Resolution 682 From the application point of view, the name and address resolution 683 is a system-independent process. An application calls functions in 684 a system library, the resolver, which is linked into the 685 application when this is built. However, these functions use IP 686 address structures, which are protocol dependent, and must be 687 reviewed to support the new IPv6 resolution calls. 689 There are two basic resolution functions. The first function 690 returns a list of all configured IP addresses for a hostname. These 691 queries can be constrained to one protocol family, for instance 692 only IPv4 or only IPv6 addresses. However, the recommendation is 693 that all configured IP addresses should be obtained to allow 694 applications to work with every kind of node. And the second 695 function returns the hostname associated to an IP address. 697 5.4 Specific IP Dependencies 699 5.4.1 IP Address Selection 701 IPv6 promotes the configuration of multiple IP addresses per node, 702 which is a difference when compared with the IPv4 model; however 703 applications only use a destination/source pair for a 704 communication. Choosing the right IP source and destination 705 addresses is a key factor that may determine the route of IP 706 datagrams. 708 Typically nodes, not applications, automatically solve the source 709 address selection. A node will choose the source address for a 710 communication following some rules of best choice, [RFC 3484], but 711 also allowing applications to make changes in the ordering rules. 713 When selecting the destination address, applications usually ask a 714 resolver for the destination IP address. The resolver returns a set 715 of valid IP addresses from a hostname. Unless applications have a 716 specific reason to select any particular destination address, they 717 should just try each element in the list until the communication 718 succeeds. 720 In some cases, the application may need to specify its source 721 address. Then the destination address selection process picks the 722 best destination for the source address (instead of picking the 723 best source address for the chosen destination address). Note that 724 there may be an increase in complexity for IP-version independent 725 applications which have to specify the source address (especially 726 for client applications; fortunately, specifying the source address 727 is not typically required), if it is not yet known which protocol 728 will be used for communication. 730 5.4.2 Application Framing 732 The Application Level Framing (ALF) architecture controls 733 mechanisms that traditionally fall within the transport layer. 734 Applications implementing ALF are often responsible for packetizing 735 data into Application Data Units (ADUs). The application problem 736 when using ALF is the ADU size selection to obtain better 737 performance. 739 Application framing is typically needed by applications using 740 connectionless protocols (such as UDP). Such applications have 741 three choices: (1) to use packet sizes no larger than IPv6 IPv6 742 minimum Maximum Transmission Unit (MTU) of 1280 bytes [RFC2460], 743 (2) to use whatever packet sizes but force IPv6 744 fragmentation/reassembly when necessary, or (3) to optimize the 745 packet size and avoid unnecessary fragmentation/reassembly, guess 746 or find out the optimal packet sizes which can be sent and 747 received, end-to-end, on the network. This memo takes no stance on 748 which approach to adopt. 750 Note that the most optimal ALF depends on dynamic factors such as 751 Path MTU or whether IPv4 or IPv6 is being used (due to different 752 header sizes, possible IPv6-in-IPv4 tunneling overhead, etc.). 753 These have to be taken into consideration when implementing 754 application framing. 756 5.4.3 Storage of IP Addresses 758 Some applications store IP addresses as information of remote 759 peers. For instance, one of the most popular ways to register 760 remote nodes in collaborative applications is based on using IP 761 addresses as registry keys. 763 Although the source code that stores IP addresses can be modified 764 to IPv6 following the previous basic porting recommendations, there 765 are some reasons why applications should not store IP addresses: 767 - IP addresses can change throughout time, for instance 768 after a renumbering process. 770 - The same node can reach a destination host using different 771 IP addresses, possibly with a different protocol version. 773 When possible, applications should store names such as FQDNs, or 774 other protocol-independent identities instead of storing addresses. 775 In this case applications are only bound to specific addresses at 776 run time, or for the duration of a cache lifetime. Other types of 777 applications, such as massive peer to peer systems with their own 778 rendezvous and discovery mechanisms, may need to cache addresses 779 for performance reasons, but cached addresses should not be treated 780 as permanent, reliable information. In highly dynamic networks any 781 form of name resolution may be impossible, and here again addresses 782 must be cached. 784 5.5 Multicast Applications 786 There is an additional problem in porting multicast applications. 787 When using multicast facilities some changes must be carried out to 788 support IPv6. First, applications must change the IPv4 multicast 789 addresses to IPv6 ones, and second, the socket configuration 790 options must be changed. 792 All the IPv6 multicast addresses encode scope; the scope was only 793 implicit in IPv4 (with multicast groups in 239/8). Also, while a 794 large number of application-specific multicast addresses have been 795 assigned with IPv4, this has been (luckily enough) avoided in IPv6. 796 So, there are no direct equivalents for all the multicast 797 addresses. For link-local multicast, it's possible to pick almost 798 anything within the link-local scope. The global groups could use 799 unicast-prefix-based addresses [RFC 3306]. All in all, this may 800 force the application developers to write more protocol dependent 801 code. 803 Another problem is/has been that IPv6 multicast does not yet have a 804 standardized mechanism for traditional Any Source Multicast for 805 Interdomain multicast. The models for Any Source Multicast (ASM) 806 or Source-Specific Multicast (SSM) are generally similar between 807 IPv4 and IPv6, but it is possible that PIM-SSM will become more 808 widely deployed in IPv6 due to its simpler architecture. 810 So, it might be beneficial to port the applications to use SSM 811 semantics, requiring off-band source discovery mechanisms and the 812 use of a different API [RFC 3678]. Inter-domain ASM service is 813 available only through a method embedding the Rendezvous Point 814 address in the multicast address [Embed-RP]. 816 Another generic problem for multiparty conferencing applications, 817 which is similar to the issues with peer-to-peer applications, is 818 that all the users of the session must use the same protocol 819 version (IPv4 or IPv6), or some form of proxies or translators must 820 be used (e.g., [MUL-GW]). 822 6. Developing IP version-independent Applications 824 As we have seen before, dual applications working with both IPv4 825 and IPv6 are recommended. These applications should avoid IP 826 dependencies in the source code. However, if IP dependencies are 827 required, one of the best solutions is based on building a 828 communication library which provides an IP version independent API 829 to applications and hides all dependencies. 831 In order to develop IP version independent applications, the 832 following guidelines should be considered. 834 6.1 IP version-independent Structures 836 All of the memory structures and APIs should be IP version- 837 independent. In that sense, one should avoid structs in_addr, 838 in6_addr, sockaddr_in and sockaddr_in6. 840 Suppose you pass a network address to some function, foo(). If you 841 use struct in_addr or struct in6_addr, you will end up with an 842 extra parameter to indicate address family, as below: 844 struct in_addr in4addr; 845 struct in6_addr in6addr; 846 /* IPv4 case */ 848 foo(&in4addr, AF_INET); 849 /* IPv6 case */ 850 foo(&in6addr, AF_INET6); 852 However, this leads to duplicated code and having to consider each 853 scenario from both perspectives independently; this is difficult to 854 maintain. So, we should use struct sockaddr_storage like below. 856 struct sockaddr_storage ss; 857 int sslen; 858 /* AF independent! - use sockaddr when passing a pointer */ 859 /* note: it's typically necessary to also pass the length 860 explicitly */ 861 foo((struct sockaddr *)&ss, sslen); 863 6.2 IP version-independent APIs 865 getaddrinfo() and getnameinfo() are new address independent 866 variants that hide the gory details of name-to-address and address- 867 to-name translations. They implement functionalities of the 868 following functions: 870 gethostbyname() 871 gethostbyaddr() 872 getservbyname() 873 getservbyport() 875 They also obsolete the functionality of gethostbyname2(), defined 876 in [RFC2133]. 878 These can perform hostname/address and service name/port lookups, 879 though the features can be turned off if desirable. Getaddrinfo() 880 can return multiple addresses, as below: 882 localhost. IN A 127.0.0.1 883 IN A 127.0.0.2 884 IN AAAA ::1 886 In this example, if IPv6 is preferred, getaddrinfo returns first 887 ::1, and then both 127.0.0.1 and 127.0.0.2 is in a random order. 889 Getaddrinfo() and getnameinfo() can query hostname as well as 890 service name/port at once. 892 It is not preferred to hardcode AF-dependent knowledge into the 893 program. The construct like below should be avoided: 895 /* BAD EXAMPLE */ 896 switch (sa->sa_family) { 897 case AF_INET: 898 salen = sizeof(struct sockaddr_in); 899 break; 900 } 902 Instead, we should use the ai_addrlen member of the addrinfo 903 structure, as returned by getaddrinfo(). 905 The gethostbyname(), gethostbyaddr(), getservbyname(), and 906 getservbyport() are mainly used to get server and client sockets. 907 Following, we will see simple examples to create these sockets 908 using the new IPv6 resolution functions. 910 6.2.1 Example of Overly Simplistic TCP Server Application 912 A simple TCP server socket at service name (or port number string) 913 SERVICE: 915 /* 916 * BAD EXAMPLE: does not implement the getaddrinfo loop as 917 * specified in 6.3. This may result in one of the following: 918 * - an IPv6 server, listening at the wildcard address, 919 * allowing IPv4 addresses through IPv4-mapped IPv6 addresses. 920 * - an IPv4 server, if IPv6 is not enabled, 921 * - an IPv6-only server, if IPv6 is enabled but IPv4-mapped IPv6 922 * addresses are not used by default, or 923 * - no server at all, if getaddrinfo supports IPv6, but the 924 * system doesn't, and socket(AF_INET6, ...) exits with an 925 * error. 926 */ 927 struct addrinfo hints, *res; 928 int error, sockfd; 930 memset(&hints, 0, sizeof(hints)); 931 hints.ai_flags = AI_PASSIVE; 932 hints.ai_family = AF_UNSPEC; 933 hints.ai_socktype = SOCK_STREAM; 935 error = getaddrinfo(NULL, SERVICE, &hints, &res); 936 if (error != 0) { 937 /* handle getaddrinfo error */ 938 } 940 sockfd = socket(res->family, res->ai_socktype, res->ai_protocol); 941 if (sockfd < 0) { 942 /* handle socket error */ 943 } 945 if (bind(sockfd, res->ai_addr, res->ai_addrlen) < 0) { 946 /* handle bind error */ 947 } 949 /* ... */ 950 freeaddrinfo(res); 952 6.2.2 Example of Overly Simplistic TCP Client Application 954 A simple TCP client socket connecting to a server which is running 955 at node name (or IP address presentation format) SERVER_NODE and 956 service name (or port number string) SERVICE: 958 /* 959 * BAD EXAMPLE: does not implement the getaddrinfo loop as 960 * specified in 6.3. This may result in one of the following: 961 * - an IPv4 connection to an IPv4 destination, 962 * - an IPv6 connection to an IPv6 destination, 963 * - an attempt to try to reach an IPv6 destination (if AAAA 964 * record found), but failing -- without fallbacks -- because: 965 * o getaddrinfo supports IPv6 but the system does not 966 * o IPv6 routing doesn't exist, so falling back to e.g. TCP 967 * timeouts 968 * o IPv6 server reached, but service not IPv6-enabled or 969 * firewalled away 970 * - if the first destination is not reached, there is no 971 * fallback to the next records 972 */ 973 struct addrinfo hints, *res; 974 int error, sockfd; 976 memset(&hints, 0, sizeof(hints)); 977 hints.ai_family = AF_UNSPEC; 978 hints.ai_socktype = SOCK_STREAM; 980 error = getaddrinfo(SERVER_NODE, SERVICE, &hints, &res); 981 if (error != 0) { 982 /* handle getaddrinfo error */ 983 } 985 sockfd = socket(res->family, res->ai_socktype, res->ai_protocol); 986 if (sockfd < 0) { 987 /* handle socket error */ 988 } 990 if (connect(sockfd, res->ai_addr, res->ai_addrlen) < 0 ) { 991 /* handle connect error */ 992 } 994 /* ... */ 996 freeaddrinfo(res); 998 6.2.3 Binary/Presentation Format Conversion 1000 In addition, we should consider the binary and presentation address 1001 format conversion APIs. The following functions convert network 1002 address structure in its presentation address format and vice 1003 versa: 1005 inet_ntop() 1006 inet_pton() 1008 Both are from the basic socket extensions for IPv6. However, these 1009 conversion functions are protocol-dependent; instead it is better 1010 to use getnameinfo()/getaddrinfo() as follows (inet_pton and 1011 inet_ntop equivalents are described in Appendix A). 1013 Conversion from network address structure to presentation format 1014 can be written: 1016 struct sockaddr_storage ss; 1017 char addrStr[INET6_ADDRSTRLEN]; 1018 char servStr[NI_MAXSERV]; 1019 int error; 1021 /* fill ss structure */ 1023 error = getnameinfo((struct sockaddr *)&ss, sizeof(ss), 1024 addrStr, sizeof(addrStr), 1025 servStr, sizeof(servStr), 1026 NI_NUMERICHOST); 1028 Conversions from presentation format to network address structure 1029 can be written as follows: 1031 struct addrinfo hints, *res; 1032 char addrStr[INET6_ADDRSTRLEN]; 1033 int error; 1035 /* fill addrStr buffer */ 1037 memset(&hints, 0, sizeof(hints)); 1038 hints.ai_family = AF_UNSPEC; 1040 error = getaddrinfo(addrStr, NULL, &hints, &res); 1041 if (error != 0) { 1042 /* handle getaddrinfo error */ 1043 } 1045 /* res->ai_addr contains the network address structure */ 1046 /* ... */ 1047 freeaddrinfo(res); 1049 6.3 Iterated Jobs for Finding the Working Address 1051 In a client code, when multiple addresses are returned from 1052 getaddrinfo(), we should try all of them until connection succeeds. 1053 When a failure occurs with socket(), connect(), bind(), or some 1054 other function, the code should go on to try the next address. 1056 In addition, if something is wrong with the socket call because the 1057 address family is not supported (i.e., in case of section 4.4), 1058 applications should try the next address structure. 1060 Note: in the following examples, the socket() return value error 1061 handling could be simplied by substituting special checking of 1062 specific error numbers by always continuing on with the socket 1063 loop. 1065 6.3.1 Example of TCP Server Application 1067 The previous example TCP server example should be written: 1069 #define MAXSOCK 2 1070 struct addrinfo hints, *res; 1071 int error, sockfd[MAXSOCK], nsock=0; 1073 memset(&hints, 0, sizeof(hints)); 1074 hints.ai_flags = AI_PASSIVE; 1075 hints.ai_family = AF_UNSPEC; 1076 hints.ai_socktype = SOCK_STREAM; 1078 error = getaddrinfo(NULL, SERVICE, &hints, &res); 1079 if (error != 0) { 1080 /* handle getaddrinfo error */ 1081 } 1083 for (aip=res; aip && nsock < MAXSOCK; aip=aip->ai_next) { 1084 sockfd[nsock] = socket(aip->ai_family, 1085 aip->ai_socktype, 1086 aip->ai_protocol); 1088 if (sockfd[nsock] < 0) { 1089 switch errno { 1090 case EAFNOSUPPORT: 1091 case EPROTONOSUPPORT: 1092 /* 1093 * e.g., skip the errors until 1094 * the last address family, 1095 * see section 4.4. 1096 */ 1097 if (aip->ai_next) 1098 continue; 1100 else { 1101 /* handle unknown protocol errors */ 1102 break; 1103 } 1104 default: 1105 /* handle other socket errors */ 1106 ; 1107 } 1109 } else { 1110 int on = 1; 1111 /* optional: works better if dual-binding to wildcard 1112 address */ 1113 if (aip->ai_family == AF_INET6) { 1114 setsockopt(sockfd[nsock], IPPROTO_IPV6, IPV6_V6ONLY, 1115 (char *)&on, sizeof(on)); 1116 /* errors are ignored */ 1117 } 1118 if (bind(sockfd[nsock], aip->ai_addr, 1119 aip->ai_addrlen) < 0 ) { 1120 /* handle bind error */ 1121 close(sockfd[nsock]); 1122 continue; 1123 } 1124 if (listen(sockfd[nsock], SOMAXCONN) < 0) { 1125 /* handle listen errors */ 1126 close(sockfd[nsock]); 1127 continue; 1128 } 1129 } 1130 nsock++; 1131 } 1132 freeaddrinfo(res); 1134 /* check that we were able to obtain the sockets */ 1136 6.3.2 Example of TCP Client Application 1138 The previous TCP client example should be written: 1140 struct addrinfo hints, *res, *aip; 1141 int sockfd, error; 1143 memset(&hints, 0, sizeof(hints)); 1144 hints.ai_family = AF_UNSPEC; 1145 hints.ai_socktype = SOCK_STREAM; 1147 error = getaddrinfo(SERVER_NODE, SERVICE, &hints, &res); 1148 if (error != 0) { 1149 /* handle getaddrinfo error */ 1150 } 1151 for (aip=res; aip; aip=aip->ai_next) { 1153 sockfd = socket(aip->ai_family, 1154 aip->ai_socktype, 1155 aip->ai_protocol); 1157 if (sockfd < 0) { 1158 switch errno { 1159 case EAFNOSUPPORT: 1160 case EPROTONOSUPPORT: 1161 /* 1162 * e.g., skip the errors until 1163 * the last address family, 1164 * see section 4.4. 1165 */ 1166 if (aip->ai_next) 1167 continue; 1168 else { 1169 /* handle unknown protocol errors */ 1170 break; 1171 } 1173 default: 1174 /* handle other socket errors */ 1175 ; 1176 } 1178 } else { 1179 if (connect(sockfd, aip->ai_addr, aip->ai_addrlen) == 0) 1180 break; 1182 /* handle connect errors */ 1183 close(sockfd); 1184 sockfd=-1; 1185 } 1186 } 1188 if (sockfd > 0) { 1189 /* socket connected to server address */ 1191 /* ... */ 1192 } 1194 freeaddrinfo(res); 1196 7. Transition Mechanism Considerations 1198 A mechanism, [NAT-PT], introduces a special set of addresses, 1199 formed of NAT-PT prefix and an IPv4 address; this refers to IPv4 1200 addresses, translated by NAT-PT DNS-ALG. In some cases, one might 1201 be tempted to handle these differently. 1203 However, IPv6 applications must not be required to distinguish 1204 "normal" and "NAT-PT translated" addresses (or any other kind of 1205 special addresses, including the IPv4-mapped IPv6-addresses): that 1206 would be completely impractical, and if such distinction must be 1207 made, it must be done elsewhere (e.g. kernel, system libraries). 1209 8. Security Considerations 1211 There are a number of security considerations with IPv6 transition 1212 but those are outside the scope of this memo. 1214 To ensure the availability and robustness of the service even when 1215 transitioning to IPv6, this memo described a number of ways to make 1216 applications more resistant to failures by cycling through 1217 addresses until a working one is found. Doing this properly is 1218 critical to avoid unavailability and loss of service. 1220 One particular point about application transition is how 1221 IPv4-mapped IPv6 addresses are handled. The use in the API can be 1222 seen as both a merit (easier application transition) and as a 1223 burden (difficulty in ensuring whether the use was legimate) Note 1224 that some systems will disable (by default) support for internal 1225 IPv4-mapped IPv6 addresses. The security concerns regarding 1226 IPv4-mapped IPv6 addresses on the wire are legitimate but disabling 1227 it internally breaks one transition mechanism for server 1228 applications which were originally written to bind() and listen() 1229 to a single socket using a wildcard address [V6MAPPED]. This 1230 should be considered in more detail when designing applications. 1232 9. Acknowledgements 1234 Some of guidelines for development of IP version-independent 1235 applications (section 6) were first brought up by [AF-APP]. Other 1236 work to document application porting guidelines has also been in 1237 progress, for example [IP-GGF] and [PRT]. We would like to thank 1238 the members of the the v6ops working group and the application area 1239 for helpful comments. Special thanks are due to Brian E. 1240 Carpenter, Antonio Querubin, Stig Venaas, Chirayu Patel, Jordi 1241 Palet, and Jason Lin for extensive review of this document. We 1242 acknowledge Ron Pike for proofreading the document. 1244 10. References 1246 Normative References 1248 [RFC 3493] R. Gilligan, S. Thomson, J. Bound, W. Stevens, "Basic 1249 Socket Interface Extensions for IPv6," RFC 3493, February 1250 2003. 1252 [RFC 3542] W. Stevens, M. Thomas, E. Nordmark, T. Jinmei, "Advanced 1253 Sockets Application Program Interface (API) for IPv6," 1254 RFC 3542, May 2003. 1256 [BIS] K. Tsuchiya, H. Higuchi, Y. Atarashi, "Dual Stack Hosts 1257 using the "Bump-In-the-Stack" Technique (BIS)," RFC 2767, 1258 February 2000. 1260 [BIA] S. Lee, M-K. Shin, Y-J. Kim, E. Nordmark, A. Durand, 1261 "Dual Stack Hosts using "Bump-in-the-API" (BIA)," RFC 1262 3338, October 2002. 1264 [RFC 2460] S. Deering, R. Hinden, "Internet Protocol, Version 6 1265 (IPv6) Specification," RFC 2460, December 1998. 1267 [RFC 3484] R. Draves, "Default Address Selection for IPv6," 1268 RFC 3484, February 2003. 1270 [RFC 3513] R. Hinden, S. Deering, "Internet Protocol Version 6 1271 (IPv6) Addressing Architecture," RFC 3513, April 2003. 1273 Informative References 1275 [2893BIS] E. Nordmark, R. E. Gilligan, "Basic Transition Mechanisms 1276 for IPv6 Hosts and Routers," , June 2004, Work-in-progress. 1279 [RFC 2732] R. Hinden, B. Carpenter, L. Masinter, "Format for Literal 1280 IPv6 Addresses in URL's," RFC 2732, December 1999. 1282 [RFC 2821] J. Klensin, "Simple Mail Transfer Protocol," RFC 2821, 1283 April 2001. 1285 [TextRep] A. Main, "Textual Representation of IPv4 and IPv6 1286 Addresses," , Oct 2003, 1287 Work in Progress. 1289 [NAT-PT] G. Tsirtsis, P. Srisuresh, "Network Address Translation 1290 - Protocol Translation (NAT-PT)," RFC 2766, February 2000. 1292 [DNSTRANS] A. Durand, J. Ihren, "DNS IPv6 transport operational 1293 guidelines," , March 2004, Work in Progress. 1296 [DNSOPV6] A. Durand, J. Ihren, P. Savola, "Operational Considerations 1297 and Issues with IPv6 DNS," , May 2004, Work in Progress. 1300 [AF-APP] J. Hagino, "Implementing AF-independent application", 1301 http://www.kame.net/newsletter/19980604/, 2001. 1303 [V6MAPPED] J. Hagino, "IPv4 mapped address considered harmful", 1304 , Apr 2002, 1305 Work in Progress. 1307 [IP-GGF] T. Chown, J. Bound, S. Jiang, P. O'Hanlon, "Guidelines for 1308 IP version independence in GGF specifications," Global 1309 Grid Forum(GGF) Documentation, September 2003, Work in 1310 Progress. 1312 [Embed-RP] P. Savola, B. Haberman, "Embedding the Address of RP in 1313 IPv6 Multicast Address," , October 2003, Work in Progress. 1316 [RFC 3306] B. Haberman, D. Thaler, "Unicast-Prefix-based IPv6 1317 Multicast Addresses," RFC 3306, August 2002. 1319 [RFC 3678] D. Thaler, B. Fenner, B. Quinn, "Socket Interface 1320 Extensions for Multicast Source Filters, RFC 3678, January 1321 2004. 1323 [MUL-GW] S. Venaas, "An IPv4 - IPv6 multicast gateway," , February 2003, 1325 Work in Progress. 1327 [PRT] E. M. Castro, "Programming guidelines on transition to 1328 IPv6, LONG project, January 2003. 1330 Authors' Addresses 1332 Myung-Ki Shin 1333 ETRI/NIST 1334 820 West Diamond Avenue 1335 Gaithersburg, MD 20899, USA 1336 Tel : +1 301 975-3613 1337 Fax : +1 301 590-0932 1338 E-mail : mshin@nist.gov 1340 Yong-Guen Hong 1341 ETRI PEC 1342 161 Gajeong-Dong, Yuseong-Gu, Daejeon 305-350, Korea 1343 Tel : +82 42 860 6447 1344 Fax : +82 42 861 5404 1345 E-mail : yghong@pec.etri.re.kr 1347 Jun-ichiro itojun HAGINO 1348 Research Laboratory, Internet Initiative Japan Inc. 1349 Takebashi Yasuda Bldg., 1350 3-13 Kanda Nishiki-cho, 1351 Chiyoda-ku,Tokyo 101-0054, JAPAN 1352 Tel: +81-3-5259-6350 1353 Fax: +81-3-5259-6351 1354 E-mail: itojun@iijlab.net 1356 Pekka Savola 1357 CSC/FUNET 1358 Espoo, Finland 1359 E-mail: psavola@funet.fi 1361 Eva M. Castro 1362 Rey Juan Carlos University (URJC) 1363 Departamento de Informatica, Estadistica y Telematica 1364 C/Tulipan s/n 1365 28933 Madrid - SPAIN 1366 E-mail: eva@gsyc.escet.urjc.es 1368 Appendix A. Other binary/Presentation Format Conversions 1370 Section 6.2.3 described the preferred way of performing 1371 binary/presentation format conversions; these can also be done 1372 using inet_pton() and inet_ntop() by writing protocol-dependent 1373 code. This is not recommended, but provided here for reference and 1374 comparison. 1376 Note that inet_ntop()/inet_pton() lose the scope identifier (if 1377 used e.g. with link-local addresses) in the conversions, contrary 1378 to the getaddrinfo()/getnameinfo() functions. 1380 A.1 Binary to Presentation using inet_ntop() 1382 Conversions from network address structure to presentation format 1383 can be written: 1385 struct sockaddr_storage ss; 1386 char addrStr[INET6_ADDRSTRLEN]; 1388 /* fill ss structure */ 1390 switch (ss.ss_family) { 1392 case AF_INET: 1393 inet_ntop(ss.ss_family, 1394 &((struct sockaddr_in *)&ss)->sin_addr, 1395 addrStr, 1396 sizeof(addrStr)); 1397 break; 1399 case AF_INET6: 1400 inet_ntop(ss.ss_family, 1401 &((struct sockaddr_in6 *)&ss)->sin6_addr, 1402 addrStr, 1403 sizeof(addrStr)); 1405 break; 1407 default: 1408 /* handle unknown family */ 1409 } 1411 Note, the destination buffer addrStr should be long enough to 1412 contain the presentation address format: INET_ADDRSTRLEN for IPv4 1413 and INET6_ADDRSTRLEN for IPv6. Since INET6_ADDRSTRLEN is longer 1414 than INET_ADDRSTRLEN, the first one is used as the destination 1415 buffer length. 1417 A.2 Presentation to Binary using inet_pton() 1419 Conversions from presentation format to network address structure 1420 can be written as follows: 1422 struct sockaddr_storage ss; 1423 struct sockaddr_in *sin; 1424 struct sockaddr_in6 *sin6; 1425 char addrStr[INET6_ADDRSTRLEN]; 1427 /* fill addrStr buffer and ss.ss_family */ 1429 switch (ss.ss_family) { 1430 case AF_INET: 1431 sin = (struct sockaddr_in *)&ss; 1432 inet_pton(ss.ss_family, 1433 addrStr, 1434 (sockaddr *)&sin->sin_addr)); 1435 break; 1437 case AF_INET6: 1438 sin6 = (struct sockaddr_in6 *)&ss; 1439 inet_pton(ss.ss_family, 1440 addrStr, 1441 (sockaddr *)&sin6->sin6_addr); 1442 break; 1444 default: 1445 /* handle unknown family */ 1446 } 1448 Note, the address family of the presentation format must be known. 1450 Intellectual Property Statement 1452 The IETF takes no position regarding the validity or scope of any 1453 Intellectual Property Rights or other rights that might be claimed 1454 to pertain to the implementation or use of the technology described 1455 in this document or the extent to which any license under such 1456 rights might or might not be available; nor does it represent that 1457 it has made any independent effort to identify any such rights. 1458 Information on the procedures with respect to rights in RFC 1459 documents can be found in BCP 78 and BCP 79. 1461 Copies of IPR disclosures made to the IETF Secretariat and any 1462 assurances of licenses to be made available, or the result of an 1463 attempt made to obtain a general license or permission for the use 1464 of such proprietary rights by implementers or users of this 1465 specification can be obtained from the IETF on-line IPR repository 1466 at http://www.ietf.org/ipr. 1468 The IETF invites any interested party to bring to its attention any 1469 copyrights, patents or patent applications, or other proprietary 1470 rights that may cover technology that may be required to implement 1471 this standard. Please address the information to the IETF at ietf- 1472 ipr@ietf.org. 1474 Disclaimer of Validity 1476 This document and the information contained herein are provided on 1477 an "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE 1478 REPRESENTS OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND 1479 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, 1480 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT 1481 THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR 1482 ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A 1483 PARTICULAR PURPOSE. 1485 Copyright Statement 1487 Copyright (C) The Internet Society (2004). This document is 1488 subject to the rights, licenses and restrictions contained in BCP 1489 78, and except as set forth therein, the authors retain all their 1490 rights. 1492 Acknowledgment 1494 Funding for the RFC Editor function is currently provided by the 1495 Internet Society.