idnits 2.17.1 draft-ietf-shim6-multihome-shim-api-02.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 1436. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1447. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1454. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1460. 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 1200: '...e multihoming shim layer SHOULD delete...' RFC 2119 keyword, line 1203: '...y forked context SHOULD be checked if ...' RFC 2119 keyword, line 1208: '... context forking MUST NOT be triggered...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 947 has weird spacing: '... u_int msg_...' == Line 948 has weird spacing: '... struct iovec...' == Line 949 has weird spacing: '... u_int msg_...' == Line 951 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 (March 5, 2007) is 6262 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 1072 == Outdated reference: A later version (-13) exists of draft-ietf-shim6-failure-detection-07 == Outdated reference: A later version (-12) exists of draft-ietf-shim6-proto-07 ** Obsolete normative reference: RFC 4423 (Obsoleted by RFC 9063) == Outdated reference: A later version (-05) exists of draft-ietf-shim6-hba-02 -- Obsolete informational reference (is this intentional?): RFC 2765 (Obsoleted by RFC 6145) Summary: 3 errors (**), 0 flaws (~~), 8 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: September 6, 2007 UC3M 6 K. Slavov 7 S. Sugimoto, Ed. 8 Ericsson 9 March 5, 2007 11 Socket Application Program Interface (API) for Multihoming Shim 12 draft-ietf-shim6-multihome-shim-api-02 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 September 6, 2007. 39 Copyright Notice 41 Copyright (C) The IETF Trust (2007). 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 multhomed 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 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 97 13. Security Considerations . . . . . . . . . . . . . . . . . . . 29 98 14. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . 29 99 15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 100 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 101 16.1. Normative References . . . . . . . . . . . . . . . . . . . 30 102 16.2. Informative References . . . . . . . . . . . . . . . . . . 31 103 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 31 104 Intellectual Property and Copyright Statements . . . . . . . . . . 33 106 1. Introduction 108 HIP and SHIM6 have a commonality in their protocol design separation 109 of identifier and locator (hereafter identifier/locator separation). 110 Both protocols aim to solve problems that are specific to multihoming 111 environment in a host centric approach. In these protocols, a sub- 112 layer within the IP layer maintains mappings of identifiers and 113 locators. 115 The shim layer is useful in a sense that the IP layer can maintain 116 the mapping of an identifier to corresponding locators. Under a 117 multihomed environment, typically, a host has more than one IP 118 address at a time. During a given transaction, a host may be 119 required to switch the IP address used for the communication to 120 another IP address to preserve the communication. A care is needed 121 to not disrupt the upper layer protocols by the address update. The 122 shim layer can make this locator update transparent to the upper 123 layer protocols. 125 In a system which is based on identifier/locator separation, upper 126 layer protocols are expected to deal with identifiers for 127 establishing and handling the communications. If an application 128 wants to have a multihoming support by the shim layer, the IP 129 addresses specified as source and destination addresses must be 130 identifiers. However, this does not necessarily mean that 131 applications are prohibited to choose specific locators in its 132 communication. It may be useful for applications, in some situation, 133 to specify a preferred locator for the flow. 135 This document recommends that the identifier/locator adaptation is 136 done only once inside the network stack of a host. That is, if 137 multiple shim sublayers exist at the IP layer, any one of them should 138 be applied exclusively for a given flow. 140 As this document specifies socket API, it is written so that the 141 contents are in line with Posix standard [POSIX] as much as possible. 142 The API specified in this document defines how to use ancillary data 143 (aka cmsg) to access locator information with recvmsg() and/or 144 sendmsg() I/O calls. Definition of API is presented in C language 145 and data types follow Posix format; intN_t means a singed integer of 146 exactly N bits (e.g. int16_t) and uintN_t means an unsigned integer 147 of exactly N bits (e.g. uint32_t). 149 The target readers of this document are application programmers who 150 develop application software which may benefit greatly from 151 multihomed environment. In addition, this document should be of 152 interest for the developers of a given shim protocol, as the shim 153 layer should provide the interface to the application. 155 2. Terminology 157 This section provides terminology used in this document. Basically 158 most of the terms used in this document are taken from the following 159 documents: 161 o SHIM6 Protocol Specification[I-D.ietf-shim6-proto] 162 o HIP Architecture[RFC4423] 163 o Reachability Protocol (REAP)[I-D.ietf-shim6-failure-detection] 165 In this document, the term "IP" refers to both IPv4 and IPv6, unless 166 the protocol version is specifically mentioned. The followings are 167 definitions of the terms that are frequently used in this document: 169 o Endpoint Identifier (EID) - An identifier used by the application 170 to specify the endpoint of a given communication. Applications 171 may handle EID in various ways such as long-lived connections, 172 callbacks, and referrals[I-D.ietf-shim6-app-refer]. 173 * In the case of SHIM6, an identifier called an ULID serves as an 174 EID. An ULID is chosen from locators available on the host. 175 * In the case of HIP, an identifier which specifies communication 176 endpoints is derived from the public key of the host, which is 177 called a Host Identifier. For the sake of backward 178 compatibility of the socket API, the Host Identifier is 179 represented in a form of hash of public key. 180 o Locator - An IP address actually used to deliver IP packets. 181 Locators should be present in the source and destination fields of 182 the IP header of a packet on the wire. 183 * List of Locators - A list of locators associated with an EID. 184 There are two lists of locators stored in a given context, one 185 is associated with the local EID and the other is associated 186 with the remote EID. As defined in [I-D.ietf-shim6-proto], the 187 list of locators associated with an EID 'A' can be denoted as 188 Ls(A). 189 * Preferred Locator - The (source/destination) locator currently 190 used to send packets within a given context. As defined in 191 [I-D.ietf-shim6-proto], the preferred locator of a host 'A' is 192 denoted as Lp(A). 193 o Shim - A conceptual (sub-)layer inside the IP Layer which 194 maintains mappings of EIDs and locators. An EID can be associated 195 with more than one locators at a time when the host is multihomed. 196 The term 'shim' does not refer to a specific protocol but refers 197 to the conceptual sublayer inside the IP layer. 198 o identifier/locator adaptation - An adaptation performed at the 199 shim layer between EIDs and locators within a given context. The 200 adaptation may end up re-writing the source and destination 201 addresses of the IP packet. In the outbound packet processing, 202 the EID pair is converted to the associated locator pair, while 203 the locator pair is converted to the EID pair in the inbound 204 packet processing. 205 o Context - State information shared by a given pair of peers, which 206 stores a binding between the EIDs and associated locators. The 207 context is maintained at the shim layer. 208 o Reachability Detection - A procedure to check reachability between 209 a given locator pair. 210 o Path - A sequence of routers that an IP packet goes through to 211 reach the destination. 212 o Path Exploration - A procedure to explore available paths for a 213 given set of locator pairs. 214 o Outage - An incident that prevents IP packets to flow from the 215 source locator to the destination locator. When there is an 216 outage, it means that there is no reachability between a given 217 locator pair. The outage can be caused by various reasons, such 218 as shortage of network resources, congestions, and human error 219 (faulty operation). 220 o Working Address Pair - An address pair is said to be working if 221 the packet containing the first address from the pair as source 222 address and the second address from the pair as destination 223 address can safely travel from the source to the destination. If 224 the reachability is confirmed in both directions, the address 225 pairs is said to be bi-directional. Otherwise, it's 226 unidirectional. 227 o Reachability Protocol (REAP) - A protocol for detecting failure 228 and exploring reachability in a multihomed environment. REAP is 229 defined in [I-D.ietf-shim6-failure-detection]. 231 3. System Overview 233 Figure 1 illustrates the system overview. The shim layer and REAP 234 component exist inside the IP layer. Applications can use the socket 235 API defined in this document to interface the shim layer and 236 transport layer for locator management and failure detection and path 237 exploration. 239 It is also possible that the shim layer interacts with transport 240 layers, but the interactions are outside the scope of this document. 242 +------------------------+ 243 | Application | 244 +------------------------+ 245 ^ ^ 246 ~~~~~~~~~~~~~|~Socket Interface|~~~~~~~~~~~~~~ 247 | v 248 +-----------|------------------------------+ 249 | | Transport Layer | 250 +-----------|------------------------------+ 251 ^ | 252 +-------------|-----|-------------------------------------+ 253 | v v | 254 | +-----------------------------+ +----------+ | IP 255 | | Shim |<----->| REAP | | Layer 256 | +-----------------------------+ +----------+ | 257 | ^ ^ | 258 +-----------------------|----------------------|----------+ 259 v v 260 +------------------------------------------+ 261 | Link Layer | 262 +------------------------------------------+ 264 Figure 1: System overview 266 4. Requirements 268 The following is the list of requirements from the application 269 perspective: 270 o Locator management. The shim layer selects a pair of locators for 271 sending IP packets within a given context. The selection is made 272 by taking miscellaneous conditions into account such as 273 reachability of the path, application's preference, and 274 characteristics of path. From the application's perspective: 275 * It should be possible to obtain the lists of locators of a 276 given context: Ls(local) and Ls(remote). 277 * It should be possible to obtain the preferred locators of a 278 given context: Lp(local) and Lp(remote). 279 o Notification from the application to the shim layer about the 280 status of the communication. Note that the notification is made 281 in an event based manner. There are mainly two aspects of the 282 feedback that application or upper layer protocol may provide for 283 the shim layer, positive and negative feedbacks [NOTE: These 284 feedbacks are mentioned in [I-D.ietf-shim6-failure-detection]]: 285 * Positive feedback could be given by the application or upper 286 layer protocol (e.g. TCP) to the shim layer informing that the 287 communication is going well. 289 * Negative feedback could be given by the application or upper 290 layer protocol (e.g. TCP) to the shim layer informing that the 291 communication status is not satisfactory. TCP could detect a 292 problem when it does not receive expected ACK from the peer. 293 ICMP error messages delivered to the upper layer protocol could 294 be a clue for application to detect potential problems. REAP 295 module may be triggered by these negative feedbacks and invoke 296 procedure of path exploration. 297 o Feedback from application to shim layer. The application should 298 be able to inform the shim layer of the timeout values for 299 detecting failures, for sending keepalives, for starting the 300 exploration procedure. In particular, the application should be 301 able to suppress the keepalives. 302 o Hot-standby. The application may request the shim layer for hot- 303 standby capabilities. In this case, alternative paths are known 304 to be working before a failure is detected. Hence it is possible 305 for the host to immediately replace the current locator pair with 306 an alternative locator pair. Hot-standby may allow applications 307 to achieve better failover. 308 o Eagerness of locator exploration. The application should be able 309 to inform the shim layer how aggressive it wants REAP mechanism to 310 perform path exploration (e.g. specifying the number of concurrent 311 attempts of discovering working locator pair) when an outage 312 occurs on the path between the currently selected locator pair. 313 o Providing locator information to application. The application 314 should be able to obtain information about the locator pair which 315 was actually used to send or receive the packet. 316 * For inbound traffic, the application may be interested in the 317 locator pair which was actually used to receive the packet. 318 * For outbound traffic, the application may be interested in the 319 locator pair which was actually used to transmit the packet. 320 In this way, the application may have additional control on the 321 locator management. For example, the application can verify if 322 its preference of locator is actually applied to the flow or not. 323 o The application should be able to specify if it wants to defer the 324 context setup or if it wants context establishment to be started 325 immediately in case there is no available context. With deferred 326 context setup, there should be no additional delay imposed by 327 context establishment in initiation of communication. 328 o Turn on/off shim. The application should be able to request to 329 turn on/off the multihoming support by the shim layer: 330 * Apply shim. The application should be able to explicitly 331 request the shim layer to apply multihoming support. 332 * Don't apply shim. The application should be able to request 333 the shim layer not to apply the multihoming support but to 334 apply normal IP processing at the IP layer. 336 o The application should be able to know if the communication is now 337 served by the shim layer or not. 338 o The application should be able to access locator information 339 regardless of its address family. In other words, no matter 340 whether the target locator is IPv4 or IPv6, the application should 341 be able to use common interface to access the locator information. 343 5. Socket Options for Multihoming Shim Layer 345 In this section, socket options that are specifc to multihome shim 346 are defined. 348 Table 1 provides a list of the socket options that are specific to 349 multihoming shim layer. These socket options can be used by either 350 getsockopt() or setsockopt() system call for a given socket. All of 351 these socket options are defined at level SOL_SHIM. 353 The first column of Table 1 gives the name of the option. The second 354 and third columns indicate whether the option can be handled by 355 getsockopt() and/or setsockopt(), respectively. The fourth column 356 provides a brief description of the socket option. The fifth column 357 shows the type of data structure specified along with the socket 358 option. By default, the data structure type is an integer. 360 +-----------------------------+-----+-----+-----------------+-------+ 361 | optname | get | set | description | dtype | 362 +-----------------------------+-----+-----+-----------------+-------+ 363 | SHIM_ASSOCIATED | o | | Check if the | int | 364 | | | | socket is | | 365 | | | | associated with | | 366 | | | | any shim | | 367 | | | | context or not. | | 368 | SHIM_DONTSHIM | o | o | Request the | int | 369 | | | | shim layer not | | 370 | | | | to apply any | | 371 | | | | multihoming | | 372 | | | | support for the | | 373 | | | | communication. | | 374 | SHIM_HOT_STANDBY | o | o | Request the | int | 375 | | | | shim layer to | | 376 | | | | prepare a | | 377 | | | | hot-standby | | 378 | | | | connection (in | | 379 | | | | addition to the | | 380 | | | | current path). | | 381 | SHIM_LOC_LOCAL_PREF | o | o | Get or set the | *1 | 382 | | | | preferred | | 383 | | | | locator on the | | 384 | | | | local side for | | 385 | | | | the context | | 386 | | | | associated with | | 387 | | | | the socket. | | 388 | SHIM_LOC_PEER_PREF | o | o | Get or set the | *1 | 389 | | | | preferred | | 390 | | | | locator on the | | 391 | | | | remote side for | | 392 | | | | the context | | 393 | | | | associated with | | 394 | | | | the socket. | | 395 | SHIM_LOC_LOCAL_RECV | o | o | Request for the | int | 396 | | | | destination | | 397 | | | | locator of the | | 398 | | | | received IP | | 399 | | | | packet. | | 400 | SHIM_LOC_PEER_RECV | o | o | Request for the | int | 401 | | | | source locator | | 402 | | | | of the received | | 403 | | | | IP packet. | | 404 | SHIM_LOCLIST_LOCAL | o | o | Get or set a | *2 | 405 | | | | list of | | 406 | | | | locators | | 407 | | | | associated with | | 408 | | | | the local EID. | | 409 | SHIM_LOCLIST_PEER | o | o | Get or set a | *2 | 410 | | | | list of | | 411 | | | | locators | | 412 | | | | associated with | | 413 | | | | the peer's EID. | | 414 | SHIM_APP_TIMEOUT | o | o | Inform the shim | int | 415 | | | | layer of a | | 416 | | | | timeout value | | 417 | | | | for detecting | | 418 | | | | failure. | | 419 | SHIM_PATHEXPLORE | o | o | Specify | *3 | 420 | | | | behavior of | | 421 | | | | path | | 422 | | | | exploration and | | 423 | | | | failure | | 424 | | | | detection. | | 425 | SHIM_CONTEXT_DEFERRED_SETUP | o | o | Specify if the | int | 426 | | | | context setup | | 427 | | | | can be deferred | | 428 | | | | or not. | | 429 +-----------------------------+-----+-----+-----------------+-------+ 431 Table 1: Socket options for multihoming shim 433 *1: Pointer to a shim_locator which is defined in Section 7. 435 *2: Pointer to an array of shim_locator. 437 *3: Pointer to a shim_pathexplore which is defined in Section 7. 439 Figure 2 illustrates how the shim specific socket options fit into 440 the system model of socket API. In the figure, it can be seen that 441 the shim layer and the additional protocol components (IPv4 and IPv6) 442 below the shim layer are new to the system model. As previously 443 mentioned, all the shim specific socket options are defined at 444 SOL_SHIM level. This design choice brings the following advantages: 446 1. It is assured that the existing socket API continue to work at 447 the layer above the shim layer. That is, those legacy API deal 448 with 'identifier' aspect of the IP addresses. 449 2. With newly defined socket options for the shim layer, the 450 application obtains additional control on locator management. 451 3. The shim specific socket options are not specific to any address 452 family (IPPROTO_IP or IPPROTO_IPV6) or any transport protocol 453 (IPPROTO_TCP or IPPROTO_UDP). 455 s1 s2 s3 s4 456 | | | | 457 +----------------|--|-------|--|----------------+ 458 | +-------+ +-------+ | 459 | IPPROTO_TCP | TCP | | UDP | | 460 | +-------+ +-------+ | 461 | | \ / | | 462 | | ----- | | 463 | | / \ | | 464 | +------+ +------+ | 465 | IPPROTO_IP | IPv4 | | IPv6 | IPPROTO_IPV6 | 466 | +------+ +------+ | 467 | \ / SOL_SOCKET 468 | +--------\-------/--------+ | 469 | SOL_SHIM | shim | | 470 | +--------/-------\--------+ | 471 | / \ | 472 | +------+ +------+ | 473 | | IPv4 | | IPv6 | | 474 | +------+ +------+ | 475 | | | | 476 +------------------|----------|-----------------+ 477 | | 478 IPv4 IPv6 479 Datagram Datagram 481 Figure 2: System model of socket API with shim layer 483 5.1. SHIM_ASSOCIATED 485 The SHIM_ASSOCIATED option can be used to check whether the socket is 486 associated with any shim context or not. 488 This option is particularly meaningful in a case where the locator 489 information of the received IP packet does not tell whether the 490 identifier/locator adaptation is performed or not. Note that the EID 491 pair and locator pair may be identical in some case. 493 This option can be specified by getsockopt(). Thus, the option is 494 read-only and the result (0 or 1) is set in the option value (the 495 fourth argument of getsockopt()). 497 Data type of the option value is integer. The option value indicates 498 presence of shim context. A returned value 1 means that the socket 499 is associated with a certain shim context at the shim layer, while a 500 return value 0 indicates that there is no context associated with the 501 socket. 503 For example, the option can be used by the application as follows: 505 int optval; 506 int optlen = sizeof(optval); 508 getsockopt(fd, SOL_SHIM, SHIM_ASSOCIATED, &optval, &optlen); 510 5.2. SHIM_DONTSHIM 512 The SHIM_DONTSHIM option can be used to request the shim layer to not 513 apply the multihoming support for the communication established over 514 the socket. 516 Data type of the option value is integer. The option value indicates 517 whether the multihoming shim support is deprecated or not. The 518 option value is binary (0 or 1). By default, the value is set to 0, 519 meaning that the shim layer applies identifier/locator adaptation for 520 the communication. In order to disable the socket option, the 521 application should call setsockopt() with optval set as 0. 523 For example, the option can be disabled by the application as 524 follows. 526 int optval; 528 optval = 0; 530 setsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, sizeof(optval)); 532 For example, the option value can be checked by the application as 533 follows. 535 int optval; 536 int len; 538 len = sizeof(optval); 540 getsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, &len); 542 5.3. SHIM_HOT_STANDBY 544 The SHIM_HOT_STANDBY option can be used to check if the shim layer 545 uses hot-standby connection or not for the communication established 546 over the socket. Hot-standby connection is another working locator 547 pair than the current locator pair. Hence this option is effective 548 only when there is a shim context associated with the socket. 550 Data type of the option value is integer. 552 The option value can be set by setsockopt(). 554 The option value can be read by getsockopt(). 556 By default, the value is set to 0, meaning that hot-standby 557 connection is disabled. 559 For example, the option can be activated by the application as 560 follows. 562 int optval; 564 optval = 1; 566 setsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, 567 sizeof(optval)); 569 For example, the option value can be checked by the application as 570 follows. 572 int optval; 573 int len; 575 len = sizeof(optval); 577 getsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, &len); 579 5.4. SHIM_PATHEXPLORE 581 This option can be used to specify behavior of path exploration to be 582 carried out. Path exploration is a procedure to find an alternative 583 locator pair when the host finds any problem with current locator 584 pair. A message used for finding an alternative locator pair is 585 called a Probe message and it is sent per locator pair. Default 586 value is defined for Initial Probe Timeout (0.5 seconds) and Initial 587 Probe (4 times) in the REAP specification. 589 The option is effective only when there is a shim context associated 590 with the socket. 592 Data type of the option value is a pointer to the buffer where a set 593 of information for path exploration is stored. The data structure is 594 defined in Section 7. 596 By default, the option value is set as NULL, meaning that the option 597 is disabled. 599 An error ENOENT will be returned when there is no context associated 600 with the socket. 602 For example, the parameters for the path exploration can be set as 603 follows. 605 struct shim6_pathexplore pe; 607 pe.pe_probenum = 4; /* times */ 608 pe.pe_keepaliveto = 10; /* seconds */ 609 pe.pe_initprobeto = 500; /* milliseconds */ 610 pe.pe_reserved = 0; 612 setsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, sizeof(pe)); 614 For example, the parameters for the path exploration can be read as 615 follows. 617 struct shim6_pathexplore pe; 618 int len; 620 len = sizeof(pe); 622 getsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, &len); 624 5.5. SHIM_LOC_LOCAL_PREF 626 The SHIM_LOC_LOCAL_PREF option can be used to read or set preferred 627 locator on local side within a given context. Hence this option is 628 effective only when there is a shim context associated with the 629 socket. 631 Data type of the option value is a pointer to the a specific data 632 structure which stores the locator information. The data structure 633 is defined in Section 7. 635 By default, the option value is set as NULL, meaning that the option 636 is disabled. 638 The preferred locator can be set by setsockopt(). Verification of 639 the locator shall be done by the shim layer before updating the 640 preferred locator. 642 The preferred locator can be read by getsockopt(). 644 An error ENOENT will be returned when there is no context associated 645 with the socket. 647 An error EINVALIDLOCATOR will be returned when the validation of the 648 specified locator failed. 650 For example, a preferred locator can be set as follows. It should be 651 noted that some members of the shim_locator (lc_ifidx and lc_flags) 652 are ignored in the write operation. 654 struct shim_locator lc; 655 struct in6_addr ip6; 657 /* ...set the locator (ip6)... */ 659 bzero(&lc, sizeof(shim_locator)); 660 lc.lc_family = AF_INET6; /* IPv6 */ 661 lc.lc_ifidx = 0; 662 lc.lc_flags = 0; 663 lc.lc_preference = 255; 664 memcpy(lc.lc_addr, &ip6, sizeof(in6_addr)); 666 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, 667 sizeof(optval)); 669 For example, the preferred locator of the context can be read by 670 application as follows. 672 struct shim_locator lc; 673 int len; 675 len = sizeof(lc); 677 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, &len); 679 5.6. SHIM_LOC_PEER_PREF 681 The SHIM_LOC_PEER_PREF option can be used to read or set preferred 682 locator on peer side within a given context. Hence this option is 683 effective only when there is a shim context associated with the 684 socket. 686 Data type of the option value is a pointer to the a specific data 687 structure which stores the locator information. The data structure 688 is defined in Section 7. 690 By default, the option value is set as NULL, meaning that the option 691 is disabled. 693 The preferred locator can be set by setsockopt(). Necessary 694 verification of the locator shall be done by the shim layer before 695 updating the preferred locator. 697 The preferred locator can be read by getsockopt(). 699 An error ENOENT will be returned when there is no context associated 700 with the socket. 702 An error EINVALIDLOCATOR will be returned when the validation of the 703 specified locator failed. 705 For example, a preferred locator can be set as follows. It should be 706 noted that some members of the shim_locator (lc_ifidx and lc_flags) 707 are ignored in the write operation. 709 The usage of the option is same as that of SHIM_LOC_LOCAL_PREF. 711 5.7. SHIM_LOC_LOCAL_RECV 713 The SHIM_LOC_LOCAL_RECV option can be used to request the shim layer 714 to store the destination locator of the received IP packet in an 715 ancillary data object which can be accessed by recvmsg(). Hence this 716 option is effective only when there is a shim context associated with 717 the socket. 719 Data type of the option value is integer. The option value should be 720 binary (0 or 1). By default, the option value is set to 0, meaning 721 that the option is disabled. 723 The option value can be set by setsockopt(). 725 The option value can be read by getsockopt(). 727 See Section 6 for the procedure to access locator information stored 728 in the ancillary data objects. 730 An error ENOENT will be returned when there is no context associated 731 with the socket. 733 For example, the option can be activated by the application as 734 follows: 736 int optval; 738 optval = 1; 740 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, 741 sizeof(optval)); 743 For example, the option value can be checked by the application as 744 follows: 746 int optval; 747 int len; 749 len = sizeof(optval); 751 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, &len); 753 5.8. SHIM_LOC_PEER_RECV 755 The SHIM_LOC_PEER_RECV option can be used to request the shim layer 756 to store the source locator of the received IP packet in an ancillary 757 data object which can be accessed by recvmsg(). Hence this option is 758 effective only when there is a shim context associated with the 759 socket. 761 Data type of the option value is integer. The option value should be 762 binary (0 or 1). By default, the option value is set to 0, meaning 763 that the option is disabled. 765 The option value can be set by setsockopt(). 767 The option value can be read by getsockopt(). 769 See Section 6 for the procedure to access locator information stored 770 in the ancillary data objects. 772 An error ENOENT will be returned when there is no context associated 773 with the socket. 775 The usage of the option is same as that of SHIM_LOC_LOCAL_RECV 776 option. 778 5.9. SHIM_LOCLIST_LOCAL 780 The SHIM_LOCLIST_LOCAL option can be used to read or set the locator 781 list associated with the local EID of the shim context associated 782 with the socket. Hence this option is effective only when there is a 783 shim context associated with the socket. 785 Data type of option value is pointer to the buffer where a locator 786 list is stored. See Section 7 for the data structure for storing the 787 locator information. By default, the option value is set as NULL, 788 meaning that the option is disabled. 790 The locator list can be read by getsockopt(). Note that the size of 791 the buffer pointed by optval argument should be large enough to store 792 an array of locator information. The number of the locator 793 information is not known beforehand. 795 The locator list can be set by setsockopt(). The buffer pointed by 796 optval argument should contain an array of locator list. 798 An error ENOENT will be returned when there is no context associated 799 with the socket. 801 An error EINVALIDLOCATOR will be returned when the validation of the 802 specified locator failed. 804 Example is TBD. 806 5.10. SHIM_LOCLIST_PEER 808 The SHIM_LOCLIST_LOCAL option can be used to read or set the locator 809 list associated with the peer EID of the shim context associated with 810 the socket. Hence this option is effective only when there is a shim 811 context associated with the socket. 813 Data type of option value is pointer to the buffer where a locator 814 list is stored. See Section 7 for the data structure for storing the 815 locator information. By default, the option value is set as NULL, 816 meaning that the option is disabled. 818 The locator list can be read by getsockopt(). Note that the size of 819 the buffer pointed by optval argument should be large enough to store 820 an array of locator information. The number of the locator 821 information is not known beforehand. 823 The locator list can be set by setsockopt(). The buffer pointed by 824 optval argument should contain an array of locator list. 826 An error ENOENT will be returned when there is no context associated 827 with the socket. 829 An error EINVALIDLOCATOR will be returned when the validation of the 830 specified locator failed. 832 The usage of the option is same as that of SHIM_LOCLIST_LOCAL. 834 5.11. SHIM_APP_TIMEOUT 836 The SHIM_APP_TIMEOUT option indicates timeout value for application 837 to detect failure. Hence this option is effective only when there is 838 a shim context associated with the socket. 840 Data type of the option value is integer. The value indicates the 841 period of timeout in seconds to send a REAP Keepalive message since 842 the last outbound traffic. By default, the option value is set as 0, 843 meaning that the option is disabled. When the option is disabled, 844 the REAP mechanism follows its default value of Send Timeout value as 845 specified in [I-D.ietf-shim6-failure-detection] 847 If the timeout value specified is longer than the Send Timeout 848 configured in the REAP component, the REAP Keepalive message should 849 be suppressed. 851 An error ENOENT will be returned when there is no context associated 852 with the socket. 854 For example, a specific timeout value can be configured by the 855 application as follows: 857 int optval; 859 optval = 15; /* 15 seconds */ 861 setsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, 862 sizeof(optval)); 864 For example, the option value namely the period of timeout can be 865 checked by the application as follows: 867 int optval; 868 int len; 870 len = sizeof(optval); 872 getsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, &len); 874 5.12. SHIM_DEFERRED_CONTEXT_SETUP 876 The SHIM_DEFERRED_CONTEXT_SETUP option indicates how initiation of 877 context setup is made in terms of timing (before or after) the 878 initial communication flow. Deferred context means that the 879 establishment of context does not put additional delay for an initial 880 transaction. 882 Data type for the option value is integer. The option value should 883 binary (0 or 1). By default, the value is set as 1, meaning that the 884 context setup is deferred. In order to disable the option, the 885 application should call setsockopt() with option value set as 0. 887 However, it should be noted that in some case, deferred context setup 888 is not possible; given EID is non-routable address and there is no 889 way to transmit any IP packet unless there is a context providing the 890 locators. In such case, context should be established prior to the 891 communication. 893 For example, the option can be disabled by the application as 894 follows: 896 int optval; 898 optval = 0; 900 setsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, 901 &optval, sizeof(optval)); 903 For example, the option value can be checked by the application as 904 follows: 906 int optval; 907 int len; 909 len = sizeof(optval); 911 getsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, 912 &optval, &len); 914 5.13. Error Handling 916 If successful, getsockopt() and setsockopt() return 0; otherwise, the 917 functions return -1 and set errno to indicate error. 919 The followings are errno codes newly defined for some shim specific 920 socket options indicating that the getsockopt() or setsockopt() 921 finished incompletely: 923 EINVALIDLOCATOR 924 This indicates that at least one of the necessary validations 925 inside the shim layer for the specified locator has failed. In 926 case of SHIM6, there are two kinds of verifications required for 927 security reasons prior to sending an IP packet to the peer's new 928 locator; one is return routability (check if the peer is actually 929 willing to receive data with the specified locator) and the other 930 is verifications based on given crypto identifier mechanisms 931 [RFC3972], [I-D.ietf-shim6-hba]. 933 6. Ancillary Data for Multihoming Shim 935 In this section, definition and usage of the ancillary data which is 936 specific to multihoming shim are provided. 938 As defined in Posix standard, sendmsg() and recvmsg() take msghdr 939 structure as its argument and they can additionally handle control 940 information along with data. Figure 18 shows the msghdr structure 941 which is defined in . msg_control member holds a 942 pointer to the buffer where the shim specific ancillary data objects 943 can be stored in addition to other ancillary data objects. 945 struct msghdr { 946 caddr_t msg_name; /* optional address */ 947 u_int msg_namelen; /* size of address */ 948 struct iovec *msg_iov; /* scatter/gather array */ 949 u_int msg_iovlen; /* # elements in msg_iov */ 950 caddr_t msg_control; /* ancillary data, see below */ 951 u_int msg_controllen; /* ancillary data buffer len */ 952 int msg_flags; /* flags on received message */ 953 }; 955 Figure 18: msghdr structure 957 The buffer pointed from the msg_control member of the msghdr 958 structure may contain a locator information which is a single locator 959 and it should be possible to process them with the existing macros 960 defined in Posix and [RFC3542]. Each cmsghdr{} should be followed by 961 data which stores a single locator. 963 In case of non-connected socket, msg_name member stores the socket 964 address of the peer which should be considered as an identifier 965 rather than a locator. The locator of the peer node should be 966 retrieved by SHIM_LOC_PEER_RECV as specified below. 968 Table 2 is a list of the shim specific ancillary data which can be 969 used for recvmsg() or sendmsg(). In any case, SOL_SHIM must be set 970 as cmsg_level. 972 +------------------------+-----------+-----------+-------------+ 973 | cmsg_type | sendmsg() | recvmsg() | cmsg_data[] | 974 +------------------------+-----------+-----------+-------------+ 975 | SHIM_LOC_LOCAL_RECV | | o | *1 | 976 | SHIM_LOC_PEER_RECV | | o | *1 | 977 | SHIM_LOC_LOCAL_SEND | o | | *1 | 978 | SHIM_LOC_PEER_SEND | o | | *1 | 979 | SHIM_FEEDBACK_POSITIVE | o | | TBD | 980 | SHIM_FEEDBACK_NEGATICE | o | | TBD | 981 +------------------------+-----------+-----------+-------------+ 983 Table 2: Shim specific ancillary data 985 *1: cmsg_data[] should include padding (if necessary) and a single 986 sockaddr_in{}/sockaddr_in6{}. 988 It should be noted that the above ancillary data can only be handled 989 in UDP and raw sockets, not in TCP sockets because there is no one- 990 to-one mapping of send/receive operations and the TCP segments being 991 transmitted/received. 993 6.1. Get Locator Information from Incoming Packet 995 Application can get locator information from the received IP packet 996 by specifying the shim specific socket options for the socket. When 997 SHIM_LOC_LOCAL_RECV and/or SHIM_LOC_PEER_RECV socket options are set, 998 the application can retrieve local and/or remote locator from the 999 ancillary data. 1001 6.2. Specify Locator Information for Outgoing Packet 1003 Application can specify the locators to be used for transmitting an 1004 IP packet by sendmsg(). When ancillary data of cmsg_type 1005 SHIM_LOC_LOCAL_SEND and/or SHIM_LOC_PEER_SEND are specified, the 1006 application can explicitly specify source and/or destination locators 1007 to be used for the communication over the socket. 1009 In addition, the application can specify the outgoing interface by 1010 SHIM_IF_SEND ancillary data. The ancillary data should contain the 1011 interface identifier of the physical interface over which the 1012 application expects the packet to be transmitted. 1014 Note that the effect is limited to the datagram transmitted by the 1015 sendmsg(). 1017 If the specified locator pair seems to be valid, the shim layer 1018 overrides the locator of the IP packet as requested. 1020 An error EINVALIDLOCATOR will be returned when validation of the 1021 specified locator failed. 1023 6.3. Notification from Application to Multihoming Shim 1025 Application may provide feedback to the shim layer in accordance with 1026 its communication status. The notification can be made by specifying 1027 shim specific ancillary data in sendmsg() call. Note that this 1028 notification is dynamic rather than static. 1030 6.3.1. SHIM_FEEDBACK_POSITIVE 1032 The application can simply inform the shim layer that its 1033 communication is going well. 1035 Data type is TBD. 1037 An error ENOENT will be returned when there is no context associated 1038 with the socket. 1040 6.3.2. SHIM_FEEDBACK_NEGATIVE 1042 The application can inform the shim layer that its communication is 1043 not going well. 1045 Data type is TBD. 1047 An error ENOENT will be returned when there is no context associated 1048 with the socket. 1050 7. Data Structures 1052 In this section, data structures specifically defined for the 1053 multihoming shim layer are introduced. Those data structures are 1055 7.1. Placeholder for Locator Information 1057 As defined in Section 5, the SHIM_LOC_LOCAL_PREF, SHIM_LOC_PEER_PREF, 1058 SHIM_LOCLIST_LOCAL, and SHIM_LOCLIST_PEER socket options need to 1059 handle one or more locator information. Locator information includes 1060 not only the locator itself but also additional information about the 1061 locator which is useful for locator management. A new data structure 1062 is defined to serve as a placeholder for the locator information. 1064 Figure 19 illustrates the data structure called shim_locator which 1065 stores a locator information. 1067 struct shim_locator { 1068 uint8_t lc_family; /* address family */ 1069 uint8_t lc_ifidx; /* interface index */ 1070 uint8_t lc_flags; /* flags */ 1071 uint8_t lc_preference; /* preference value */ 1072 uint8_t lc_addr[16]; /* locator */ 1073 }; 1075 Figure 19: shim locator structure 1077 lc_family 1078 Address family of the locator (e.g. AF_INET, AF_INET6). It is 1079 required that the parameter contains non-zero value indicating the 1080 exact address family of the locator. 1082 lc_ifidx 1083 Interface index of the network interface to which the locator is 1084 assigned. This field should be valid only in read (getsockopt()) 1085 operation. 1086 lc_flags 1087 Each bit of the flags represents a specific characteristics of the 1088 locator. HBA is defined as 0x01. CGA is defined as 0x02. The 1089 other bits are TBD. 1090 lc_preference 1091 Indicates preference of the locator. The preference is 1092 represented by integer. 1093 lc_addr 1094 Contains the locator. For the cases where a locator whose size is 1095 smaller than 16 bytes, encoding rule should be provided for each 1096 locator of a given address family. For instance, in case of 1097 AF_INET (IPv4), the last 4 bytes of lc_addr should contain the 1098 IPv4 address. 1100 7.2. Path Exploration Parameter 1102 As defined in Section 5, SHIM_PATHEXPLORE allows application to set 1103 or read the parameters for path exploration and failure detection. A 1104 new data structure called shim_pathexplore is defined to store the 1105 necessary parameters. Figure 20 illustrates the data structure. The 1106 data structure can be used by getsockopt() or setsockopt() as an 1107 argument. 1109 struct shim_pathexplore { 1110 uint8_t pe_probenum; /* # of initial probe */ 1111 uint8_t pe_keepaliveto; /* Keepalive Timeout */ 1112 uint16_t pe_initprobeto; /* Initial Probe Timeout */ 1113 uint32_t pe_reserved; /* reserved */ 1114 }; 1116 Figure 20: path explore structure 1118 pe_probenum 1119 Indicates the number of initial probe messages to be sent. 1120 Default value of this parameter should follow what is specified in 1121 [I-D.ietf-shim6-failure-detection]. 1122 pe_keepaliveto 1123 Indicates timeout value for detecting a failure when the host does 1124 not receive any packets for a certain period of time while there 1125 is outbound traffic. When the timer expires, path exploration 1126 procedure will be carried out by sending a REAP Probe message. 1127 Default value of this parameter should follow what is specified in 1128 [I-D.ietf-shim6-failure-detection]. 1130 pe_initprobeto 1131 Indicates retransmission timer of REAP Probe message in 1132 milliseconds. Note that this timer is applied before exponential 1133 back-off is started. A REAP Probe message for the same locator 1134 pair may be retransmitted. Default value of this parameter should 1135 follow what is specified in [I-D.ietf-shim6-failure-detection]. 1136 pe_reserved 1137 A reserved field for future extension. By default, the field 1138 should be initialized with zero. 1140 8. Implications for Existing Socket API Extensions 1142 Some of the socket options defined in this document have some 1143 overlapping with existing socket API and care should be made for the 1144 usage not to confuse the features. 1146 The socket options for requesting specific locators to be used for a 1147 given transaction (SHIM_LOC_LOCAL_PREF and SHIM_LOC_PEER_PREF) are 1148 semantically similar to the existing socket API (IPV6_PKTINFO). The 1149 socket options for obtaining the locator information from the 1150 received IP packet (SHIM_LOC_LOCAL_RECV and SHIM_LOC_PEER_RECV) are 1151 semantically similar to the existing socket API (IP_RECVDSTADDR and 1152 IPV6_PKTINFO). 1154 In IPv4, application can obtain the destination IP address of the 1155 received IP packet (IP_RECVDSTADDR). If the shim layer performs 1156 identifier/locator adaptation for the received packet, the 1157 destination EID should be stored in the ancillary data 1158 (IP_RECVDSTADDR). 1160 In IPv6, [RFC3542] defines that IPV6_PKTINFO can be used to specify 1161 source IPv6 address and the outgoing interface for outgoing packets, 1162 and retrieve destination IPv6 address and receiving interface for 1163 incoming packets. This information is stored in ancillary data being 1164 IPV6_PKTINFO specified as cmsg_type. Existing socket API should 1165 continue to work above the shim layer, that is, the IP addresses 1166 handled in IPV6_PKTINFO should be EIDs, not the locators. 1168 Baseline is that the above existing socket API (IP_RECVDSTADDR and 1169 IPV6_PKTINFO) is assumed to work above the multihoming shim layer. 1170 In other words, the IP addresses those socket options deal with are 1171 EIDs rather than locators. 1173 9. Resolving Conflicts with Preference Values 1175 Since the multihoming shim API allows application to specify 1176 preference value for the context which is associated with the socket 1177 instance, there may be a conflict with preference values specified by 1178 different applications. For instance, application A and B may 1179 establish communication over the same EID pair while each application 1180 have different preference in their choice of local locator. 1182 SHIM6 supports a notion of forking context in which a context is 1183 split when there is a conflict with preference values specified by 1184 multiple applications. Thus, context forking can simply resolve the 1185 conflicting situation which may be caused by the use of socket 1186 options for multihoming shim layer. 1188 9.1. Implicit Forking 1190 Socket options defined in Section 5 may cause conflicting situation 1191 when the target context is shared by multiple applications. In such 1192 case, socket handler and the multihoming shim layer should react as 1193 follows; socket handler should inform the shim layer that context 1194 forking is required. In SHIM6, when a context is forked, an unique 1195 identifier called Forked Instance Identifier (FII) is assigned to the 1196 newly forked context. The forked context is then exclusively 1197 associated with the socket through which non-default preference value 1198 was specified. The forked context is maintained by the multihoming 1199 shim layer during the lifetime of associated socket instance. When 1200 the socket is closed, the multihoming shim layer SHOULD delete 1201 associated context. In this way, garbage collection can be carried 1202 out to cleanup unused forked contexts. Upon garbage collection, 1203 every forked context SHOULD be checked if there is no socket 1204 (process) associated with the context. If there is none, the forked 1205 context should be deleted. When a forked context is torn down, SHIM6 1206 should notify the peer about the deletion of forked context. 1208 As opposed to socket options, context forking MUST NOT be triggered 1209 by any use of ancillary data that are specific to multihoming shim 1210 defined in Section 6. 1212 10. Discussion 1214 In this section, open issues are introduced. 1216 10.1. Naming at Socket Layer 1218 getsockname() and getpeername() system calls are used to obtain the 1219 'name' of endpoint which is actually a pair of IP address and port 1220 number assigned to a given socket. getsockname() is used when an 1221 application wants to obtain the local IP address and port number 1222 assigned for a given socket instance. getpeername() is used when an 1223 application wants to obtain the remote IP address and port number. 1225 The above is based on a traditional system model of the socket API 1226 where an IP address is expected to play both the role of identifier 1227 and the role of locator. 1229 In a system model where a shim layer exists inside the IP layer, both 1230 getsockname() and getpeername() deal with identifiers, namely EIDs. 1231 In this sense, the shim layer serves to (1) hide locators and (2) 1232 provide access to the identifier for the application over the legacy 1233 socket APIs. 1235 10.2. Additional Requirements from Application 1237 At the moment, it is not certain if following requirements are common 1238 in all the multihomed environments (SHIM6 and HIP). These are mainly 1239 identified during discussions made on SHIM6 WG mailing list. 1240 o The application should be able to set preferences for the 1241 locators, local and remote one and also to the preferences of the 1242 local locators that will be passed to the peer. 1244 10.3. Issues of Header Conversion among Different Address Family 1246 The shim layer performs identifier/locator adaptation. Therefore, in 1247 some case, the whole IP header can be replaced with new IP header of 1248 a different address family (e.g. conversion from IPv4 to IPv6 or vice 1249 versa). Hence, there is an issue how to make the conversion with 1250 minimum impact. Note that this issue is common in other protocol 1251 conversion such as SIIT[RFC2765]. 1253 As addressed in SIIT specification, some of the features (IPv6 1254 routing headers, hop-by-hop extension headers, or destination 1255 headers) from IPv6 are not convertible to IPv4. In addition, notion 1256 of source routing is not exactly the same in IPv4 and IPv6. Hence, 1257 there is certain limitation in protocol conversion between IPv4 and 1258 IPv6. 1260 The question is how should the shim layer behave when it is face with 1261 limitation problem of protocol conversion. Should we introduce new 1262 error something like ENOSUITABLELOCATOR ? 1264 10.4. Handling of Unknown Locator Provided by Application 1266 There might be a case where application provides the shim layer new 1267 locator with the SHIM_LOC_*_PREF socket options or SHIM_LOC_*_SEND 1268 ancillary data. Then there is a question how should the shim layer 1269 treat the new locator informed by the application. 1271 In principle, locator information are exchanged by the shim protocol. 1272 However, there might be a case where application acquires information 1273 about the locator and prefers to use it for its communication. 1275 11. Changes 1277 11.1. Changes from version 00 to version 01 1279 The followings are changes from version 00 to version 01: 1280 o Define shim_locator{} data type which is a placeholder for 1281 locator. 1282 o Define shim_pathexplore{} data type in which a set of REAP 1283 parameters are stored. 1284 o Remove descriptions about "stickiness" of socket options. 1285 o Deprecate SHIM_IF_RECV and SHIM_IF_SEND socket options. 1286 o Give default value and how to disable given socket option. 1288 11.2. Changes from version 01 to version 02 1290 The followings are changes from version 01 to version 02: 1291 o Add section describing context forking. 1292 o Rephrase conclusion section. 1293 o Separate normative references from informative references. 1294 o Remove texts from discussion section that are not relevant to the 1295 contents of the document. 1296 o Add section describing change history (this section). 1298 12. IANA Considerations 1300 This document contains no IANA consideration. 1302 13. Security Considerations 1304 This document does not specify any security mechanism for the shim 1305 layer. Fundamentally, the shim layer has a potential to impose 1306 security threats, as it changes the source and/or destination IP 1307 addresses of the IP packet being sent or received. Therefore, the 1308 basic assumption is that the security mechanism defined in each 1309 protocol of the shim layer is strictly applied. 1311 14. Conclusion 1313 In this document, the Application Program Interface (API) for 1314 multihoming shim layer is specified. The socket API allows 1315 applications to have additional control of the locator management and 1316 interface to the REAP mechanism inside the multihoming shim layer. 1318 Socket options for multihoming shim layer can be used by getsockopt() 1319 and/or setcokopt() system calls. Besides, applications can use some 1320 ancillary data that are specific to multihoming shim layer to get 1321 locator from received packet or to set locator for outgoing packet. 1323 From an architectural point of view, the socket API provides extends 1324 the existing socket API framework in the face of ID/Locator 1325 separation. With regard to API that relate to IP address management, 1326 it is assured that existing socket API continue to work above the 1327 shim layer dealing with identifiers, while multihoming shim API deals 1328 with locators. 1330 15. Acknowledgments 1332 Authors would like to thank Jari Arkko who participated in the 1333 discussion that lead to the first version of this document, and 1334 Tatuya Jinmei who thoroughly reviewed the early version of this draft 1335 and provided detailed comments on socket API related issues. 1337 16. References 1339 16.1. Normative References 1341 [I-D.ietf-shim6-failure-detection] 1342 Arkko, J. and I. Beijnum, "Failure Detection and Locator 1343 Pair Exploration Protocol for IPv6 Multihoming", 1344 draft-ietf-shim6-failure-detection-07 (work in progress), 1345 December 2006. 1347 [I-D.ietf-shim6-proto] 1348 Bagnulo, M. and E. Nordmark, "Level 3 multihoming shim 1349 protocol", draft-ietf-shim6-proto-07 (work in progress), 1350 December 2006. 1352 [POSIX] "IEEE Std. 1003.1-2001 Standard for Information Technology 1353 -- Portable Operating System Interface (POSIX). Open group 1354 Technical Standard: Base Specifications, Issue 6, 1355 http://www.opengroup.org/austin", December 2001. 1357 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 1358 "Advanced Sockets Application Program Interface (API) for 1359 IPv6", RFC 3542, May 2003. 1361 [RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol 1362 (HIP) Architecture", RFC 4423, May 2006. 1364 16.2. Informative References 1366 [I-D.ietf-shim6-app-refer] 1367 Nordmark, E., "Shim6 Application Referral Issues", 1368 draft-ietf-shim6-app-refer-00 (work in progress), 1369 July 2005. 1371 [I-D.ietf-shim6-hba] 1372 Bagnulo, M., "Hash Based Addresses (HBA)", 1373 draft-ietf-shim6-hba-02 (work in progress), October 2006. 1375 [RFC2765] Nordmark, E., "Stateless IP/ICMP Translation Algorithm 1376 (SIIT)", RFC 2765, February 2000. 1378 [RFC3972] Aura, T., "Cryptographically Generated Addresses (CGA)", 1379 RFC 3972, March 2005. 1381 Authors' Addresses 1383 Miika Komu 1384 Helsinki Institue for Information Technology 1385 Tammasaarenkatu 3 1386 Helsinki 1387 Finland 1389 Phone: +358503841531 1390 Fax: +35896949768 1391 Email: miika@iki.fi 1392 URI: http://www.hiit.fi/ 1394 Marcelo Bagnulo 1395 Universidad Carlos III de Madrid 1396 Av. Universidad 30 1397 Leganes 28911 1398 SPAIN 1400 Phone: +34 91 6248837 1401 Email: marcelo@it.uc3m.es 1402 URI: http://it.uc3m.es/marcelo 1403 Kristian Slavov 1404 Ericsson Research Nomadiclab 1405 Hirsalantie 11 1406 Jorvas FI-02420 1407 Finland 1409 Phone: +358 9 299 3286 1410 Email: kristian.slavov@ericsson.com 1412 Shinta Sugimoto (editor) 1413 Nippon Ericsson K.K. 1414 Koraku Mori Building 1415 1-4-14, Koraku, Bunkyo-ku 1416 Tokyo 112-0004 1417 Japan 1419 Phone: +81 3 3830 2241 1420 Email: shinta.sugimoto@ericsson.com 1422 Full Copyright Statement 1424 Copyright (C) The IETF Trust (2007). 1426 This document is subject to the rights, licenses and restrictions 1427 contained in BCP 78, and except as set forth therein, the authors 1428 retain all their rights. 1430 This document and the information contained herein are provided on an 1431 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1432 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1433 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1434 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1435 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1436 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1438 Intellectual Property 1440 The IETF takes no position regarding the validity or scope of any 1441 Intellectual Property Rights or other rights that might be claimed to 1442 pertain to the implementation or use of the technology described in 1443 this document or the extent to which any license under such rights 1444 might or might not be available; nor does it represent that it has 1445 made any independent effort to identify any such rights. Information 1446 on the procedures with respect to rights in RFC documents can be 1447 found in BCP 78 and BCP 79. 1449 Copies of IPR disclosures made to the IETF Secretariat and any 1450 assurances of licenses to be made available, or the result of an 1451 attempt made to obtain a general license or permission for the use of 1452 such proprietary rights by implementers or users of this 1453 specification can be obtained from the IETF on-line IPR repository at 1454 http://www.ietf.org/ipr. 1456 The IETF invites any interested party to bring to its attention any 1457 copyrights, patents or patent applications, or other proprietary 1458 rights that may cover technology that may be required to implement 1459 this standard. Please address the information to the IETF at 1460 ietf-ipr@ietf.org. 1462 Acknowledgment 1464 Funding for the RFC Editor function is provided by the IETF 1465 Administrative Support Activity (IASA).