idnits 2.17.1 draft-ietf-shim6-multihome-shim-api-07.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 1747. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1758. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1765. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1771. 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 1379: '...e multihoming shim layer SHOULD delete...' RFC 2119 keyword, line 1382: '...y forked context SHOULD be checked if ...' RFC 2119 keyword, line 1387: '... context forking MUST NOT be triggered...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 1097 has weird spacing: '... u_int msg_...' == Line 1098 has weird spacing: '... struct iovec...' == Line 1099 has weird spacing: '... u_int msg_...' == Line 1101 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 (November 3, 2008) is 5624 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 927 -- Looks like a reference, but probably isn't: '1' on line 937 -- Looks like a reference, but probably isn't: '16' on line 1216 == Outdated reference: A later version (-12) exists of draft-ietf-shim6-proto-10 ** 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 (~~), 6 warnings (==), 12 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: May 7, 2009 UC3M 6 K. Slavov 7 S. Sugimoto, Ed. 8 Ericsson 9 November 3, 2008 11 Socket Application Program Interface (API) for Multihoming Shim 12 draft-ietf-shim6-multihome-shim-api-07 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 May 7, 2009. 39 Abstract 41 This document specifies sockets API extensions for the multihoming 42 shim layer. The API aims to enable interactions between applications 43 and the multihoming shim layer for advanced locator management, and 44 access to information about failure detection and path exploration. 46 This document is based on an assumption that a multihomed host is 47 equipped with a conceptual sub-layer (hereafter "shim") inside the IP 48 layer that maintains mappings between identifiers and locators. 50 Examples of the shim are SHIM6 and HIP. 52 Table of Contents 54 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 55 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 56 3. System Overview . . . . . . . . . . . . . . . . . . . . . . . 6 57 4. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 7 58 5. Socket Options for Multihoming Shim Layer . . . . . . . . . . 9 59 5.1. SHIM_ASSOCIATED . . . . . . . . . . . . . . . . . . . . . 12 60 5.2. SHIM_DONTSHIM . . . . . . . . . . . . . . . . . . . . . . 13 61 5.3. SHIM_HOT_STANDBY . . . . . . . . . . . . . . . . . . . . . 13 62 5.4. SHIM_PATHEXPLORE . . . . . . . . . . . . . . . . . . . . . 14 63 5.5. SHIM_LOC_LOCAL_PREF . . . . . . . . . . . . . . . . . . . 15 64 5.6. SHIM_LOC_PEER_PREF . . . . . . . . . . . . . . . . . . . . 16 65 5.7. SHIM_LOC_LOCAL_RECV . . . . . . . . . . . . . . . . . . . 17 66 5.8. SHIM_LOC_PEER_RECV . . . . . . . . . . . . . . . . . . . . 18 67 5.9. SHIM_LOC_LOCAL_SEND . . . . . . . . . . . . . . . . . . . 18 68 5.10. SHIM_LOC_PEER_SEND . . . . . . . . . . . . . . . . . . . . 19 69 5.11. SHIM_LOCLIST_LOCAL . . . . . . . . . . . . . . . . . . . . 20 70 5.12. SHIM_LOCLIST_PEER . . . . . . . . . . . . . . . . . . . . 22 71 5.13. SHIM_APP_TIMEOUT . . . . . . . . . . . . . . . . . . . . . 22 72 5.14. SHIM_DEFERRED_CONTEXT_SETUP . . . . . . . . . . . . . . . 23 73 5.15. Error Handling . . . . . . . . . . . . . . . . . . . . . . 24 74 6. Ancillary Data for Multihoming Shim . . . . . . . . . . . . . 24 75 6.1. Get Locator Information from Incoming Packet . . . . . . . 26 76 6.2. Specify Locator Information for Outgoing Packet . . . . . 26 77 6.3. Notification from Application to Multihoming Shim . . . . 26 78 7. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 27 79 7.1. Placeholder for Locator Information . . . . . . . . . . . 27 80 7.2. Path Exploration Parameter . . . . . . . . . . . . . . . . 28 81 7.3. Feedback Information . . . . . . . . . . . . . . . . . . . 29 82 8. Implications for Existing Socket API Extensions . . . . . . . 29 83 9. Resolving Conflicts with Preference Values . . . . . . . . . . 30 84 9.1. Implicit Forking . . . . . . . . . . . . . . . . . . . . . 30 85 10. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 31 86 10.1. Naming at Socket Layer . . . . . . . . . . . . . . . . . . 31 87 10.2. Additional Requirements from Applications . . . . . . . . 31 88 10.3. Issues of Header Conversion among Different Address 89 Family . . . . . . . . . . . . . . . . . . . . . . . . . . 32 90 10.4. Handling of Unknown Locator Provided by Application . . . 32 91 11. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 92 11.1. Changes from version 00 to version 01 . . . . . . . . . . 32 93 11.2. Changes from version 01 to version 02 . . . . . . . . . . 33 94 11.3. Changes from version 02 to version 03 . . . . . . . . . . 33 95 11.4. Changes from version 03 to version 04 . . . . . . . . . . 33 96 11.5. Changes from version 04 to version 05 . . . . . . . . . . 33 97 11.6. Changes from version 05 to version 06 . . . . . . . . . . 33 98 11.7. Changes from version 06 to version 07 . . . . . . . . . . 33 99 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 100 13. Security Considerations . . . . . . . . . . . . . . . . . . . 33 101 14. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . 34 102 15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 34 103 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 104 16.1. Normative References . . . . . . . . . . . . . . . . . . . 34 105 16.2. Informative References . . . . . . . . . . . . . . . . . . 35 106 Appendix A. Context Forking . . . . . . . . . . . . . . . . . . . 35 107 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 38 108 Intellectual Property and Copyright Statements . . . . . . . . . . 40 110 1. Introduction 112 HIP and SHIM6 have a commonality in their protocol design in the 113 sense that the roles of an IP address as an identifier and a locator 114 are clearly distinguished. Hereafter this design principle is called 115 "identifier/locator separation" in this document. Both protocols aim 116 to solve problems that are specific to multihoming environment in an 117 endhost centric approach. In these protocols, a sub-layer within the 118 IP layer maintains mappings of identifiers and locators. 120 The shim layer is useful in a sense that the IP layer can maintain 121 the mapping of an identifier to the corresponding locators. Under a 122 multihomed environment, typically, a host has more than one IP 123 address at a time. During the transaction, the host may be required 124 to switch the IP address in use to another IP address to preserve the 125 communication. Such an address update should be kept hidden from the 126 upper layer protocols to avoid communication disruption. The shim 127 layer aims to make the address update transparent to the upper layer 128 protocols. 130 In a system which is based on identifier/locator separation, upper 131 layer protocols are expected to deal with identifiers for 132 establishing and handling the communications. If an application 133 wants to have multihoming support from the shim layer, the IP 134 addresses specified as source and destination addresses must be 135 identifiers. However, this does not necessarily mean that 136 applications are prohibited to choose specific locators for its 137 communication. It may be useful for some applications to specify a 138 preferred locator for a given flow. 140 This document recommends that the switching of identifier and locator 141 is done only once inside the TCP/IP stack of an endhost. That is, if 142 multiple shim sub-layers exist at the IP layer, any one of them 143 should be applied exclusively for a given flow. 145 As this document specifies sockets API extensions, it is written so 146 that the syntax and semantics are in line with the Posix standard 147 [POSIX] as much as possible. The API specified in this document 148 defines how to use ancillary data (aka cmsg) to access the locator 149 information with recvmsg() and/or sendmsg() I/O calls. The 150 definition of API is presented in C language and data types follow 151 the Posix format; intN_t means a singed integer of exactly N bits 152 (e.g. int16_t) and uintN_t means an unsigned integer of exactly N 153 bits (e.g. uint32_t). 155 The target readers of this document are application programmers who 156 develop application software which may benefit greatly from 157 multihomed environments. In addition, this document aims to provide 158 necessary information for developers of multihoming shim protocols to 159 implement API for enabling advanced locator management. 161 2. Terminology 163 This section provides terminology used in this document. Basically 164 most of the terms used in this document are taken from the following 165 documents: 167 o SHIM6 Protocol Specification[I-D.ietf-shim6-proto] 168 o HIP Architecture[RFC4423] 169 o Reachability Protocol (REAP)[I-D.ietf-shim6-failure-detection] 171 In this document, the term "IP" refers to both IPv4 and IPv6, unless 172 the protocol version is specifically mentioned. The following are 173 definitions of terms frequently used in this document: 175 o Endpoint identifier (EID) - The identifier used by the application 176 to specify the endpoint of a given communication. Applications 177 may handle EIDs in various ways such as long-lived connections, 178 callbacks, and referrals[I-D.ietf-shim6-app-refer]. 179 * In the case of SHIM6, an identifier called a ULID serves as an 180 EID. A ULID is chosen from locators available on the host. 181 * In the case of HIP, an identifier called a Host Identifier 182 serves as an EID. A Host Identifier is derived from the public 183 key of a given host. For the sake of backward compatibility 184 with the sockets API, the Host Identifier is represented in a 185 form of hash of public key. 186 o Locator - The IP address actually used to deliver IP packets. 187 Locators are present in the source and destination fields of the 188 IP header of a packet on the wire. 189 * List of locators - A list of locators associated with an EID. 190 There are two lists of locators stored in a given context. One 191 is associated with the local EID and the other is associated 192 with the remote EID. As defined in [I-D.ietf-shim6-proto], the 193 list of locators associated with an EID 'A' is denoted as 194 Ls(A). 195 * Preferred locator - The (source/destination) locator currently 196 used to send packets within a given context. As defined in 197 [I-D.ietf-shim6-proto], the preferred locator of a host 'A' is 198 denoted as Lp(A). 199 o Shim - The conceptual sub-layer inside the IP layer which 200 maintains mappings between EIDs and locators. An EID can be 201 associated with more than one locator at a time when the host is 202 multihomed. The term 'shim' does not refer to a specific protocol 203 but refers to the conceptual sub-layer inside the IP layer. 205 o Identifier/locator adaptation - The adaptation performed at the 206 shim layer which may end up re-writing the source and/or 207 destination addresses of an IP packet. In the outbound packet 208 processing, the EID pair is converted to the associated locator 209 pair. In the inbound packet processing, the locator pair is 210 converted to the EID pair. 211 o Context - The state information shared by a given pair of peers, 212 which stores a binding between the EID and associated locators. 213 Contexts are maintained by the shim layer. 214 o Reachability detection - The procedure to check reachability 215 between a given locator pair. 216 o Path - The sequence of routers that an IP packet goes through to 217 reach the destination. 218 o Path exploration - The procedure to explore available paths for a 219 given set of locator pairs. 220 o Outage - The incident that prevents IP packets to flow from the 221 source locator to the destination locator. When there is an 222 outage, it means that there is no reachability between a given 223 locator pair. The outage may be caused by various reasons, such 224 as shortage of network resources, congestion, and human error 225 (faulty operation). 226 o Working address pair - The address pair is considered to be 227 "working" if the packet can safely travel from the source to the 228 destination where the packet contains the first address from the 229 pair as the source address and the second address from the pair as 230 the destination address. If reachability is confirmed in both 231 directions, the address pair is considered to be working bi- 232 directionally. 233 o Reachability protocol (REAP) - The protocol for detecting failure 234 and exploring reachability in a multihomed environment. REAP is 235 defined in [I-D.ietf-shim6-failure-detection]. 237 3. System Overview 239 Figure 1 illustrates the system overview. The shim layer and REAP 240 component exist inside the IP layer. Applications use the sockets 241 API defined in this document to interface with the shim layer and the 242 transport layer for locator management, failure detection, and path 243 exploration. 245 It may also be possible that the shim layer interacts with the 246 transport layer, however, such an interaction is outside the scope of 247 this document. 249 +------------------------+ 250 | Application | 251 +------------------------+ 252 ^ ^ 253 ~~~~~~~~~~~~~|~Socket Interface|~~~~~~~~~~~~~~ 254 | v 255 +-----------|------------------------------+ 256 | | Transport Layer | 257 +-----------|------------------------------+ 258 ^ | 259 +-------------|-----|-------------------------------------+ 260 | v v | 261 | +-----------------------------+ +----------+ | IP 262 | | Shim |<----->| REAP | | Layer 263 | +-----------------------------+ +----------+ | 264 | ^ ^ | 265 +-----------------------|----------------------|----------+ 266 v v 267 +------------------------------------------+ 268 | Link Layer | 269 +------------------------------------------+ 271 Figure 1: System overview 273 4. Requirements 275 The following is a list of requirements from applications: 276 o Locator management. The shim layer selects a pair of locators for 277 sending IP packets within a given context. The selection is made 278 by taking miscellaneous conditions into account such as 279 reachability of the path, application's preference, and 280 characteristics of path. From applications' perspective: 281 * It should be possible to obtain the lists of locators of a 282 given context: Ls(local) and Ls(remote). 283 * It should be possible to obtain the preferred locators of a 284 given context: Lp(local) and Lp(remote). 285 o Notification from applications to the shim layer about the status 286 of the communication. The notification occurs in an event-based 287 manner. Applications and/or upper layer protocols may provide 288 positive feedbacks or negative feedbacks to the shim layer. 289 [NOTE: These feedbacks are mentioned in 290 [I-D.ietf-shim6-failure-detection]]: 291 * Applications and/or upper layer protocols (e.g., TCP) may 292 provide positive feedbacks to the shim layer informing that the 293 communication is going well. 295 * Applications and/or upper layer protocols (e.g., TCP) may 296 provide negative feedbacks to the shim layer informing that the 297 communication status is not satisfactory. TCP may detect a 298 problem when it does not receive any expected ACK message from 299 the peer. Besides, a receipt of an ICMP error message could be 300 a clue for the application to detect problems. The REAP module 301 may be triggered by these negative feedbacks and invoke the 302 path exploration procedure. 303 o Feedback from applications to the shim layer. Applications should 304 be able to inform the shim layer of the timeout values for 305 detecting failures, sending keepalives, and starting the 306 exploration procedure. In particular, applications should be able 307 to suppress keepalives. 308 o Hot-standby. Applications may request the shim layer for the hot- 309 standby capability. This means that, alternative paths are known 310 to be working in advance of a failure detection. In such a case, 311 it is possible for the host to immediately replace the current 312 locator pair with an alternative locator pair. 313 o Eagerness for locator exploration. An application should be able 314 to inform the shim layer of how aggressively it wants the REAP 315 mechanism to perform a path exploration (e.g., by specifying the 316 number of concurrent attempts of discovery of working locator 317 pairs) when an outage occurs on the path between the locator pair 318 in use. 319 o Providing locator information to applications. An application 320 should be able to obtain information about the locator pair which 321 was actually used to send or receive the packet. 322 * For inbound traffic, the application may be interested in the 323 locator pair which was actually used to receive the packet. 324 * For outbound traffic, the application may be interested in the 325 locator pair which was actually used to transmit the packet. 326 In this way, applications may have additional control on the 327 locator management. For example, an application becomes able to 328 verify if its preference for locator is actually applied to the 329 flow or not. 330 o Applications should be able to specify if they want to defer the 331 context setup, or if they want context establishment to be started 332 immediately in the case where there is no available context. A 333 deferred context setup means that the initiation of communication 334 should not be blocked to wait for completion of the context 335 establishment. 336 o Turn on/off shim. An application should be able to request to 337 turn on or turn off the multihoming support by the shim layer: 338 * Apply shim. The application should be able to explicitly 339 request the shim layer to apply multihoming support. 340 * Don't apply shim. The application should be able to request 341 the shim layer not to apply the multihoming support but to 342 apply normal IP processing at the IP layer. 344 o An application should be able to know if the communication is now 345 being served by the shim layer or not. 346 o An application should be able to use a common interface to access 347 an IPv4 locator and an IPv6 locator. 349 5. Socket Options for Multihoming Shim Layer 351 In this section, socket options that are specific to multihomed shim 352 are defined. 354 Table 1 shows a list of the socket options that are specific to the 355 multihoming shim layer. An application may specify these socket 356 options for a given socket either by the getsockopt() system call or 357 by the setsockopt() system call. All of these socket options are 358 defined at level SOL_SHIM. 360 The first column of Table 1 gives the name of the option. The second 361 and third columns indicate whether the option can be handled by the 362 getsockopt() system call and/or by the setsockopt() system call. The 363 fourth column provides a brief description of the socket option. The 364 fifth column shows the type of data structure specified along with 365 the socket option. By default, the data structure type is an 366 integer. 368 +-----------------------------+-----+-----+-----------------+-------+ 369 | optname | get | set | description | dtype | 370 +-----------------------------+-----+-----+-----------------+-------+ 371 | SHIM_ASSOCIATED | o | | Check if the | int | 372 | | | | socket is | | 373 | | | | associated with | | 374 | | | | any shim | | 375 | | | | context or not. | | 376 | SHIM_DONTSHIM | o | o | Request the | int | 377 | | | | shim layer not | | 378 | | | | to apply any | | 379 | | | | multihoming | | 380 | | | | support for the | | 381 | | | | communication. | | 382 | SHIM_HOT_STANDBY | o | o | Request the | int | 383 | | | | shim layer to | | 384 | | | | prepare a | | 385 | | | | hot-standby | | 386 | | | | connection (in | | 387 | | | | addition to the | | 388 | | | | current path). | | 389 | SHIM_LOC_LOCAL_PREF | o | o | Get or set the | *1 | 390 | | | | preferred | | 391 | | | | locator on the | | 392 | | | | local side for | | 393 | | | | the context | | 394 | | | | associated with | | 395 | | | | the socket. | | 396 | SHIM_LOC_PEER_PREF | o | o | Get or set the | *1 | 397 | | | | preferred | | 398 | | | | locator on the | | 399 | | | | remote side for | | 400 | | | | the context | | 401 | | | | associated with | | 402 | | | | the socket. | | 403 | SHIM_LOC_LOCAL_RECV | o | o | Request for the | int | 404 | | | | destination | | 405 | | | | locator of the | | 406 | | | | received IP | | 407 | | | | packet. | | 408 | SHIM_LOC_PEER_RECV | o | o | Request for the | int | 409 | | | | source locator | | 410 | | | | of the received | | 411 | | | | IP packet. | | 412 | SHIM_LOC_LOCAL_SEND | o | o | Request the use | *2 | 413 | | | | of specific | | 414 | | | | locator as | | 415 | | | | source locator | | 416 | | | | of outgoing IP | | 417 | | | | packets. | | 418 | SHIM_LOC_PEER_SEND | o | o | Request the use | *2 | 419 | | | | of specific | | 420 | | | | locator as | | 421 | | | | destination | | 422 | | | | locator of | | 423 | | | | outgoing IP | | 424 | | | | packets. | | 425 | SHIM_LOCLIST_LOCAL | o | o | Get or set the | *3 | 426 | | | | list of | | 427 | | | | locators | | 428 | | | | associated with | | 429 | | | | the local EID. | | 430 | SHIM_LOCLIST_PEER | o | o | Get or set the | *3 | 431 | | | | list of | | 432 | | | | locators | | 433 | | | | associated with | | 434 | | | | the peer's EID. | | 435 | SHIM_APP_TIMEOUT | o | o | Inform the shim | int | 436 | | | | layer of the | | 437 | | | | timeout value | | 438 | | | | for detecting | | 439 | | | | failure. | | 440 | SHIM_PATHEXPLORE | o | o | Specify | *4 | 441 | | | | behavior of | | 442 | | | | path | | 443 | | | | exploration and | | 444 | | | | failure | | 445 | | | | detection. | | 446 | SHIM_CONTEXT_DEFERRED_SETUP | o | o | Specify if the | int | 447 | | | | context setup | | 448 | | | | can be deferred | | 449 | | | | or not. | | 450 +-----------------------------+-----+-----+-----------------+-------+ 452 Table 1: Socket options for multihoming shim 454 *1: Pointer to a shim_locator which is defined in Section 7. 456 *2: Pointer to shim_locator data structure. 458 *3: Pointer to an array of shim_locator. 460 *4: Pointer to a shim_pathexplore which is defined in Section 7. 462 Figure 2 illustrates how the shim specific socket options fit into 463 the system model of socket API. The figure shows that the shim layer 464 and the additional protocol components (IPv4 and IPv6) below the shim 465 layer are new to the system model. As previously mentioned, all the 466 shim specific socket options are defined at SOL_SHIM level. This 467 design choice brings the following advantages: 469 1. The existing sockets API continue to work at the layer above the 470 shim layer. That is, those legacy API handle IP addresses as 471 identifiers. 472 2. With newly defined socket options for the shim layer, the 473 application obtains additional control of locator management. 474 3. The shim specific socket options can be kept independent from 475 address family (IPPROTO_IP or IPPROTO_IPV6) and transport 476 protocol (IPPROTO_TCP or IPPROTO_UDP). 478 s1 s2 s3 s4 479 | | | | 480 +----------------|--|-------|--|----------------+ 481 | +-------+ +-------+ | 482 | IPPROTO_TCP | TCP | | UDP | | 483 | +-------+ +-------+ | 484 | | \ / | | 485 | | ----- | | 486 | | / \ | | 487 | +------+ +------+ | 488 | IPPROTO_IP | IPv4 | | IPv6 | IPPROTO_IPV6 | 489 | +------+ +------+ | 490 | \ / SOL_SOCKET 491 | +--------\-------/--------+ | 492 | SOL_SHIM | shim | | 493 | +--------/-------\--------+ | 494 | / \ | 495 | +------+ +------+ | 496 | | IPv4 | | IPv6 | | 497 | +------+ +------+ | 498 | | | | 499 +------------------|----------|-----------------+ 500 | | 501 IPv4 IPv6 502 Datagram Datagram 504 Figure 2: System model of sockets API with shim layer 506 5.1. SHIM_ASSOCIATED 508 The SHIM_ASSOCIATED option can be used to check whether the socket is 509 associated with any shim context or not. 511 This option is particularly meaningful in the case where the locator 512 information of the received IP packet does not tell whether the 513 identifier/locator adaptation is performed or not. Note that the EID 514 pair and locator pair may be identical in some case. 516 This option can be specified by getsockopt(). Thus, the option is 517 read-only and the result (0 or 1) is set in the option value (the 518 fourth argument of getsockopt()). 520 The data type of the option value is an integer. The option value 521 indicates the presence of shim context. A returned value 1 means 522 that the socket is associated with a shim context at the shim layer, 523 while a return value 0 indicates that there is no shim context 524 associated with the socket. 526 For example, the option can be used by the application as follows: 528 int optval; 529 int optlen = sizeof(optval); 531 getsockopt(fd, SOL_SHIM, SHIM_ASSOCIATED, &optval, &optlen); 533 5.2. SHIM_DONTSHIM 535 The SHIM_DONTSHIM option can be used to request the shim layer to not 536 apply the multihoming support for the communication established over 537 the socket. 539 The data type of the option value is an integer. The option value 540 indicates whether the multihoming shim support is deprecated or not. 541 The option value is binary (0 or 1). By default, the value is set to 542 0, which means that the shim layer applies identifier/locator 543 adaptation for the flow. In order to disable the socket option, the 544 application should call setsockopt() with optval set to 0. 546 For example, the application may disable the socket option as 547 follows: 549 int optval; 551 optval = 0; 553 setsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, sizeof(optval)); 555 For example, the application may check the option value as follows: 557 int optval; 558 int len; 560 len = sizeof(optval); 562 getsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, &len); 564 5.3. SHIM_HOT_STANDBY 566 The SHIM_HOT_STANDBY option can be used to check if the shim layer 567 uses hot-standby connection or not for the communication established 568 over the socket. A hot-standby connection is based on an alternative 569 working locator pair to the current locator pair. This option is 570 effective only when there is a shim context associated with the 571 socket. 573 The data type of the option value is an integer. 575 The option value can be set by setsockopt(). 577 The option value can be read by getsockopt(). 579 By default, the value is set to 0, meaning that hot-standby 580 connection is disabled. 582 For example, the option can be activated by the application as 583 follows. 585 int optval; 587 optval = 1; 589 setsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, 590 sizeof(optval)); 592 For example, the option value can be checked by the application as 593 follows. 595 int optval; 596 int len; 598 len = sizeof(optval); 600 getsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, &len); 602 5.4. SHIM_PATHEXPLORE 604 The application may specify this socket option to specify specify 605 behavior of path exploration. Path exploration is a procedure to 606 find an alternative locator pair when the host finds any problem with 607 the current locator pair. The message used for finding an 608 alternative locator pair is called the Probe message and it is sent 609 per locator pair. The REAP specification defines the default values 610 for Initial Probe Timeout and Initial Probe. 612 The option is effective only when there is a shim context associated 613 with the socket. 615 The data type of the option value is a pointer to the buffer where a 616 set of information for path exploration is stored. The data 617 structure is defined in Section 7. 619 By default, the option value is set to NULL, meaning that the option 620 is disabled. 622 An error ENOENT will be returned when there is no context associated 623 with the socket. 625 For example, the parameters for the path exploration can be set as 626 follows. 628 struct shim6_pathexplore pe; 630 pe.pe_probenum = 4; /* times */ 631 pe.pe_keepaliveto = 10; /* seconds */ 632 pe.pe_initprobeto = 500; /* milliseconds */ 633 pe.pe_reserved = 0; 635 setsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, sizeof(pe)); 637 For example, the parameters for the path exploration can be read as 638 follows. 640 struct shim6_pathexplore pe; 641 int len; 643 len = sizeof(pe); 645 getsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, &len); 647 5.5. SHIM_LOC_LOCAL_PREF 649 The SHIM_LOC_LOCAL_PREF option can be used to read or set preferred 650 locator on local side within a given context. Hence this option is 651 effective only when there is a shim context associated with the 652 socket. 654 The data type of the option value is a pointer to the specific data 655 structure which stores the locator information. The data structure 656 is defined in Section 7. 658 By default, the option value is set to NULL, meaning that the option 659 is disabled. 661 The preferred locator can be set by setsockopt(). Verification of 662 the locator shall be done by the shim layer before updating the 663 preferred locator. 665 The preferred locator can be read by getsockopt(). 667 An error ENOENT will be returned when there is no context associated 668 with the socket. 670 An error EINVALIDLOCATOR will be returned when the validation of the 671 specified locator failed. 673 For example, a preferred locator can be set as follows. It should be 674 noted that some members of the shim_locator (lc_ifidx and lc_flags) 675 are ignored in the write operation. 677 struct shim_locator lc; 678 struct in6_addr ip6; 680 /* ...set the locator (ip6)... */ 682 memset(&lc, 0, sizeof(shim_locator)); 683 lc.lc_family = AF_INET6; /* IPv6 */ 684 lc.lc_ifidx = 0; 685 lc.lc_flags = 0; 686 lc.lc_preference = 255; 687 memcpy(lc.lc_addr, &ip6, sizeof(in6_addr)); 689 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, 690 sizeof(optval)); 692 For example, the preferred locator of the context can be read by 693 application as follows. 695 struct shim_locator lc; 696 int len; 698 len = sizeof(lc); 700 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, &len); 702 5.6. SHIM_LOC_PEER_PREF 704 The SHIM_LOC_PEER_PREF option can be used to read or set preferred 705 locator on peer side within a given context. Hence this option is 706 effective only when there is a shim context associated with the 707 socket. 709 The data type of the option value is a pointer to the specific data 710 structure which stores the locator information. The data structure 711 is defined in Section 7. 713 By default, the option value is set to NULL, meaning that the option 714 is disabled. 716 The preferred locator can be set by setsockopt(). The shim layer 717 shall perform verification of the locator before updating the 718 preferred locator. 720 The preferred locator can be read by getsockopt(). 722 An error ENOENT will be returned when there is no context associated 723 with the socket. 725 An error EINVALIDLOCATOR will be returned when the validation of the 726 specified locator failed. 728 For example, a preferred locator can be set as follows. It should be 729 noted that some members of the shim_locator (lc_ifidx and lc_flags) 730 are ignored in the write operation. 732 The usage of the option is same as that of SHIM_LOC_LOCAL_PREF. 734 5.7. SHIM_LOC_LOCAL_RECV 736 The SHIM_LOC_LOCAL_RECV option can be used to request the shim layer 737 to store the destination locator of the received IP packet in an 738 ancillary data object which can be accessed by recvmsg(). Hence this 739 option is effective only when there is a shim context associated with 740 the socket. 742 The data type of the option value is integer. The option value 743 should be binary (0 or 1). By default, the option value is set to 0, 744 meaning that the option is disabled. 746 The option value can be set by setsockopt(). 748 The option value can be read by getsockopt(). 750 See Section 6 for the procedure to access locator information stored 751 in the ancillary data objects. 753 An error ENOENT will be returned when there is no context associated 754 with the socket. 756 For example, the option can be activated by the application as 757 follows: 759 int optval; 761 optval = 1; 763 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, 764 sizeof(optval)); 766 For example, the option value can be checked by the application as 767 follows: 769 int optval; 770 int len; 772 len = sizeof(optval); 774 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, &len); 776 5.8. SHIM_LOC_PEER_RECV 778 The SHIM_LOC_PEER_RECV option can be used to request the shim layer 779 to store the source locator of the received IP packet in an ancillary 780 data object which can be accessed by recvmsg(). Hence this option is 781 effective only when there is a shim context associated with the 782 socket. 784 The data type of the option value is integer. The option value 785 should be binary (0 or 1). By default, the option value is set to 0, 786 meaning that the option is disabled. 788 The option value can be set by setsockopt(). 790 The option value can be read by getsockopt(). 792 See Section 6 for the procedure to access locator information stored 793 in the ancillary data objects. 795 An error ENOENT will be returned when there is no context associated 796 with the socket. 798 The usage of the option is same as that of SHIM_LOC_LOCAL_RECV 799 option. 801 5.9. SHIM_LOC_LOCAL_SEND 803 The SHIM_LOC_LOCAL_SEND option can be used to request the shim layer 804 to use specific locator for the source locator of IP packets to be 805 sent from the socket. Hence this option is effective only when there 806 is a shim context associated with the socket. 808 The data type of option value is pointer to shim_locator data 809 structure. 811 The local locator can be specified by setsockopt() providing a valid 812 locator which is stored in a shim_locator data structure. When a 813 zero-filled locator is specified, pre-existing setting of local 814 locator is inactivated. 816 The local locator specified can be obtained by getsockopt(). The 817 locator can be obtained from the option value. 819 An error ENOENT will be returned when there is no context associated 820 with the socket. 822 An error EINVALIDLOCATOR when invalid locator is specified. 824 For example, a preferred local locator can be specified as follows. 826 struct shim_locator locator; 827 struct in6_addr ia6; 829 /* an IPv6 address preferred for the source locator is copied 830 to the parameter ia6 */ 832 memset(&locator, 0, sizeof(locator)); 834 /* fill shim_locator data structure */ 835 locator.lc_family = AF_INET6; 836 locator.lc_ifidx = 1; 837 locator.lc_flags = 0; 838 locator.lc_preference = 0; 839 memcpy(&locator.lc_addr, &ia6, sizeof(ia6)); 841 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, 842 sizeof(locator)); 844 For example, a preferred local locator can be read as follows. 846 struct shim_locator locator; 848 memset(&locator, 0, sizeof(locator)); 850 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, 851 sizeof(locator)); 853 /* check locator */ 855 5.10. SHIM_LOC_PEER_SEND 857 The SHIM_LOC_PEER_SEND option can be used to request the shim layer 858 to use specific locator for the destination locator of IP packets to 859 be sent from the socket. Hence this option is effective only when 860 there is a shim context associated with the socket. 862 The data type of the option value is a pointer to shim_locator data 863 structure. 865 The remote locator can be specified by setsockopt() providing a valid 866 locator which is stored in a shim_locator data structure. When a 867 zero-filled locator is specified, pre-existing setting of remote 868 locator is inactivated. 870 The remote locator specified can be obtained by getsockopt(). The 871 locator can be obtained from the option value. 873 An error ENOENT will be returned when there is no context associated 874 with the socket. 876 An error EINVALIDLOCATOR when invalid locator is specified. 878 The usage of the option is as the same as that of SHIM_LOC_LOCAL_SEND 879 option. 881 5.11. SHIM_LOCLIST_LOCAL 883 The SHIM_LOCLIST_LOCAL option can be used to read or set the locator 884 list associated with the local EID of the shim context associated 885 with the socket. Hence this option is effective only when there is a 886 shim context associated with the socket. 888 The data type of the option value is a pointer to the buffer where a 889 locator list is stored. See Section 7 for the data structure for 890 storing the locator information. By default, the option value is set 891 to NULL, meaning that the option is disabled. 893 The locator list can be read by getsockopt(). Note that the size of 894 the buffer pointed by optval argument should be large enough to store 895 an array of locator information. The number of the locator 896 information is not known beforehand. 898 The locator list can be set by setsockopt(). The buffer pointed by 899 optval argument should contain an array of locator list. 901 An error ENOENT will be returned when there is no context associated 902 with the socket. 904 An error EINVALIDLOCATOR will be returned when the validation of the 905 specified locator failed. 907 For example, a list of locators to be associated with the local EID 908 can be specified as follows: 910 struct shim_locator locators[SHIM_MAX_LOCATORS]; 911 struct sockaddr_in *sin; 912 struct sockaddr_in6 *sin6; 914 memset(locators, 0, sizeof(locators)); 916 ... 918 /* obtain local IP addresses from local interfaces */ 920 ... 922 /* first locator (an IPv6 address) */ 923 locators[0].lc_family = AF_INET6; 924 locators[0].lc_ifidx = 0; 925 locators[0].lc_flags = 0; 926 locators[0].lc_preference = 1; 927 memcpy(&locators[0].lc_addr, &sa6->sin6_addr, 928 sizeof(sa6->sin6_addr)); 930 ... 932 /* second locator (an IPv4 address) */ 933 locators[1].lc_family = AF_INET; 934 locators[1].lc_ifidx = 0; 935 locators[1].lc_flags = 0; 936 locators[1].lc_preference = 0; 937 memcpy(&locators[1].lc_addr, &sa->sin_addr, sizeof(sa->sin_addr)); 939 setsockopt(fd, SOL_SHIM, SHIM_LOCLIST_LOCAL, locators, 940 sizeof(locators)); 942 For example, a list of locators that are associated with the local 943 EID can be obtained as follows: 945 struct shim_locator locators[SHIM_MAX_LOCATORS]; 947 memset(locators, 0, sizeof(locators)); 949 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, locators, 950 sizeof(locators)); 952 /* parse locators */ 953 ... 955 5.12. SHIM_LOCLIST_PEER 957 The SHIM_LOCLIST_PEER option can be used to read or set the locator 958 list associated with the peer EID of the shim context associated with 959 the socket. Hence this option is effective only when there is a shim 960 context associated with the socket. 962 The data type of the option value is a pointer to the buffer where a 963 locator list is stored. See Section 7 for the data structure for 964 storing the locator information. By default, the option value is set 965 to NULL, meaning that the option is disabled. 967 The locator list can be read by getsockopt(). Note that the size of 968 the buffer pointed by optval argument should be large enough to store 969 an array of locator information. The number of the locator 970 information is not known beforehand. 972 The locator list can be set by setsockopt(). The buffer pointed by 973 optval argument should contain an array of locator list. 975 An error ENOENT will be returned when there is no context associated 976 with the socket. 978 An error EINVALIDLOCATOR will be returned when the validation of the 979 specified locator failed. 981 The usage of the option is same as that of SHIM_LOCLIST_LOCAL. 983 5.13. SHIM_APP_TIMEOUT 985 The SHIM_APP_TIMEOUT option indicates timeout value for application 986 to detect failure. Hence this option is effective only when there is 987 a shim context associated with the socket. 989 The data type of the option value is an integer. The value indicates 990 the period of timeout in seconds to send a REAP Keepalive message 991 since the last outbound traffic. By default, the option value is set 992 to 0, meaning that the option is disabled. When the option is 993 disabled, the REAP mechanism follows its default value of Send 994 Timeout value as specified in [I-D.ietf-shim6-failure-detection] 996 If the timeout value specified is longer than the Send Timeout 997 configured in the REAP component, the REAP Keepalive message should 998 be suppressed. 1000 An error ENOENT will be returned when there is no context associated 1001 with the socket. 1003 For example, a specific timeout value can be configured by the 1004 application as follows: 1006 int optval; 1008 optval = 15; /* 15 seconds */ 1010 setsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, 1011 sizeof(optval)); 1013 For example, the option value namely the period of timeout can be 1014 checked by the application as follows: 1016 int optval; 1017 int len; 1019 len = sizeof(optval); 1021 getsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, &len); 1023 5.14. SHIM_DEFERRED_CONTEXT_SETUP 1025 The SHIM_DEFERRED_CONTEXT_SETUP option indicates how initiation of 1026 context setup is made in terms of timing (before or after) the 1027 initial communication flow. Deferred context means that the 1028 establishment of context does not put additional delay for an initial 1029 transaction. 1031 The data type for the option value is an integer. The option value 1032 should binary (0 or 1). By default, the value is set to 1, meaning 1033 that the context setup is deferred. In order to disable the option, 1034 the application should call setsockopt() with option value set to 0. 1036 However, it should be noted that deferred context setup may not be 1037 possible in some cases. For instance, an EID may be non-routable 1038 address (e.g., Host Identifier in HIP) and there is no way to 1039 transmit any IP packet unless there is a context providing the 1040 locators. In such a case, a context should be established prior to 1041 the communication. 1043 For example, the option can be disabled by the application as 1044 follows: 1046 int optval; 1048 optval = 0; 1050 setsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, 1051 &optval, sizeof(optval)); 1053 For example, the option value can be checked by the application as 1054 follows: 1056 int optval; 1057 int len; 1059 len = sizeof(optval); 1061 getsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, 1062 &optval, &len); 1064 5.15. Error Handling 1066 If successful, getsockopt() and setsockopt() return 0; otherwise, the 1067 functions return -1 and set errno to indicate error. 1069 The following are new error values defined for some shim specific 1070 socket options indicating that the getsockopt() or setsockopt() 1071 finished incompletely: 1073 EINVALIDLOCATOR 1074 This indicates that at least one of the necessary validations 1075 inside the shim layer for the specified locator has failed. In 1076 case of SHIM6, there are two kinds of verifications required for 1077 security reasons prior to sending an IP packet to the peer's new 1078 locator; one is the return routability (check if the peer is 1079 actually willing to receive data with the specified locator) and 1080 the other one is the verification based on crypto identifier 1081 mechanisms [RFC3972], [I-D.ietf-shim6-hba]. 1083 6. Ancillary Data for Multihoming Shim 1085 In this section, the definition and the usage of the ancillary data 1086 specific to multihoming shim are provided. 1088 As defined in the Posix standard, sendmsg() and recvmsg() input a 1089 msghdr structure as their arguments. These system calls can handle 1090 control information along with data. Figure 3 shows the msghdr 1091 structure which is defined in . The member msg_control 1092 holds a pointer to the buffer where the shim specific ancillary data 1093 objects can be stored in addition to other ancillary data objects. 1095 struct msghdr { 1096 caddr_t msg_name; /* optional address */ 1097 u_int msg_namelen; /* size of address */ 1098 struct iovec *msg_iov; /* scatter/gather array */ 1099 u_int msg_iovlen; /* # elements in msg_iov */ 1100 caddr_t msg_control; /* ancillary data, see below */ 1101 u_int msg_controllen; /* ancillary data buffer len */ 1102 int msg_flags; /* flags on received message */ 1103 }; 1105 Figure 3: msghdr structure 1107 The buffer pointed by the member msg_control of the msghdr structure 1108 may contain locator information which is a single locator and it 1109 should be possible to process them with the existing macros defined 1110 in Posix and [RFC3542]. Each cmsghdr{} should be followed by data 1111 which stores a single locator. 1113 In case of non-connected socket, msg_name member stores the socket 1114 address of the peer which should be considered as an identifier 1115 rather than a locator. The locator of the peer node should be 1116 retrieved by SHIM_LOC_PEER_RECV as specified below. 1118 Table 2 is a list of the shim specific ancillary data which can be 1119 used for recvmsg() or sendmsg(). In any case, SOL_SHIM must be set 1120 as cmsg_level. 1122 +---------------------+-----------+-----------+-----------------+ 1123 | cmsg_type | sendmsg() | recvmsg() | cmsg_data[] | 1124 +---------------------+-----------+-----------+-----------------+ 1125 | SHIM_LOC_LOCAL_RECV | | o | *1 | 1126 | SHIM_LOC_PEER_RECV | | o | *1 | 1127 | SHIM_LOC_LOCAL_SEND | o | | *1 | 1128 | SHIM_LOC_PEER_SEND | o | | *1 | 1129 | SHIM_FEEDBACK | o | | shim_feedback{} | 1130 +---------------------+-----------+-----------+-----------------+ 1132 Table 2: Shim specific ancillary data 1134 *1: cmsg_data[] should include padding (if necessary) and a single 1135 sockaddr_in{}/sockaddr_in6{}. 1137 It should be noted that the above ancillary data can only be handled 1138 by a UDP or a raw socket and not by a TCP socket. This is because 1139 there is no one-to-one mapping between a single send/receive 1140 operation and a TCP segment being transmitted/received. 1142 6.1. Get Locator Information from Incoming Packet 1144 An application can get locator information from the received IP 1145 packet by specifying the shim specific socket options for the socket. 1146 When SHIM_LOC_LOCAL_RECV and/or SHIM_LOC_PEER_RECV socket options are 1147 set, the application can retrieve local and/or remote locator from 1148 the ancillary data. 1150 6.2. Specify Locator Information for Outgoing Packet 1152 An application can specify the locators to be used for transmitting 1153 an IP packet by sendmsg(). When the ancillary data of cmsg_type 1154 SHIM_LOC_LOCAL_SEND and/or SHIM_LOC_PEER_SEND are specified, the 1155 application can explicitly specify the source and/or the destination 1156 locators to be used for the communication over the socket. 1158 In addition, the application can specify the outgoing interface by 1159 SHIM_IF_SEND ancillary data. The ancillary data should contain the 1160 interface identifier of the physical interface over which the 1161 application expects the packet to be transmitted. 1163 Note that the effect is limited to the datagram transmitted by the 1164 sendmsg(). 1166 If the specified locator pair is verified, the shim layer overrides 1167 the locators of the IP packet. 1169 An error EINVALIDLOCATOR will be returned when validation of the 1170 specified locator failed. 1172 6.3. Notification from Application to Multihoming Shim 1174 An application may provide feedbacks to the shim layer about the 1175 communication status. Such feedbacks are particularly useful for the 1176 shim layer in the absence of REAP mechanism to monitor the 1177 reachability status of the currently used locator pair in a given 1178 shim context. 1180 The notification can be made by sendmsg() specifying a new ancillary 1181 data called SHIM_FEEDBACK. The ancillary data can be handled by 1182 specifying SHIM_FEEDBACK option in cmsg_type. 1184 An error ENOENT will be returned when there is no context associated 1185 with the socket. 1187 See Section 7.3 for details of the data structure to be used. Note 1188 that this specification does not specify the exact behavior of the 1189 shim layer when a feedback is given by an application. 1191 7. Data Structures 1193 In this section, data structures specifically defined for the 1194 multihoming shim layer are introduced. These data structures are 1195 either used as a parameter for setsockopt()/getsockopt() (as 1196 mentioned in Section 5) or as a parameter for ancillary data to be 1197 processed by sendmsg()/recvmsg() (as mentioned in Section 6). 1199 7.1. Placeholder for Locator Information 1201 As defined in Section 5, the SHIM_LOC_LOCAL_PREF, SHIM_LOC_PEER_PREF, 1202 SHIM_LOCLIST_LOCAL, and SHIM_LOCLIST_PEER socket options need to 1203 handle one or more locator information. Locator information includes 1204 not only the locator itself but also additional information about the 1205 locator which is useful for locator management. A new data structure 1206 is defined to serve as a placeholder for the locator information. 1208 Figure 4 illustrates the data structure called shim_locator which 1209 stores a locator information. 1211 struct shim_locator { 1212 uint8_t lc_family; /* address family */ 1213 uint8_t lc_ifidx; /* interface index */ 1214 uint8_t lc_flags; /* flags */ 1215 uint8_t lc_preference; /* preference value */ 1216 uint8_t lc_addr[16]; /* address data */ 1217 }; 1219 Figure 4: shim locator structure 1221 lc_family 1222 Address family of the locator (e.g. AF_INET, AF_INET6). It is 1223 required that the parameter contains non-zero value indicating the 1224 exact address family of the locator. 1225 lc_ifidx 1226 Interface index of the network interface to which the locator is 1227 assigned. This field should be valid only in a read 1228 (getsockopt()) operation. 1229 lc_flags 1230 Each bit of the flags represents a specific characteristics of the 1231 locator. Hash Based Address (HBA) is defined as 0x01. 1232 Cryptographically Generated Address (CGA) is defined as 0x02. 1233 lc_preference 1234 Indicates a preference of the locator. The preference is 1235 represented by an integer. 1237 lc_addr 1238 Contains the locator. In the case where a locator whose size is 1239 smaller than 16 bytes, an encoding rule should be provided for 1240 each locator of a given address family. For instance, in case of 1241 AF_INET (IPv4), the locator should be in the format of an IPv4- 1242 mapped IPv6 address as defined in RFC 4291[RFC4291]. 1244 7.2. Path Exploration Parameter 1246 As defined in Section 5, SHIM_PATHEXPLORE allows application to set 1247 or read the parameters for path exploration and failure detection. A 1248 new data structure called shim_pathexplore is defined to store the 1249 necessary parameters. Figure 5 illustrates the data structure. The 1250 data structure can be passed to getsockopt() or setsockopt() as an 1251 argument. 1253 struct shim_pathexplore { 1254 uint8_t pe_probenum; /* # of initial probe */ 1255 uint8_t pe_keepaliveto; /* Keepalive Timeout */ 1256 uint16_t pe_initprobeto; /* Initial Probe Timeout */ 1257 uint32_t pe_reserved; /* reserved */ 1258 }; 1260 Figure 5: path explore structure 1262 pe_probenum 1263 Indicates the number of initial probe messages to be sent. 1264 Default value of this parameter should follow what is specified in 1265 [I-D.ietf-shim6-failure-detection]. 1266 pe_keepaliveto 1267 Indicates timeout value for detecting a failure when the host does 1268 not receive any packets for a certain period of time while there 1269 is outbound traffic. When the timer expires, path exploration 1270 procedure will be carried out by sending a REAP Probe message. 1271 Default value of this parameter should follow what is specified in 1272 [I-D.ietf-shim6-failure-detection]. 1273 pe_initprobeto 1274 Indicates retransmission timer of REAP Probe message in 1275 milliseconds. Note that this timer is applied before exponential 1276 back-off is started. A REAP Probe message for the same locator 1277 pair may be retransmitted. Default value of this parameter should 1278 follow what is specified in [I-D.ietf-shim6-failure-detection]. 1279 pe_reserved 1280 A reserved field for future extension. By default, the field 1281 should be initialized to zero. 1283 7.3. Feedback Information 1285 As mentioned in Section 6.3, applications can inform the shim layer 1286 about the status of unicast reachability of the locator pair 1287 currently in use. The feedback information can be handled by using 1288 ancillary data called SHIM_FEEDBACK. A new data structure named 1289 shim_feedback is illustrated in Figure 6. 1291 struct shim_feedback { 1292 uint8_t fb_direction; /* direction of traffic */ 1293 uint8_t fb_indicator; /* indicator (1-3) */ 1294 uint16_t fb_reserved; /* reserved */ 1295 }; 1297 Figure 6: feedback information structure 1299 direction 1300 Indicates direction of reachability between a locator pair in 1301 question. A value 0 indicates outbound and a value 1 indicates 1302 inbound direction. 1303 indicator 1304 A value indicating the degree of satisfaction of a unidirectional 1305 reachability for a given locator pair. 1306 * 0: Default value. Whenever this value is specified the 1307 feedback information must not be processed by the shim layer. 1308 * 1: Unable to connect. There is no unidirectional reachability 1309 between the locator pair in question. 1310 * 2: Unsatisfactory. The application is not satisfied with the 1311 unidirectional reachability between the locator pair in 1312 question. 1313 * 3: Satisfactory. There is satisfactory unidirectional 1314 reachability between the locator pair in question. 1315 reserved 1316 Reserved field. Must be ignored by the receiver. 1318 8. Implications for Existing Socket API Extensions 1320 Some of the socket options defined in this document are overlapping 1321 with existing sockets API and care should be taken for the usage not 1322 to confuse with the overlapping features. 1324 The socket options for requesting specific locators to be used for a 1325 given transaction (SHIM_LOC_LOCAL_PREF and SHIM_LOC_PEER_PREF) are 1326 semantically similar to the existing sockets API (IPV6_PKTINFO). The 1327 socket options for obtaining the locator information from the 1328 received IP packet (SHIM_LOC_LOCAL_RECV and SHIM_LOC_PEER_RECV) are 1329 semantically similar to the existing sockets API (IP_RECVDSTADDR and 1330 IPV6_PKTINFO). 1332 In IPv4, application can obtain the destination IP address of the 1333 received IP packet (IP_RECVDSTADDR). If the shim layer performs 1334 identifier/locator adaptation for the received packet, the 1335 destination EID should be stored in the ancillary data 1336 (IP_RECVDSTADDR). 1338 In IPv6, [RFC3542] defines that IPV6_PKTINFO can be used to specify 1339 source IPv6 address and the outgoing interface for outgoing packets, 1340 and retrieve destination IPv6 address and receiving interface for 1341 incoming packets. This information is stored in ancillary data being 1342 IPV6_PKTINFO specified as cmsg_type. Existing sockets API should 1343 continue to work above the shim layer, that is, the IP addresses 1344 handled in IPV6_PKTINFO should be EIDs, not the locators. 1346 Baseline is that the above existing sockets API (IP_RECVDSTADDR and 1347 IPV6_PKTINFO) is assumed to work above the multihoming shim layer. 1348 In other words, the IP addresses those socket options deal with are 1349 EIDs rather than locators. 1351 9. Resolving Conflicts with Preference Values 1353 Since the multihoming shim API allows application to specify 1354 preference value for the context which is associated with the socket 1355 instance, there may be a conflict with preference values specified by 1356 different applications. For instance, application A and B may 1357 establish communication over the same EID pair while both 1358 applications have different preference in their choice of local 1359 locator. 1361 SHIM6 supports a notion of context forking in which a context is 1362 split when there is a conflict with preference values specified by 1363 multiple applications. Thus, context forking can simply resolve the 1364 conflicting situation which may be caused by the use of socket 1365 options for multihoming shim layer. 1367 9.1. Implicit Forking 1369 Socket options defined in Section 5 may cause conflicting situation 1370 when the target context is shared by multiple applications. In such 1371 case, socket handler and the multihoming shim layer should react as 1372 follows; socket handler should inform the shim layer that context 1373 forking is required. In SHIM6, when a context is forked, an unique 1374 identifier called Forked Instance Identifier (FII) is assigned to the 1375 newly forked context. The forked context is then exclusively 1376 associated with the socket through which non-default preference value 1377 was specified. The forked context is maintained by the multihoming 1378 shim layer during the lifetime of associated socket instance. When 1379 the socket is closed, the multihoming shim layer SHOULD delete 1380 associated context. In this way, garbage collection can be carried 1381 out to cleanup unused forked contexts. Upon garbage collection, 1382 every forked context SHOULD be checked if there is no socket 1383 (process) associated with the context. If there is none, the forked 1384 context should be deleted. When a forked context is torn down, SHIM6 1385 should notify the peer about the deletion of forked context. 1387 As opposed to socket options, context forking MUST NOT be triggered 1388 by any use of ancillary data that is specific to multihoming shim as 1389 defined in Section 6. 1391 10. Discussion 1393 In this section, open issues are introduced. 1395 10.1. Naming at Socket Layer 1397 The getsockname() and getpeername() system calls are used to obtain 1398 the 'name' of an endpoint which is actually a pair of IP address and 1399 port number assigned to a given socket. getsockname() is used when an 1400 application wants to obtain the local IP address and port number 1401 assigned for a given socket instance. getpeername() is used when an 1402 application obtains the remote IP address and port number. 1404 The above is based on a traditional system model of the sockets API 1405 where an IP address is expected to play both the role of identifier 1406 and the role of locator. 1408 In a system model where a shim layer exists inside the IP layer, both 1409 getsockname() and getpeername() deal with identifiers, namely EIDs. 1410 In this sense, the shim layer serves to (1) hide locators and (2) 1411 provide access to the identifier for the application over the legacy 1412 socket APIs. 1414 10.2. Additional Requirements from Applications 1416 At the moment, it is not certain if following requirements are common 1417 in all the multihomed environments (SHIM6 and HIP). These are mainly 1418 identified during discussions made on SHIM6 WG mailing list. 1419 o The application should be able to set preferences for the 1420 locators, local and remote ones, and also to the preferences of 1421 the local locators that will be passed to the peer. 1423 10.3. Issues of Header Conversion among Different Address Family 1425 The shim layer performs identifier/locator adaptation. Therefore, in 1426 some case, the whole IP header can be replaced with new IP header of 1427 a different address family (e.g. conversion from IPv4 to IPv6 or vice 1428 versa). Hence, there is an issue how to make the conversion with 1429 minimum impact. Note that this issue is common in other protocol 1430 conversion such as SIIT[RFC2765]. 1432 As addressed in SIIT specification, some of the features (IPv6 1433 routing headers, hop-by-hop extension headers, or destination 1434 headers) from IPv6 are not convertible to IPv4. In addition, notion 1435 of source routing is not exactly the same in IPv4 and IPv6. Hence, 1436 there is certain limitation in protocol conversion between IPv4 and 1437 IPv6. 1439 The question is how should the shim layer behave when it is face with 1440 limitation problem of protocol conversion. Should we introduce new 1441 error something like ENOSUITABLELOCATOR ? 1443 10.4. Handling of Unknown Locator Provided by Application 1445 There might be a case where application provides the shim layer new 1446 locator with the SHIM_LOC_*_PREF socket options or SHIM_LOC_*_SEND 1447 ancillary data. Then there is a question how should the shim layer 1448 treat the new locator informed by the application. 1450 In principle, locator information are exchanged by the shim protocol. 1451 However, there might be a case where application acquires information 1452 about the locator and prefers to use it for its communication. 1454 11. Changes 1456 11.1. Changes from version 00 to version 01 1458 The followings are changes from version 00 to version 01: 1459 o Define shim_locator{} data type which is a placeholder for 1460 locator. 1461 o Define shim_pathexplore{} data type in which a set of REAP 1462 parameters are stored. 1463 o Remove descriptions about "stickiness" of socket options. 1464 o Deprecate SHIM_IF_RECV and SHIM_IF_SEND socket options. 1465 o Give default value and how to disable given socket option. 1467 11.2. Changes from version 01 to version 02 1469 The followings are changes from version 01 to version 02: 1470 o Add section describing context forking. 1471 o Rephrase conclusion section. 1472 o Separate normative references from informative references. 1473 o Remove texts from discussion section that are not relevant to the 1474 contents of the document. 1475 o Add section describing change history (this section). 1477 11.3. Changes from version 02 to version 03 1479 The followings are changes from version 02 to version 03: 1480 o Add an Appendix section describing the issue of context forking. 1482 11.4. Changes from version 03 to version 04 1484 The followings are changes from version 03 to version 04: 1485 o Updated reference. 1486 o Correct typo and grammatical errors. 1488 11.5. Changes from version 04 to version 05 1490 The followings are changes from version 04 to version 05: 1491 o Added definition of SHIM_FEEDBACK ancillary data. 1492 o Added an example of code using the SHIM_LOCLIST_LOCAL 1493 o Added SHIM_LOC_LOCAL_SEND and SHIM_LOC_PEER_SEND socket options. 1495 11.6. Changes from version 05 to version 06 1497 The followings are changes from version 04 to version 05: 1498 o Updated references. 1500 11.7. Changes from version 06 to version 07 1502 The followings are changes from version 06 to version 07: 1503 o Resolved editorial issues. 1505 12. IANA Considerations 1507 This document contains no IANA consideration. 1509 13. Security Considerations 1511 This document does not specify any security mechanism for the shim 1512 layer. Fundamentally, the shim layer has a potential to impose 1513 security threats, as it changes the source and/or destination IP 1514 addresses of the IP packet being sent or received. Therefore, the 1515 basic assumption is that the security mechanism defined in each 1516 protocol of the shim layer is strictly applied. 1518 14. Conclusion 1520 In this document, the Application Program Interface (API) for 1521 multihoming shim layer is specified. The sockets API allows 1522 applications to have additional control of the locator management and 1523 interface to the REAP mechanism inside the multihoming shim layer. 1525 Socket options for multihoming shim layer can be used by getsockopt() 1526 and/or setsockopt() system calls. Besides, applications can use some 1527 ancillary data that are specific to multihoming shim layer to get 1528 locator from received packet or to set locator for outgoing packet. 1530 From an architectural point of view, the sockets API provides extends 1531 the existing sockets API framework in the face of ID/Locator 1532 separation. With regard to API that relate to IP address management, 1533 it is assured that existing sockets API continue to work above the 1534 shim layer dealing with identifiers, while multihoming shim API deals 1535 with locators. 1537 15. Acknowledgments 1539 Authors would like to thank Jari Arkko who participated in the 1540 discussion that lead to the first version of this document, and 1541 Tatuya Jinmei who thoroughly reviewed the early version of this draft 1542 and provided detailed comments on sockets API related issues. Thomas 1543 Henderson provided valuable comments especially from HIP 1544 perspectives. 1546 16. References 1548 16.1. Normative References 1550 [I-D.ietf-shim6-failure-detection] 1551 Arkko, J. and I. Beijnum, "Failure Detection and Locator 1552 Pair Exploration Protocol for IPv6 Multihoming", 1553 draft-ietf-shim6-failure-detection-13 (work in progress), 1554 June 2008. 1556 [I-D.ietf-shim6-proto] 1557 Bagnulo, M. and E. Nordmark, "Level 3 multihoming shim 1558 protocol", draft-ietf-shim6-proto-10 (work in progress), 1559 February 2008. 1561 [POSIX] "IEEE Std. 1003.1-2001 Standard for Information Technology 1562 -- Portable Operating System Interface (POSIX). Open group 1563 Technical Standard: Base Specifications, Issue 6, 1564 http://www.opengroup.org/austin", December 2001. 1566 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 1567 "Advanced Sockets Application Program Interface (API) for 1568 IPv6", RFC 3542, May 2003. 1570 [RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol 1571 (HIP) Architecture", RFC 4423, May 2006. 1573 16.2. Informative References 1575 [I-D.ietf-shim6-app-refer] 1576 Nordmark, E., "Shim6 Application Referral Issues", 1577 draft-ietf-shim6-app-refer-00 (work in progress), 1578 July 2005. 1580 [I-D.ietf-shim6-hba] 1581 Bagnulo, M., "Hash Based Addresses (HBA)", 1582 draft-ietf-shim6-hba-05 (work in progress), December 2007. 1584 [RFC2765] Nordmark, E., "Stateless IP/ICMP Translation Algorithm 1585 (SIIT)", RFC 2765, February 2000. 1587 [RFC3972] Aura, T., "Cryptographically Generated Addresses (CGA)", 1588 RFC 3972, March 2005. 1590 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 1591 Architecture", RFC 4291, February 2006. 1593 Appendix A. Context Forking 1595 In this section, an issue concerning context forking and its relation 1596 to the multihoming shim API are discussed. 1598 SHIM6 supports a notion of context forking. A peer may decide to 1599 fork a context for certain reason (e.g. upper layer protocol prefers 1600 to use different locator pair than the one defined in available 1601 context). The procedure of forking context is done similar to the 1602 normal context establishment, performing the 4-way message exchange. 1603 A peer who has decided to fork a context initiates the context 1604 establishment. Hereafter, we call this peer initiator. 1606 Once the forked context is established between the peers, on the 1607 initiator side, it is possible to apply forked context to the packet 1608 flow since the system maintains an association between the forked 1609 context and the socket owned by the application that has requested 1610 the context forking. How this association is maintained is 1611 implementation specific issue. However, on the responder side, there 1612 is a question on how the outbound packet can be multiplexed by the 1613 shim layer. Since there are more than one SHIM6 contexts that match 1614 with the ULID pair of the packet flow. There is a need to 1615 differentiate packet flows not only by the ULID pairs but some other 1616 information and associate a given packet flow with specific context. 1618 Figure 7 gives an example of a scenario where two communicating peers 1619 fork a context. Initially, there has been a single transaction 1620 between the peers, by the application 1 (App1). Accordingly, another 1621 transaction is started, by application 2 (App2). Both of the 1622 transactions are made based the same ULID pair. The first context 1623 pair (Ctx1) is established for the transaction of App1. Given the 1624 requests from App2, the shim layer on Peer 1 decides to fork a 1625 context. Accordingly, a forked context (Ctx2) is established between 1626 the peers, which should be exclusively applied to the transaction of 1627 App2. Ideally, multiplexing and demultiplexing of packet flows that 1628 relate to App1 and App2 should be done as illustrated in Figure 7. 1629 However, as mentioned earlier, the responder needs to multiplex 1630 outbound flows of App1 and App2 somehow. Note that if a context 1631 forking occurs on the initiator side, a context forking needs to 1632 occur also on the responder side. 1634 Peer 1 Peer 2 1635 (initiator) (responder) 1637 +----+ +----+ +----+ +----+ 1638 |App1| |App2| |App1| |App2| 1639 +----+ +----+ +----+ +----+ 1640 |^ |^ ^| ^| 1641 v| v| |v |v 1642 -----S1-------------S2----- -----S1-------------S2----- 1643 || || || || 1644 || || || || 1646 Ctx1 Ctx2 Ctx1 Ctx2 1647 ULID: ULID: ULID: ULID: 1648 Loc: Loc: Loc: Loc: 1649 FII: 0 FII: 100 FII: 0 FII: 100 1651 |^ |^ ^| ^| 1652 || || || || 1653 || || || || 1654 \..............||........................../| || 1655 \.............||.........................../ || 1656 || || 1657 \|........................................./| 1658 \........................................../ 1660 Figure 7: context forking 1662 To overcome the problem mentioned above, there are some solutions. 1664 One viable approach is to let the system implicitly maintain an 1665 association between the socket and the associated context by keeping 1666 the record of inbound packet processing. That is, the system stores 1667 the information about the context on which the inbound packet flow 1668 was demultiplexed. The information comprises the ULID pair and FII 1669 of the context and is stored in the socket instance. Later, the 1670 system can use the information to identify the associated context in 1671 outbound packet processing. This approach should be feasible as far 1672 as there is bi-directional user traffic. 1674 Another viable approach is to extend SHIM6 protocol by adding 1675 capability of exchanging additional information to identify the 1676 packet flow from others which needs to be handled by a newly forked 1677 context. The information exchange can be done during the context 1678 establishment. The initiator appends 5 tuple of the packet flow to 1679 be handled by the newly forked context. Note that the additional 1680 information provided by the 5 tuple are source and destination port 1681 numbers and upper layer protocol. The information is later used by 1682 the shim layer to multiplex the outbound packet flow on the responder 1683 side. 1685 The socket options for multihoming shim can be used by the 1686 application to trigger the context forking in implicit manner. The 1687 peer becomes an initiator in the establishment of the forked context. 1688 Once the forked context is established between the peers, application 1689 on each end can influence the preference on context by utilizing the 1690 multihoming shim API. 1692 Authors' Addresses 1694 Miika Komu 1695 Helsinki Institute for Information Technology 1696 Tammasaarenkatu 3 1697 Helsinki 1698 Finland 1700 Phone: +358503841531 1701 Fax: +35896949768 1702 Email: miika@iki.fi 1703 URI: http://www.hiit.fi/ 1705 Marcelo Bagnulo 1706 Universidad Carlos III de Madrid 1707 Av. Universidad 30 1708 Leganes 28911 1709 SPAIN 1711 Phone: +34 91 6248837 1712 Email: marcelo@it.uc3m.es 1713 URI: http://it.uc3m.es/marcelo 1715 Kristian Slavov 1716 Ericsson Research Nomadiclab 1717 Hirsalantie 11 1718 Jorvas FI-02420 1719 Finland 1721 Phone: +358 9 299 3286 1722 Email: kristian.slavov@ericsson.com 1723 Shinta Sugimoto (editor) 1724 Nippon Ericsson K.K. 1725 Koraku Mori Building 1726 1-4-14, Koraku, Bunkyo-ku 1727 Tokyo 112-0004 1728 Japan 1730 Phone: +81 3 3830 2241 1731 Email: shinta.sugimoto@ericsson.com 1733 Full Copyright Statement 1735 Copyright (C) The IETF Trust (2008). 1737 This document is subject to the rights, licenses and restrictions 1738 contained in BCP 78, and except as set forth therein, the authors 1739 retain all their rights. 1741 This document and the information contained herein are provided on an 1742 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1743 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1744 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1745 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1746 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1747 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1749 Intellectual Property 1751 The IETF takes no position regarding the validity or scope of any 1752 Intellectual Property Rights or other rights that might be claimed to 1753 pertain to the implementation or use of the technology described in 1754 this document or the extent to which any license under such rights 1755 might or might not be available; nor does it represent that it has 1756 made any independent effort to identify any such rights. Information 1757 on the procedures with respect to rights in RFC documents can be 1758 found in BCP 78 and BCP 79. 1760 Copies of IPR disclosures made to the IETF Secretariat and any 1761 assurances of licenses to be made available, or the result of an 1762 attempt made to obtain a general license or permission for the use of 1763 such proprietary rights by implementers or users of this 1764 specification can be obtained from the IETF on-line IPR repository at 1765 http://www.ietf.org/ipr. 1767 The IETF invites any interested party to bring to its attention any 1768 copyrights, patents or patent applications, or other proprietary 1769 rights that may cover technology that may be required to implement 1770 this standard. Please address the information to the IETF at 1771 ietf-ipr@ietf.org.