idnits 2.17.1 draft-ietf-shim6-multihome-shim-api-04.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** It looks like you're using RFC 3978 boilerplate. You should update this to the boilerplate described in the IETF Trust License Policy document (see https://trustee.ietf.org/license-info), which is required now. -- Found old boilerplate from RFC 3978, Section 5.1 on line 19. -- Found old boilerplate from RFC 3978, Section 5.5, updated by RFC 4748 on line 1541. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1552. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1559. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1565. Checking nits according to https://www.ietf.org/id-info/1id-guidelines.txt: ---------------------------------------------------------------------------- No issues found here. Checking nits according to https://www.ietf.org/id-info/checklist : ---------------------------------------------------------------------------- ** The document seems to lack a both a reference to RFC 2119 and the recommended RFC 2119 boilerplate, even if it appears to use RFC 2119 keywords. RFC 2119 keyword, line 1203: '...e multihoming shim layer SHOULD delete...' RFC 2119 keyword, line 1206: '...y forked context SHOULD be checked if ...' RFC 2119 keyword, line 1211: '... context forking MUST NOT be triggered...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 950 has weird spacing: '... u_int msg_...' == Line 951 has weird spacing: '... struct iovec...' == Line 952 has weird spacing: '... u_int msg_...' == Line 954 has weird spacing: '... u_int msg_...' -- 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 (February 7, 2008) is 5923 days in the past. Is this intentional? -- Found something which looks like a code comment -- if you have code sections in the document, please surround them with '' and '' lines. Checking references for intended status: Informational ---------------------------------------------------------------------------- -- Looks like a reference, but probably isn't: '16' on line 1075 == Outdated reference: A later version (-13) exists of draft-ietf-shim6-failure-detection-10 == Outdated reference: A later version (-12) exists of draft-ietf-shim6-proto-09 ** Obsolete normative reference: RFC 4423 (Obsoleted by RFC 9063) -- Obsolete informational reference (is this intentional?): RFC 2765 (Obsoleted by RFC 6145) Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 10 comments (--). Run idnits with the --verbose option for more detailed information about the items above. -------------------------------------------------------------------------------- 2 SHIM6 Working Group M. Komu 3 Internet-Draft HIIT 4 Intended status: Informational M. Bagnulo 5 Expires: August 10, 2008 UC3M 6 K. Slavov 7 S. Sugimoto, Ed. 8 Ericsson 9 February 7, 2008 11 Socket Application Program Interface (API) for Multihoming Shim 12 draft-ietf-shim6-multihome-shim-api-04 14 Status of this Memo 16 By submitting this Internet-Draft, each author represents that any 17 applicable patent or other IPR claims of which he or she is aware 18 have been or will be disclosed, and any of which he or she becomes 19 aware will be disclosed, in accordance with Section 6 of BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF), its areas, and its working groups. Note that 23 other groups may also distribute working documents as Internet- 24 Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/ietf/1id-abstracts.txt. 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 This Internet-Draft will expire on August 10, 2008. 39 Copyright Notice 41 Copyright (C) The IETF Trust (2008). 43 Abstract 45 This document specifies a socket API for the multihoming shim layer. 46 The API aims to enable interactions between the applications and the 47 multihoming shim layer for advanced locator management and access to 48 information about failure detection and path exploration. 50 This document is based on an assumption that a multihomed host is 51 equipped with a conceptual sublayer (here after "shim") inside the IP 52 layer that maintains mappings between identifiers and locators. 53 Examples of the shim are SHIM6 and HIP. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 3. System Overview . . . . . . . . . . . . . . . . . . . . . . . 6 60 4. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 5. Socket Options for Multihoming Shim Layer . . . . . . . . . . 9 62 5.1. SHIM_ASSOCIATED . . . . . . . . . . . . . . . . . . . . . 12 63 5.2. SHIM_DONTSHIM . . . . . . . . . . . . . . . . . . . . . . 13 64 5.3. SHIM_HOT_STANDBY . . . . . . . . . . . . . . . . . . . . . 13 65 5.4. SHIM_PATHEXPLORE . . . . . . . . . . . . . . . . . . . . . 14 66 5.5. SHIM_LOC_LOCAL_PREF . . . . . . . . . . . . . . . . . . . 15 67 5.6. SHIM_LOC_PEER_PREF . . . . . . . . . . . . . . . . . . . . 16 68 5.7. SHIM_LOC_LOCAL_RECV . . . . . . . . . . . . . . . . . . . 17 69 5.8. SHIM_LOC_PEER_RECV . . . . . . . . . . . . . . . . . . . . 18 70 5.9. SHIM_LOCLIST_LOCAL . . . . . . . . . . . . . . . . . . . . 18 71 5.10. SHIM_LOCLIST_PEER . . . . . . . . . . . . . . . . . . . . 19 72 5.11. SHIM_APP_TIMEOUT . . . . . . . . . . . . . . . . . . . . . 19 73 5.12. SHIM_DEFERRED_CONTEXT_SETUP . . . . . . . . . . . . . . . 20 74 5.13. Error Handling . . . . . . . . . . . . . . . . . . . . . . 21 75 6. Ancillary Data for Multihoming Shim . . . . . . . . . . . . . 21 76 6.1. Get Locator Information from Incoming Packet . . . . . . . 23 77 6.2. Specify Locator Information for Outgoing Packet . . . . . 23 78 6.3. Notification from Application to Multihoming Shim . . . . 23 79 6.3.1. SHIM_FEEDBACK_POSITIVE . . . . . . . . . . . . . . . . 23 80 6.3.2. SHIM_FEEDBACK_NEGATIVE . . . . . . . . . . . . . . . . 24 81 7. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 24 82 7.1. Placeholder for Locator Information . . . . . . . . . . . 24 83 7.2. Path Exploration Parameter . . . . . . . . . . . . . . . . 25 84 8. Implications for Existing Socket API Extensions . . . . . . . 26 85 9. Resolving Conflicts with Preference Values . . . . . . . . . . 26 86 9.1. Implicit Forking . . . . . . . . . . . . . . . . . . . . . 27 87 10. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 27 88 10.1. Naming at Socket Layer . . . . . . . . . . . . . . . . . . 27 89 10.2. Additional Requirements from Application . . . . . . . . . 28 90 10.3. Issues of Header Conversion among Different Address 91 Family . . . . . . . . . . . . . . . . . . . . . . . . . . 28 92 10.4. Handling of Unknown Locator Provided by Application . . . 28 93 11. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 94 11.1. Changes from version 00 to version 01 . . . . . . . . . . 29 95 11.2. Changes from version 01 to version 02 . . . . . . . . . . 29 96 11.3. Changes from version 02 to version 03 . . . . . . . . . . 29 98 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 99 13. Security Considerations . . . . . . . . . . . . . . . . . . . 29 100 14. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . 30 101 15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 102 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 103 16.1. Normative References . . . . . . . . . . . . . . . . . . . 30 104 16.2. Informative References . . . . . . . . . . . . . . . . . . 31 105 Appendix A. Context Forking . . . . . . . . . . . . . . . . . . . 31 106 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 33 107 Intellectual Property and Copyright Statements . . . . . . . . . . 35 109 1. Introduction 111 HIP and SHIM6 have a commonality in their protocol design separation 112 of identifier and locator (hereafter identifier/locator separation). 113 Both protocols aim to solve problems that are specific to multihoming 114 environment in a host centric approach. In these protocols, a sub- 115 layer within the IP layer maintains mappings of identifiers and 116 locators. 118 The shim layer is useful in a sense that the IP layer can maintain 119 the mapping of an identifier to corresponding locators. Under a 120 multihomed environment, typically, a host has more than one IP 121 address at a time. During a given transaction, a host may be 122 required to switch the IP address used for the communication to 123 another IP address to preserve the communication. The protocol stack 124 should take care of isolating the upper layer from disruption by the 125 address update. The shim layer can make this locator update 126 transparent to the upper layer protocols. 128 In a system which is based on identifier/locator separation, upper 129 layer protocols are expected to deal with identifiers for 130 establishing and handling the communications. If an application 131 wants to have a multihoming support by the shim layer, the IP 132 addresses specified as source and destination addresses must be 133 identifiers. However, this does not necessarily mean that 134 applications are prohibited to choose specific locators in its 135 communication. It may be useful for applications, in some situation, 136 to specify a preferred locator for the flow. 138 This document recommends that the identifier/locator adaptation is 139 done only once inside the network stack of a host. That is, if 140 multiple shim sublayers exist at the IP layer, any one of them should 141 be applied exclusively for a given flow. 143 As this document specifies socket API, it is written so that the 144 contents are in line with Posix standard [POSIX] as much as possible. 145 The API specified in this document defines how to use ancillary data 146 (aka cmsg) to access locator information with recvmsg() and/or 147 sendmsg() I/O calls. Definition of API is presented in C language 148 and data types follow Posix format; intN_t means a singed integer of 149 exactly N bits (e.g. int16_t) and uintN_t means an unsigned integer 150 of exactly N bits (e.g. uint32_t). 152 The target readers of this document are application programmers who 153 develop application software which may benefit greatly from 154 multihomed environment. In addition, this document should be of 155 interest for the developers of a given shim protocol, as the shim 156 layer should provide the interface to the application. 158 2. Terminology 160 This section provides terminology used in this document. Basically 161 most of the terms used in this document are taken from the following 162 documents: 164 o SHIM6 Protocol Specification[I-D.ietf-shim6-proto] 165 o HIP Architecture[RFC4423] 166 o Reachability Protocol (REAP)[I-D.ietf-shim6-failure-detection] 168 In this document, the term "IP" refers to both IPv4 and IPv6, unless 169 the protocol version is specifically mentioned. The followings are 170 definitions of the terms that are frequently used in this document: 172 o Endpoint Identifier (EID) - An identifier used by the application 173 to specify the endpoint of a given communication. Applications 174 may handle EID in various ways such as long-lived connections, 175 callbacks, and referrals[I-D.ietf-shim6-app-refer]. 176 * In the case of SHIM6, an identifier called an ULID serves as an 177 EID. An ULID is chosen from locators available on the host. 178 * In the case of HIP, an identifier which specifies communication 179 endpoints is derived from the public key of the host, which is 180 called a Host Identifier. For the sake of backward 181 compatibility of the socket API, the Host Identifier is 182 represented in a form of hash of public key. 183 o Locator - An IP address actually used to deliver IP packets. 184 Locators should be present in the source and destination fields of 185 the IP header of a packet on the wire. 186 * List of Locators - A list of locators associated with an EID. 187 There are two lists of locators stored in a given context, one 188 is associated with the local EID and the other is associated 189 with the remote EID. As defined in [I-D.ietf-shim6-proto], the 190 list of locators associated with an EID 'A' can be denoted as 191 Ls(A). 192 * Preferred Locator - The (source/destination) locator currently 193 used to send packets within a given context. As defined in 194 [I-D.ietf-shim6-proto], the preferred locator of a host 'A' is 195 denoted as Lp(A). 196 o Shim - A conceptual (sub-)layer inside the IP Layer which 197 maintains mappings of EIDs and locators. An EID can be associated 198 with more than one locators at a time when the host is multihomed. 199 The term 'shim' does not refer to a specific protocol but refers 200 to the conceptual sublayer inside the IP layer. 201 o identifier/locator adaptation - An adaptation performed at the 202 shim layer between EIDs and locators within a given context. The 203 adaptation may end up re-writing the source and destination 204 addresses of the IP packet. In the outbound packet processing, 205 the EID pair is converted to the associated locator pair, while 206 the locator pair is converted to the EID pair in the inbound 207 packet processing. 208 o Context - State information shared by a given pair of peers, which 209 stores a binding between the EIDs and associated locators. The 210 context is maintained at the shim layer. 211 o Reachability Detection - A procedure to check reachability between 212 a given locator pair. 213 o Path - A sequence of routers that an IP packet goes through to 214 reach the destination. 215 o Path Exploration - A procedure to explore available paths for a 216 given set of locator pairs. 217 o Outage - An incident that prevents IP packets to flow from the 218 source locator to the destination locator. When there is an 219 outage, it means that there is no reachability between a given 220 locator pair. The outage can be caused by various reasons, such 221 as shortage of network resources, congestion, and human error 222 (faulty operation). 223 o Working Address Pair - An address pair is said to be working if 224 the packet containing the first address from the pair as source 225 address and the second address from the pair as destination 226 address can safely travel from the source to the destination. If 227 the reachability is confirmed in both directions, the address 228 pairs is said to be bi-directional. Otherwise, it's 229 unidirectional. 230 o Reachability Protocol (REAP) - A protocol for detecting failure 231 and exploring reachability in a multihomed environment. REAP is 232 defined in [I-D.ietf-shim6-failure-detection]. 234 3. System Overview 236 Figure 1 illustrates the system overview. The shim layer and REAP 237 component exist inside the IP layer. Applications can use the socket 238 API defined in this document to interface the shim layer and 239 transport layer for locator management and failure detection and path 240 exploration. 242 It is also possible that the shim layer interacts with transport 243 layers, but the interactions are outside the scope of this document. 245 +------------------------+ 246 | Application | 247 +------------------------+ 248 ^ ^ 249 ~~~~~~~~~~~~~|~Socket Interface|~~~~~~~~~~~~~~ 250 | v 251 +-----------|------------------------------+ 252 | | Transport Layer | 253 +-----------|------------------------------+ 254 ^ | 255 +-------------|-----|-------------------------------------+ 256 | v v | 257 | +-----------------------------+ +----------+ | IP 258 | | Shim |<----->| REAP | | Layer 259 | +-----------------------------+ +----------+ | 260 | ^ ^ | 261 +-----------------------|----------------------|----------+ 262 v v 263 +------------------------------------------+ 264 | Link Layer | 265 +------------------------------------------+ 267 Figure 1: System overview 269 4. Requirements 271 The following is the list of requirements from the application 272 perspective: 273 o Locator management. The shim layer selects a pair of locators for 274 sending IP packets within a given context. The selection is made 275 by taking miscellaneous conditions into account such as 276 reachability of the path, application's preference, and 277 characteristics of path. From the application's perspective: 278 * It should be possible to obtain the lists of locators of a 279 given context: Ls(local) and Ls(remote). 280 * It should be possible to obtain the preferred locators of a 281 given context: Lp(local) and Lp(remote). 282 o Notification from the application to the shim layer about the 283 status of the communication. Note that the notification is made 284 in an event based manner. There are mainly two aspects of the 285 feedback that application or upper layer protocol may provide for 286 the shim layer, positive and negative feedbacks [NOTE: These 287 feedbacks are mentioned in [I-D.ietf-shim6-failure-detection]]: 288 * Positive feedback could be given by the application or upper 289 layer protocol (e.g. TCP) to the shim layer informing that the 290 communication is going well. 292 * Negative feedback could be given by the application or upper 293 layer protocol (e.g. TCP) to the shim layer informing that the 294 communication status is not satisfactory. TCP could detect a 295 problem when it does not receive expected ACK from the peer. 296 ICMP error messages delivered to the upper layer protocol could 297 be a clue for application to detect potential problems. REAP 298 module may be triggered by these negative feedbacks and invoke 299 procedure of path exploration. 300 o Feedback from application to shim layer. The application should 301 be able to inform the shim layer of the timeout values for 302 detecting failures, for sending keepalives, for starting the 303 exploration procedure. In particular, the application should be 304 able to suppress the keepalives. 305 o Hot-standby. The application may request the shim layer for hot- 306 standby capabilities. In this case, alternative paths are known 307 to be working before a failure is detected. Hence it is possible 308 for the host to immediately replace the current locator pair with 309 an alternative locator pair. Hot-standby may allow applications 310 to achieve better failover. 311 o Eagerness of locator exploration. The application should be able 312 to inform the shim layer how aggressive it wants REAP mechanism to 313 perform path exploration (e.g. specifying the number of concurrent 314 attempts of discovering working locator pair) when an outage 315 occurs on the path between the currently selected locator pair. 316 o Providing locator information to application. The application 317 should be able to obtain information about the locator pair which 318 was actually used to send or receive the packet. 319 * For inbound traffic, the application may be interested in the 320 locator pair which was actually used to receive the packet. 321 * For outbound traffic, the application may be interested in the 322 locator pair which was actually used to transmit the packet. 323 In this way, the application may have additional control on the 324 locator management. For example, the application can verify if 325 its preference of locator is actually applied to the flow or not. 326 o The application should be able to specify if it wants to defer the 327 context setup or if it wants context establishment to be started 328 immediately in case there is no available context. With deferred 329 context setup, there should be no additional delay imposed by 330 context establishment in initiation of communication. 331 o Turn on/off shim. The application should be able to request to 332 turn on/off the multihoming support by the shim layer: 333 * Apply shim. The application should be able to explicitly 334 request the shim layer to apply multihoming support. 335 * Don't apply shim. The application should be able to request 336 the shim layer not to apply the multihoming support but to 337 apply normal IP processing at the IP layer. 339 o The application should be able to know if the communication is now 340 served by the shim layer or not. 341 o The application should be able to access locator information 342 regardless of its address family. In other words, no matter 343 whether the target locator is IPv4 or IPv6, the application should 344 be able to use common interface to access the locator information. 346 5. Socket Options for Multihoming Shim Layer 348 In this section, socket options that are specific to multihomed shim 349 are defined. 351 Table 1 provides a list of the socket options that are specific to 352 multihoming shim layer. These socket options can be used by either 353 getsockopt() or setsockopt() system call for a given socket. All of 354 these socket options are defined at level SOL_SHIM. 356 The first column of Table 1 gives the name of the option. The second 357 and third columns indicate whether the option can be handled by 358 getsockopt() and/or setsockopt(), respectively. The fourth column 359 provides a brief description of the socket option. The fifth column 360 shows the type of data structure specified along with the socket 361 option. By default, the data structure type is an integer. 363 +-----------------------------+-----+-----+-----------------+-------+ 364 | optname | get | set | description | dtype | 365 +-----------------------------+-----+-----+-----------------+-------+ 366 | SHIM_ASSOCIATED | o | | Check if the | int | 367 | | | | socket is | | 368 | | | | associated with | | 369 | | | | any shim | | 370 | | | | context or not. | | 371 | SHIM_DONTSHIM | o | o | Request the | int | 372 | | | | shim layer not | | 373 | | | | to apply any | | 374 | | | | multihoming | | 375 | | | | support for the | | 376 | | | | communication. | | 377 | SHIM_HOT_STANDBY | o | o | Request the | int | 378 | | | | shim layer to | | 379 | | | | prepare a | | 380 | | | | hot-standby | | 381 | | | | connection (in | | 382 | | | | addition to the | | 383 | | | | current path). | | 384 | SHIM_LOC_LOCAL_PREF | o | o | Get or set the | *1 | 385 | | | | preferred | | 386 | | | | locator on the | | 387 | | | | local side for | | 388 | | | | the context | | 389 | | | | associated with | | 390 | | | | the socket. | | 391 | SHIM_LOC_PEER_PREF | o | o | Get or set the | *1 | 392 | | | | preferred | | 393 | | | | locator on the | | 394 | | | | remote side for | | 395 | | | | the context | | 396 | | | | associated with | | 397 | | | | the socket. | | 398 | SHIM_LOC_LOCAL_RECV | o | o | Request for the | int | 399 | | | | destination | | 400 | | | | locator of the | | 401 | | | | received IP | | 402 | | | | packet. | | 403 | SHIM_LOC_PEER_RECV | o | o | Request for the | int | 404 | | | | source locator | | 405 | | | | of the received | | 406 | | | | IP packet. | | 407 | SHIM_LOCLIST_LOCAL | o | o | Get or set a | *2 | 408 | | | | list of | | 409 | | | | locators | | 410 | | | | associated with | | 411 | | | | the local EID. | | 412 | SHIM_LOCLIST_PEER | o | o | Get or set a | *2 | 413 | | | | list of | | 414 | | | | locators | | 415 | | | | associated with | | 416 | | | | the peer's EID. | | 417 | SHIM_APP_TIMEOUT | o | o | Inform the shim | int | 418 | | | | layer of a | | 419 | | | | timeout value | | 420 | | | | for detecting | | 421 | | | | failure. | | 422 | SHIM_PATHEXPLORE | o | o | Specify | *3 | 423 | | | | behavior of | | 424 | | | | path | | 425 | | | | exploration and | | 426 | | | | failure | | 427 | | | | detection. | | 428 | SHIM_CONTEXT_DEFERRED_SETUP | o | o | Specify if the | int | 429 | | | | context setup | | 430 | | | | can be deferred | | 431 | | | | or not. | | 432 +-----------------------------+-----+-----+-----------------+-------+ 434 Table 1: Socket options for multihoming shim 436 *1: Pointer to a shim_locator which is defined in Section 7. 438 *2: Pointer to an array of shim_locator. 440 *3: Pointer to a shim_pathexplore which is defined in Section 7. 442 Figure 2 illustrates how the shim specific socket options fit into 443 the system model of socket API. In the figure, it can be seen that 444 the shim layer and the additional protocol components (IPv4 and IPv6) 445 below the shim layer are new to the system model. As previously 446 mentioned, all the shim specific socket options are defined at 447 SOL_SHIM level. This design choice brings the following advantages: 449 1. It is assured that the existing socket API continue to work at 450 the layer above the shim layer. That is, those legacy API deal 451 with 'identifier' aspect of the IP addresses. 452 2. With newly defined socket options for the shim layer, the 453 application obtains additional control on locator management. 454 3. The shim specific socket options are not specific to any address 455 family (IPPROTO_IP or IPPROTO_IPV6) or any transport protocol 456 (IPPROTO_TCP or IPPROTO_UDP). 458 s1 s2 s3 s4 459 | | | | 460 +----------------|--|-------|--|----------------+ 461 | +-------+ +-------+ | 462 | IPPROTO_TCP | TCP | | UDP | | 463 | +-------+ +-------+ | 464 | | \ / | | 465 | | ----- | | 466 | | / \ | | 467 | +------+ +------+ | 468 | IPPROTO_IP | IPv4 | | IPv6 | IPPROTO_IPV6 | 469 | +------+ +------+ | 470 | \ / SOL_SOCKET 471 | +--------\-------/--------+ | 472 | SOL_SHIM | shim | | 473 | +--------/-------\--------+ | 474 | / \ | 475 | +------+ +------+ | 476 | | IPv4 | | IPv6 | | 477 | +------+ +------+ | 478 | | | | 479 +------------------|----------|-----------------+ 480 | | 481 IPv4 IPv6 482 Datagram Datagram 484 Figure 2: System model of socket API with shim layer 486 5.1. SHIM_ASSOCIATED 488 The SHIM_ASSOCIATED option can be used to check whether the socket is 489 associated with any shim context or not. 491 This option is particularly meaningful in a case where the locator 492 information of the received IP packet does not tell whether the 493 identifier/locator adaptation is performed or not. Note that the EID 494 pair and locator pair may be identical in some case. 496 This option can be specified by getsockopt(). Thus, the option is 497 read-only and the result (0 or 1) is set in the option value (the 498 fourth argument of getsockopt()). 500 Data type of the option value is integer. The option value indicates 501 presence of shim context. A returned value 1 means that the socket 502 is associated with a certain shim context at the shim layer, while a 503 return value 0 indicates that there is no context associated with the 504 socket. 506 For example, the option can be used by the application as follows: 508 int optval; 509 int optlen = sizeof(optval); 511 getsockopt(fd, SOL_SHIM, SHIM_ASSOCIATED, &optval, &optlen); 513 5.2. SHIM_DONTSHIM 515 The SHIM_DONTSHIM option can be used to request the shim layer to not 516 apply the multihoming support for the communication established over 517 the socket. 519 Data type of the option value is integer. The option value indicates 520 whether the multihoming shim support is deprecated or not. The 521 option value is binary (0 or 1). By default, the value is set to 0, 522 meaning that the shim layer applies identifier/locator adaptation for 523 the communication. In order to disable the socket option, the 524 application should call setsockopt() with optval set as 0. 526 For example, the option can be disabled by the application as 527 follows. 529 int optval; 531 optval = 0; 533 setsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, sizeof(optval)); 535 For example, the option value can be checked by the application as 536 follows. 538 int optval; 539 int len; 541 len = sizeof(optval); 543 getsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, &len); 545 5.3. SHIM_HOT_STANDBY 547 The SHIM_HOT_STANDBY option can be used to check if the shim layer 548 uses hot-standby connection or not for the communication established 549 over the socket. Hot-standby connection is another working locator 550 pair than the current locator pair. Hence this option is effective 551 only when there is a shim context associated with the socket. 553 Data type of the option value is integer. 555 The option value can be set by setsockopt(). 557 The option value can be read by getsockopt(). 559 By default, the value is set to 0, meaning that hot-standby 560 connection is disabled. 562 For example, the option can be activated by the application as 563 follows. 565 int optval; 567 optval = 1; 569 setsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, 570 sizeof(optval)); 572 For example, the option value can be checked by the application as 573 follows. 575 int optval; 576 int len; 578 len = sizeof(optval); 580 getsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, &len); 582 5.4. SHIM_PATHEXPLORE 584 This option can be used to specify behavior of path exploration to be 585 carried out. Path exploration is a procedure to find an alternative 586 locator pair when the host finds any problem with current locator 587 pair. A message used for finding an alternative locator pair is 588 called a Probe message and it is sent per locator pair. Default 589 value is defined for Initial Probe Timeout (0.5 seconds) and Initial 590 Probe (4 times) in the REAP specification. 592 The option is effective only when there is a shim context associated 593 with the socket. 595 Data type of the option value is a pointer to the buffer where a set 596 of information for path exploration is stored. The data structure is 597 defined in Section 7. 599 By default, the option value is set as NULL, meaning that the option 600 is disabled. 602 An error ENOENT will be returned when there is no context associated 603 with the socket. 605 For example, the parameters for the path exploration can be set as 606 follows. 608 struct shim6_pathexplore pe; 610 pe.pe_probenum = 4; /* times */ 611 pe.pe_keepaliveto = 10; /* seconds */ 612 pe.pe_initprobeto = 500; /* milliseconds */ 613 pe.pe_reserved = 0; 615 setsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, sizeof(pe)); 617 For example, the parameters for the path exploration can be read as 618 follows. 620 struct shim6_pathexplore pe; 621 int len; 623 len = sizeof(pe); 625 getsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, &len); 627 5.5. SHIM_LOC_LOCAL_PREF 629 The SHIM_LOC_LOCAL_PREF option can be used to read or set preferred 630 locator on local side within a given context. Hence this option is 631 effective only when there is a shim context associated with the 632 socket. 634 Data type of the option value is a pointer to the specific data 635 structure which stores the locator information. The data structure 636 is defined in Section 7. 638 By default, the option value is set as NULL, meaning that the option 639 is disabled. 641 The preferred locator can be set by setsockopt(). Verification of 642 the locator shall be done by the shim layer before updating the 643 preferred locator. 645 The preferred locator can be read by getsockopt(). 647 An error ENOENT will be returned when there is no context associated 648 with the socket. 650 An error EINVALIDLOCATOR will be returned when the validation of the 651 specified locator failed. 653 For example, a preferred locator can be set as follows. It should be 654 noted that some members of the shim_locator (lc_ifidx and lc_flags) 655 are ignored in the write operation. 657 struct shim_locator lc; 658 struct in6_addr ip6; 660 /* ...set the locator (ip6)... */ 662 bzero(&lc, sizeof(shim_locator)); 663 lc.lc_family = AF_INET6; /* IPv6 */ 664 lc.lc_ifidx = 0; 665 lc.lc_flags = 0; 666 lc.lc_preference = 255; 667 memcpy(lc.lc_addr, &ip6, sizeof(in6_addr)); 669 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, 670 sizeof(optval)); 672 For example, the preferred locator of the context can be read by 673 application as follows. 675 struct shim_locator lc; 676 int len; 678 len = sizeof(lc); 680 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, &len); 682 5.6. SHIM_LOC_PEER_PREF 684 The SHIM_LOC_PEER_PREF option can be used to read or set preferred 685 locator on peer side within a given context. Hence this option is 686 effective only when there is a shim context associated with the 687 socket. 689 Data type of the option value is a pointer to the specific data 690 structure which stores the locator information. The data structure 691 is defined in Section 7. 693 By default, the option value is set as NULL, meaning that the option 694 is disabled. 696 The preferred locator can be set by setsockopt(). Necessary 697 verification of the locator shall be done by the shim layer before 698 updating the preferred locator. 700 The preferred locator can be read by getsockopt(). 702 An error ENOENT will be returned when there is no context associated 703 with the socket. 705 An error EINVALIDLOCATOR will be returned when the validation of the 706 specified locator failed. 708 For example, a preferred locator can be set as follows. It should be 709 noted that some members of the shim_locator (lc_ifidx and lc_flags) 710 are ignored in the write operation. 712 The usage of the option is same as that of SHIM_LOC_LOCAL_PREF. 714 5.7. SHIM_LOC_LOCAL_RECV 716 The SHIM_LOC_LOCAL_RECV option can be used to request the shim layer 717 to store the destination locator of the received IP packet in an 718 ancillary data object which can be accessed by recvmsg(). Hence this 719 option is effective only when there is a shim context associated with 720 the socket. 722 Data type of the option value is integer. The option value should be 723 binary (0 or 1). By default, the option value is set to 0, meaning 724 that the option is disabled. 726 The option value can be set by setsockopt(). 728 The option value can be read by getsockopt(). 730 See Section 6 for the procedure to access locator information stored 731 in the ancillary data objects. 733 An error ENOENT will be returned when there is no context associated 734 with the socket. 736 For example, the option can be activated by the application as 737 follows: 739 int optval; 741 optval = 1; 743 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, 744 sizeof(optval)); 746 For example, the option value can be checked by the application as 747 follows: 749 int optval; 750 int len; 752 len = sizeof(optval); 754 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, &len); 756 5.8. SHIM_LOC_PEER_RECV 758 The SHIM_LOC_PEER_RECV option can be used to request the shim layer 759 to store the source locator of the received IP packet in an ancillary 760 data object which can be accessed by recvmsg(). Hence this option is 761 effective only when there is a shim context associated with the 762 socket. 764 Data type of the option value is integer. The option value should be 765 binary (0 or 1). By default, the option value is set to 0, meaning 766 that the option is disabled. 768 The option value can be set by setsockopt(). 770 The option value can be read by getsockopt(). 772 See Section 6 for the procedure to access locator information stored 773 in the ancillary data objects. 775 An error ENOENT will be returned when there is no context associated 776 with the socket. 778 The usage of the option is same as that of SHIM_LOC_LOCAL_RECV 779 option. 781 5.9. SHIM_LOCLIST_LOCAL 783 The SHIM_LOCLIST_LOCAL option can be used to read or set the locator 784 list associated with the local EID of the shim context associated 785 with the socket. Hence this option is effective only when there is a 786 shim context associated with the socket. 788 Data type of option value is pointer to the buffer where a locator 789 list is stored. See Section 7 for the data structure for storing the 790 locator information. By default, the option value is set as NULL, 791 meaning that the option is disabled. 793 The locator list can be read by getsockopt(). Note that the size of 794 the buffer pointed by optval argument should be large enough to store 795 an array of locator information. The number of the locator 796 information is not known beforehand. 798 The locator list can be set by setsockopt(). The buffer pointed by 799 optval argument should contain an array of locator list. 801 An error ENOENT will be returned when there is no context associated 802 with the socket. 804 An error EINVALIDLOCATOR will be returned when the validation of the 805 specified locator failed. 807 Example is TBD. 809 5.10. SHIM_LOCLIST_PEER 811 The SHIM_LOCLIST_LOCAL option can be used to read or set the locator 812 list associated with the peer EID of the shim context associated with 813 the socket. Hence this option is effective only when there is a shim 814 context associated with the socket. 816 Data type of option value is pointer to the buffer where a locator 817 list is stored. See Section 7 for the data structure for storing the 818 locator information. By default, the option value is set as NULL, 819 meaning that the option is disabled. 821 The locator list can be read by getsockopt(). Note that the size of 822 the buffer pointed by optval argument should be large enough to store 823 an array of locator information. The number of the locator 824 information is not known beforehand. 826 The locator list can be set by setsockopt(). The buffer pointed by 827 optval argument should contain an array of locator list. 829 An error ENOENT will be returned when there is no context associated 830 with the socket. 832 An error EINVALIDLOCATOR will be returned when the validation of the 833 specified locator failed. 835 The usage of the option is same as that of SHIM_LOCLIST_LOCAL. 837 5.11. SHIM_APP_TIMEOUT 839 The SHIM_APP_TIMEOUT option indicates timeout value for application 840 to detect failure. Hence this option is effective only when there is 841 a shim context associated with the socket. 843 Data type of the option value is integer. The value indicates the 844 period of timeout in seconds to send a REAP Keepalive message since 845 the last outbound traffic. By default, the option value is set as 0, 846 meaning that the option is disabled. When the option is disabled, 847 the REAP mechanism follows its default value of Send Timeout value as 848 specified in [I-D.ietf-shim6-failure-detection] 850 If the timeout value specified is longer than the Send Timeout 851 configured in the REAP component, the REAP Keepalive message should 852 be suppressed. 854 An error ENOENT will be returned when there is no context associated 855 with the socket. 857 For example, a specific timeout value can be configured by the 858 application as follows: 860 int optval; 862 optval = 15; /* 15 seconds */ 864 setsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, 865 sizeof(optval)); 867 For example, the option value namely the period of timeout can be 868 checked by the application as follows: 870 int optval; 871 int len; 873 len = sizeof(optval); 875 getsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, &len); 877 5.12. SHIM_DEFERRED_CONTEXT_SETUP 879 The SHIM_DEFERRED_CONTEXT_SETUP option indicates how initiation of 880 context setup is made in terms of timing (before or after) the 881 initial communication flow. Deferred context means that the 882 establishment of context does not put additional delay for an initial 883 transaction. 885 Data type for the option value is integer. The option value should 886 binary (0 or 1). By default, the value is set as 1, meaning that the 887 context setup is deferred. In order to disable the option, the 888 application should call setsockopt() with option value set as 0. 890 However, it should be noted that in some case, deferred context setup 891 is not possible; given EID is non-routable address and there is no 892 way to transmit any IP packet unless there is a context providing the 893 locators. In such case, context should be established prior to the 894 communication. 896 For example, the option can be disabled by the application as 897 follows: 899 int optval; 901 optval = 0; 903 setsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, 904 &optval, sizeof(optval)); 906 For example, the option value can be checked by the application as 907 follows: 909 int optval; 910 int len; 912 len = sizeof(optval); 914 getsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, 915 &optval, &len); 917 5.13. Error Handling 919 If successful, getsockopt() and setsockopt() return 0; otherwise, the 920 functions return -1 and set errno to indicate error. 922 The followings are errno codes newly defined for some shim specific 923 socket options indicating that the getsockopt() or setsockopt() 924 finished incompletely: 926 EINVALIDLOCATOR 927 This indicates that at least one of the necessary validations 928 inside the shim layer for the specified locator has failed. In 929 case of SHIM6, there are two kinds of verifications required for 930 security reasons prior to sending an IP packet to the peer's new 931 locator; one is return routability (check if the peer is actually 932 willing to receive data with the specified locator) and the other 933 is verifications based on given crypto identifier mechanisms 934 [RFC3972], [I-D.ietf-shim6-hba]. 936 6. Ancillary Data for Multihoming Shim 938 In this section, definition and usage of the ancillary data which is 939 specific to multihoming shim are provided. 941 As defined in Posix standard, sendmsg() and recvmsg() take msghdr 942 structure as its argument and they can additionally handle control 943 information along with data. Figure 18 shows the msghdr structure 944 which is defined in . msg_control member holds a 945 pointer to the buffer where the shim specific ancillary data objects 946 can be stored in addition to other ancillary data objects. 948 struct msghdr { 949 caddr_t msg_name; /* optional address */ 950 u_int msg_namelen; /* size of address */ 951 struct iovec *msg_iov; /* scatter/gather array */ 952 u_int msg_iovlen; /* # elements in msg_iov */ 953 caddr_t msg_control; /* ancillary data, see below */ 954 u_int msg_controllen; /* ancillary data buffer len */ 955 int msg_flags; /* flags on received message */ 956 }; 958 Figure 18: msghdr structure 960 The buffer pointed from the msg_control member of the msghdr 961 structure may contain a locator information which is a single locator 962 and it should be possible to process them with the existing macros 963 defined in Posix and [RFC3542]. Each cmsghdr{} should be followed by 964 data which stores a single locator. 966 In case of non-connected socket, msg_name member stores the socket 967 address of the peer which should be considered as an identifier 968 rather than a locator. The locator of the peer node should be 969 retrieved by SHIM_LOC_PEER_RECV as specified below. 971 Table 2 is a list of the shim specific ancillary data which can be 972 used for recvmsg() or sendmsg(). In any case, SOL_SHIM must be set 973 as cmsg_level. 975 +------------------------+-----------+-----------+-------------+ 976 | cmsg_type | sendmsg() | recvmsg() | cmsg_data[] | 977 +------------------------+-----------+-----------+-------------+ 978 | SHIM_LOC_LOCAL_RECV | | o | *1 | 979 | SHIM_LOC_PEER_RECV | | o | *1 | 980 | SHIM_LOC_LOCAL_SEND | o | | *1 | 981 | SHIM_LOC_PEER_SEND | o | | *1 | 982 | SHIM_FEEDBACK_POSITIVE | o | | TBD | 983 | SHIM_FEEDBACK_NEGATIVE | o | | TBD | 984 +------------------------+-----------+-----------+-------------+ 986 Table 2: Shim specific ancillary data 988 *1: cmsg_data[] should include padding (if necessary) and a single 989 sockaddr_in{}/sockaddr_in6{}. 991 It should be noted that the above ancillary data can only be handled 992 in UDP and raw sockets, not in TCP sockets because there is no one- 993 to-one mapping of send/receive operations and the TCP segments being 994 transmitted/received. 996 6.1. Get Locator Information from Incoming Packet 998 Application can get locator information from the received IP packet 999 by specifying the shim specific socket options for the socket. When 1000 SHIM_LOC_LOCAL_RECV and/or SHIM_LOC_PEER_RECV socket options are set, 1001 the application can retrieve local and/or remote locator from the 1002 ancillary data. 1004 6.2. Specify Locator Information for Outgoing Packet 1006 Application can specify the locators to be used for transmitting an 1007 IP packet by sendmsg(). When ancillary data of cmsg_type 1008 SHIM_LOC_LOCAL_SEND and/or SHIM_LOC_PEER_SEND are specified, the 1009 application can explicitly specify source and/or destination locators 1010 to be used for the communication over the socket. 1012 In addition, the application can specify the outgoing interface by 1013 SHIM_IF_SEND ancillary data. The ancillary data should contain the 1014 interface identifier of the physical interface over which the 1015 application expects the packet to be transmitted. 1017 Note that the effect is limited to the datagram transmitted by the 1018 sendmsg(). 1020 If the specified locator pair seems to be valid, the shim layer 1021 overrides the locator of the IP packet as requested. 1023 An error EINVALIDLOCATOR will be returned when validation of the 1024 specified locator failed. 1026 6.3. Notification from Application to Multihoming Shim 1028 Application may provide feedback to the shim layer in accordance with 1029 its communication status. The notification can be made by specifying 1030 shim specific ancillary data in sendmsg() call. Note that this 1031 notification is dynamic rather than static. 1033 6.3.1. SHIM_FEEDBACK_POSITIVE 1035 The application can simply inform the shim layer that its 1036 communication is going well. 1038 Data type is TBD. 1040 An error ENOENT will be returned when there is no context associated 1041 with the socket. 1043 6.3.2. SHIM_FEEDBACK_NEGATIVE 1045 The application can inform the shim layer that its communication is 1046 not going well. 1048 Data type is TBD. 1050 An error ENOENT will be returned when there is no context associated 1051 with the socket. 1053 7. Data Structures 1055 In this section, data structures specifically defined for the 1056 multihoming shim layer are introduced. Those data structures are 1058 7.1. Placeholder for Locator Information 1060 As defined in Section 5, the SHIM_LOC_LOCAL_PREF, SHIM_LOC_PEER_PREF, 1061 SHIM_LOCLIST_LOCAL, and SHIM_LOCLIST_PEER socket options need to 1062 handle one or more locator information. Locator information includes 1063 not only the locator itself but also additional information about the 1064 locator which is useful for locator management. A new data structure 1065 is defined to serve as a placeholder for the locator information. 1067 Figure 19 illustrates the data structure called shim_locator which 1068 stores a locator information. 1070 struct shim_locator { 1071 uint8_t lc_family; /* address family */ 1072 uint8_t lc_ifidx; /* interface index */ 1073 uint8_t lc_flags; /* flags */ 1074 uint8_t lc_preference; /* preference value */ 1075 uint8_t lc_addr[16]; /* locator */ 1076 }; 1078 Figure 19: shim locator structure 1080 lc_family 1081 Address family of the locator (e.g. AF_INET, AF_INET6). It is 1082 required that the parameter contains non-zero value indicating the 1083 exact address family of the locator. 1085 lc_ifidx 1086 Interface index of the network interface to which the locator is 1087 assigned. This field should be valid only in read (getsockopt()) 1088 operation. 1089 lc_flags 1090 Each bit of the flags represents a specific characteristics of the 1091 locator. HBA is defined as 0x01. CGA is defined as 0x02. The 1092 other bits are TBD. 1093 lc_preference 1094 Indicates preference of the locator. The preference is 1095 represented by integer. 1096 lc_addr 1097 Contains the locator. For the cases where a locator whose size is 1098 smaller than 16 bytes, encoding rule should be provided for each 1099 locator of a given address family. For instance, in case of 1100 AF_INET (IPv4), the last 4 bytes of lc_addr should contain the 1101 IPv4 address. 1103 7.2. Path Exploration Parameter 1105 As defined in Section 5, SHIM_PATHEXPLORE allows application to set 1106 or read the parameters for path exploration and failure detection. A 1107 new data structure called shim_pathexplore is defined to store the 1108 necessary parameters. Figure 20 illustrates the data structure. The 1109 data structure can be used by getsockopt() or setsockopt() as an 1110 argument. 1112 struct shim_pathexplore { 1113 uint8_t pe_probenum; /* # of initial probe */ 1114 uint8_t pe_keepaliveto; /* Keepalive Timeout */ 1115 uint16_t pe_initprobeto; /* Initial Probe Timeout */ 1116 uint32_t pe_reserved; /* reserved */ 1117 }; 1119 Figure 20: path explore structure 1121 pe_probenum 1122 Indicates the number of initial probe messages to be sent. 1123 Default value of this parameter should follow what is specified in 1124 [I-D.ietf-shim6-failure-detection]. 1125 pe_keepaliveto 1126 Indicates timeout value for detecting a failure when the host does 1127 not receive any packets for a certain period of time while there 1128 is outbound traffic. When the timer expires, path exploration 1129 procedure will be carried out by sending a REAP Probe message. 1130 Default value of this parameter should follow what is specified in 1131 [I-D.ietf-shim6-failure-detection]. 1133 pe_initprobeto 1134 Indicates retransmission timer of REAP Probe message in 1135 milliseconds. Note that this timer is applied before exponential 1136 back-off is started. A REAP Probe message for the same locator 1137 pair may be retransmitted. Default value of this parameter should 1138 follow what is specified in [I-D.ietf-shim6-failure-detection]. 1139 pe_reserved 1140 A reserved field for future extension. By default, the field 1141 should be initialized with zero. 1143 8. Implications for Existing Socket API Extensions 1145 Some of the socket options defined in this document have some 1146 overlapping with existing socket API and care should be made for the 1147 usage not to confuse the features. 1149 The socket options for requesting specific locators to be used for a 1150 given transaction (SHIM_LOC_LOCAL_PREF and SHIM_LOC_PEER_PREF) are 1151 semantically similar to the existing socket API (IPV6_PKTINFO). The 1152 socket options for obtaining the locator information from the 1153 received IP packet (SHIM_LOC_LOCAL_RECV and SHIM_LOC_PEER_RECV) are 1154 semantically similar to the existing socket API (IP_RECVDSTADDR and 1155 IPV6_PKTINFO). 1157 In IPv4, application can obtain the destination IP address of the 1158 received IP packet (IP_RECVDSTADDR). If the shim layer performs 1159 identifier/locator adaptation for the received packet, the 1160 destination EID should be stored in the ancillary data 1161 (IP_RECVDSTADDR). 1163 In IPv6, [RFC3542] defines that IPV6_PKTINFO can be used to specify 1164 source IPv6 address and the outgoing interface for outgoing packets, 1165 and retrieve destination IPv6 address and receiving interface for 1166 incoming packets. This information is stored in ancillary data being 1167 IPV6_PKTINFO specified as cmsg_type. Existing socket API should 1168 continue to work above the shim layer, that is, the IP addresses 1169 handled in IPV6_PKTINFO should be EIDs, not the locators. 1171 Baseline is that the above existing socket API (IP_RECVDSTADDR and 1172 IPV6_PKTINFO) is assumed to work above the multihoming shim layer. 1173 In other words, the IP addresses those socket options deal with are 1174 EIDs rather than locators. 1176 9. Resolving Conflicts with Preference Values 1178 Since the multihoming shim API allows application to specify 1179 preference value for the context which is associated with the socket 1180 instance, there may be a conflict with preference values specified by 1181 different applications. For instance, application A and B may 1182 establish communication over the same EID pair while each application 1183 have different preference in their choice of local locator. 1185 SHIM6 supports a notion of forking context in which a context is 1186 split when there is a conflict with preference values specified by 1187 multiple applications. Thus, context forking can simply resolve the 1188 conflicting situation which may be caused by the use of socket 1189 options for multihoming shim layer. 1191 9.1. Implicit Forking 1193 Socket options defined in Section 5 may cause conflicting situation 1194 when the target context is shared by multiple applications. In such 1195 case, socket handler and the multihoming shim layer should react as 1196 follows; socket handler should inform the shim layer that context 1197 forking is required. In SHIM6, when a context is forked, an unique 1198 identifier called Forked Instance Identifier (FII) is assigned to the 1199 newly forked context. The forked context is then exclusively 1200 associated with the socket through which non-default preference value 1201 was specified. The forked context is maintained by the multihoming 1202 shim layer during the lifetime of associated socket instance. When 1203 the socket is closed, the multihoming shim layer SHOULD delete 1204 associated context. In this way, garbage collection can be carried 1205 out to cleanup unused forked contexts. Upon garbage collection, 1206 every forked context SHOULD be checked if there is no socket 1207 (process) associated with the context. If there is none, the forked 1208 context should be deleted. When a forked context is torn down, SHIM6 1209 should notify the peer about the deletion of forked context. 1211 As opposed to socket options, context forking MUST NOT be triggered 1212 by any use of ancillary data that are specific to multihoming shim 1213 defined in Section 6. 1215 10. Discussion 1217 In this section, open issues are introduced. 1219 10.1. Naming at Socket Layer 1221 getsockname() and getpeername() system calls are used to obtain the 1222 'name' of endpoint which is actually a pair of IP address and port 1223 number assigned to a given socket. getsockname() is used when an 1224 application wants to obtain the local IP address and port number 1225 assigned for a given socket instance. getpeername() is used when an 1226 application wants to obtain the remote IP address and port number. 1228 The above is based on a traditional system model of the socket API 1229 where an IP address is expected to play both the role of identifier 1230 and the role of locator. 1232 In a system model where a shim layer exists inside the IP layer, both 1233 getsockname() and getpeername() deal with identifiers, namely EIDs. 1234 In this sense, the shim layer serves to (1) hide locators and (2) 1235 provide access to the identifier for the application over the legacy 1236 socket APIs. 1238 10.2. Additional Requirements from Application 1240 At the moment, it is not certain if following requirements are common 1241 in all the multihomed environments (SHIM6 and HIP). These are mainly 1242 identified during discussions made on SHIM6 WG mailing list. 1243 o The application should be able to set preferences for the 1244 locators, local and remote one and also to the preferences of the 1245 local locators that will be passed to the peer. 1247 10.3. Issues of Header Conversion among Different Address Family 1249 The shim layer performs identifier/locator adaptation. Therefore, in 1250 some case, the whole IP header can be replaced with new IP header of 1251 a different address family (e.g. conversion from IPv4 to IPv6 or vice 1252 versa). Hence, there is an issue how to make the conversion with 1253 minimum impact. Note that this issue is common in other protocol 1254 conversion such as SIIT[RFC2765]. 1256 As addressed in SIIT specification, some of the features (IPv6 1257 routing headers, hop-by-hop extension headers, or destination 1258 headers) from IPv6 are not convertible to IPv4. In addition, notion 1259 of source routing is not exactly the same in IPv4 and IPv6. Hence, 1260 there is certain limitation in protocol conversion between IPv4 and 1261 IPv6. 1263 The question is how should the shim layer behave when it is face with 1264 limitation problem of protocol conversion. Should we introduce new 1265 error something like ENOSUITABLELOCATOR ? 1267 10.4. Handling of Unknown Locator Provided by Application 1269 There might be a case where application provides the shim layer new 1270 locator with the SHIM_LOC_*_PREF socket options or SHIM_LOC_*_SEND 1271 ancillary data. Then there is a question how should the shim layer 1272 treat the new locator informed by the application. 1274 In principle, locator information are exchanged by the shim protocol. 1275 However, there might be a case where application acquires information 1276 about the locator and prefers to use it for its communication. 1278 11. Changes 1280 11.1. Changes from version 00 to version 01 1282 The followings are changes from version 00 to version 01: 1283 o Define shim_locator{} data type which is a placeholder for 1284 locator. 1285 o Define shim_pathexplore{} data type in which a set of REAP 1286 parameters are stored. 1287 o Remove descriptions about "stickiness" of socket options. 1288 o Deprecate SHIM_IF_RECV and SHIM_IF_SEND socket options. 1289 o Give default value and how to disable given socket option. 1291 11.2. Changes from version 01 to version 02 1293 The followings are changes from version 01 to version 02: 1294 o Add section describing context forking. 1295 o Rephrase conclusion section. 1296 o Separate normative references from informative references. 1297 o Remove texts from discussion section that are not relevant to the 1298 contents of the document. 1299 o Add section describing change history (this section). 1301 11.3. Changes from version 02 to version 03 1303 The followings are changes from version 02 to version 03: 1304 o Add an Appendix section describing the issue of context forking. 1306 12. IANA Considerations 1308 This document contains no IANA consideration. 1310 13. Security Considerations 1312 This document does not specify any security mechanism for the shim 1313 layer. Fundamentally, the shim layer has a potential to impose 1314 security threats, as it changes the source and/or destination IP 1315 addresses of the IP packet being sent or received. Therefore, the 1316 basic assumption is that the security mechanism defined in each 1317 protocol of the shim layer is strictly applied. 1319 14. Conclusion 1321 In this document, the Application Program Interface (API) for 1322 multihoming shim layer is specified. The socket API allows 1323 applications to have additional control of the locator management and 1324 interface to the REAP mechanism inside the multihoming shim layer. 1326 Socket options for multihoming shim layer can be used by getsockopt() 1327 and/or setsockopt() system calls. Besides, applications can use some 1328 ancillary data that are specific to multihoming shim layer to get 1329 locator from received packet or to set locator for outgoing packet. 1331 From an architectural point of view, the socket API provides extends 1332 the existing socket API framework in the face of ID/Locator 1333 separation. With regard to API that relate to IP address management, 1334 it is assured that existing socket API continue to work above the 1335 shim layer dealing with identifiers, while multihoming shim API deals 1336 with locators. 1338 15. Acknowledgments 1340 Authors would like to thank Jari Arkko who participated in the 1341 discussion that lead to the first version of this document, and 1342 Tatuya Jinmei who thoroughly reviewed the early version of this draft 1343 and provided detailed comments on socket API related issues. 1345 16. References 1347 16.1. Normative References 1349 [I-D.ietf-shim6-failure-detection] 1350 Arkko, J. and I. Beijnum, "Failure Detection and Locator 1351 Pair Exploration Protocol for IPv6 Multihoming", 1352 draft-ietf-shim6-failure-detection-10 (work in progress), 1353 January 2008. 1355 [I-D.ietf-shim6-proto] 1356 Bagnulo, M. and E. Nordmark, "Level 3 multihoming shim 1357 protocol", draft-ietf-shim6-proto-09 (work in progress), 1358 October 2007. 1360 [POSIX] "IEEE Std. 1003.1-2001 Standard for Information Technology 1361 -- Portable Operating System Interface (POSIX). Open group 1362 Technical Standard: Base Specifications, Issue 6, 1363 http://www.opengroup.org/austin", December 2001. 1365 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 1366 "Advanced Sockets Application Program Interface (API) for 1367 IPv6", RFC 3542, May 2003. 1369 [RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol 1370 (HIP) Architecture", RFC 4423, May 2006. 1372 16.2. Informative References 1374 [I-D.ietf-shim6-app-refer] 1375 Nordmark, E., "Shim6 Application Referral Issues", 1376 draft-ietf-shim6-app-refer-00 (work in progress), 1377 July 2005. 1379 [I-D.ietf-shim6-hba] 1380 Bagnulo, M., "Hash Based Addresses (HBA)", 1381 draft-ietf-shim6-hba-05 (work in progress), December 2007. 1383 [RFC2765] Nordmark, E., "Stateless IP/ICMP Translation Algorithm 1384 (SIIT)", RFC 2765, February 2000. 1386 [RFC3972] Aura, T., "Cryptographically Generated Addresses (CGA)", 1387 RFC 3972, March 2005. 1389 Appendix A. Context Forking 1391 In this section, an issue concerning context forking and its relation 1392 to the multihoming shim API are discussed. 1394 SHIM6 supports a notion of context forking. A peer may decide to 1395 fork a context for certain reason (e.g. upper layer protocol prefers 1396 to use different locator pair than the one defined in available 1397 context). The procedure of forking context is done similar to the 1398 normal context establishment, performing the 4-way message exchange. 1399 A peer who has decided to fork a context initiates the context 1400 establishment. Hereafter, we call this peer initiator. 1402 Once the forked context is established between the peers, on the 1403 initiator side, it is possible to apply forked context to the packet 1404 flow since the system maintains an association between the forked 1405 context and the socket owned by the application that has requested 1406 the context forking. How this association is maintained is 1407 implementation specific issue. However, on the responder side, there 1408 is a question on how the outbound packet can be multiplexed by the 1409 shim layer. Since there are more than one SHIM6 contexts that match 1410 with the ULID pair of the packet flow. There is a need to 1411 differentiate packet flows not only by the ULID pairs but some other 1412 information and associate a given packet flow with specific context. 1414 Figure 21 gives an example of a scenario where two communicating 1415 peers fork a context. Initially, there has been a single transaction 1416 between the peers, by the application 1 (App1). Accordingly, another 1417 transaction is started, by application 2 (App2). Both of the 1418 transactions are made based the same ULID pair. The first context 1419 pair (Ctx1) is established for the transaction of App1. Given the 1420 requests from App2, the shim layer on Peer 1 decides to fork a 1421 context. Accordingly, a forked context (Ctx2) is established between 1422 the peers, which should be exclusively applied to the transaction of 1423 App2. Ideally, multiplexing and demultiplexing of packet flows that 1424 relate to App1 and App2 should be done as illustrated in Figure 21. 1425 However, as mentioned earlier, on the responder side, there is a 1426 problem with multiplexing the outbound packet flows of App1 and App2. 1428 Peer 1 Peer 2 1429 (initiator) (responder) 1431 +----+ +----+ +----+ +----+ 1432 |App1| |App2| |App1| |App2| 1433 +----+ +----+ +----+ +----+ 1434 |^ |^ ^| ^| 1435 v| v| |v |v 1436 -----S1-------------S2----- -----S1-------------S2----- 1437 || || || || 1438 || || || || 1440 Ctx1 Ctx2 Ctx1 Ctx2 1441 ULID: ULID: ULID: ULID: 1442 Loc: Loc: Loc: Loc: 1443 FII: 0 FII: 100 FII: 0 FII: 100 1445 |^ |^ ^| ^| 1446 || || || || 1447 || || || || 1448 \..............||........................../| || 1449 \.............||.........................../ || 1450 || || 1451 \|........................................./| 1452 \........................................../ 1454 Figure 21: context forking 1456 To overcome the problem mentioned above, there are some solutions. 1458 One viable approach is to let the system implicitly maintain an 1459 association between the socket and the associated context by keeping 1460 the record of inbound packet processing. That is, the system stores 1461 the information about the context on which the inbound packet flow 1462 was demultiplexed. The information comprises the ULID pair and FII 1463 of the context and is stored in the socket instance. Later, the 1464 system can use the information to identify the associated context in 1465 outbound packet processing. This approach should be feasible as far 1466 as there is bi-directional user traffic. 1468 Another viable approach is to extend SHIM6 protocol by adding 1469 capability of exchanging additional information to identify the 1470 packet flow from others which needs to be handled by a newly forked 1471 context. The information exchange can be done during the context 1472 establishment. The initiator appends 5 tuple of the packet flow to 1473 be handled by the newly forked context. Note that the additional 1474 information provided by the 5 tuple are source and destination port 1475 numbers and upper layer protocol. The information is later used by 1476 the shim layer to multiplex the outbound packet flow on the responder 1477 side. 1479 The socket options for multihoming shim can be used by the 1480 application to trigger the context forking in implicit manner. The 1481 peer becomes an initiator in the establishment of the forked context. 1482 Once the forked context is established between the peers, application 1483 on each end can influence the preference on context by utilizing the 1484 multihoming shim API. 1486 Authors' Addresses 1488 Miika Komu 1489 Helsinki Institute for Information Technology 1490 Tammasaarenkatu 3 1491 Helsinki 1492 Finland 1494 Phone: +358503841531 1495 Fax: +35896949768 1496 Email: miika@iki.fi 1497 URI: http://www.hiit.fi/ 1498 Marcelo Bagnulo 1499 Universidad Carlos III de Madrid 1500 Av. Universidad 30 1501 Leganes 28911 1502 SPAIN 1504 Phone: +34 91 6248837 1505 Email: marcelo@it.uc3m.es 1506 URI: http://it.uc3m.es/marcelo 1508 Kristian Slavov 1509 Ericsson Research Nomadiclab 1510 Hirsalantie 11 1511 Jorvas FI-02420 1512 Finland 1514 Phone: +358 9 299 3286 1515 Email: kristian.slavov@ericsson.com 1517 Shinta Sugimoto (editor) 1518 Nippon Ericsson K.K. 1519 Koraku Mori Building 1520 1-4-14, Koraku, Bunkyo-ku 1521 Tokyo 112-0004 1522 Japan 1524 Phone: +81 3 3830 2241 1525 Email: shinta.sugimoto@ericsson.com 1527 Full Copyright Statement 1529 Copyright (C) The IETF Trust (2008). 1531 This document is subject to the rights, licenses and restrictions 1532 contained in BCP 78, and except as set forth therein, the authors 1533 retain all their rights. 1535 This document and the information contained herein are provided on an 1536 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1537 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1538 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1539 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1540 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1541 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1543 Intellectual Property 1545 The IETF takes no position regarding the validity or scope of any 1546 Intellectual Property Rights or other rights that might be claimed to 1547 pertain to the implementation or use of the technology described in 1548 this document or the extent to which any license under such rights 1549 might or might not be available; nor does it represent that it has 1550 made any independent effort to identify any such rights. Information 1551 on the procedures with respect to rights in RFC documents can be 1552 found in BCP 78 and BCP 79. 1554 Copies of IPR disclosures made to the IETF Secretariat and any 1555 assurances of licenses to be made available, or the result of an 1556 attempt made to obtain a general license or permission for the use of 1557 such proprietary rights by implementers or users of this 1558 specification can be obtained from the IETF on-line IPR repository at 1559 http://www.ietf.org/ipr. 1561 The IETF invites any interested party to bring to its attention any 1562 copyrights, patents or patent applications, or other proprietary 1563 rights that may cover technology that may be required to implement 1564 this standard. Please address the information to the IETF at 1565 ietf-ipr@ietf.org. 1567 Acknowledgment 1569 Funding for the RFC Editor function is provided by the IETF 1570 Administrative Support Activity (IASA).