idnits 2.17.1 draft-ietf-shim6-multihome-shim-api-08.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- ** The document seems to lack a License Notice according IETF Trust Provisions of 28 Dec 2009, Section 6.b.i or Provisions of 12 Sep 2009 Section 6.b -- however, there's a paragraph with a matching beginning. Boilerplate error? (You're using the IETF Trust Provisions' Section 6.b License Notice from 12 Feb 2009 rather than one of the newer Notices. See https://trustee.ietf.org/license-info/.) 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 1387: '...e multihoming shim layer SHOULD delete...' RFC 2119 keyword, line 1390: '...y forked context SHOULD be checked if ...' RFC 2119 keyword, line 1395: '... context forking MUST NOT be triggered...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1105 has weird spacing: '... u_int msg_...' == Line 1106 has weird spacing: '... struct iovec...' == Line 1107 has weird spacing: '... u_int msg_...' == Line 1109 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 (May 7, 2009) is 5468 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: '0' on line 935 -- Looks like a reference, but probably isn't: '1' on line 945 -- Looks like a reference, but probably isn't: '16' on line 1224 ** 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 (~~), 5 warnings (==), 7 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: November 8, 2009 UC3M 6 K. Slavov 7 S. Sugimoto, Ed. 8 Ericsson 9 May 7, 2009 11 Socket Application Program Interface (API) for Multihoming Shim 12 draft-ietf-shim6-multihome-shim-api-08 14 Status of this Memo 16 This Internet-Draft is submitted to IETF in full conformance with the 17 provisions of BCP 78 and BCP 79. 19 Internet-Drafts are working documents of the Internet Engineering 20 Task Force (IETF), its areas, and its working groups. Note that 21 other groups may also distribute working documents as Internet- 22 Drafts. 24 Internet-Drafts are draft documents valid for a maximum of six months 25 and may be updated, replaced, or obsoleted by other documents at any 26 time. It is inappropriate to use Internet-Drafts as reference 27 material or to cite them other than as "work in progress." 29 The list of current Internet-Drafts can be accessed at 30 http://www.ietf.org/ietf/1id-abstracts.txt. 32 The list of Internet-Draft Shadow Directories can be accessed at 33 http://www.ietf.org/shadow.html. 35 This Internet-Draft will expire on November 8, 2009. 37 Copyright Notice 39 Copyright (c) 2009 IETF Trust and the persons identified as the 40 document authors. All rights reserved. 42 This document is subject to BCP 78 and the IETF Trust's Legal 43 Provisions Relating to IETF Documents in effect on the date of 44 publication of this document (http://trustee.ietf.org/license-info). 45 Please review these documents carefully, as they describe your rights 46 and restrictions with respect to this document. 48 Abstract 50 This document specifies sockets API extensions for the multihoming 51 shim layer. The API aims to enable interactions between applications 52 and the multihoming shim layer for advanced locator management, and 53 access to information about failure detection and path exploration. 55 This document is based on an assumption that a multihomed host is 56 equipped with a conceptual sub-layer (hereafter "shim") inside the IP 57 layer that maintains mappings between identifiers and locators. 58 Examples of the shim are SHIM6 and HIP. 60 Table of Contents 62 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 63 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 64 3. System Overview . . . . . . . . . . . . . . . . . . . . . . . 6 65 4. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 7 66 5. Socket Options for Multihoming Shim Layer . . . . . . . . . . 9 67 5.1. SHIM_ASSOCIATED . . . . . . . . . . . . . . . . . . . . . 12 68 5.2. SHIM_DONTSHIM . . . . . . . . . . . . . . . . . . . . . . 13 69 5.3. SHIM_HOT_STANDBY . . . . . . . . . . . . . . . . . . . . . 13 70 5.4. SHIM_PATHEXPLORE . . . . . . . . . . . . . . . . . . . . . 14 71 5.5. SHIM_LOC_LOCAL_PREF . . . . . . . . . . . . . . . . . . . 15 72 5.6. SHIM_LOC_PEER_PREF . . . . . . . . . . . . . . . . . . . . 16 73 5.7. SHIM_LOC_LOCAL_RECV . . . . . . . . . . . . . . . . . . . 17 74 5.8. SHIM_LOC_PEER_RECV . . . . . . . . . . . . . . . . . . . . 18 75 5.9. SHIM_LOC_LOCAL_SEND . . . . . . . . . . . . . . . . . . . 18 76 5.10. SHIM_LOC_PEER_SEND . . . . . . . . . . . . . . . . . . . . 19 77 5.11. SHIM_LOCLIST_LOCAL . . . . . . . . . . . . . . . . . . . . 20 78 5.12. SHIM_LOCLIST_PEER . . . . . . . . . . . . . . . . . . . . 22 79 5.13. SHIM_APP_TIMEOUT . . . . . . . . . . . . . . . . . . . . . 22 80 5.14. SHIM_DEFERRED_CONTEXT_SETUP . . . . . . . . . . . . . . . 23 81 5.15. Error Handling . . . . . . . . . . . . . . . . . . . . . . 24 82 6. Ancillary Data for Multihoming Shim . . . . . . . . . . . . . 24 83 6.1. Get Locator Information from Incoming Packet . . . . . . . 26 84 6.2. Specify Locator Information for Outgoing Packet . . . . . 26 85 6.3. Notification from Application to Multihoming Shim . . . . 26 86 7. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 27 87 7.1. Placeholder for Locator Information . . . . . . . . . . . 27 88 7.2. Path Exploration Parameter . . . . . . . . . . . . . . . . 28 89 7.3. Feedback Information . . . . . . . . . . . . . . . . . . . 29 90 8. Implications for Existing Socket API Extensions . . . . . . . 29 91 9. Resolving Conflicts with Preference Values . . . . . . . . . . 30 92 9.1. Implicit Forking . . . . . . . . . . . . . . . . . . . . . 30 93 10. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 31 94 10.1. Naming at Socket Layer . . . . . . . . . . . . . . . . . . 31 95 10.2. Additional Requirements from Applications . . . . . . . . 31 96 10.3. Issues of Header Conversion among Different Address 97 Family . . . . . . . . . . . . . . . . . . . . . . . . . . 32 98 10.4. Handling of Unknown Locator Provided by Application . . . 32 99 11. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 100 11.1. Changes from version 00 to version 01 . . . . . . . . . . 32 101 11.2. Changes from version 01 to version 02 . . . . . . . . . . 33 102 11.3. Changes from version 02 to version 03 . . . . . . . . . . 33 103 11.4. Changes from version 03 to version 04 . . . . . . . . . . 33 104 11.5. Changes from version 04 to version 05 . . . . . . . . . . 33 105 11.6. Changes from version 05 to version 06 . . . . . . . . . . 33 106 11.7. Changes from version 06 to version 07 . . . . . . . . . . 33 107 11.8. Changes from version 07 to version 08 . . . . . . . . . . 33 108 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 109 13. Security Considerations . . . . . . . . . . . . . . . . . . . 34 110 14. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . 34 111 15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 34 112 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 113 16.1. Normative References . . . . . . . . . . . . . . . . . . . 34 114 16.2. Informative References . . . . . . . . . . . . . . . . . . 35 115 Appendix A. Context Forking . . . . . . . . . . . . . . . . . . . 35 116 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38 118 1. Introduction 120 HIP and SHIM6 have a commonality in their protocol design in the 121 sense that the roles of an IP address as an identifier and a locator 122 are clearly distinguished. Hereafter this design principle is called 123 "identifier/locator separation" in this document. Both protocols aim 124 to solve problems that are specific to multihoming environment in an 125 endhost centric approach. In these protocols, a sub-layer within the 126 IP layer maintains mappings of identifiers and locators. 128 The shim layer is useful in a sense that the IP layer can maintain 129 the mapping of an identifier to the corresponding locators. Under a 130 multihomed environment, typically, a host has more than one IP 131 address at a time. During the transaction, the host may be required 132 to switch the IP address in use to another IP address to preserve the 133 communication. Such an address update should be kept hidden from the 134 upper layer protocols to avoid communication disruption. The shim 135 layer aims to make the address update transparent to the upper layer 136 protocols. 138 In a system which is based on identifier/locator separation, upper 139 layer protocols are expected to deal with identifiers for 140 establishing and handling the communications. If an application 141 wants to have multihoming support from the shim layer, the IP 142 addresses specified as source and destination addresses must be 143 identifiers. However, this does not necessarily mean that 144 applications are prohibited to choose specific locators for its 145 communication. It may be useful for some applications to specify a 146 preferred locator for a given flow. 148 This document recommends that the switching of identifier and locator 149 is done only once inside the TCP/IP stack of an endhost. That is, if 150 multiple shim sub-layers exist at the IP layer, any one of them 151 should be applied exclusively for a given flow. 153 As this document specifies sockets API extensions, it is written so 154 that the syntax and semantics are in line with the Posix standard 155 [POSIX] as much as possible. The API specified in this document 156 defines how to use ancillary data (aka cmsg) to access the locator 157 information with recvmsg() and/or sendmsg() I/O calls. The 158 definition of API is presented in C language and data types follow 159 the Posix format; intN_t means a singed integer of exactly N bits 160 (e.g. int16_t) and uintN_t means an unsigned integer of exactly N 161 bits (e.g. uint32_t). 163 The target readers of this document are application programmers who 164 develop application software which may benefit greatly from 165 multihomed environments. In addition, this document aims to provide 166 necessary information for developers of multihoming shim protocols to 167 implement API for enabling advanced locator management. 169 2. Terminology 171 This section provides terminology used in this document. Basically 172 most of the terms used in this document are taken from the following 173 documents: 175 o SHIM6 Protocol Specification[I-D.ietf-shim6-proto] 176 o HIP Architecture[RFC4423] 177 o Reachability Protocol (REAP)[I-D.ietf-shim6-failure-detection] 179 In this document, the term "IP" refers to both IPv4 and IPv6, unless 180 the protocol version is specifically mentioned. The following are 181 definitions of terms frequently used in this document: 183 o Endpoint identifier (EID) - The identifier used by the application 184 to specify the endpoint of a given communication. Applications 185 may handle EIDs in various ways such as long-lived connections, 186 callbacks, and referrals[I-D.ietf-shim6-app-refer]. 187 * In the case of SHIM6, an identifier called a ULID serves as an 188 EID. A ULID is chosen from locators available on the host. 189 * In the case of HIP, an identifier called a Host Identifier 190 serves as an EID. A Host Identifier is derived from the public 191 key of a given host. For the sake of backward compatibility 192 with the sockets API, the Host Identifier is represented in a 193 form of hash of public key. 194 o Locator - The IP address actually used to deliver IP packets. 195 Locators are present in the source and destination fields of the 196 IP header of a packet on the wire. 197 * List of locators - A list of locators associated with an EID. 198 There are two lists of locators stored in a given context. One 199 is associated with the local EID and the other is associated 200 with the remote EID. As defined in [I-D.ietf-shim6-proto], the 201 list of locators associated with an EID 'A' is denoted as 202 Ls(A). 203 * Preferred locator - The (source/destination) locator currently 204 used to send packets within a given context. As defined in 205 [I-D.ietf-shim6-proto], the preferred locator of a host 'A' is 206 denoted as Lp(A). 207 o Shim - The conceptual sub-layer inside the IP layer which 208 maintains mappings between EIDs and locators. An EID can be 209 associated with more than one locator at a time when the host is 210 multihomed. The term 'shim' does not refer to a specific protocol 211 but refers to the conceptual sub-layer inside the IP layer. 213 o Identifier/locator adaptation - The adaptation performed at the 214 shim layer which may end up re-writing the source and/or 215 destination addresses of an IP packet. In the outbound packet 216 processing, the EID pair is converted to the associated locator 217 pair. In the inbound packet processing, the locator pair is 218 converted to the EID pair. 219 o Context - The state information shared by a given pair of peers, 220 which stores a binding between the EID and associated locators. 221 Contexts are maintained by the shim layer. 222 o Reachability detection - The procedure to check reachability 223 between a given locator pair. 224 o Path - The sequence of routers that an IP packet goes through to 225 reach the destination. 226 o Path exploration - The procedure to explore available paths for a 227 given set of locator pairs. 228 o Outage - The incident that prevents IP packets to flow from the 229 source locator to the destination locator. When there is an 230 outage, it means that there is no reachability between a given 231 locator pair. The outage may be caused by various reasons, such 232 as shortage of network resources, congestion, and human error 233 (faulty operation). 234 o Working address pair - The address pair is considered to be 235 "working" if the packet can safely travel from the source to the 236 destination where the packet contains the first address from the 237 pair as the source address and the second address from the pair as 238 the destination address. If reachability is confirmed in both 239 directions, the address pair is considered to be working bi- 240 directionally. 241 o Reachability protocol (REAP) - The protocol for detecting failure 242 and exploring reachability in a multihomed environment. REAP is 243 defined in [I-D.ietf-shim6-failure-detection]. 245 3. System Overview 247 Figure 1 illustrates the system overview. The shim layer and REAP 248 component exist inside the IP layer. Applications use the sockets 249 API defined in this document to interface with the shim layer and the 250 transport layer for locator management, failure detection, and path 251 exploration. 253 It may also be possible that the shim layer interacts with the 254 transport layer, however, such an interaction is outside the scope of 255 this document. 257 +------------------------+ 258 | Application | 259 +------------------------+ 260 ^ ^ 261 ~~~~~~~~~~~~~|~Socket Interface|~~~~~~~~~~~~~~ 262 | v 263 +-----------|------------------------------+ 264 | | Transport Layer | 265 +-----------|------------------------------+ 266 ^ | 267 +-------------|-----|-------------------------------------+ 268 | v v | 269 | +-----------------------------+ +----------+ | IP 270 | | Shim |<----->| REAP | | Layer 271 | +-----------------------------+ +----------+ | 272 | ^ ^ | 273 +-----------------------|----------------------|----------+ 274 v v 275 +------------------------------------------+ 276 | Link Layer | 277 +------------------------------------------+ 279 Figure 1: System overview 281 4. Requirements 283 The following is a list of requirements from applications: 284 o Locator management. The shim layer selects a pair of locators for 285 sending IP packets within a given context. The selection is made 286 by taking miscellaneous conditions into account such as 287 reachability of the path, application's preference, and 288 characteristics of path. From applications' perspective: 289 * It should be possible to obtain the lists of locators of a 290 given context: Ls(local) and Ls(remote). 291 * It should be possible to obtain the preferred locators of a 292 given context: Lp(local) and Lp(remote). 293 o Notification from applications to the shim layer about the status 294 of the communication. The notification occurs in an event-based 295 manner. Applications and/or upper layer protocols may provide 296 positive feedbacks or negative feedbacks to the shim layer. 297 [NOTE: These feedbacks are mentioned in 298 [I-D.ietf-shim6-failure-detection]]: 299 * Applications and/or upper layer protocols (e.g., TCP) may 300 provide positive feedbacks to the shim layer informing that the 301 communication is going well. 303 * Applications and/or upper layer protocols (e.g., TCP) may 304 provide negative feedbacks to the shim layer informing that the 305 communication status is not satisfactory. TCP may detect a 306 problem when it does not receive any expected ACK message from 307 the peer. Besides, a receipt of an ICMP error message could be 308 a clue for the application to detect problems. The REAP module 309 may be triggered by these negative feedbacks and invoke the 310 path exploration procedure. 311 o Feedback from applications to the shim layer. Applications should 312 be able to inform the shim layer of the timeout values for 313 detecting failures, sending keepalives, and starting the 314 exploration procedure. In particular, applications should be able 315 to suppress keepalives. 316 o Hot-standby. Applications may request the shim layer for the hot- 317 standby capability. This means that, alternative paths are known 318 to be working in advance of a failure detection. In such a case, 319 it is possible for the host to immediately replace the current 320 locator pair with an alternative locator pair. 321 o Eagerness for locator exploration. An application should be able 322 to inform the shim layer of how aggressively it wants the REAP 323 mechanism to perform a path exploration (e.g., by specifying the 324 number of concurrent attempts of discovery of working locator 325 pairs) when an outage occurs on the path between the locator pair 326 in use. 327 o Providing locator information to applications. An application 328 should be able to obtain information about the locator pair which 329 was actually used to send or receive the packet. 330 * For inbound traffic, the application may be interested in the 331 locator pair which was actually used to receive the packet. 332 * For outbound traffic, the application may be interested in the 333 locator pair which was actually used to transmit the packet. 334 In this way, applications may have additional control on the 335 locator management. For example, an application becomes able to 336 verify if its preference for locator is actually applied to the 337 flow or not. 338 o Applications should be able to specify if they want to defer the 339 context setup, or if they want context establishment to be started 340 immediately in the case where there is no available context. A 341 deferred context setup means that the initiation of communication 342 should not be blocked to wait for completion of the context 343 establishment. 344 o Turn on/off shim. An application should be able to request to 345 turn on or turn off the multihoming support by the shim layer: 346 * Apply shim. The application should be able to explicitly 347 request the shim layer to apply multihoming support. 348 * Don't apply shim. The application should be able to request 349 the shim layer not to apply the multihoming support but to 350 apply normal IP processing at the IP layer. 352 o An application should be able to know if the communication is now 353 being served by the shim layer or not. 354 o An application should be able to use a common interface to access 355 an IPv4 locator and an IPv6 locator. 357 5. Socket Options for Multihoming Shim Layer 359 In this section, socket options that are specific to multihomed shim 360 are defined. 362 Table 1 shows a list of the socket options that are specific to the 363 multihoming shim layer. An application may specify these socket 364 options for a given socket either by the getsockopt() system call or 365 by the setsockopt() system call. All of these socket options are 366 defined at level SOL_SHIM. 368 The first column of Table 1 gives the name of the option. The second 369 and third columns indicate whether the option can be handled by the 370 getsockopt() system call and/or by the setsockopt() system call. The 371 fourth column provides a brief description of the socket option. The 372 fifth column shows the type of data structure specified along with 373 the socket option. By default, the data structure type is an 374 integer. 376 +-----------------------------+-----+-----+-----------------+-------+ 377 | optname | get | set | description | dtype | 378 +-----------------------------+-----+-----+-----------------+-------+ 379 | SHIM_ASSOCIATED | o | | Check if the | int | 380 | | | | socket is | | 381 | | | | associated with | | 382 | | | | any shim | | 383 | | | | context or not. | | 384 | SHIM_DONTSHIM | o | o | Request the | int | 385 | | | | shim layer not | | 386 | | | | to apply any | | 387 | | | | multihoming | | 388 | | | | support for the | | 389 | | | | communication. | | 390 | SHIM_HOT_STANDBY | o | o | Request the | int | 391 | | | | shim layer to | | 392 | | | | prepare a | | 393 | | | | hot-standby | | 394 | | | | connection (in | | 395 | | | | addition to the | | 396 | | | | current path). | | 397 | SHIM_LOC_LOCAL_PREF | o | o | Get or set the | *1 | 398 | | | | preferred | | 399 | | | | locator on the | | 400 | | | | local side for | | 401 | | | | the context | | 402 | | | | associated with | | 403 | | | | the socket. | | 404 | SHIM_LOC_PEER_PREF | o | o | Get or set the | *1 | 405 | | | | preferred | | 406 | | | | locator on the | | 407 | | | | remote side for | | 408 | | | | the context | | 409 | | | | associated with | | 410 | | | | the socket. | | 411 | SHIM_LOC_LOCAL_RECV | o | o | Request for the | int | 412 | | | | destination | | 413 | | | | locator of the | | 414 | | | | received IP | | 415 | | | | packet. | | 416 | SHIM_LOC_PEER_RECV | o | o | Request for the | int | 417 | | | | source locator | | 418 | | | | of the received | | 419 | | | | IP packet. | | 420 | SHIM_LOC_LOCAL_SEND | o | o | Request the use | *2 | 421 | | | | of specific | | 422 | | | | locator as | | 423 | | | | source locator | | 424 | | | | of outgoing IP | | 425 | | | | packets. | | 426 | SHIM_LOC_PEER_SEND | o | o | Request the use | *2 | 427 | | | | of specific | | 428 | | | | locator as | | 429 | | | | destination | | 430 | | | | locator of | | 431 | | | | outgoing IP | | 432 | | | | packets. | | 433 | SHIM_LOCLIST_LOCAL | o | o | Get or set the | *3 | 434 | | | | list of | | 435 | | | | locators | | 436 | | | | associated with | | 437 | | | | the local EID. | | 438 | SHIM_LOCLIST_PEER | o | o | Get or set the | *3 | 439 | | | | list of | | 440 | | | | locators | | 441 | | | | associated with | | 442 | | | | the peer's EID. | | 443 | SHIM_APP_TIMEOUT | o | o | Inform the shim | int | 444 | | | | layer of the | | 445 | | | | timeout value | | 446 | | | | for detecting | | 447 | | | | failure. | | 448 | SHIM_PATHEXPLORE | o | o | Specify | *4 | 449 | | | | behavior of | | 450 | | | | path | | 451 | | | | exploration and | | 452 | | | | failure | | 453 | | | | detection. | | 454 | SHIM_CONTEXT_DEFERRED_SETUP | o | o | Specify if the | int | 455 | | | | context setup | | 456 | | | | can be deferred | | 457 | | | | or not. | | 458 +-----------------------------+-----+-----+-----------------+-------+ 460 Table 1: Socket options for multihoming shim 462 *1: Pointer to a shim_locator which is defined in Section 7. 464 *2: Pointer to shim_locator data structure. 466 *3: Pointer to an array of shim_locator. 468 *4: Pointer to a shim_pathexplore which is defined in Section 7. 470 Figure 2 illustrates how the shim specific socket options fit into 471 the system model of socket API. The figure shows that the shim layer 472 and the additional protocol components (IPv4 and IPv6) below the shim 473 layer are new to the system model. As previously mentioned, all the 474 shim specific socket options are defined at SOL_SHIM level. This 475 design choice brings the following advantages: 477 1. The existing sockets API continue to work at the layer above the 478 shim layer. That is, those legacy API handle IP addresses as 479 identifiers. 480 2. With newly defined socket options for the shim layer, the 481 application obtains additional control of locator management. 482 3. The shim specific socket options can be kept independent from 483 address family (IPPROTO_IP or IPPROTO_IPV6) and transport 484 protocol (IPPROTO_TCP or IPPROTO_UDP). 486 s1 s2 s3 s4 487 | | | | 488 +----------------|--|-------|--|----------------+ 489 | +-------+ +-------+ | 490 | IPPROTO_TCP | TCP | | UDP | | 491 | +-------+ +-------+ | 492 | | \ / | | 493 | | ----- | | 494 | | / \ | | 495 | +------+ +------+ | 496 | IPPROTO_IP | IPv4 | | IPv6 | IPPROTO_IPV6 | 497 | +------+ +------+ | 498 | \ / SOL_SOCKET 499 | +--------\-------/--------+ | 500 | SOL_SHIM | shim | | 501 | +--------/-------\--------+ | 502 | / \ | 503 | +------+ +------+ | 504 | | IPv4 | | IPv6 | | 505 | +------+ +------+ | 506 | | | | 507 +------------------|----------|-----------------+ 508 | | 509 IPv4 IPv6 510 Datagram Datagram 512 Figure 2: System model of sockets API with shim layer 514 5.1. SHIM_ASSOCIATED 516 The SHIM_ASSOCIATED option can be used to check whether the socket is 517 associated with any shim context or not. 519 This option is particularly meaningful in the case where the locator 520 information of the received IP packet does not tell whether the 521 identifier/locator adaptation is performed or not. Note that the EID 522 pair and locator pair may be identical in some case. 524 This option can be specified by getsockopt(). Thus, the option is 525 read-only and the result (0 or 1) is set in the option value (the 526 fourth argument of getsockopt()). 528 The data type of the option value is an integer. The option value 529 indicates the presence of shim context. A returned value 1 means 530 that the socket is associated with a shim context at the shim layer, 531 while a return value 0 indicates that there is no shim context 532 associated with the socket. 534 For example, the option can be used by the application as follows: 536 int optval; 537 int optlen = sizeof(optval); 539 getsockopt(fd, SOL_SHIM, SHIM_ASSOCIATED, &optval, &optlen); 541 5.2. SHIM_DONTSHIM 543 The SHIM_DONTSHIM option can be used to request the shim layer to not 544 apply the multihoming support for the communication established over 545 the socket. 547 The data type of the option value is an integer. The option value 548 indicates whether the multihoming shim support is deprecated or not. 549 The option value is binary (0 or 1). By default, the value is set to 550 0, which means that the shim layer applies identifier/locator 551 adaptation for the flow. In order to disable the socket option, the 552 application should call setsockopt() with optval set to 0. 554 For example, the application may disable the socket option as 555 follows: 557 int optval; 559 optval = 0; 561 setsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, sizeof(optval)); 563 For example, the application may check the option value as follows: 565 int optval; 566 int len; 568 len = sizeof(optval); 570 getsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, &len); 572 5.3. SHIM_HOT_STANDBY 574 The SHIM_HOT_STANDBY option can be used to check if the shim layer 575 uses hot-standby connection or not for the communication established 576 over the socket. A hot-standby connection is based on an alternative 577 working locator pair to the current locator pair. This option is 578 effective only when there is a shim context associated with the 579 socket. 581 The data type of the option value is an integer. 583 The option value can be set by setsockopt(). 585 The option value can be read by getsockopt(). 587 By default, the value is set to 0, meaning that hot-standby 588 connection is disabled. 590 For example, the option can be activated by the application as 591 follows. 593 int optval; 595 optval = 1; 597 setsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, 598 sizeof(optval)); 600 For example, the option value can be checked by the application as 601 follows. 603 int optval; 604 int len; 606 len = sizeof(optval); 608 getsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, &len); 610 5.4. SHIM_PATHEXPLORE 612 The application may specify this socket option to specify specify 613 behavior of path exploration. Path exploration is a procedure to 614 find an alternative locator pair when the host finds any problem with 615 the current locator pair. The message used for finding an 616 alternative locator pair is called the Probe message and it is sent 617 per locator pair. The REAP specification defines the default values 618 for Initial Probe Timeout and Initial Probe. 620 The option is effective only when there is a shim context associated 621 with the socket. 623 The data type of the option value is a pointer to the buffer where a 624 set of information for path exploration is stored. The data 625 structure is defined in Section 7. 627 By default, the option value is set to NULL, meaning that the option 628 is disabled. 630 An error ENOENT will be returned when there is no context associated 631 with the socket. 633 For example, the parameters for the path exploration can be set as 634 follows. 636 struct shim6_pathexplore pe; 638 pe.pe_probenum = 4; /* times */ 639 pe.pe_keepaliveto = 10; /* seconds */ 640 pe.pe_initprobeto = 500; /* milliseconds */ 641 pe.pe_reserved = 0; 643 setsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, sizeof(pe)); 645 For example, the parameters for the path exploration can be read as 646 follows. 648 struct shim6_pathexplore pe; 649 int len; 651 len = sizeof(pe); 653 getsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, &len); 655 5.5. SHIM_LOC_LOCAL_PREF 657 The SHIM_LOC_LOCAL_PREF option can be used to read or set preferred 658 locator on local side within a given context. Hence this option is 659 effective only when there is a shim context associated with the 660 socket. 662 The data type of the option value is a pointer to the specific data 663 structure which stores the locator information. The data structure 664 is defined in Section 7. 666 By default, the option value is set to NULL, meaning that the option 667 is disabled. 669 The preferred locator can be set by setsockopt(). Verification of 670 the locator shall be done by the shim layer before updating the 671 preferred locator. 673 The preferred locator can be read by getsockopt(). 675 An error ENOENT will be returned when there is no context associated 676 with the socket. 678 An error EINVALIDLOCATOR will be returned when the validation of the 679 specified locator failed. 681 For example, a preferred locator can be set as follows. It should be 682 noted that some members of the shim_locator (lc_ifidx and lc_flags) 683 are ignored in the write operation. 685 struct shim_locator lc; 686 struct in6_addr ip6; 688 /* ...set the locator (ip6)... */ 690 memset(&lc, 0, sizeof(shim_locator)); 691 lc.lc_family = AF_INET6; /* IPv6 */ 692 lc.lc_ifidx = 0; 693 lc.lc_flags = 0; 694 lc.lc_preference = 255; 695 memcpy(lc.lc_addr, &ip6, sizeof(in6_addr)); 697 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, 698 sizeof(optval)); 700 For example, the preferred locator of the context can be read by 701 application as follows. 703 struct shim_locator lc; 704 int len; 706 len = sizeof(lc); 708 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, &len); 710 5.6. SHIM_LOC_PEER_PREF 712 The SHIM_LOC_PEER_PREF option can be used to read or set preferred 713 locator on peer side within a given context. Hence this option is 714 effective only when there is a shim context associated with the 715 socket. 717 The data type of the option value is a pointer to the specific data 718 structure which stores the locator information. The data structure 719 is defined in Section 7. 721 By default, the option value is set to NULL, meaning that the option 722 is disabled. 724 The preferred locator can be set by setsockopt(). The shim layer 725 shall perform verification of the locator before updating the 726 preferred locator. 728 The preferred locator can be read by getsockopt(). 730 An error ENOENT will be returned when there is no context associated 731 with the socket. 733 An error EINVALIDLOCATOR will be returned when the validation of the 734 specified locator failed. 736 For example, a preferred locator can be set as follows. It should be 737 noted that some members of the shim_locator (lc_ifidx and lc_flags) 738 are ignored in the write operation. 740 The usage of the option is same as that of SHIM_LOC_LOCAL_PREF. 742 5.7. SHIM_LOC_LOCAL_RECV 744 The SHIM_LOC_LOCAL_RECV option can be used to request the shim layer 745 to store the destination locator of the received IP packet in an 746 ancillary data object which can be accessed by recvmsg(). Hence this 747 option is effective only when there is a shim context associated with 748 the socket. 750 The data type of the option value is integer. The option value 751 should be binary (0 or 1). By default, the option value is set to 0, 752 meaning that the option is disabled. 754 The option value can be set by setsockopt(). 756 The option value can be read by getsockopt(). 758 See Section 6 for the procedure to access locator information stored 759 in the ancillary data objects. 761 An error ENOENT will be returned when there is no context associated 762 with the socket. 764 For example, the option can be activated by the application as 765 follows: 767 int optval; 769 optval = 1; 771 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, 772 sizeof(optval)); 774 For example, the option value can be checked by the application as 775 follows: 777 int optval; 778 int len; 780 len = sizeof(optval); 782 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, &len); 784 5.8. SHIM_LOC_PEER_RECV 786 The SHIM_LOC_PEER_RECV option can be used to request the shim layer 787 to store the source locator of the received IP packet in an ancillary 788 data object which can be accessed by recvmsg(). Hence this option is 789 effective only when there is a shim context associated with the 790 socket. 792 The data type of the option value is integer. The option value 793 should be binary (0 or 1). By default, the option value is set to 0, 794 meaning that the option is disabled. 796 The option value can be set by setsockopt(). 798 The option value can be read by getsockopt(). 800 See Section 6 for the procedure to access locator information stored 801 in the ancillary data objects. 803 An error ENOENT will be returned when there is no context associated 804 with the socket. 806 The usage of the option is same as that of SHIM_LOC_LOCAL_RECV 807 option. 809 5.9. SHIM_LOC_LOCAL_SEND 811 The SHIM_LOC_LOCAL_SEND option can be used to request the shim layer 812 to use specific locator for the source locator of IP packets to be 813 sent from the socket. Hence this option is effective only when there 814 is a shim context associated with the socket. 816 The data type of option value is pointer to shim_locator data 817 structure. 819 The local locator can be specified by setsockopt() providing a valid 820 locator which is stored in a shim_locator data structure. When a 821 zero-filled locator is specified, pre-existing setting of local 822 locator is inactivated. 824 The local locator specified can be obtained by getsockopt(). The 825 locator can be obtained from the option value. 827 An error ENOENT will be returned when there is no context associated 828 with the socket. 830 An error EINVALIDLOCATOR when invalid locator is specified. 832 For example, a preferred local locator can be specified as follows. 834 struct shim_locator locator; 835 struct in6_addr ia6; 837 /* an IPv6 address preferred for the source locator is copied 838 to the parameter ia6 */ 840 memset(&locator, 0, sizeof(locator)); 842 /* fill shim_locator data structure */ 843 locator.lc_family = AF_INET6; 844 locator.lc_ifidx = 1; 845 locator.lc_flags = 0; 846 locator.lc_preference = 0; 847 memcpy(&locator.lc_addr, &ia6, sizeof(ia6)); 849 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, 850 sizeof(locator)); 852 For example, a preferred local locator can be read as follows. 854 struct shim_locator locator; 856 memset(&locator, 0, sizeof(locator)); 858 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, 859 sizeof(locator)); 861 /* check locator */ 863 5.10. SHIM_LOC_PEER_SEND 865 The SHIM_LOC_PEER_SEND option can be used to request the shim layer 866 to use specific locator for the destination locator of IP packets to 867 be sent from the socket. Hence this option is effective only when 868 there is a shim context associated with the socket. 870 The data type of the option value is a pointer to shim_locator data 871 structure. 873 The remote locator can be specified by setsockopt() providing a valid 874 locator which is stored in a shim_locator data structure. When a 875 zero-filled locator is specified, pre-existing setting of remote 876 locator is inactivated. 878 The remote locator specified can be obtained by getsockopt(). The 879 locator can be obtained from the option value. 881 An error ENOENT will be returned when there is no context associated 882 with the socket. 884 An error EINVALIDLOCATOR when invalid locator is specified. 886 The usage of the option is as the same as that of SHIM_LOC_LOCAL_SEND 887 option. 889 5.11. SHIM_LOCLIST_LOCAL 891 The SHIM_LOCLIST_LOCAL option can be used to read or set the locator 892 list associated with the local EID of the shim context associated 893 with the socket. Hence this option is effective only when there is a 894 shim context associated with the socket. 896 The data type of the option value is a pointer to the buffer where a 897 locator list is stored. See Section 7 for the data structure for 898 storing the locator information. By default, the option value is set 899 to NULL, meaning that the option is disabled. 901 The locator list can be read by getsockopt(). Note that the size of 902 the buffer pointed by optval argument should be large enough to store 903 an array of locator information. The number of the locator 904 information is not known beforehand. 906 The locator list can be set by setsockopt(). The buffer pointed by 907 optval argument should contain an array of locator list. 909 An error ENOENT will be returned when there is no context associated 910 with the socket. 912 An error EINVALIDLOCATOR will be returned when the validation of the 913 specified locator failed. 915 For example, a list of locators to be associated with the local EID 916 can be specified as follows: 918 struct shim_locator locators[SHIM_MAX_LOCATORS]; 919 struct sockaddr_in *sin; 920 struct sockaddr_in6 *sin6; 922 memset(locators, 0, sizeof(locators)); 924 ... 926 /* obtain local IP addresses from local interfaces */ 928 ... 930 /* first locator (an IPv6 address) */ 931 locators[0].lc_family = AF_INET6; 932 locators[0].lc_ifidx = 0; 933 locators[0].lc_flags = 0; 934 locators[0].lc_preference = 1; 935 memcpy(&locators[0].lc_addr, &sa6->sin6_addr, 936 sizeof(sa6->sin6_addr)); 938 ... 940 /* second locator (an IPv4 address) */ 941 locators[1].lc_family = AF_INET; 942 locators[1].lc_ifidx = 0; 943 locators[1].lc_flags = 0; 944 locators[1].lc_preference = 0; 945 memcpy(&locators[1].lc_addr, &sa->sin_addr, sizeof(sa->sin_addr)); 947 setsockopt(fd, SOL_SHIM, SHIM_LOCLIST_LOCAL, locators, 948 sizeof(locators)); 950 For example, a list of locators that are associated with the local 951 EID can be obtained as follows: 953 struct shim_locator locators[SHIM_MAX_LOCATORS]; 955 memset(locators, 0, sizeof(locators)); 957 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, locators, 958 sizeof(locators)); 960 /* parse locators */ 961 ... 963 5.12. SHIM_LOCLIST_PEER 965 The SHIM_LOCLIST_PEER option can be used to read or set the locator 966 list associated with the peer EID of the shim context associated with 967 the socket. Hence this option is effective only when there is a shim 968 context associated with the socket. 970 The data type of the option value is a pointer to the buffer where a 971 locator list is stored. See Section 7 for the data structure for 972 storing the locator information. By default, the option value is set 973 to NULL, meaning that the option is disabled. 975 The locator list can be read by getsockopt(). Note that the size of 976 the buffer pointed by optval argument should be large enough to store 977 an array of locator information. The number of the locator 978 information is not known beforehand. 980 The locator list can be set by setsockopt(). The buffer pointed by 981 optval argument should contain an array of locator list. 983 An error ENOENT will be returned when there is no context associated 984 with the socket. 986 An error EINVALIDLOCATOR will be returned when the validation of the 987 specified locator failed. 989 The usage of the option is same as that of SHIM_LOCLIST_LOCAL. 991 5.13. SHIM_APP_TIMEOUT 993 The SHIM_APP_TIMEOUT option indicates timeout value for application 994 to detect failure. Hence this option is effective only when there is 995 a shim context associated with the socket. 997 The data type of the option value is an integer. The value indicates 998 the period of timeout in seconds to send a REAP Keepalive message 999 since the last outbound traffic. By default, the option value is set 1000 to 0, meaning that the option is disabled. When the option is 1001 disabled, the REAP mechanism follows its default value of Send 1002 Timeout value as specified in [I-D.ietf-shim6-failure-detection] 1004 If the timeout value specified is longer than the Send Timeout 1005 configured in the REAP component, the REAP Keepalive message should 1006 be suppressed. 1008 An error ENOENT will be returned when there is no context associated 1009 with the socket. 1011 For example, a specific timeout value can be configured by the 1012 application as follows: 1014 int optval; 1016 optval = 15; /* 15 seconds */ 1018 setsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, 1019 sizeof(optval)); 1021 For example, the option value namely the period of timeout can be 1022 checked by the application as follows: 1024 int optval; 1025 int len; 1027 len = sizeof(optval); 1029 getsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, &len); 1031 5.14. SHIM_DEFERRED_CONTEXT_SETUP 1033 The SHIM_DEFERRED_CONTEXT_SETUP option indicates how initiation of 1034 context setup is made in terms of timing (before or after) the 1035 initial communication flow. Deferred context means that the 1036 establishment of context does not put additional delay for an initial 1037 transaction. 1039 The data type for the option value is an integer. The option value 1040 should binary (0 or 1). By default, the value is set to 1, meaning 1041 that the context setup is deferred. In order to disable the option, 1042 the application should call setsockopt() with option value set to 0. 1044 However, it should be noted that deferred context setup may not be 1045 possible in some cases. For instance, an EID may be non-routable 1046 address (e.g., Host Identifier in HIP) and there is no way to 1047 transmit any IP packet unless there is a context providing the 1048 locators. In such a case, a context should be established prior to 1049 the communication. 1051 For example, the option can be disabled by the application as 1052 follows: 1054 int optval; 1056 optval = 0; 1058 setsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, 1059 &optval, sizeof(optval)); 1061 For example, the option value can be checked by the application as 1062 follows: 1064 int optval; 1065 int len; 1067 len = sizeof(optval); 1069 getsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, 1070 &optval, &len); 1072 5.15. Error Handling 1074 If successful, getsockopt() and setsockopt() return 0; otherwise, the 1075 functions return -1 and set errno to indicate error. 1077 The following are new error values defined for some shim specific 1078 socket options indicating that the getsockopt() or setsockopt() 1079 finished incompletely: 1081 EINVALIDLOCATOR 1082 This indicates that at least one of the necessary validations 1083 inside the shim layer for the specified locator has failed. In 1084 case of SHIM6, there are two kinds of verifications required for 1085 security reasons prior to sending an IP packet to the peer's new 1086 locator; one is the return routability (check if the peer is 1087 actually willing to receive data with the specified locator) and 1088 the other one is the verification based on crypto identifier 1089 mechanisms [RFC3972], [I-D.ietf-shim6-hba]. 1091 6. Ancillary Data for Multihoming Shim 1093 In this section, the definition and the usage of the ancillary data 1094 specific to multihoming shim are provided. 1096 As defined in the Posix standard, sendmsg() and recvmsg() input a 1097 msghdr structure as their arguments. These system calls can handle 1098 control information along with data. Figure 3 shows the msghdr 1099 structure which is defined in . The member msg_control 1100 holds a pointer to the buffer where the shim specific ancillary data 1101 objects can be stored in addition to other ancillary data objects. 1103 struct msghdr { 1104 caddr_t msg_name; /* optional address */ 1105 u_int msg_namelen; /* size of address */ 1106 struct iovec *msg_iov; /* scatter/gather array */ 1107 u_int msg_iovlen; /* # elements in msg_iov */ 1108 caddr_t msg_control; /* ancillary data, see below */ 1109 u_int msg_controllen; /* ancillary data buffer len */ 1110 int msg_flags; /* flags on received message */ 1111 }; 1113 Figure 3: msghdr structure 1115 The buffer pointed by the member msg_control of the msghdr structure 1116 may contain locator information which is a single locator and it 1117 should be possible to process them with the existing macros defined 1118 in Posix and [RFC3542]. Each cmsghdr{} should be followed by data 1119 which stores a single locator. 1121 In case of non-connected socket, msg_name member stores the socket 1122 address of the peer which should be considered as an identifier 1123 rather than a locator. The locator of the peer node should be 1124 retrieved by SHIM_LOC_PEER_RECV as specified below. 1126 Table 2 is a list of the shim specific ancillary data which can be 1127 used for recvmsg() or sendmsg(). In any case, SOL_SHIM must be set 1128 as cmsg_level. 1130 +---------------------+-----------+-----------+-----------------+ 1131 | cmsg_type | sendmsg() | recvmsg() | cmsg_data[] | 1132 +---------------------+-----------+-----------+-----------------+ 1133 | SHIM_LOC_LOCAL_RECV | | o | *1 | 1134 | SHIM_LOC_PEER_RECV | | o | *1 | 1135 | SHIM_LOC_LOCAL_SEND | o | | *1 | 1136 | SHIM_LOC_PEER_SEND | o | | *1 | 1137 | SHIM_FEEDBACK | o | | shim_feedback{} | 1138 +---------------------+-----------+-----------+-----------------+ 1140 Table 2: Shim specific ancillary data 1142 *1: cmsg_data[] should include padding (if necessary) and a single 1143 sockaddr_in{}/sockaddr_in6{}. 1145 It should be noted that the above ancillary data can only be handled 1146 by a UDP or a raw socket and not by a TCP socket. This is because 1147 there is no one-to-one mapping between a single send/receive 1148 operation and a TCP segment being transmitted/received. 1150 6.1. Get Locator Information from Incoming Packet 1152 An application can get locator information from the received IP 1153 packet by specifying the shim specific socket options for the socket. 1154 When SHIM_LOC_LOCAL_RECV and/or SHIM_LOC_PEER_RECV socket options are 1155 set, the application can retrieve local and/or remote locator from 1156 the ancillary data. 1158 6.2. Specify Locator Information for Outgoing Packet 1160 An application can specify the locators to be used for transmitting 1161 an IP packet by sendmsg(). When the ancillary data of cmsg_type 1162 SHIM_LOC_LOCAL_SEND and/or SHIM_LOC_PEER_SEND are specified, the 1163 application can explicitly specify the source and/or the destination 1164 locators to be used for the communication over the socket. 1166 In addition, the application can specify the outgoing interface by 1167 SHIM_IF_SEND ancillary data. The ancillary data should contain the 1168 interface identifier of the physical interface over which the 1169 application expects the packet to be transmitted. 1171 Note that the effect is limited to the datagram transmitted by the 1172 sendmsg(). 1174 If the specified locator pair is verified, the shim layer overrides 1175 the locators of the IP packet. 1177 An error EINVALIDLOCATOR will be returned when validation of the 1178 specified locator failed. 1180 6.3. Notification from Application to Multihoming Shim 1182 An application may provide feedbacks to the shim layer about the 1183 communication status. Such feedbacks are particularly useful for the 1184 shim layer in the absence of REAP mechanism to monitor the 1185 reachability status of the currently used locator pair in a given 1186 shim context. 1188 The notification can be made by sendmsg() specifying a new ancillary 1189 data called SHIM_FEEDBACK. The ancillary data can be handled by 1190 specifying SHIM_FEEDBACK option in cmsg_type. 1192 An error ENOENT will be returned when there is no context associated 1193 with the socket. 1195 See Section 7.3 for details of the data structure to be used. Note 1196 that this specification does not specify the exact behavior of the 1197 shim layer when a feedback is given by an application. 1199 7. Data Structures 1201 In this section, data structures specifically defined for the 1202 multihoming shim layer are introduced. These data structures are 1203 either used as a parameter for setsockopt()/getsockopt() (as 1204 mentioned in Section 5) or as a parameter for ancillary data to be 1205 processed by sendmsg()/recvmsg() (as mentioned in Section 6). 1207 7.1. Placeholder for Locator Information 1209 As defined in Section 5, the SHIM_LOC_LOCAL_PREF, SHIM_LOC_PEER_PREF, 1210 SHIM_LOCLIST_LOCAL, and SHIM_LOCLIST_PEER socket options need to 1211 handle one or more locator information. Locator information includes 1212 not only the locator itself but also additional information about the 1213 locator which is useful for locator management. A new data structure 1214 is defined to serve as a placeholder for the locator information. 1216 Figure 4 illustrates the data structure called shim_locator which 1217 stores a locator information. 1219 struct shim_locator { 1220 uint8_t lc_family; /* address family */ 1221 uint8_t lc_ifidx; /* interface index */ 1222 uint8_t lc_flags; /* flags */ 1223 uint8_t lc_preference; /* preference value */ 1224 uint8_t lc_addr[16]; /* address data */ 1225 }; 1227 Figure 4: shim locator structure 1229 lc_family 1230 Address family of the locator (e.g. AF_INET, AF_INET6). It is 1231 required that the parameter contains non-zero value indicating the 1232 exact address family of the locator. 1233 lc_ifidx 1234 Interface index of the network interface to which the locator is 1235 assigned. This field should be valid only in a read 1236 (getsockopt()) operation. 1237 lc_flags 1238 Each bit of the flags represents a specific characteristics of the 1239 locator. Hash Based Address (HBA) is defined as 0x01. 1240 Cryptographically Generated Address (CGA) is defined as 0x02. 1241 lc_preference 1242 Indicates a preference of the locator. The preference is 1243 represented by an integer. 1245 lc_addr 1246 Contains the locator. In the case where a locator whose size is 1247 smaller than 16 bytes, an encoding rule should be provided for 1248 each locator of a given address family. For instance, in case of 1249 AF_INET (IPv4), the locator should be in the format of an IPv4- 1250 mapped IPv6 address as defined in RFC 4291[RFC4291]. 1252 7.2. Path Exploration Parameter 1254 As defined in Section 5, SHIM_PATHEXPLORE allows application to set 1255 or read the parameters for path exploration and failure detection. A 1256 new data structure called shim_pathexplore is defined to store the 1257 necessary parameters. Figure 5 illustrates the data structure. The 1258 data structure can be passed to getsockopt() or setsockopt() as an 1259 argument. 1261 struct shim_pathexplore { 1262 uint8_t pe_probenum; /* # of initial probe */ 1263 uint8_t pe_keepaliveto; /* Keepalive Timeout */ 1264 uint16_t pe_initprobeto; /* Initial Probe Timeout */ 1265 uint32_t pe_reserved; /* reserved */ 1266 }; 1268 Figure 5: path explore structure 1270 pe_probenum 1271 Indicates the number of initial probe messages to be sent. 1272 Default value of this parameter should follow what is specified in 1273 [I-D.ietf-shim6-failure-detection]. 1274 pe_keepaliveto 1275 Indicates timeout value for detecting a failure when the host does 1276 not receive any packets for a certain period of time while there 1277 is outbound traffic. When the timer expires, path exploration 1278 procedure will be carried out by sending a REAP Probe message. 1279 Default value of this parameter should follow what is specified in 1280 [I-D.ietf-shim6-failure-detection]. 1281 pe_initprobeto 1282 Indicates retransmission timer of REAP Probe message in 1283 milliseconds. Note that this timer is applied before exponential 1284 back-off is started. A REAP Probe message for the same locator 1285 pair may be retransmitted. Default value of this parameter should 1286 follow what is specified in [I-D.ietf-shim6-failure-detection]. 1287 pe_reserved 1288 A reserved field for future extension. By default, the field 1289 should be initialized to zero. 1291 7.3. Feedback Information 1293 As mentioned in Section 6.3, applications can inform the shim layer 1294 about the status of unicast reachability of the locator pair 1295 currently in use. The feedback information can be handled by using 1296 ancillary data called SHIM_FEEDBACK. A new data structure named 1297 shim_feedback is illustrated in Figure 6. 1299 struct shim_feedback { 1300 uint8_t fb_direction; /* direction of traffic */ 1301 uint8_t fb_indicator; /* indicator (1-3) */ 1302 uint16_t fb_reserved; /* reserved */ 1303 }; 1305 Figure 6: feedback information structure 1307 direction 1308 Indicates direction of reachability between a locator pair in 1309 question. A value 0 indicates outbound and a value 1 indicates 1310 inbound direction. 1311 indicator 1312 A value indicating the degree of satisfaction of a unidirectional 1313 reachability for a given locator pair. 1314 * 0: Default value. Whenever this value is specified the 1315 feedback information must not be processed by the shim layer. 1316 * 1: Unable to connect. There is no unidirectional reachability 1317 between the locator pair in question. 1318 * 2: Unsatisfactory. The application is not satisfied with the 1319 unidirectional reachability between the locator pair in 1320 question. 1321 * 3: Satisfactory. There is satisfactory unidirectional 1322 reachability between the locator pair in question. 1323 reserved 1324 Reserved field. Must be ignored by the receiver. 1326 8. Implications for Existing Socket API Extensions 1328 Some of the socket options defined in this document are overlapping 1329 with existing sockets API and care should be taken for the usage not 1330 to confuse with the overlapping features. 1332 The socket options for requesting specific locators to be used for a 1333 given transaction (SHIM_LOC_LOCAL_PREF and SHIM_LOC_PEER_PREF) are 1334 semantically similar to the existing sockets API (IPV6_PKTINFO). The 1335 socket options for obtaining the locator information from the 1336 received IP packet (SHIM_LOC_LOCAL_RECV and SHIM_LOC_PEER_RECV) are 1337 semantically similar to the existing sockets API (IP_RECVDSTADDR and 1338 IPV6_PKTINFO). 1340 In IPv4, application can obtain the destination IP address of the 1341 received IP packet (IP_RECVDSTADDR). If the shim layer performs 1342 identifier/locator adaptation for the received packet, the 1343 destination EID should be stored in the ancillary data 1344 (IP_RECVDSTADDR). 1346 In IPv6, [RFC3542] defines that IPV6_PKTINFO can be used to specify 1347 source IPv6 address and the outgoing interface for outgoing packets, 1348 and retrieve destination IPv6 address and receiving interface for 1349 incoming packets. This information is stored in ancillary data being 1350 IPV6_PKTINFO specified as cmsg_type. Existing sockets API should 1351 continue to work above the shim layer, that is, the IP addresses 1352 handled in IPV6_PKTINFO should be EIDs, not the locators. 1354 Baseline is that the above existing sockets API (IP_RECVDSTADDR and 1355 IPV6_PKTINFO) is assumed to work above the multihoming shim layer. 1356 In other words, the IP addresses those socket options deal with are 1357 EIDs rather than locators. 1359 9. Resolving Conflicts with Preference Values 1361 Since the multihoming shim API allows application to specify 1362 preference value for the context which is associated with the socket 1363 instance, there may be a conflict with preference values specified by 1364 different applications. For instance, application A and B may 1365 establish communication over the same EID pair while both 1366 applications have different preference in their choice of local 1367 locator. 1369 SHIM6 supports a notion of context forking in which a context is 1370 split when there is a conflict with preference values specified by 1371 multiple applications. Thus, context forking can simply resolve the 1372 conflicting situation which may be caused by the use of socket 1373 options for multihoming shim layer. 1375 9.1. Implicit Forking 1377 Socket options defined in Section 5 may cause conflicting situation 1378 when the target context is shared by multiple applications. In such 1379 case, socket handler and the multihoming shim layer should react as 1380 follows; socket handler should inform the shim layer that context 1381 forking is required. In SHIM6, when a context is forked, an unique 1382 identifier called Forked Instance Identifier (FII) is assigned to the 1383 newly forked context. The forked context is then exclusively 1384 associated with the socket through which non-default preference value 1385 was specified. The forked context is maintained by the multihoming 1386 shim layer during the lifetime of associated socket instance. When 1387 the socket is closed, the multihoming shim layer SHOULD delete 1388 associated context. In this way, garbage collection can be carried 1389 out to cleanup unused forked contexts. Upon garbage collection, 1390 every forked context SHOULD be checked if there is no socket 1391 (process) associated with the context. If there is none, the forked 1392 context should be deleted. When a forked context is torn down, SHIM6 1393 should notify the peer about the deletion of forked context. 1395 As opposed to socket options, context forking MUST NOT be triggered 1396 by any use of ancillary data that is specific to multihoming shim as 1397 defined in Section 6. 1399 10. Discussion 1401 In this section, open issues are introduced. 1403 10.1. Naming at Socket Layer 1405 The getsockname() and getpeername() system calls are used to obtain 1406 the 'name' of an endpoint which is actually a pair of IP address and 1407 port number assigned to a given socket. getsockname() is used when an 1408 application wants to obtain the local IP address and port number 1409 assigned for a given socket instance. getpeername() is used when an 1410 application obtains the remote IP address and port number. 1412 The above is based on a traditional system model of the sockets API 1413 where an IP address is expected to play both the role of identifier 1414 and the role of locator. 1416 In a system model where a shim layer exists inside the IP layer, both 1417 getsockname() and getpeername() deal with identifiers, namely EIDs. 1418 In this sense, the shim layer serves to (1) hide locators and (2) 1419 provide access to the identifier for the application over the legacy 1420 socket APIs. 1422 10.2. Additional Requirements from Applications 1424 At the moment, it is not certain if following requirements are common 1425 in all the multihomed environments (SHIM6 and HIP). These are mainly 1426 identified during discussions made on SHIM6 WG mailing list. 1427 o The application should be able to set preferences for the 1428 locators, local and remote ones, and also to the preferences of 1429 the local locators that will be passed to the peer. 1431 10.3. Issues of Header Conversion among Different Address Family 1433 The shim layer performs identifier/locator adaptation. Therefore, in 1434 some case, the whole IP header can be replaced with new IP header of 1435 a different address family (e.g. conversion from IPv4 to IPv6 or vice 1436 versa). Hence, there is an issue how to make the conversion with 1437 minimum impact. Note that this issue is common in other protocol 1438 conversion such as SIIT[RFC2765]. 1440 As addressed in SIIT specification, some of the features (IPv6 1441 routing headers, hop-by-hop extension headers, or destination 1442 headers) from IPv6 are not convertible to IPv4. In addition, notion 1443 of source routing is not exactly the same in IPv4 and IPv6. Hence, 1444 there is certain limitation in protocol conversion between IPv4 and 1445 IPv6. 1447 The question is how should the shim layer behave when it is face with 1448 limitation problem of protocol conversion. Should we introduce new 1449 error something like ENOSUITABLELOCATOR ? 1451 10.4. Handling of Unknown Locator Provided by Application 1453 There might be a case where application provides the shim layer new 1454 locator with the SHIM_LOC_*_PREF socket options or SHIM_LOC_*_SEND 1455 ancillary data. Then there is a question how should the shim layer 1456 treat the new locator informed by the application. 1458 In principle, locator information are exchanged by the shim protocol. 1459 However, there might be a case where application acquires information 1460 about the locator and prefers to use it for its communication. 1462 11. Changes 1464 11.1. Changes from version 00 to version 01 1466 The followings are changes from version 00 to version 01: 1467 o Define shim_locator{} data type which is a placeholder for 1468 locator. 1469 o Define shim_pathexplore{} data type in which a set of REAP 1470 parameters are stored. 1471 o Remove descriptions about "stickiness" of socket options. 1472 o Deprecate SHIM_IF_RECV and SHIM_IF_SEND socket options. 1473 o Give default value and how to disable given socket option. 1475 11.2. Changes from version 01 to version 02 1477 The followings are changes from version 01 to version 02: 1478 o Add section describing context forking. 1479 o Rephrase conclusion section. 1480 o Separate normative references from informative references. 1481 o Remove texts from discussion section that are not relevant to the 1482 contents of the document. 1483 o Add section describing change history (this section). 1485 11.3. Changes from version 02 to version 03 1487 The followings are changes from version 02 to version 03: 1488 o Add an Appendix section describing the issue of context forking. 1490 11.4. Changes from version 03 to version 04 1492 The followings are changes from version 03 to version 04: 1493 o Updated reference. 1494 o Correct typo and grammatical errors. 1496 11.5. Changes from version 04 to version 05 1498 The followings are changes from version 04 to version 05: 1499 o Added definition of SHIM_FEEDBACK ancillary data. 1500 o Added an example of code using the SHIM_LOCLIST_LOCAL 1501 o Added SHIM_LOC_LOCAL_SEND and SHIM_LOC_PEER_SEND socket options. 1503 11.6. Changes from version 05 to version 06 1505 The followings are changes from version 04 to version 05: 1506 o Updated references. 1508 11.7. Changes from version 06 to version 07 1510 The followings are changes from version 06 to version 07: 1511 o Resolved editorial issues. 1513 11.8. Changes from version 07 to version 08 1515 No changes are made except for updates of the references. 1517 12. IANA Considerations 1519 This document contains no IANA consideration. 1521 13. Security Considerations 1523 This document does not specify any security mechanism for the shim 1524 layer. Fundamentally, the shim layer has a potential to impose 1525 security threats, as it changes the source and/or destination IP 1526 addresses of the IP packet being sent or received. Therefore, the 1527 basic assumption is that the security mechanism defined in each 1528 protocol of the shim layer is strictly applied. 1530 14. Conclusion 1532 In this document, the Application Program Interface (API) for 1533 multihoming shim layer is specified. The sockets API allows 1534 applications to have additional control of the locator management and 1535 interface to the REAP mechanism inside the multihoming shim layer. 1537 Socket options for multihoming shim layer can be used by getsockopt() 1538 and/or setsockopt() system calls. Besides, applications can use some 1539 ancillary data that are specific to multihoming shim layer to get 1540 locator from received packet or to set locator for outgoing packet. 1542 From an architectural point of view, the sockets API provides extends 1543 the existing sockets API framework in the face of ID/Locator 1544 separation. With regard to API that relate to IP address management, 1545 it is assured that existing sockets API continue to work above the 1546 shim layer dealing with identifiers, while multihoming shim API deals 1547 with locators. 1549 15. Acknowledgments 1551 Authors would like to thank Jari Arkko who participated in the 1552 discussion that lead to the first version of this document, and 1553 Tatuya Jinmei who thoroughly reviewed the early version of this draft 1554 and provided detailed comments on sockets API related issues. Thomas 1555 Henderson provided valuable comments especially from HIP 1556 perspectives. 1558 16. References 1560 16.1. Normative References 1562 [I-D.ietf-shim6-failure-detection] 1563 Arkko, J. and I. Beijnum, "Failure Detection and Locator 1564 Pair Exploration Protocol for IPv6 Multihoming", 1565 draft-ietf-shim6-failure-detection-13 (work in progress), 1566 June 2008. 1568 [I-D.ietf-shim6-proto] 1569 Bagnulo, M. and E. Nordmark, "Level 3 multihoming shim 1570 protocol", draft-ietf-shim6-proto-12 (work in progress), 1571 February 2009. 1573 [POSIX] "IEEE Std. 1003.1-2001 Standard for Information Technology 1574 -- Portable Operating System Interface (POSIX). Open group 1575 Technical Standard: Base Specifications, Issue 6, 1576 http://www.opengroup.org/austin", December 2001. 1578 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 1579 "Advanced Sockets Application Program Interface (API) for 1580 IPv6", RFC 3542, May 2003. 1582 [RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol 1583 (HIP) Architecture", RFC 4423, May 2006. 1585 16.2. Informative References 1587 [I-D.ietf-shim6-app-refer] 1588 Nordmark, E., "Shim6 Application Referral Issues", 1589 draft-ietf-shim6-app-refer-00 (work in progress), 1590 July 2005. 1592 [I-D.ietf-shim6-hba] 1593 Bagnulo, M., "Hash Based Addresses (HBA)", 1594 draft-ietf-shim6-hba-05 (work in progress), December 2007. 1596 [RFC2765] Nordmark, E., "Stateless IP/ICMP Translation Algorithm 1597 (SIIT)", RFC 2765, February 2000. 1599 [RFC3972] Aura, T., "Cryptographically Generated Addresses (CGA)", 1600 RFC 3972, March 2005. 1602 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 1603 Architecture", RFC 4291, February 2006. 1605 Appendix A. Context Forking 1607 In this section, an issue concerning context forking and its relation 1608 to the multihoming shim API are discussed. 1610 SHIM6 supports a notion of context forking. A peer may decide to 1611 fork a context for certain reason (e.g. upper layer protocol prefers 1612 to use different locator pair than the one defined in available 1613 context). The procedure of forking context is done similar to the 1614 normal context establishment, performing the 4-way message exchange. 1615 A peer who has decided to fork a context initiates the context 1616 establishment. Hereafter, we call this peer initiator. 1618 Once the forked context is established between the peers, on the 1619 initiator side, it is possible to apply forked context to the packet 1620 flow since the system maintains an association between the forked 1621 context and the socket owned by the application that has requested 1622 the context forking. How this association is maintained is 1623 implementation specific issue. However, on the responder side, there 1624 is a question on how the outbound packet can be multiplexed by the 1625 shim layer. Since there are more than one SHIM6 contexts that match 1626 with the ULID pair of the packet flow. There is a need to 1627 differentiate packet flows not only by the ULID pairs but some other 1628 information and associate a given packet flow with specific context. 1630 Figure 7 gives an example of a scenario where two communicating peers 1631 fork a context. Initially, there has been a single transaction 1632 between the peers, by the application 1 (App1). Accordingly, another 1633 transaction is started, by application 2 (App2). Both of the 1634 transactions are made based the same ULID pair. The first context 1635 pair (Ctx1) is established for the transaction of App1. Given the 1636 requests from App2, the shim layer on Peer 1 decides to fork a 1637 context. Accordingly, a forked context (Ctx2) is established between 1638 the peers, which should be exclusively applied to the transaction of 1639 App2. Ideally, multiplexing and demultiplexing of packet flows that 1640 relate to App1 and App2 should be done as illustrated in Figure 7. 1641 However, as mentioned earlier, the responder needs to multiplex 1642 outbound flows of App1 and App2 somehow. Note that if a context 1643 forking occurs on the initiator side, a context forking needs to 1644 occur also on the responder side. 1646 Peer 1 Peer 2 1647 (initiator) (responder) 1649 +----+ +----+ +----+ +----+ 1650 |App1| |App2| |App1| |App2| 1651 +----+ +----+ +----+ +----+ 1652 |^ |^ ^| ^| 1653 v| v| |v |v 1654 -----S1-------------S2----- -----S1-------------S2----- 1655 || || || || 1656 || || || || 1658 Ctx1 Ctx2 Ctx1 Ctx2 1659 ULID: ULID: ULID: ULID: 1660 Loc: Loc: Loc: Loc: 1661 FII: 0 FII: 100 FII: 0 FII: 100 1663 |^ |^ ^| ^| 1664 || || || || 1665 || || || || 1666 \..............||........................../| || 1667 \.............||.........................../ || 1668 || || 1669 \|........................................./| 1670 \........................................../ 1672 Figure 7: context forking 1674 To overcome the problem mentioned above, there are some solutions. 1676 One viable approach is to let the system implicitly maintain an 1677 association between the socket and the associated context by keeping 1678 the record of inbound packet processing. That is, the system stores 1679 the information about the context on which the inbound packet flow 1680 was demultiplexed. The information comprises the ULID pair and FII 1681 of the context and is stored in the socket instance. Later, the 1682 system can use the information to identify the associated context in 1683 outbound packet processing. This approach should be feasible as far 1684 as there is bi-directional user traffic. 1686 Another viable approach is to extend SHIM6 protocol by adding 1687 capability of exchanging additional information to identify the 1688 packet flow from others which needs to be handled by a newly forked 1689 context. The information exchange can be done during the context 1690 establishment. The initiator appends 5 tuple of the packet flow to 1691 be handled by the newly forked context. Note that the additional 1692 information provided by the 5 tuple are source and destination port 1693 numbers and upper layer protocol. The information is later used by 1694 the shim layer to multiplex the outbound packet flow on the responder 1695 side. 1697 The socket options for multihoming shim can be used by the 1698 application to trigger the context forking in implicit manner. The 1699 peer becomes an initiator in the establishment of the forked context. 1700 Once the forked context is established between the peers, application 1701 on each end can influence the preference on context by utilizing the 1702 multihoming shim API. 1704 Authors' Addresses 1706 Miika Komu 1707 Helsinki Institute for Information Technology 1708 Tammasaarenkatu 3 1709 Helsinki 1710 Finland 1712 Phone: +358503841531 1713 Fax: +35896949768 1714 Email: miika@iki.fi 1715 URI: http://www.hiit.fi/ 1717 Marcelo Bagnulo 1718 Universidad Carlos III de Madrid 1719 Av. Universidad 30 1720 Leganes 28911 1721 SPAIN 1723 Phone: +34 91 6248837 1724 Email: marcelo@it.uc3m.es 1725 URI: http://it.uc3m.es/marcelo 1727 Kristian Slavov 1728 Ericsson Research Nomadiclab 1729 Hirsalantie 11 1730 Jorvas FI-02420 1731 Finland 1733 Phone: +358 9 299 3286 1734 Email: kristian.slavov@ericsson.com 1735 Shinta Sugimoto (editor) 1736 Nippon Ericsson K.K. 1737 Koraku Mori Building 1738 1-4-14, Koraku, Bunkyo-ku 1739 Tokyo 112-0004 1740 Japan 1742 Phone: +81 3 3830 2241 1743 Email: shinta.sugimoto@ericsson.com