INTERNET DRAFT Myung-Ki Shin Expires: December 2003 Yong-Guen Hong ETRI Jun-ichiro itojun Hagino IIJ Pekka Savola CSC/FUNET Eva M. Castro GSYC/URJC June 2003 Application Aspects of IPv6 Transition Status of this Memo This document is an Internet-Draft and is in full conformance with all provisions of Section 10 of RFC2026. Internet Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and working groups. Note that other groups may also distribute working documents as Internet-Drafts. Internet-Drafts are draft documents valid for a maximum of six months and may be updated, replaced, or obsolete by other documents at anytime. It is inappropriate to use Internet Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. Abstract The document specifies application aspects of IPv6 transition. As IPv6 is deployed, the application developers and the administrators will face several problems. This draft clarifies the problems and considerations occurring in transition period between IPv4 applications and IPv6 applications. It also proposes guidelines that help application developers understand how to develop IP version-independent applications during the transition period. Shin et al. Expires December 2003 [Page 1] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 Table of Contents: 1. Introduction .............................................. 2 2. Overview of IPv6 application transition ................... 3 3. Problems with IPv6 application transition ................. 4 3.1 Dual stack vs. application versions ...................... 4 3.2 DNS name resolution ...................................... 4 3.3 Application selection .................................... 4 4. Description of transition scenarios and guidelines ........ 5 4.1 IPv4 applications in a dual-stack node ................... 6 4.2 IPv6 applications in a dual-stack node ................... 6 4.3 IPv4/IPv6 applications in a dual stack node .............. 9 4.4 IPv4/IPv6 applications in an IPv4-only node .............. 9 5. Application porting considerations ........................10 5.1 Presentation format for an IP address ....................10 5.2 Transport layer API ..................................... 11 5.3 Name and address resolution ............................. 12 5.4 Specific IP dependencies ................................ 12 6. Developing IP version-independent applications ........... 13 6.1 IP version-independent structures ....................... 14 6.2 IP version-independent APIs ............................. 14 6.3 Iterated jobs for finding the working address ........... 18 7. Transition mechanism considerations ...................... 19 8. Security considerations .................................. 19 9. References ............................................... 20 Authors' Addresses .......................................... 21 1. Introduction As IPv6 is introduced in the IPv4-based Internet, several general issues when starting to use IPv6 in a predominant IPv4 world are being discussed, such as routing, addressing, DNS, scenarios, etc. One important key to a successful IPv6 transition is the compatibility with the large installed base of IPv4 hosts and routers. This issue had been already studied in [RFC 2893] and [RFC 2185]. In addition, various kinds of transition mechanisms have been developed to migrate to IPv6 network. However, even if these mechanisms are fully deployed, we still have problems occuring in the transition period between IPv4 applications and IPv6 applications. This document specifies application aspects of IPv6 transition. As IPv6 networks are deployed and the network transition discussed, we should also consider IPv6 application porting in a node. [BIS] and [BIA] have been proposed as short-term solutions, but these mechanisms should not be used when the application-specific source code is available. Ultimately, application developers will modify application programs to support both IPv4 and IPv6 (named, IP version-independent program). During the transition period, Shin et al. Expires December 2003 [Page 2] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 administrators may have various versions of an application (IPv4- only, IPv6-only or one supporting both IPv4 and IPv6) in a node (dual-stack or IPv4-only node). This draft clarifies the problems and considerations occurring in the transition period between IPv4 applications and IPv6 applications. It also proposes guidelines that help application developers understand how to develop IP version-independent applications during the transition period. 2. Overview of IPv6 application transition The transition of an application can be classifed as follows: +-------------------+ | appv4 | (appv4 - IPv4-only applications) +-------------------+ | TCP / UDP | +-------------------+ | IPv4 | IPv6 | +-------------------+ Case 1. IPv4 applications in a dual-stack node +-------------------+ | appv4 | appv6 | (appv6 - IPv6-only applications) +-------------------+ | TCP / UDP | +-------------------+ | IPv4 | IPv6 | +-------------------+ Case 2. IPv4-only applications and IPv6-only applications in a dual-stack node +-------------------+ | appv4/v6 | (appv4/v6 - applications supporting +-------------------+ both IPv4 and IPv6) | TCP / UDP | +-------------------+ | IPv4 | IPv6 | +-------------------+ Case 3. Applications supporting both IPv4 and IPv6 in a dual-stack node +-------------------+ | appv4/v6 | (appv4/v6 - applications supporting +-------------------+ both IPv4 and IPv6) | TCP / UDP | +-------------------+ | IPv4 | +-------------------+ Case 4. Applications supporting both IPv4 and IPv6 Shin et al. Expires December 2003 [Page 3] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 in an IPv4-only node Figure 1. Overview of IPv6 Application Transition Figure 1 shows the cases of IPv6 application transition. Case 1 : IPv4-only applications in a dual-stack node. IPv6 protocol is introduced in a node, but applications are not yet ported to IPv6. Case 2 : IPv4-only applications and IPv6-only applications in a dual-stack node. Applications are ported for IPv6-only. Therefore, there are two same applications for different protocol versions (e.g., ping and ping6). Case 3 : Applications supporting both IPv4 and IPv6 in a dual stack node. Applications are ported for both IPv4 and IPv6 support. Therefore, the existing IPv4 applications can be removed. Case 4 : Applications supporting both IPv4 and IPv6 in an IPv4-only node. Applications are ported for both IPv4 and IPv6 support, but to ease support, the same applications may also have to work when IPv6 is not used. 3. Problems with IPv6 application transition As IPv6 is deployed, the application developers and the administrators will face several problems. 3.1 Dual-stack vs. application versions Considering the cases above, IPv4 and IPv6 protocol stack in a node is likely to co-exist for a long time. During this period, applications are expected to be able to handle IPv6 over some time period, not at the same time as IPv6 protocol is introduced. That is, operating system being dual stack does not mean having both IPv4 and IPv6 applications. Therefore, application introduction may be independent of protocol stacks in a node. It is even probable that applications capable of both IPv4 and IPv6 will have to work properly IPv4-only nodes (whether IPv6 protocol is completely disabled or there is no IPv6 connectivity at all). 3.2 DNS name resolution Shin et al. Expires December 2003 [Page 4] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 The role of the DNS name resolver in a node is to get the list of destination addresses. DNS queries and responses are sent using IPv4 transport, even though IPv6 addresses are being resolved, or using IPv6 transport. This issue has been already discussed in [DNS]. The issue of DNS name resolving related to application transition is that a client application can not know the version of peer application by only doing a DNS name lookup. For example, if a server application does not support IPv6 yet, but runs on a dual- stack machine for other IPv6 services and this is listed with a AAAA record in the DNS, the client application will fail to connect to the server application, because there is a mis-match between the DNS query result (i.e. IPv6 addresses) and a server application version (i.e. IPv4). It is bad practise to add a AAAA record for node that does not support all the services using IPv6 (rather, a AAAA record for the specific service name and address should be used), but the application cannot depend on "good practise", and this must be handled. In consequence, the application has to try both protocol versions, and if the first to try fails, detect the failure and try using the other protocol version. 3.3 Application selection During the application transition period, system administrators may have various versions of the same application (an IPv4-only application, an IPv6-only application, or an application supporting both IPv4 and IPv6). Therefore, the users may be confused by their various application versions, because they don't know the version of peer application by DNS query results. To avoid problems with mismatching DNS query results, it is desirable to have hybrid applications, supporting both protocol versions. Alternative approach is to have a "wrapper application" which performs certain tasks (like figures out which protocol version will be used) and calls the IPv4/IPv6-only applications as necessary (these kind of "wrapper applications" only work for certain kinds of, usually simple, applications). Nonetheless, there should be some reasonable logic on how to perform application selection. 4. Description of transition scenarios and guidelines Once the IPv6 network is deployed, applications can use IPv6 network services and establish IPv6 connections. However, upgrading every node to IPv6 at the same time is not feasible and Shin et al. Expires December 2003 [Page 5] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 transition from IPv4 to IPv6 will be a gradual process. Dual-stack nodes are one of the ways to maintain IPv4 compatibility in unicast communications. In this section we will analyze different transition scenarios and guidelines to maintain interoperability between applications running in different type of nodes. 4.1 IPv4 applications in a dual-stack node This scenario happens if IPv6 protocol is added in a node but IPv6-capable applications aren't yet available or installed. Although the node implements the dual stack, IPv4 applications can only manage IPv4 communications, and IPv4 packets will be exchanged. Then, IPv4 applications can only accept/establish connections from/to nodes which implement IPv4 stack. There could be some problems when an IPv4 client tries to connect to an IPv4 server running at dual stack. At the client side, the resolver can return all IP addresses of the server node, however only IPv4 ones will be valid for the IPv4 client application. The client application should be modified to cycle through all the addresses and end up trying the IPv4 one. In order to allow an application to communicate with other nodes exchanging IPv6 packets, the first priority is to port applications to IPv6. In some cases (e.g. no source code is available), existing IPv4 applications can work if the [BIS] or [BIA] mechanism is installed in the node. The main difference between them is, while [BIS] is for systems with no IPv6 stack, [BIA] is for systems with an IPv6 stack. Thus, [BIS] is not proper on installation in a dual-stack node. These mechanisms translate between IPv4 and IPv6 communications. However, these mechanisms should not be used when an application source code is available to prevent the mis-use of them, for example, an excuse not to port software. Considering the applicability of [BIA] and [BIS], it is good for early adopters who do not have all applications handy, but not for mainstream production usage. Besides, not all applications work using these mechanisms, if applications exchange IP addresses as application data, these mechanisms will not be able to solve the problem. When [BIA] or [BIS] is used, the same previous problem --the IPv4 client in a [BIS]/[BIA] node trying to connect to an IPv4 server in a dual stack-- arises. In this case, not always we will be able to use the same mechanism that before, since most cases the source code will not be available. However, we can rely on [BIA]/[BIS] mechanism, which should cycle through all the addresses instead of applications. Shin et al. Expires December 2003 [Page 6] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 4.2 IPv6 applications in a dual-stack node As we have seen in the previous section, finally applications should be ported to IPv6. The easiest way to port an IPv4 application is to substitute the old IPv4 API references by the IPv6 new ones, one-to-one API mapping. Then, an IPv6-only source code is obtained. This IPv6-only source code can not work in IPv4- only nodes, so the old IPv4 application should be maintained in these nodes. Then, we will get two same applications working with different protocol versions, depending on the node they are running (e.g., telnet and telnet6). This case is undesirable since maintaining two versions of the same source code per application, could be a difficult task. Most implementations of dual stack allow IPv6-only applications interoperate with IPv4 and IPv6 ones. IPv4 packets going to IPv6 applications on a dual-stack node, reach their destination because their addresses are mapped to IPv6 ones using IPv4-mapped IPv6 addresses: from x.y.z.w IPv4 address the ::FFFF.x.y.z.w IPv4-mapped IPv6 address is built. +----------------------------------------------+ | +------------------------------------------+ | | | | | | | IPv6-only applications | | | | | | | +------------------------------------------+ | | | | | +------------------------------------------+ | | | | | | | TCP/UDP | | | | | | | +------------------------------------------+ | | IPv4-mapped | | IPv6 | | IPv6 addresses | | addresses | | +--------------------+ +-------------------+ | | | IPv4 | | IPv6 | | | +--------------------+ +-------------------+ | | IPv4 | | | | adresses | | | +--------------|-----------------|-------------+ | | IPv4 packets IPv6 packets When an IPv4 client application sends data to an IPv6-only server, running on a dual-stack node using wildcard address, the IPv4 client address is translated to the IPv4-mapped IPv6 address in the dual-stack node to allow IPv6 application to manage this communication. The IPv6 server will use this mapped address as if it were a regular IPv6 address, and a usual IPv6 connection. However, IPv4 packets will be exchanged between the applications. Shin et al. Expires December 2003 [Page 7] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 Kernels with dual stack properly translate IPv4-mapped IPv6 addresses to IPv4 ones and vice versa. When an IPv6 client application, in a dual-stack node, sends data to an IPv4 server application, the IPv6 client will get an IPv4- mapped IPv6 address from the hostname resolution API functions. The IPv6 client will use this special address as if it were a regular IPv6 address, and a usual IPv6 connection. However, again IPv4 packets will be exchanged between applications. The interoperability between IPv4 and IPv6 applications, using the client/server communication model, provided by the dual-stack can be summarized as follows: +-------------------+-------------------+ | IPv4 server | IPv6 server | +---------+---------+---------+---------+ | IPv4- | Dual | IPv6- | Dual | | only | stack | only | stack | | node | node | node | node | +-------+---------+---------+---------+---------+---------+ | |IPv4-only| | | | IPv4 | | |node | {IPv4} | IPv4 | -- | (mapped | | | | | | | addr) | |IPv4 |---------+---------+---------+---------+---------+ |client |Dual- | | | | IPv4 | | |stack | IPv4 | IPv4 | -- | (mapped | | |node | | | | addr) | +-------+---------+---------+---------+---------+---------+ | |IPv6-only| | | | | | |node | -- | -- | {IPv6} | IPv6 | | | | | | | | |IPv6 |---------+---------+---------+---------+---------+ |client |Dual- | IPv4 | IPv4 | | | | |stack | (mapped | (mapped | IPv6 | IPv6 | | |node | addr) | addr) | | | +-------+---------+---------------------------------------+ Note : { } means that this combination is not needed in this scenario. The default behavior of IPv6 applications in these dual-stack nodes allows the IPv4 communication using the IPv4-mapped IPv6 addresses. However, it is possible IPv6 applications allow connections only with IPv6 nodes (e.g. IPv6_ONLY socket option), so the interoperability with IPv4 nodes is broken. This option could be useful if applications use new IPv6 features, such as flowlabel. There are other implementations of dual stack which do not use IPv4-mapped IPv6 addresses to allow the interoperability between IPv4 and IPv6 applications. Then, the two application versions should run in the same dual stack node, with different names (possibly attached with '6'). Simple application selection rule is Shin et al. Expires December 2003 [Page 8] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 as follows: rule 1 - default application selection is the application for IPv6, only if IPv6 connectivity is provided. rule 2 - if it fails, then the IPv4 application is tried. 4.3 IPv4/IPv6 applications in a dual stack node Applications should be ported for both IPv4 and IPv6 support, named dual applications or IP version-independent applications, and then the existing IPv4 applications could be removed. Since we have an only version of each application, the source code will be easy to maintain and to modify. This transition case is the most advisable. During IPv6 transition period, applications supporting both IPv4 and IPv6 should be able to communicate with other applications, irrespective of the versions of the protocol stack or the application in the node. Dual applications allow more interoperability between heterogeneous applications and nodes. If the source code is written in a protocol independent way, neither IPv4 supposition nor IPv6, applications will be able to communicate with any combination of application and type of node. Applications should prefer IPv6 if the remote node and application support it. However if IPv6 connections fail, dual applications will automatically try IPv4 ones. The resolver returns a list of valid addresses for the remote node and applications can iterate through all, firstly trying IPv6 ones, until connection succeeds. A more detail porting guideline will be described in section 6. 4.4 IPv4/IPv6 applications in an IPv4-only node As the transition is likely to happen over a longer timeframe, applications that have already been ported to support both IPv4 and IPv6 may be run on IPv4-only nodes. This would typically be done to avoid having to support two application versions for older and newer operating systems, or to support the case that the user wants to disable IPv6 for some reason. Depending on how application/operating system support is done, some may want to ignore this case, but usually no assumptions can be made and applications should work in this scenario too. An example is an application that issues a socket() command, first trying AF_INET6 and then AF_INET. However, if the kernel does not have IPv6 support, the call will result in an EPROTONOSUPPORT or EAFNOSUPPORT error. Typically, if errors are encountered, this Shin et al. Expires December 2003 [Page 9] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 leads to exiting the socket loop, and AF_INET6 will not even be tried. The application will need to handle this case or build the loop in such a way that errors are ignored until the last address family. So, this case is just an extension of the IPv4/IPv6 support in the previous case, covering one relatively common but often ignored case. 5. Application porting considerations The minimum changes in IPv4 applications to work using IPv6 are basically based on the different size and format of IPv4 and IPv6 addresses. Applications have been developed with the assumption they would use IPv4 as network protocol. This assumption is the responsible of many IP dependencies through source code. The following list summarizes the more common IP version dependencies in applications: a) Presentation format for an IP address: it is an ASCII string which represents the IP address, dotted-decimal string for IPv4 and hexadecimal string for IPv6. b) Transport layer API: functions to establish communications and to exchange information. c) Name and address resolution: conversion functions between hostnames and IP addresses, and vice versa. d) Specific IP dependencies: more specific IP version dependencies, such as: IP address selection, application framing, storage of IP addresses. Next, the problems with the previous IP version dependencies are analyzed and some recommendations are given to modify the application source code in a protocol independent way, which will allow applications to work in both IPv4 and IPv6 nodes. 5.1 Presentation format for an IP address Many applications use IP addresses to identify network nodes and to establish connections to destination addresses. For instance, on using the client/server model, clients usually need an IP address, as an application parameter, to connect to a server. This IP address is usually provided in the presentation format, as string. There are two problems, when porting the presentation format for an IP address: the allocated memory and the management of the Shin et al. Expires December 2003 [Page 10] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 presentation format. Usually, the allocated memory to contain an IPv4 address representation as string is not enough to contain an IPv6 one. Applications should be modified to prevent from overflowing the buffer holding the presentation format for an IP address, larger in IPv6. IPv4 and IPv6 do not use the same presentation format. IPv4 uses dot (.) to separate the four octets written in decimal notation and IPv6 uses colon (:) to separate each pair of octets written in hexadecimal notation. In order to support both, IPv4 and IPv6, the management functions of presentation format, such as IP address parsers, should be changed to be complaint with both formats. A particular case of an IP address parser is presented when managing the Uniform Resource Locators (URLs). Applications using URLs, as Internet browsers, should accept the literal IP address enclosed in brackets [RFC 2732]. For instance: http://[IPv6Address]:80/index.html. This new format solves the ambiguity with the colon character, since it is used in the IPv6 addresses as a separator between each pair of address octets and in the IPv4 networks as a separator between the address and the service port number. The use of FQDNs instead of presentation format for IP addresses is always preferable, since FQDNs keep the same format in IPv4 and IPv6. 5.2 Transport layer API Communication applications often include a transport module that establishes communications. Usually, this module manages everything related to communications and uses a transport layer API, typically as a network library. When porting to IPv6 most changes should be made in this application transport module, in order to be adapted to the new IPv6 API. As a general case, porting an existing application to IPv6 requires to examine the following issues related to the API: - Network information storage: IP address data structures. The new structures must contain 128-bit IP addresses. The use of generic address structures, which can store any address family, is recommended. Sometimes special addresses are hard-coded in the application source; developers should pay attention to them in order to use the new address format. Some of these special IP addresses are: wildcard local, loopback and broadcast. IPv6 is not implementing the broadcast addresses, so applications can use multicast instead. Shin et al. Expires December 2003 [Page 11] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 - Address conversion functions. The address conversion functions convert binary address representation to presentation format and vice versa. The new conversion functions are prepared to the IPv6 address format. - Communication API functions. These functions manage communications. Their signatures are defined based on generic socket address structure. Then, the same functions are valid for IPv6. However, the IP address data structures used when calling these functions require the updates. - Network configuration options. They are used when configuring different communication models for Input/Output (I/O) operations (blocking/nonblocking, I/O multiplexing, etc) and should be translated to the IPv6 ones. 5.3 Name and address resolution Applications usually call functions in a system library, known as the resolver, to realize the name and address resolution. Since these functions use IP address structures, which are protocol dependent, not only the functions but also the structures must be reviewed to support IPv6. There are new resolution functions that provide protocol independence for applications, since knowing the address family is not required to carry out the resolution. Resolution queries should not be constrained to one address family, IPv4 or IPv6 addresses. For intance, when getting IP addresses for a hostname, applications should ask for all configured IP addresses to allow applications to communicate to every kind of node. 5.4 Specific IP dependencies 5.4.1 IP address selection IPv6 promotes the configuration of multiple IP addresses per node, which is a different model of IPv4; however applications only use a destination/source pair for a communication. Choosing the right IP source and destination addresses is a key factor that may determine the route of IP datagrams. Typically nodes, not applications, automatically solve the source address selection. A node will choose the source address for a communication following some rules of best choice, [RFC 3484], but also allowing applications to make changes in the ordering rules. When selecting the destination address, applications usually ask a Shin et al. Expires December 2003 [Page 12] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 resolver for the destination IP address. The resolver returns a set of valid IP addresses from a hostname. Applications should select from this list which destination address to use. They may try each element in the list until the communication succeeds. 5.4.2 Application framing The Application Level Framing (ALF) architecture controls mechanisms that traditionally fall within the transport layer. Applications implementing ALF are often responsible for packetizing data into Application Data Units (ADUs). The application problem when using ALF is the ADU size selection to obtain better performance. Applications can use 1280 octets as data length. [RFC 2460] specifies IPv6 requires that every link in the Internet have an Maximum Transmission Unit (MTU) of 1280 octets or greater. However, in order to get better performance ADU size should be calculated based on the length of transmission unit of underlying protocols. 5.4.3 Storage of IP addresses Some applications store IP addresses as information of remote peers. For instance, one of the most popular ways to register remote nodes in collaborative applications is based on using IP addresses as registry keys. Although the source code that stores IP addresses can be modified to IPv6 following the previous basic porting recommendations, there are some reasons why applications should not store IP addresses: - IP addresses can change throughout the time, for instance after a renumbering process. - The same node can reach a destination host using different source IP addresses, all of them configured in the source network interface. Instead of using IP addresses, applications should use FQDNs. Hence, applications delegate the resolution of the IP addresses to the name resolution system, which will return the associated IP address at the moment of the query. 6. Developing IP version-independent applications As we have seen before, dual applications working on IPv4 and IPv6 are recommended. These applications should avoid IP dependencies in the source code. However if IP dependencies are required, one of the best solutions is based on building a communication library Shin et al. Expires December 2003 [Page 13] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 which provides an IP version independent API to applications and hides all dependencies. In order to get IP version independent source code, the following developing guidelines should be considered. 6.1 IP version-independent structures All of the memory structures and APIs should be IP version- independent. In that sense, we should avoid struct in_addr and in6_addr, and struct sockaddr_in and struct sockaddr_in6. Suppose you pass an network address to some function, foo(). If you use struct in_addr or struct in6_addr, you will end up with extra parameter to indicate address family, as below: struct in_addr in4addr; struct in6_addr in6addr; /* IPv4 case */ foo(&in4addr, AF_INET); /* IPv6 case */ foo(&in6addr, AF_INET6); This way the network address and address family is will not live together, and leads to bunch of if/switch statement and mistakes in programming. So, we should use struct sockaddr_storage like below. struct sockaddr_storage ss; int sslen; /* AF independent! - use sockaddr when passing a pointer */ foo((struct sockaddr *)&ss); /* if you need portability to Linux/Solaris, you need to pass length explicitly */ foo((struct sockaddr *)&ss, sslen); 6.2 IP version-independent APIs getaddrinfo() and getnameinfo() are new address independent variant that hides every gory detail in name-to-address translation, or vice versa. It implements functionalities for the following functions: gethostbyname() gethostbyaddr() getservbyname() getservbyport() These can perform DNS/hostname table lookup, though it can be turned off if you want. getaddrinfo() can return multiple addresses, if a host have multiple address with multiple address Shin et al. Expires December 2003 [Page 14] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 families, as below: localhost. IN A 127.0.0.1 IN AAAA ::1 It can query hostname as well as service name/port at once. Therefore, we can bury all the gory details about initializing sockaddr structure into library function. As well, it is not preferred to hardcode AF-dependent knowledge into the program. The construct like below should be avoided: /* BAD EXAMPLE */ switch (sa->sa_family) { case AF_INET: salen = sizeof(struct sockaddr_in); break; } Instead, we should use res->ai_addrlen returned by getaddrinfo(). The gethostbyname(), gethostbyaddr(), getservbyname(), and getservbyport() are mainly used to get server and client sockets. Following, we will see simple examples to create these sockets using the net IPv6 resolution functions. A simple TCP server socket at service name (or port number string) SERVICE: struct addrinfo hints, *res; int error, sockfd; memset(&hints, 0, sizeof(hints)); hints.ai_flags = AI_PASSIVE; hints.ai_family = AF_UNSPEC; hints.ai_socktype = SOCK_STREAM; error = getaddrinfo(NULL, SERVICE, &hints, &res); if (error != 0) { /* handle getaddrinfo error */ } sockfd = socket(res->family, res->ai_socktype, res->ai_protocol); if (sockfd < 0) { /* handle socket error */ } if (bind(sockfd, res->ai_addr, res->ai_addrlen) < 0) { /* handle bind error */ } /* ... */ Shin et al. Expires December 2003 [Page 15] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 freeaddrinfo(res); A simple TCP client socket connecting to a server which is running at node name (or IP address presentation format) SERVER_NODE and service name (or port number string) SERVICE: struct addrinfo hints, *res; int error, sockfd; memset(&hints, 0, sizeof(hints)); hints.ai_family = AF_UNSPEC; hints.ai_socktype = SOCK_STREAM; error = getaddrinfo(SERVER_NODE, SERVICE, &hints, &res); if (error != 0) { /* handle getaddrinfo error */ } sockfd = socket(res->family, res->ai_socktype, res->ai_protocol); if (sockfd < 0) { /* handle socket error */ } if (connect(sockfd, res->ai_addr, res->ai_addrlen) < 0 ) { /* handle connect error */ } /* ... */ freeaddrinfo(res); In addition, we should consider the binary and presentation address format conversion APIs. The following functions convert network address structure in its presentation address format and vice versa: inet_ntop() inet_pton() Both are from the basic socket extensions for IPv6. Since these functions are not protocol independent, we should write code for the different address families. a) Conversions from network address structure to presentation format can be written: struct sockaddr_storage ss; char addrStr[ADDR_STRLEN]; /* fill ss structure */ switch (ss.ss_family) { Shin et al. Expires December 2003 [Page 16] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 case AF_INET: inet_ntop(ss.ss_family, &((struct sockaddr_in *)&ss)->sin_addr, addrStr, sizeof(addrStr)); break; case AF_INET6: inet_ntop(ss.ss_family, &((struct sockaddr_in6 *)&ss)->sin6_addr, addrStr, sizeof(addrStr)); break; default: /* handle unknown family */ } Note, the destination buffer addrStr should be long enough to contain the presentation address format: INET_ADDRSTRLEN for IPv4 and INET6_ADDRSTRLEN for IPv6. Then, ADDR_STRLEN should be at least the maximum between them. However, this conversion is protocol dependent. We can write the same conversion using getnameinfo() in a protocol independent way. struct sockaddr_storage ss; char addrStr[ADDR_STRLEN]; char addrStr[SERV_STRLEN]; int error; /* fill ss structure */ error = getnameinfo((struct sockaddr *)&ss, sizeof(ss), addrStr, sizeof(addrStr), servStr, sizeof(servStr), NI_NUMERICHOST); b) Conversions from presentation format to network address structure can be written as follows: struct sockaddr_storage ss; struct sockaddr_in *sin; struct sockaddr_in6 *sin6; char addrStr[ADDR_STRLEN]; /* fill addrStr buffer and ss.ss_family */ switch (ss.ss_family) { case AF_INET: sin = (struct sockaddr_in *)&ss; Shin et al. Expires December 2003 [Page 17] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 inet_pton(ss.ss_family, addrStr, (sockaddr *)&sin->sin_addr)); break; case AF_INET6: sin6 = (struct sockaddr_in6 *)&ss; inet_pton(ss.ss_family, addrStr, (sockaddr *)&sin6->sin6_addr); break; default: /* handle unknown family */ } Note, the address family of the presentation format must be known. This conversion may be also written in a protocol independent way using getaddrinfo(). struct addrinfo hints, *res; char addrStr[ADDR_STRLEN]; int error; /* fill addrStr buffer */ memset(&hints, 0, sizeof(hints)); hints.ai_family = AF_UNSPEC; error = getaddrinfo(addrStr, NULL, &hints, &res); if (error != 0) { /* handle getaddrinfo error */ } /* res->ai_addr contains the network address structure */ /* ... */ freeaddrinfo(res); 6.3 Iterated jobs for finding the working address In a client code, when multiple addresses are returned from getaddrinfo(), we should try all of them until connection succeds. When there exist failure on socket() or connect(), go on to next address. That is, the client code should do iterated jobs (using the other application out of addresses returned by the getaddrinfo(). In addition, if something is wrong with the socket call because the address family is not supported (i.e., in case of section 4.4), Shin et al. Expires December 2003 [Page 18] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 developers should try the next address structure. Then, the previous TCP client example should be written: struct addrinfo hints, *res, *aip; int sockfd, error, afNotSupp; afNotSupp=AF_UNSPEC; /* overwrite the family not supported in this machine */ memset(&hints, 0, sizeof(hints)); hints.ai_family = AF_UNSPEC; hints.ai_socktype = SOCK_STREAM; error = getaddrinfo(SERVER_NODE, SERVICE, &hints, &res); if (error != 0) { /* handle getaddrinfo error */ } for (aip=res; aip; aip=aip->ai_next) { if (aip->ai_family == afNotSupp) continue; sockfd = socket(aip->ai_family, aip->ai_socktype, aip->ai_protocol); if (sockfd < 0) { switch errno { case EAFNOSUPPORT: /* handle unknown protocol errors */ afNotSupp=aip->ai_family; break; default: /* handle other socket errors */ ; } } else { if (connect(sockfd, aip->ai_addr, aip->ai_addrlen) == 0) break; /* handle connect errors */ close(sockfd); sockfd=-1; } } if (sockfd > 0) { /* socket connected to server address */ Shin et al. Expires December 2003 [Page 19] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 /* ... */ } freeaddrinfo(res); 7. Transition mechanism considerations Under [NAT-PT] mechanism, a pair of IPv6-only and IPv4-only applications could be enough but one should note one special case (NAT-PT prefix + IPv4 address) which one might be tempted to handle differently. This is an IPv4 addresses, translated by NAT-PT DNS ALG [DNS-ALG]. IPv6 applications, in general, must not be required to distinguish "normal" and "NAT-PT translated" addresses: that would be completely unscalable, and if such distinction must be made, it must be done elsewhere (e.g. kernel, system libraries). 8. Security considerations See the each security consideration section listed in section 9 - Normative References. Each issue on application transtion is not studied yet. One particular point about application transition is how IPv4- mapped IPv6-addresses are handled. The use in the API can be seen as both a merit (easier application transition) and as a burden (difficulty in ensuring whether the use was legimate) [V6MAPPED]. This may have to be considered in more detail. 9. References Normative References [RFC 2553] R. Gilligan, S. Thomson, J. Bound, W. Stevens, "Basic Socket Interface Extensions for IPv6," RFC 2553, March 1999. [RFC 3542] W. Stevens, M. Thomas, E. Nordmark, T. Jinmei, "Advanced Sockets Application Program Interface (API) for IPv6," RFC 3542, May 2003. [BIS] K. Tsuchiya, H. Higuchi, Y. Atarashi, "Dual Stack Hosts using the "Bump-In-the-Stack" Technique (BIS)," RFC 2767, February 2000. [BIA] S. Lee, M-K. Shin, Y-J. Kim, E. Nordmark, A. Durand, "Dual Stack Hosts using "Bump-in-the-API" (BIA)," RFC 3338, October 2002. [NAT-PT] G. Tsirtsis, P. Srisuresh, "Network Address Translation Shin et al. Expires December 2003 [Page 20] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 - Protocol Translation (NAT-PT)," RFC 2766, February 2000. Informative References [RFC 2893] R Gilligan, E. Nordmark, "Transition Mechanisms for IPv6 Hosts and Routers," RFC 2893, August 2000. [RFC 2185] R. Callon, D. Haskin, "Routing Aspects Of IPv6 Transition," RFC 2185, September 1997. [RFC 2460] S. Deering, R. Hinden, "Internet Protocol, Version 6 (IPv6) Specification,", RFC 2460, December 1998. [RFC 3484] R. Draves, "Default Address Selection for IPv6," RFC 3484, February 2003. [RFC 2732] R. Hinden, B. Carpenter, L. Masinter, "Format for Literal IPv6 Addresses in URL's," RFC 2732, December 1999. [DNS-ALG] A. Durand, "Issues with NAT-PT DNS ALG in RFC2766", , February 2002, Work in Progress. [DNS] A. Durand, J. Ihren, "IPv6 DNS transition issues," , February 2003, Work in Progress. [AF-APP] Jun-ichiro itojun Hagino, "Implementing AF-independent application", http://www.kame.net/newsletter/19980604/, 2001. [V6MAPPED] Jun-ichiro itojun Hagino, "IPv4 mapped address considered harmful", , work-in-progress, Apr 2002. Authors' Addresses Myung-Ki Shin ETRI PEC 161 Kajong-Dong, Yusong-Gu, Taejon 305-350, Korea Tel : +82 42 860 4847 Fax : +82 42 861 5404 E-mail : mkshin@pec.etri.re.kr Yong-Guen Hong ETRI PEC 161 Kajong-Dong, Yusong-Gu, Taejon 305-350, Korea Tel : +82 42 860 6447 Fax : +82 42 861 5404 E-mail : yghong@pec.etri.re.kr Shin et al. Expires December 2003 [Page 21] INTERNET-DRAFT Application Aspects of IPv6 Transition June 2003 Jun-ichiro itojun HAGINO Research Laboratory, Internet Initiative Japan Inc. Jinbocho Mitsui Buildling, 1-105, Kanda-Jinbocho, Chiyoda-ku,Tokyo 101-0051, JAPAN Tel: +81-3-5205-6464 Fax: +81-3-5205-6465 E-mail: itojun@iijlab.net Pekka Savola CSC/FUNET E-mail : psavola@funet.fi Eva M. Castro Universidad Rey Juan Carlos Escuela Superior de Ciencias Experimentales y Tecnologia Departamento de Informatica, Estadistica y Telematica C/ Tulipan s/n - 28933 Mostoles - Madrid SPAIN E-mail: eva@gsyc.escet.urjc.es Shin et al. Expires December 2003 [Page 22]