idnits 2.17.1 draft-ietf-shim6-multihome-shim-api-05.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 1725. -- Found old boilerplate from RFC 3979, Section 5, paragraph 1 on line 1736. -- Found old boilerplate from RFC 3979, Section 5, paragraph 2 on line 1743. -- Found old boilerplate from RFC 3979, Section 5, paragraph 3 on line 1749. 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 1372: '...e multihoming shim layer SHOULD delete...' RFC 2119 keyword, line 1375: '...y forked context SHOULD be checked if ...' RFC 2119 keyword, line 1380: '... context forking MUST NOT be triggered...' Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust Copyright Line does not match the current year == Line 1091 has weird spacing: '... u_int msg_...' == Line 1092 has weird spacing: '... struct iovec...' == Line 1093 has weird spacing: '... u_int msg_...' == Line 1095 has weird spacing: '... u_int msg_...' -- The document seems to lack a disclaimer for pre-RFC5378 work, but may have content which was first submitted before 10 November 2008. If you have contacted all the original authors and they are all willing to grant the BCP78 rights to the IETF Trust, then this is fine, and you can ignore this comment. If not, you may need to add the pre-RFC5378 disclaimer. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 23, 2008) is 5906 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 922 -- Looks like a reference, but probably isn't: '1' on line 932 -- Looks like a reference, but probably isn't: '16' on line 1210 == Outdated reference: A later version (-13) exists of draft-ietf-shim6-failure-detection-10 == Outdated reference: A later version (-12) exists of draft-ietf-shim6-proto-09 ** Obsolete normative reference: RFC 4423 (Obsoleted by RFC 9063) -- Obsolete informational reference (is this intentional?): RFC 2765 (Obsoleted by RFC 6145) Summary: 3 errors (**), 0 flaws (~~), 7 warnings (==), 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: August 26, 2008 UC3M 6 K. Slavov 7 S. Sugimoto, Ed. 8 Ericsson 9 February 23, 2008 11 Socket Application Program Interface (API) for Multihoming Shim 12 draft-ietf-shim6-multihome-shim-api-05 14 Status of this Memo 16 By submitting this Internet-Draft, each author represents that any 17 applicable patent or other IPR claims of which he or she is aware 18 have been or will be disclosed, and any of which he or she becomes 19 aware will be disclosed, in accordance with Section 6 of BCP 79. 21 Internet-Drafts are working documents of the Internet Engineering 22 Task Force (IETF), its areas, and its working groups. Note that 23 other groups may also distribute working documents as Internet- 24 Drafts. 26 Internet-Drafts are draft documents valid for a maximum of six months 27 and may be updated, replaced, or obsoleted by other documents at any 28 time. It is inappropriate to use Internet-Drafts as reference 29 material or to cite them other than as "work in progress." 31 The list of current Internet-Drafts can be accessed at 32 http://www.ietf.org/ietf/1id-abstracts.txt. 34 The list of Internet-Draft Shadow Directories can be accessed at 35 http://www.ietf.org/shadow.html. 37 This Internet-Draft will expire on August 26, 2008. 39 Copyright Notice 41 Copyright (C) The IETF Trust (2008). 43 Abstract 45 This document specifies a socket API for the multihoming shim layer. 46 The API aims to enable interactions between the applications and the 47 multihoming shim layer for advanced locator management and access to 48 information about failure detection and path exploration. 50 This document is based on an assumption that a multihomed host is 51 equipped with a conceptual sublayer (here after "shim") inside the IP 52 layer that maintains mappings between identifiers and locators. 53 Examples of the shim are SHIM6 and HIP. 55 Table of Contents 57 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 58 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 59 3. System Overview . . . . . . . . . . . . . . . . . . . . . . . 6 60 4. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 7 61 5. Socket Options for Multihoming Shim Layer . . . . . . . . . . 9 62 5.1. SHIM_ASSOCIATED . . . . . . . . . . . . . . . . . . . . . 12 63 5.2. SHIM_DONTSHIM . . . . . . . . . . . . . . . . . . . . . . 13 64 5.3. SHIM_HOT_STANDBY . . . . . . . . . . . . . . . . . . . . . 13 65 5.4. SHIM_PATHEXPLORE . . . . . . . . . . . . . . . . . . . . . 14 66 5.5. SHIM_LOC_LOCAL_PREF . . . . . . . . . . . . . . . . . . . 15 67 5.6. SHIM_LOC_PEER_PREF . . . . . . . . . . . . . . . . . . . . 16 68 5.7. SHIM_LOC_LOCAL_RECV . . . . . . . . . . . . . . . . . . . 17 69 5.8. SHIM_LOC_PEER_RECV . . . . . . . . . . . . . . . . . . . . 18 70 5.9. SHIM_LOC_LOCAL_SEND . . . . . . . . . . . . . . . . . . . 18 71 5.10. SHIM_LOC_PEER_SEND . . . . . . . . . . . . . . . . . . . . 19 72 5.11. SHIM_LOCLIST_LOCAL . . . . . . . . . . . . . . . . . . . . 20 73 5.12. SHIM_LOCLIST_PEER . . . . . . . . . . . . . . . . . . . . 22 74 5.13. SHIM_APP_TIMEOUT . . . . . . . . . . . . . . . . . . . . . 22 75 5.14. SHIM_DEFERRED_CONTEXT_SETUP . . . . . . . . . . . . . . . 23 76 5.15. Error Handling . . . . . . . . . . . . . . . . . . . . . . 24 77 6. Ancillary Data for Multihoming Shim . . . . . . . . . . . . . 24 78 6.1. Get Locator Information from Incoming Packet . . . . . . . 26 79 6.2. Specify Locator Information for Outgoing Packet . . . . . 26 80 6.3. Notification from Application to Multihoming Shim . . . . 26 81 7. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 27 82 7.1. Placeholder for Locator Information . . . . . . . . . . . 27 83 7.2. Path Exploration Parameter . . . . . . . . . . . . . . . . 28 84 7.3. Feedback Information . . . . . . . . . . . . . . . . . . . 29 85 8. Implications for Existing Socket API Extensions . . . . . . . 29 86 9. Resolving Conflicts with Preference Values . . . . . . . . . . 30 87 9.1. Implicit Forking . . . . . . . . . . . . . . . . . . . . . 30 88 10. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 31 89 10.1. Naming at Socket Layer . . . . . . . . . . . . . . . . . . 31 90 10.2. Additional Requirements from Application . . . . . . . . . 31 91 10.3. Issues of Header Conversion among Different Address 92 Family . . . . . . . . . . . . . . . . . . . . . . . . . . 32 93 10.4. Handling of Unknown Locator Provided by Application . . . 32 94 11. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 95 11.1. Changes from version 00 to version 01 . . . . . . . . . . 32 96 11.2. Changes from version 01 to version 02 . . . . . . . . . . 33 97 11.3. Changes from version 02 to version 03 . . . . . . . . . . 33 98 11.4. Changes from version 03 to version 04 . . . . . . . . . . 33 99 11.5. Changes from version 04 to version 05 . . . . . . . . . . 33 100 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 101 13. Security Considerations . . . . . . . . . . . . . . . . . . . 33 102 14. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . 33 103 15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 34 104 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 105 16.1. Normative References . . . . . . . . . . . . . . . . . . . 34 106 16.2. Informative References . . . . . . . . . . . . . . . . . . 35 107 Appendix A. Context Forking . . . . . . . . . . . . . . . . . . . 35 108 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 37 109 Intellectual Property and Copyright Statements . . . . . . . . . . 39 111 1. Introduction 113 HIP and SHIM6 have a commonality in their protocol design separation 114 of identifier and locator (hereafter identifier/locator separation). 115 Both protocols aim to solve problems that are specific to multihoming 116 environment in a host centric approach. In these protocols, a sub- 117 layer within the IP layer maintains mappings of identifiers and 118 locators. 120 The shim layer is useful in a sense that the IP layer can maintain 121 the mapping of an identifier to corresponding locators. Under a 122 multihomed environment, typically, a host has more than one IP 123 address at a time. During a given transaction, a host may be 124 required to switch the IP address used for the communication to 125 another IP address to preserve the communication. The protocol stack 126 should take care of isolating the upper layer from disruption by the 127 address update. The shim layer can make this locator update 128 transparent to the upper layer 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 a multihoming support by 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 in its 137 communication. It may be useful for applications, in some situation, 138 to specify a preferred locator for the flow. 140 This document recommends that the identifier/locator adaptation is 141 done only once inside the network stack of a host. That is, if 142 multiple shim sublayers exist at the IP layer, any one of them should 143 be applied exclusively for a given flow. 145 As this document specifies socket API, it is written so that the 146 contents are in line with Posix standard [POSIX] as much as possible. 147 The API specified in this document defines how to use ancillary data 148 (aka cmsg) to access locator information with recvmsg() and/or 149 sendmsg() I/O calls. Definition of API is presented in C language 150 and data types follow Posix format; intN_t means a singed integer of 151 exactly N bits (e.g. int16_t) and uintN_t means an unsigned integer 152 of exactly N bits (e.g. uint32_t). 154 The target readers of this document are application programmers who 155 develop application software which may benefit greatly from 156 multihomed environment. In addition, this document should be of 157 interest for the developers of a given shim protocol, as the shim 158 layer should provide the interface to the application. 160 2. Terminology 162 This section provides terminology used in this document. Basically 163 most of the terms used in this document are taken from the following 164 documents: 166 o SHIM6 Protocol Specification[I-D.ietf-shim6-proto] 167 o HIP Architecture[RFC4423] 168 o Reachability Protocol (REAP)[I-D.ietf-shim6-failure-detection] 170 In this document, the term "IP" refers to both IPv4 and IPv6, unless 171 the protocol version is specifically mentioned. The followings are 172 definitions of the terms that are frequently used in this document: 174 o Endpoint Identifier (EID) - An identifier used by the application 175 to specify the endpoint of a given communication. Applications 176 may handle EID in various ways such as long-lived connections, 177 callbacks, and referrals[I-D.ietf-shim6-app-refer]. 178 * In the case of SHIM6, an identifier called an ULID serves as an 179 EID. An ULID is chosen from locators available on the host. 180 * In the case of HIP, an identifier which specifies communication 181 endpoints is derived from the public key of the host, which is 182 called a Host Identifier. For the sake of backward 183 compatibility of the socket API, the Host Identifier is 184 represented in a form of hash of public key. 185 o Locator - An IP address actually used to deliver IP packets. 186 Locators should be present in the source and destination fields of 187 the IP header of a packet on the wire. 188 * List of Locators - A list of locators associated with an EID. 189 There are two lists of locators stored in a given context, one 190 is associated with the local EID and the other is associated 191 with the remote EID. As defined in [I-D.ietf-shim6-proto], the 192 list of locators associated with an EID 'A' can be denoted as 193 Ls(A). 194 * Preferred Locator - The (source/destination) locator currently 195 used to send packets within a given context. As defined in 196 [I-D.ietf-shim6-proto], the preferred locator of a host 'A' is 197 denoted as Lp(A). 198 o Shim - A conceptual (sub-)layer inside the IP Layer which 199 maintains mappings of EIDs and locators. An EID can be associated 200 with more than one locators at a time when the host is multihomed. 201 The term 'shim' does not refer to a specific protocol but refers 202 to the conceptual sublayer inside the IP layer. 203 o identifier/locator adaptation - An adaptation performed at the 204 shim layer between EIDs and locators within a given context. The 205 adaptation may end up re-writing the source and destination 206 addresses of the IP packet. In the outbound packet processing, 207 the EID pair is converted to the associated locator pair, while 208 the locator pair is converted to the EID pair in the inbound 209 packet processing. 210 o Context - State information shared by a given pair of peers, which 211 stores a binding between the EIDs and associated locators. The 212 context is maintained at the shim layer. 213 o Reachability Detection - A procedure to check reachability between 214 a given locator pair. 215 o Path - A sequence of routers that an IP packet goes through to 216 reach the destination. 217 o Path Exploration - A procedure to explore available paths for a 218 given set of locator pairs. 219 o Outage - An incident that prevents IP packets to flow from the 220 source locator to the destination locator. When there is an 221 outage, it means that there is no reachability between a given 222 locator pair. The outage can be caused by various reasons, such 223 as shortage of network resources, congestion, and human error 224 (faulty operation). 225 o Working Address Pair - An address pair is said to be working if 226 the packet containing the first address from the pair as source 227 address and the second address from the pair as destination 228 address can safely travel from the source to the destination. If 229 the reachability is confirmed in both directions, the address 230 pairs is said to be bi-directional. Otherwise, it's 231 unidirectional. 232 o Reachability Protocol (REAP) - A protocol for detecting failure 233 and exploring reachability in a multihomed environment. REAP is 234 defined in [I-D.ietf-shim6-failure-detection]. 236 3. System Overview 238 Figure 1 illustrates the system overview. The shim layer and REAP 239 component exist inside the IP layer. Applications can use the socket 240 API defined in this document to interface the shim layer and 241 transport layer for locator management and failure detection and path 242 exploration. 244 It is also possible that the shim layer interacts with transport 245 layers, but the interactions are outside the scope of this document. 247 +------------------------+ 248 | Application | 249 +------------------------+ 250 ^ ^ 251 ~~~~~~~~~~~~~|~Socket Interface|~~~~~~~~~~~~~~ 252 | v 253 +-----------|------------------------------+ 254 | | Transport Layer | 255 +-----------|------------------------------+ 256 ^ | 257 +-------------|-----|-------------------------------------+ 258 | v v | 259 | +-----------------------------+ +----------+ | IP 260 | | Shim |<----->| REAP | | Layer 261 | +-----------------------------+ +----------+ | 262 | ^ ^ | 263 +-----------------------|----------------------|----------+ 264 v v 265 +------------------------------------------+ 266 | Link Layer | 267 +------------------------------------------+ 269 Figure 1: System overview 271 4. Requirements 273 The following is the list of requirements from the application 274 perspective: 275 o Locator management. The shim layer selects a pair of locators for 276 sending IP packets within a given context. The selection is made 277 by taking miscellaneous conditions into account such as 278 reachability of the path, application's preference, and 279 characteristics of path. From the application's perspective: 280 * It should be possible to obtain the lists of locators of a 281 given context: Ls(local) and Ls(remote). 282 * It should be possible to obtain the preferred locators of a 283 given context: Lp(local) and Lp(remote). 284 o Notification from the application to the shim layer about the 285 status of the communication. Note that the notification is made 286 in an event based manner. There are mainly two aspects of the 287 feedback that application or upper layer protocol may provide for 288 the shim layer, positive and negative feedbacks [NOTE: These 289 feedbacks are mentioned in [I-D.ietf-shim6-failure-detection]]: 290 * Positive feedback could be given by the application or upper 291 layer protocol (e.g. TCP) to the shim layer informing that the 292 communication is going well. 294 * Negative feedback could be given by the application or upper 295 layer protocol (e.g. TCP) to the shim layer informing that the 296 communication status is not satisfactory. TCP could detect a 297 problem when it does not receive expected ACK from the peer. 298 ICMP error messages delivered to the upper layer protocol could 299 be a clue for application to detect potential problems. REAP 300 module may be triggered by these negative feedbacks and invoke 301 procedure of path exploration. 302 o Feedback from application to shim layer. The application should 303 be able to inform the shim layer of the timeout values for 304 detecting failures, for sending keepalives, for starting the 305 exploration procedure. In particular, the application should be 306 able to suppress the keepalives. 307 o Hot-standby. The application may request the shim layer for hot- 308 standby capabilities. In this case, alternative paths are known 309 to be working before a failure is detected. Hence it is possible 310 for the host to immediately replace the current locator pair with 311 an alternative locator pair. Hot-standby may allow applications 312 to achieve better failover. 313 o Eagerness of locator exploration. The application should be able 314 to inform the shim layer how aggressive it wants REAP mechanism to 315 perform path exploration (e.g. specifying the number of concurrent 316 attempts of discovering working locator pair) when an outage 317 occurs on the path between the currently selected locator pair. 318 o Providing locator information to application. The application 319 should be able to obtain information about the locator pair which 320 was actually used to send or receive the packet. 321 * For inbound traffic, the application may be interested in the 322 locator pair which was actually used to receive the packet. 323 * For outbound traffic, the application may be interested in the 324 locator pair which was actually used to transmit the packet. 325 In this way, the application may have additional control on the 326 locator management. For example, the application can verify if 327 its preference of locator is actually applied to the flow or not. 328 o The application should be able to specify if it wants to defer the 329 context setup or if it wants context establishment to be started 330 immediately in case there is no available context. With deferred 331 context setup, there should be no additional delay imposed by 332 context establishment in initiation of communication. 333 o Turn on/off shim. The application should be able to request to 334 turn on/off the multihoming support by the shim layer: 335 * Apply shim. The application should be able to explicitly 336 request the shim layer to apply multihoming support. 337 * Don't apply shim. The application should be able to request 338 the shim layer not to apply the multihoming support but to 339 apply normal IP processing at the IP layer. 341 o The application should be able to know if the communication is now 342 served by the shim layer or not. 343 o The application should be able to access locator information 344 regardless of its address family. In other words, no matter 345 whether the target locator is IPv4 or IPv6, the application should 346 be able to use common interface to access the locator information. 348 5. Socket Options for Multihoming Shim Layer 350 In this section, socket options that are specific to multihomed shim 351 are defined. 353 Table 1 provides a list of the socket options that are specific to 354 multihoming shim layer. These socket options can be used by either 355 getsockopt() or setsockopt() system call for a given socket. All of 356 these socket options are defined at level SOL_SHIM. 358 The first column of Table 1 gives the name of the option. The second 359 and third columns indicate whether the option can be handled by 360 getsockopt() and/or setsockopt(), respectively. The fourth column 361 provides a brief description of the socket option. The fifth column 362 shows the type of data structure specified along with the socket 363 option. By default, the data structure type is an integer. 365 +-----------------------------+-----+-----+-----------------+-------+ 366 | optname | get | set | description | dtype | 367 +-----------------------------+-----+-----+-----------------+-------+ 368 | SHIM_ASSOCIATED | o | | Check if the | int | 369 | | | | socket is | | 370 | | | | associated with | | 371 | | | | any shim | | 372 | | | | context or not. | | 373 | SHIM_DONTSHIM | o | o | Request the | int | 374 | | | | shim layer not | | 375 | | | | to apply any | | 376 | | | | multihoming | | 377 | | | | support for the | | 378 | | | | communication. | | 379 | SHIM_HOT_STANDBY | o | o | Request the | int | 380 | | | | shim layer to | | 381 | | | | prepare a | | 382 | | | | hot-standby | | 383 | | | | connection (in | | 384 | | | | addition to the | | 385 | | | | current path). | | 386 | SHIM_LOC_LOCAL_PREF | o | o | Get or set the | *1 | 387 | | | | preferred | | 388 | | | | locator on the | | 389 | | | | local side for | | 390 | | | | the context | | 391 | | | | associated with | | 392 | | | | the socket. | | 393 | SHIM_LOC_PEER_PREF | o | o | Get or set the | *1 | 394 | | | | preferred | | 395 | | | | locator on the | | 396 | | | | remote side for | | 397 | | | | the context | | 398 | | | | associated with | | 399 | | | | the socket. | | 400 | SHIM_LOC_LOCAL_RECV | o | o | Request for the | int | 401 | | | | destination | | 402 | | | | locator of the | | 403 | | | | received IP | | 404 | | | | packet. | | 405 | SHIM_LOC_PEER_RECV | o | o | Request for the | int | 406 | | | | source locator | | 407 | | | | of the received | | 408 | | | | IP packet. | | 409 | SHIM_LOC_LOCAL_SEND | o | o | Request use of | *2 | 410 | | | | specific | | 411 | | | | locator as | | 412 | | | | source locator | | 413 | | | | of outgoing IP | | 414 | | | | packets. | | 415 | SHIM_LOC_PEER_SEND | o | o | Request use of | *2 | 416 | | | | specific | | 417 | | | | locator as | | 418 | | | | destination | | 419 | | | | locator of | | 420 | | | | outgoing IP | | 421 | | | | packets. | | 422 | SHIM_LOCLIST_LOCAL | o | o | Get or set a | *3 | 423 | | | | list of | | 424 | | | | locators | | 425 | | | | associated with | | 426 | | | | the local EID. | | 427 | SHIM_LOCLIST_PEER | o | o | Get or set a | *3 | 428 | | | | list of | | 429 | | | | locators | | 430 | | | | associated with | | 431 | | | | the peer's EID. | | 432 | SHIM_APP_TIMEOUT | o | o | Inform the shim | int | 433 | | | | layer of a | | 434 | | | | timeout value | | 435 | | | | for detecting | | 436 | | | | failure. | | 437 | SHIM_PATHEXPLORE | o | o | Specify | *4 | 438 | | | | behavior of | | 439 | | | | path | | 440 | | | | exploration and | | 441 | | | | failure | | 442 | | | | detection. | | 443 | SHIM_CONTEXT_DEFERRED_SETUP | o | o | Specify if the | int | 444 | | | | context setup | | 445 | | | | can be deferred | | 446 | | | | or not. | | 447 +-----------------------------+-----+-----+-----------------+-------+ 449 Table 1: Socket options for multihoming shim 451 *1: Pointer to a shim_locator which is defined in Section 7. 453 *2: Pointer to shim_locator data structure. 455 *3: Pointer to an array of shim_locator. 457 *4: Pointer to a shim_pathexplore which is defined in Section 7. 459 Figure 2 illustrates how the shim specific socket options fit into 460 the system model of socket API. In the figure, it can be seen that 461 the shim layer and the additional protocol components (IPv4 and IPv6) 462 below the shim layer are new to the system model. As previously 463 mentioned, all the shim specific socket options are defined at 464 SOL_SHIM level. This design choice brings the following advantages: 466 1. It is assured that the existing socket API continue to work at 467 the layer above the shim layer. That is, those legacy API deal 468 with 'identifier' aspect of the IP addresses. 469 2. With newly defined socket options for the shim layer, the 470 application obtains additional control on locator management. 471 3. The shim specific socket options are not specific to any address 472 family (IPPROTO_IP or IPPROTO_IPV6) or any transport protocol 473 (IPPROTO_TCP or IPPROTO_UDP). 475 s1 s2 s3 s4 476 | | | | 477 +----------------|--|-------|--|----------------+ 478 | +-------+ +-------+ | 479 | IPPROTO_TCP | TCP | | UDP | | 480 | +-------+ +-------+ | 481 | | \ / | | 482 | | ----- | | 483 | | / \ | | 484 | +------+ +------+ | 485 | IPPROTO_IP | IPv4 | | IPv6 | IPPROTO_IPV6 | 486 | +------+ +------+ | 487 | \ / SOL_SOCKET 488 | +--------\-------/--------+ | 489 | SOL_SHIM | shim | | 490 | +--------/-------\--------+ | 491 | / \ | 492 | +------+ +------+ | 493 | | IPv4 | | IPv6 | | 494 | +------+ +------+ | 495 | | | | 496 +------------------|----------|-----------------+ 497 | | 498 IPv4 IPv6 499 Datagram Datagram 501 Figure 2: System model of socket API with shim layer 503 5.1. SHIM_ASSOCIATED 505 The SHIM_ASSOCIATED option can be used to check whether the socket is 506 associated with any shim context or not. 508 This option is particularly meaningful in a case where the locator 509 information of the received IP packet does not tell whether the 510 identifier/locator adaptation is performed or not. Note that the EID 511 pair and locator pair may be identical in some case. 513 This option can be specified by getsockopt(). Thus, the option is 514 read-only and the result (0 or 1) is set in the option value (the 515 fourth argument of getsockopt()). 517 Data type of the option value is integer. The option value indicates 518 presence of shim context. A returned value 1 means that the socket 519 is associated with a certain shim context at the shim layer, while a 520 return value 0 indicates that there is no context associated with the 521 socket. 523 For example, the option can be used by the application as follows: 525 int optval; 526 int optlen = sizeof(optval); 528 getsockopt(fd, SOL_SHIM, SHIM_ASSOCIATED, &optval, &optlen); 530 5.2. SHIM_DONTSHIM 532 The SHIM_DONTSHIM option can be used to request the shim layer to not 533 apply the multihoming support for the communication established over 534 the socket. 536 Data type of the option value is integer. The option value indicates 537 whether the multihoming shim support is deprecated or not. The 538 option value is binary (0 or 1). By default, the value is set to 0, 539 meaning that the shim layer applies identifier/locator adaptation for 540 the communication. In order to disable the socket option, the 541 application should call setsockopt() with optval set as 0. 543 For example, the option can be disabled by the application as 544 follows. 546 int optval; 548 optval = 0; 550 setsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, sizeof(optval)); 552 For example, the option value can be checked by the application as 553 follows. 555 int optval; 556 int len; 558 len = sizeof(optval); 560 getsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, &len); 562 5.3. SHIM_HOT_STANDBY 564 The SHIM_HOT_STANDBY option can be used to check if the shim layer 565 uses hot-standby connection or not for the communication established 566 over the socket. Hot-standby connection is another working locator 567 pair than the current locator pair. Hence this option is effective 568 only when there is a shim context associated with the socket. 570 Data type of the option value is integer. 572 The option value can be set by setsockopt(). 574 The option value can be read by getsockopt(). 576 By default, the value is set to 0, meaning that hot-standby 577 connection is disabled. 579 For example, the option can be activated by the application as 580 follows. 582 int optval; 584 optval = 1; 586 setsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, 587 sizeof(optval)); 589 For example, the option value can be checked by the application as 590 follows. 592 int optval; 593 int len; 595 len = sizeof(optval); 597 getsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, &len); 599 5.4. SHIM_PATHEXPLORE 601 This option can be used to specify behavior of path exploration to be 602 carried out. Path exploration is a procedure to find an alternative 603 locator pair when the host finds any problem with current locator 604 pair. A message used for finding an alternative locator pair is 605 called a Probe message and it is sent per locator pair. Default 606 value is defined for Initial Probe Timeout (0.5 seconds) and Initial 607 Probe (4 times) in the REAP specification. 609 The option is effective only when there is a shim context associated 610 with the socket. 612 Data type of the option value is a pointer to the buffer where a set 613 of information for path exploration is stored. The data structure is 614 defined in Section 7. 616 By default, the option value is set as NULL, meaning that the option 617 is disabled. 619 An error ENOENT will be returned when there is no context associated 620 with the socket. 622 For example, the parameters for the path exploration can be set as 623 follows. 625 struct shim6_pathexplore pe; 627 pe.pe_probenum = 4; /* times */ 628 pe.pe_keepaliveto = 10; /* seconds */ 629 pe.pe_initprobeto = 500; /* milliseconds */ 630 pe.pe_reserved = 0; 632 setsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, sizeof(pe)); 634 For example, the parameters for the path exploration can be read as 635 follows. 637 struct shim6_pathexplore pe; 638 int len; 640 len = sizeof(pe); 642 getsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, &len); 644 5.5. SHIM_LOC_LOCAL_PREF 646 The SHIM_LOC_LOCAL_PREF option can be used to read or set preferred 647 locator on local side within a given context. Hence this option is 648 effective only when there is a shim context associated with the 649 socket. 651 Data type of the option value is a pointer to the specific data 652 structure which stores the locator information. The data structure 653 is defined in Section 7. 655 By default, the option value is set as NULL, meaning that the option 656 is disabled. 658 The preferred locator can be set by setsockopt(). Verification of 659 the locator shall be done by the shim layer before updating the 660 preferred locator. 662 The preferred locator can be read by getsockopt(). 664 An error ENOENT will be returned when there is no context associated 665 with the socket. 667 An error EINVALIDLOCATOR will be returned when the validation of the 668 specified locator failed. 670 For example, a preferred locator can be set as follows. It should be 671 noted that some members of the shim_locator (lc_ifidx and lc_flags) 672 are ignored in the write operation. 674 struct shim_locator lc; 675 struct in6_addr ip6; 677 /* ...set the locator (ip6)... */ 679 bzero(&lc, sizeof(shim_locator)); 680 lc.lc_family = AF_INET6; /* IPv6 */ 681 lc.lc_ifidx = 0; 682 lc.lc_flags = 0; 683 lc.lc_preference = 255; 684 memcpy(lc.lc_addr, &ip6, sizeof(in6_addr)); 686 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, 687 sizeof(optval)); 689 For example, the preferred locator of the context can be read by 690 application as follows. 692 struct shim_locator lc; 693 int len; 695 len = sizeof(lc); 697 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, &len); 699 5.6. SHIM_LOC_PEER_PREF 701 The SHIM_LOC_PEER_PREF option can be used to read or set preferred 702 locator on peer side within a given context. Hence this option is 703 effective only when there is a shim context associated with the 704 socket. 706 Data type of the option value is a pointer to the specific data 707 structure which stores the locator information. The data structure 708 is defined in Section 7. 710 By default, the option value is set as NULL, meaning that the option 711 is disabled. 713 The preferred locator can be set by setsockopt(). Necessary 714 verification of the locator shall be done by the shim layer before 715 updating the preferred locator. 717 The preferred locator can be read by getsockopt(). 719 An error ENOENT will be returned when there is no context associated 720 with the socket. 722 An error EINVALIDLOCATOR will be returned when the validation of the 723 specified locator failed. 725 For example, a preferred locator can be set as follows. It should be 726 noted that some members of the shim_locator (lc_ifidx and lc_flags) 727 are ignored in the write operation. 729 The usage of the option is same as that of SHIM_LOC_LOCAL_PREF. 731 5.7. SHIM_LOC_LOCAL_RECV 733 The SHIM_LOC_LOCAL_RECV option can be used to request the shim layer 734 to store the destination locator of the received IP packet in an 735 ancillary data object which can be accessed by recvmsg(). Hence this 736 option is effective only when there is a shim context associated with 737 the socket. 739 Data type of the option value is integer. The option value should be 740 binary (0 or 1). By default, the option value is set to 0, meaning 741 that the option is disabled. 743 The option value can be set by setsockopt(). 745 The option value can be read by getsockopt(). 747 See Section 6 for the procedure to access locator information stored 748 in the ancillary data objects. 750 An error ENOENT will be returned when there is no context associated 751 with the socket. 753 For example, the option can be activated by the application as 754 follows: 756 int optval; 758 optval = 1; 760 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, 761 sizeof(optval)); 763 For example, the option value can be checked by the application as 764 follows: 766 int optval; 767 int len; 769 len = sizeof(optval); 771 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, &len); 773 5.8. SHIM_LOC_PEER_RECV 775 The SHIM_LOC_PEER_RECV option can be used to request the shim layer 776 to store the source locator of the received IP packet in an ancillary 777 data object which can be accessed by recvmsg(). Hence this option is 778 effective only when there is a shim context associated with the 779 socket. 781 Data type of the option value is integer. The option value should be 782 binary (0 or 1). By default, the option value is set to 0, meaning 783 that the option is disabled. 785 The option value can be set by setsockopt(). 787 The option value can be read by getsockopt(). 789 See Section 6 for the procedure to access locator information stored 790 in the ancillary data objects. 792 An error ENOENT will be returned when there is no context associated 793 with the socket. 795 The usage of the option is same as that of SHIM_LOC_LOCAL_RECV 796 option. 798 5.9. SHIM_LOC_LOCAL_SEND 800 The SHIM_LOC_LOCAL_SEND option can be used to request the shim layer 801 to use specific locator for the source locator of IP packets to be 802 sent from the socket. Hence this option is effective only when there 803 is a shim context associated with the socket. 805 Data type of option value is pointer to shim_locator data structure. 807 The local locator can be specified by setsockopt() providing a valid 808 locator which is stored in a shim_locator data structure. When a 809 zero-filled locator is specified, pre-existing setting of local 810 locator is deactivated. 812 The local locator specified can be obtained by getsockopt(). The 813 locator can be obtained from the option value. 815 An error ENOENT will be returned when there is no context associated 816 with the socket. 818 An error EINVALIDLOCATOR when invalid locator is specified. 820 For example, a preferred local locator can be specified as follows. 822 struct shim_locator locator; 823 struct in6_addr ia6; 825 /* an IPv6 address preferred for the source locator is copied 826 to the parameter ia6 */ 828 memset(&locator, 0, sizeof(locator)); 830 /* fill shim_locator data structure */ 831 locator.lc_family = AF_INET6; 832 locator.lc_ifidx = 1; 833 locator.lc_flags = 0; 834 locator.lc_preference = 0; 835 memcpy(&locator.lc_addr, &ia6, sizeof(ia6)); 837 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, 838 sizeof(locator)); 840 For example, a preferred local locator can be read as follows. 842 struct shim_locator locator; 844 memset(&locator, 0, sizeof(locator)); 846 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, 847 sizeof(locator)); 849 /* check locator */ 851 5.10. SHIM_LOC_PEER_SEND 853 The SHIM_LOC_PEER_SEND option can be used to request the shim layer 854 to use specific locator for the destination locator of IP packets to 855 be sent from the socket. Hence this option is effective only when 856 there is a shim context associated with the socket. 858 Data type of option value is pointer to shim_locator data structure. 860 The remote locator can be specified by setsockopt() providing a valid 861 locator which is stored in a shim_locator data structure. When a 862 zero-filled locator is specified, pre-existing setting of remote 863 locator is deactivated. 865 The remote locator specified can be obtained by getsockopt(). The 866 locator can be obtained from the option value. 868 An error ENOENT will be returned when there is no context associated 869 with the socket. 871 An error EINVALIDLOCATOR when invalid locator is specified. 873 The usage of the option is as the same as that of SHIM_LOC_LOCAL_SEND 874 option. 876 5.11. SHIM_LOCLIST_LOCAL 878 The SHIM_LOCLIST_LOCAL option can be used to read or set the locator 879 list associated with the local EID of the shim context associated 880 with the socket. Hence this option is effective only when there is a 881 shim context associated with the socket. 883 Data type of option value is pointer to the buffer where a locator 884 list is stored. See Section 7 for the data structure for storing the 885 locator information. By default, the option value is set as NULL, 886 meaning that the option is disabled. 888 The locator list can be read by getsockopt(). Note that the size of 889 the buffer pointed by optval argument should be large enough to store 890 an array of locator information. The number of the locator 891 information is not known beforehand. 893 The locator list can be set by setsockopt(). The buffer pointed by 894 optval argument should contain an array of locator list. 896 An error ENOENT will be returned when there is no context associated 897 with the socket. 899 An error EINVALIDLOCATOR will be returned when the validation of the 900 specified locator failed. 902 For example, a list of locators to be associated with the local EID 903 can be specified as follows: 905 struct shim_locator locators[SHIM_MAX_LOCATORS]; 906 struct sockaddr_in *sin; 907 struct sockaddr_in6 *sin6; 909 memset(locators, 0, sizeof(locators)); 911 ... 913 /* obtain local IP addresses from local interfaces */ 915 ... 917 /* first locator (an IPv6 address) */ 918 locators[0].lc_family = AF_INET6; 919 locators[0].lc_ifidx = 0; 920 locators[0].lc_flags = 0; 921 locators[0].lc_preference = 1; 922 memcpy(&locators[0].lc_addr, &sa6->sin6_addr, 923 sizeof(sa6->sin6_addr)); 925 ... 927 /* second locator (an IPv4 address) */ 928 locators[1].lc_family = AF_INET; 929 locators[1].lc_ifidx = 0; 930 locators[1].lc_flags = 0; 931 locators[1].lc_preference = 0; 932 memcpy(&locators[1].lc_addr, &sa->sin_addr, sizeof(sa->sin_addr)); 934 setsockopt(fd, SOL_SHIM, SHIM_LOCLIST_LOCAL, locators, 935 sizeof(locators)); 937 For example, a list of locators that are associated with the local 938 EID can be obtained as follows: 940 struct shim_locator locators[SHIM_MAX_LOCATORS]; 942 memset(locators, 0, sizeof(locators)); 944 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, locators, 945 sizeof(locators)); 947 /* parse locators */ 948 ... 950 5.12. SHIM_LOCLIST_PEER 952 The SHIM_LOCLIST_PEER option can be used to read or set the locator 953 list associated with the peer EID of the shim context associated with 954 the socket. Hence this option is effective only when there is a shim 955 context associated with the socket. 957 Data type of option value is pointer to the buffer where a locator 958 list is stored. See Section 7 for the data structure for storing the 959 locator information. By default, the option value is set as NULL, 960 meaning that the option is disabled. 962 The locator list can be read by getsockopt(). Note that the size of 963 the buffer pointed by optval argument should be large enough to store 964 an array of locator information. The number of the locator 965 information is not known beforehand. 967 The locator list can be set by setsockopt(). The buffer pointed by 968 optval argument should contain an array of locator list. 970 An error ENOENT will be returned when there is no context associated 971 with the socket. 973 An error EINVALIDLOCATOR will be returned when the validation of the 974 specified locator failed. 976 The usage of the option is same as that of SHIM_LOCLIST_LOCAL. 978 5.13. SHIM_APP_TIMEOUT 980 The SHIM_APP_TIMEOUT option indicates timeout value for application 981 to detect failure. Hence this option is effective only when there is 982 a shim context associated with the socket. 984 Data type of the option value is integer. The value indicates the 985 period of timeout in seconds to send a REAP Keepalive message since 986 the last outbound traffic. By default, the option value is set as 0, 987 meaning that the option is disabled. When the option is disabled, 988 the REAP mechanism follows its default value of Send Timeout value as 989 specified in [I-D.ietf-shim6-failure-detection] 991 If the timeout value specified is longer than the Send Timeout 992 configured in the REAP component, the REAP Keepalive message should 993 be suppressed. 995 An error ENOENT will be returned when there is no context associated 996 with the socket. 998 For example, a specific timeout value can be configured by the 999 application as follows: 1001 int optval; 1003 optval = 15; /* 15 seconds */ 1005 setsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, 1006 sizeof(optval)); 1008 For example, the option value namely the period of timeout can be 1009 checked by the application as follows: 1011 int optval; 1012 int len; 1014 len = sizeof(optval); 1016 getsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, &len); 1018 5.14. SHIM_DEFERRED_CONTEXT_SETUP 1020 The SHIM_DEFERRED_CONTEXT_SETUP option indicates how initiation of 1021 context setup is made in terms of timing (before or after) the 1022 initial communication flow. Deferred context means that the 1023 establishment of context does not put additional delay for an initial 1024 transaction. 1026 Data type for the option value is integer. The option value should 1027 binary (0 or 1). By default, the value is set as 1, meaning that the 1028 context setup is deferred. In order to disable the option, the 1029 application should call setsockopt() with option value set as 0. 1031 However, it should be noted that in some case, deferred context setup 1032 is not possible; given EID is non-routable address and there is no 1033 way to transmit any IP packet unless there is a context providing the 1034 locators. In such case, context should be established prior to the 1035 communication. 1037 For example, the option can be disabled by the application as 1038 follows: 1040 int optval; 1042 optval = 0; 1044 setsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, 1045 &optval, sizeof(optval)); 1047 For example, the option value can be checked by the application as 1048 follows: 1050 int optval; 1051 int len; 1053 len = sizeof(optval); 1055 getsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, 1056 &optval, &len); 1058 5.15. Error Handling 1060 If successful, getsockopt() and setsockopt() return 0; otherwise, the 1061 functions return -1 and set errno to indicate error. 1063 The followings are errno codes newly defined for some shim specific 1064 socket options indicating that the getsockopt() or setsockopt() 1065 finished incompletely: 1067 EINVALIDLOCATOR 1068 This indicates that at least one of the necessary validations 1069 inside the shim layer for the specified locator has failed. In 1070 case of SHIM6, there are two kinds of verifications required for 1071 security reasons prior to sending an IP packet to the peer's new 1072 locator; one is return routability (check if the peer is actually 1073 willing to receive data with the specified locator) and the other 1074 is verifications based on given crypto identifier mechanisms 1075 [RFC3972], [I-D.ietf-shim6-hba]. 1077 6. Ancillary Data for Multihoming Shim 1079 In this section, definition and usage of the ancillary data which is 1080 specific to multihoming shim are provided. 1082 As defined in Posix standard, sendmsg() and recvmsg() take msghdr 1083 structure as its argument and they can additionally handle control 1084 information along with data. Figure 22 shows the msghdr structure 1085 which is defined in . msg_control member holds a 1086 pointer to the buffer where the shim specific ancillary data objects 1087 can be stored in addition to other ancillary data objects. 1089 struct msghdr { 1090 caddr_t msg_name; /* optional address */ 1091 u_int msg_namelen; /* size of address */ 1092 struct iovec *msg_iov; /* scatter/gather array */ 1093 u_int msg_iovlen; /* # elements in msg_iov */ 1094 caddr_t msg_control; /* ancillary data, see below */ 1095 u_int msg_controllen; /* ancillary data buffer len */ 1096 int msg_flags; /* flags on received message */ 1097 }; 1099 Figure 22: msghdr structure 1101 The buffer pointed from the msg_control member of the msghdr 1102 structure may contain a locator information which is a single locator 1103 and it should be possible to process them with the existing macros 1104 defined in Posix and [RFC3542]. Each cmsghdr{} should be followed by 1105 data which stores a single locator. 1107 In case of non-connected socket, msg_name member stores the socket 1108 address of the peer which should be considered as an identifier 1109 rather than a locator. The locator of the peer node should be 1110 retrieved by SHIM_LOC_PEER_RECV as specified below. 1112 Table 2 is a list of the shim specific ancillary data which can be 1113 used for recvmsg() or sendmsg(). In any case, SOL_SHIM must be set 1114 as cmsg_level. 1116 +---------------------+-----------+-----------+-----------------+ 1117 | cmsg_type | sendmsg() | recvmsg() | cmsg_data[] | 1118 +---------------------+-----------+-----------+-----------------+ 1119 | SHIM_LOC_LOCAL_RECV | | o | *1 | 1120 | SHIM_LOC_PEER_RECV | | o | *1 | 1121 | SHIM_LOC_LOCAL_SEND | o | | *1 | 1122 | SHIM_LOC_PEER_SEND | o | | *1 | 1123 | SHIM_FEEDBACK | o | | shim_feedback{} | 1124 +---------------------+-----------+-----------+-----------------+ 1126 Table 2: Shim specific ancillary data 1128 *1: cmsg_data[] should include padding (if necessary) and a single 1129 sockaddr_in{}/sockaddr_in6{}. 1131 It should be noted that the above ancillary data can only be handled 1132 in UDP and raw sockets, not in TCP sockets because there is no one- 1133 to-one mapping of send/receive operations and the TCP segments being 1134 transmitted/received. 1136 6.1. Get Locator Information from Incoming Packet 1138 Application can get locator information from the received IP packet 1139 by specifying the shim specific socket options for the socket. When 1140 SHIM_LOC_LOCAL_RECV and/or SHIM_LOC_PEER_RECV socket options are set, 1141 the application can retrieve local and/or remote locator from the 1142 ancillary data. 1144 6.2. Specify Locator Information for Outgoing Packet 1146 Application can specify the locators to be used for transmitting an 1147 IP packet by sendmsg(). When ancillary data of cmsg_type 1148 SHIM_LOC_LOCAL_SEND and/or SHIM_LOC_PEER_SEND are specified, the 1149 application can explicitly specify source and/or destination locators 1150 to be used for the communication over the socket. 1152 In addition, the application can specify the outgoing interface by 1153 SHIM_IF_SEND ancillary data. The ancillary data should contain the 1154 interface identifier of the physical interface over which the 1155 application expects the packet to be transmitted. 1157 Note that the effect is limited to the datagram transmitted by the 1158 sendmsg(). 1160 If the specified locator pair seems to be valid, the shim layer 1161 overrides the locator of the IP packet as requested. 1163 An error EINVALIDLOCATOR will be returned when validation of the 1164 specified locator failed. 1166 6.3. Notification from Application to Multihoming Shim 1168 Application may provide feedback to the shim layer about the 1169 communication status. Such feedback is particularly useful for the 1170 shim layer in the absence of REAP mechanism to monitor the 1171 reachability status of currently used locator pair in a given shim 1172 context. 1174 The notification can be made by sendmsg() specifying a new ancillary 1175 data called SHIM_FEEDBACK. The ancillary data can be handled by 1176 specifying SHIM_FEEDBACK option in cmsg_type. 1178 An error ENOENT will be returned when there is no context associated 1179 with the socket. 1181 See Section 7.3 for details of the data structure to be used. Note 1182 that this specification does not specify the exact behavior of the 1183 shim layer when a feedback information is given by an application. 1185 7. Data Structures 1187 In this section, data structures specifically defined for the 1188 multihoming shim layer are introduced. Those data structure are 1189 either used as a parameter for setsockopt()/getsockopt() (as 1190 mentioned in Section 5) or a parameter for ancillary data to be 1191 processed by sendmsg()/recvmsg() (as mentioned in Section 6). 1193 7.1. Placeholder for Locator Information 1195 As defined in Section 5, the SHIM_LOC_LOCAL_PREF, SHIM_LOC_PEER_PREF, 1196 SHIM_LOCLIST_LOCAL, and SHIM_LOCLIST_PEER socket options need to 1197 handle one or more locator information. Locator information includes 1198 not only the locator itself but also additional information about the 1199 locator which is useful for locator management. A new data structure 1200 is defined to serve as a placeholder for the locator information. 1202 Figure 23 illustrates the data structure called shim_locator which 1203 stores a locator information. 1205 struct shim_locator { 1206 uint8_t lc_family; /* address family */ 1207 uint8_t lc_ifidx; /* interface index */ 1208 uint8_t lc_flags; /* flags */ 1209 uint8_t lc_preference; /* preference value */ 1210 uint8_t lc_addr[16]; /* address data */ 1211 }; 1213 Figure 23: shim locator structure 1215 lc_family 1216 Address family of the locator (e.g. AF_INET, AF_INET6). It is 1217 required that the parameter contains non-zero value indicating the 1218 exact address family of the locator. 1219 lc_ifidx 1220 Interface index of the network interface to which the locator is 1221 assigned. This field should be valid only in read (getsockopt()) 1222 operation. 1223 lc_flags 1224 Each bit of the flags represents a specific characteristics of the 1225 locator. HBA is defined as 0x01. CGA is defined as 0x02. The 1226 other bits are TBD. 1227 lc_preference 1228 Indicates preference of the locator. The preference is 1229 represented by integer. 1231 lc_addr 1232 Contains the locator. For the cases where a locator whose size is 1233 smaller than 16 bytes, encoding rule should be provided for each 1234 locator of a given address family. For instance, in case of 1235 AF_INET (IPv4), the first 4 bytes of lc_addr should contain the 1236 IPv4 address. 1238 7.2. Path Exploration Parameter 1240 As defined in Section 5, SHIM_PATHEXPLORE allows application to set 1241 or read the parameters for path exploration and failure detection. A 1242 new data structure called shim_pathexplore is defined to store the 1243 necessary parameters. Figure 24 illustrates the data structure. The 1244 data structure can be used by getsockopt() or setsockopt() as an 1245 argument. 1247 struct shim_pathexplore { 1248 uint8_t pe_probenum; /* # of initial probe */ 1249 uint8_t pe_keepaliveto; /* Keepalive Timeout */ 1250 uint16_t pe_initprobeto; /* Initial Probe Timeout */ 1251 uint32_t pe_reserved; /* reserved */ 1252 }; 1254 Figure 24: path explore structure 1256 pe_probenum 1257 Indicates the number of initial probe messages to be sent. 1258 Default value of this parameter should follow what is specified in 1259 [I-D.ietf-shim6-failure-detection]. 1260 pe_keepaliveto 1261 Indicates timeout value for detecting a failure when the host does 1262 not receive any packets for a certain period of time while there 1263 is outbound traffic. When the timer expires, path exploration 1264 procedure will be carried out by sending a REAP Probe message. 1265 Default value of this parameter should follow what is specified in 1266 [I-D.ietf-shim6-failure-detection]. 1267 pe_initprobeto 1268 Indicates retransmission timer of REAP Probe message in 1269 milliseconds. Note that this timer is applied before exponential 1270 back-off is started. A REAP Probe message for the same locator 1271 pair may be retransmitted. Default value of this parameter should 1272 follow what is specified in [I-D.ietf-shim6-failure-detection]. 1273 pe_reserved 1274 A reserved field for future extension. By default, the field 1275 should be initialized with zero. 1277 7.3. Feedback Information 1279 As mentioned in Section 6.3, applications can inform the shim layer 1280 about the status of unicast reachability of the locator pair 1281 currently in use. The feedback information can be handled by using 1282 ancillary data called SHIM_FEEDBACK. A new data structure named 1283 shim_feedback is illustrated in Figure 25). 1285 struct shim_feedback { 1286 uint8_t fb_direction; /* direction of traffic */ 1287 uint8_t fb_indicator; /* indicator (1-3) */ 1288 uint16_t fb_reserved; /* reserved */ 1289 }; 1291 Figure 25: feedback information structure 1293 direction 1294 Indicates direction of reachability between a locator pair in 1295 question. A value 0 indicates outbound and a value 1 indicates 1296 inbound. 1297 indicator 1298 A value indicating the degree of satisfaction of a unidirectional 1299 reachability for a given locator pair. 1300 * 0: Default value. Whenever this value is specified the 1301 feedback information must not be processed by the shim layer. 1302 * 1: Unable to connect. There is no unidirectional reachability 1303 between the locator pair in question. 1304 * 2: Unsatisfactory. The application is not satisfied with the 1305 unidirectional reachability between the locator pair in 1306 question. 1307 * 3: Satisfactory. There is satisfactory unidirectional 1308 reachability between the locator pair in question. 1309 reserved 1310 Reserved field. Must be ignored by the receiver. 1312 8. Implications for Existing Socket API Extensions 1314 Some of the socket options defined in this document have some 1315 overlapping with existing socket API and care should be made for the 1316 usage not to confuse the features. 1318 The socket options for requesting specific locators to be used for a 1319 given transaction (SHIM_LOC_LOCAL_PREF and SHIM_LOC_PEER_PREF) are 1320 semantically similar to the existing socket API (IPV6_PKTINFO). The 1321 socket options for obtaining the locator information from the 1322 received IP packet (SHIM_LOC_LOCAL_RECV and SHIM_LOC_PEER_RECV) are 1323 semantically similar to the existing socket API (IP_RECVDSTADDR and 1324 IPV6_PKTINFO). 1326 In IPv4, application can obtain the destination IP address of the 1327 received IP packet (IP_RECVDSTADDR). If the shim layer performs 1328 identifier/locator adaptation for the received packet, the 1329 destination EID should be stored in the ancillary data 1330 (IP_RECVDSTADDR). 1332 In IPv6, [RFC3542] defines that IPV6_PKTINFO can be used to specify 1333 source IPv6 address and the outgoing interface for outgoing packets, 1334 and retrieve destination IPv6 address and receiving interface for 1335 incoming packets. This information is stored in ancillary data being 1336 IPV6_PKTINFO specified as cmsg_type. Existing socket API should 1337 continue to work above the shim layer, that is, the IP addresses 1338 handled in IPV6_PKTINFO should be EIDs, not the locators. 1340 Baseline is that the above existing socket API (IP_RECVDSTADDR and 1341 IPV6_PKTINFO) is assumed to work above the multihoming shim layer. 1342 In other words, the IP addresses those socket options deal with are 1343 EIDs rather than locators. 1345 9. Resolving Conflicts with Preference Values 1347 Since the multihoming shim API allows application to specify 1348 preference value for the context which is associated with the socket 1349 instance, there may be a conflict with preference values specified by 1350 different applications. For instance, application A and B may 1351 establish communication over the same EID pair while each application 1352 have different preference in their choice of local locator. 1354 SHIM6 supports a notion of forking context in which a context is 1355 split when there is a conflict with preference values specified by 1356 multiple applications. Thus, context forking can simply resolve the 1357 conflicting situation which may be caused by the use of socket 1358 options for multihoming shim layer. 1360 9.1. Implicit Forking 1362 Socket options defined in Section 5 may cause conflicting situation 1363 when the target context is shared by multiple applications. In such 1364 case, socket handler and the multihoming shim layer should react as 1365 follows; socket handler should inform the shim layer that context 1366 forking is required. In SHIM6, when a context is forked, an unique 1367 identifier called Forked Instance Identifier (FII) is assigned to the 1368 newly forked context. The forked context is then exclusively 1369 associated with the socket through which non-default preference value 1370 was specified. The forked context is maintained by the multihoming 1371 shim layer during the lifetime of associated socket instance. When 1372 the socket is closed, the multihoming shim layer SHOULD delete 1373 associated context. In this way, garbage collection can be carried 1374 out to cleanup unused forked contexts. Upon garbage collection, 1375 every forked context SHOULD be checked if there is no socket 1376 (process) associated with the context. If there is none, the forked 1377 context should be deleted. When a forked context is torn down, SHIM6 1378 should notify the peer about the deletion of forked context. 1380 As opposed to socket options, context forking MUST NOT be triggered 1381 by any use of ancillary data that are specific to multihoming shim 1382 defined in Section 6. 1384 10. Discussion 1386 In this section, open issues are introduced. 1388 10.1. Naming at Socket Layer 1390 getsockname() and getpeername() system calls are used to obtain the 1391 'name' of endpoint which is actually a pair of IP address and port 1392 number assigned to a given socket. getsockname() is used when an 1393 application wants to obtain the local IP address and port number 1394 assigned for a given socket instance. getpeername() is used when an 1395 application wants to obtain the remote IP address and port number. 1397 The above is based on a traditional system model of the socket API 1398 where an IP address is expected to play both the role of identifier 1399 and the role of locator. 1401 In a system model where a shim layer exists inside the IP layer, both 1402 getsockname() and getpeername() deal with identifiers, namely EIDs. 1403 In this sense, the shim layer serves to (1) hide locators and (2) 1404 provide access to the identifier for the application over the legacy 1405 socket APIs. 1407 10.2. Additional Requirements from Application 1409 At the moment, it is not certain if following requirements are common 1410 in all the multihomed environments (SHIM6 and HIP). These are mainly 1411 identified during discussions made on SHIM6 WG mailing list. 1412 o The application should be able to set preferences for the 1413 locators, local and remote one and also to the preferences of the 1414 local locators that will be passed to the peer. 1416 10.3. Issues of Header Conversion among Different Address Family 1418 The shim layer performs identifier/locator adaptation. Therefore, in 1419 some case, the whole IP header can be replaced with new IP header of 1420 a different address family (e.g. conversion from IPv4 to IPv6 or vice 1421 versa). Hence, there is an issue how to make the conversion with 1422 minimum impact. Note that this issue is common in other protocol 1423 conversion such as SIIT[RFC2765]. 1425 As addressed in SIIT specification, some of the features (IPv6 1426 routing headers, hop-by-hop extension headers, or destination 1427 headers) from IPv6 are not convertible to IPv4. In addition, notion 1428 of source routing is not exactly the same in IPv4 and IPv6. Hence, 1429 there is certain limitation in protocol conversion between IPv4 and 1430 IPv6. 1432 The question is how should the shim layer behave when it is face with 1433 limitation problem of protocol conversion. Should we introduce new 1434 error something like ENOSUITABLELOCATOR ? 1436 10.4. Handling of Unknown Locator Provided by Application 1438 There might be a case where application provides the shim layer new 1439 locator with the SHIM_LOC_*_PREF socket options or SHIM_LOC_*_SEND 1440 ancillary data. Then there is a question how should the shim layer 1441 treat the new locator informed by the application. 1443 In principle, locator information are exchanged by the shim protocol. 1444 However, there might be a case where application acquires information 1445 about the locator and prefers to use it for its communication. 1447 11. Changes 1449 11.1. Changes from version 00 to version 01 1451 The followings are changes from version 00 to version 01: 1452 o Define shim_locator{} data type which is a placeholder for 1453 locator. 1454 o Define shim_pathexplore{} data type in which a set of REAP 1455 parameters are stored. 1456 o Remove descriptions about "stickiness" of socket options. 1457 o Deprecate SHIM_IF_RECV and SHIM_IF_SEND socket options. 1458 o Give default value and how to disable given socket option. 1460 11.2. Changes from version 01 to version 02 1462 The followings are changes from version 01 to version 02: 1463 o Add section describing context forking. 1464 o Rephrase conclusion section. 1465 o Separate normative references from informative references. 1466 o Remove texts from discussion section that are not relevant to the 1467 contents of the document. 1468 o Add section describing change history (this section). 1470 11.3. Changes from version 02 to version 03 1472 The followings are changes from version 02 to version 03: 1473 o Add an Appendix section describing the issue of context forking. 1475 11.4. Changes from version 03 to version 04 1477 The followings are changes from version 03 to version 04: 1478 o Updated reference. 1479 o Correct typo and grammatical errors. 1481 11.5. Changes from version 04 to version 05 1483 The followings are changes from version 04 to version 05: 1484 o Added definition of SHIM_FEEDBACK ancillary data. 1485 o Added an example of code using the SHIM_LOCLIST_LOCAL 1486 o Added SHIM_LOC_LOCAL_SEND and SHIM_LOC_PEER_SEND socket options. 1488 12. IANA Considerations 1490 This document contains no IANA consideration. 1492 13. Security Considerations 1494 This document does not specify any security mechanism for the shim 1495 layer. Fundamentally, the shim layer has a potential to impose 1496 security threats, as it changes the source and/or destination IP 1497 addresses of the IP packet being sent or received. Therefore, the 1498 basic assumption is that the security mechanism defined in each 1499 protocol of the shim layer is strictly applied. 1501 14. Conclusion 1503 In this document, the Application Program Interface (API) for 1504 multihoming shim layer is specified. The socket API allows 1505 applications to have additional control of the locator management and 1506 interface to the REAP mechanism inside the multihoming shim layer. 1508 Socket options for multihoming shim layer can be used by getsockopt() 1509 and/or setsockopt() system calls. Besides, applications can use some 1510 ancillary data that are specific to multihoming shim layer to get 1511 locator from received packet or to set locator for outgoing packet. 1513 From an architectural point of view, the socket API provides extends 1514 the existing socket API framework in the face of ID/Locator 1515 separation. With regard to API that relate to IP address management, 1516 it is assured that existing socket API continue to work above the 1517 shim layer dealing with identifiers, while multihoming shim API deals 1518 with locators. 1520 15. Acknowledgments 1522 Authors would like to thank Jari Arkko who participated in the 1523 discussion that lead to the first version of this document, and 1524 Tatuya Jinmei who thoroughly reviewed the early version of this draft 1525 and provided detailed comments on socket API related issues. Thomas 1526 Henderson provided valuable comments especially from HIP 1527 perspectives. 1529 16. References 1531 16.1. Normative References 1533 [I-D.ietf-shim6-failure-detection] 1534 Arkko, J. and I. Beijnum, "Failure Detection and Locator 1535 Pair Exploration Protocol for IPv6 Multihoming", 1536 draft-ietf-shim6-failure-detection-10 (work in progress), 1537 January 2008. 1539 [I-D.ietf-shim6-proto] 1540 Bagnulo, M. and E. Nordmark, "Level 3 multihoming shim 1541 protocol", draft-ietf-shim6-proto-09 (work in progress), 1542 October 2007. 1544 [POSIX] "IEEE Std. 1003.1-2001 Standard for Information Technology 1545 -- Portable Operating System Interface (POSIX). Open group 1546 Technical Standard: Base Specifications, Issue 6, 1547 http://www.opengroup.org/austin", December 2001. 1549 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 1550 "Advanced Sockets Application Program Interface (API) for 1551 IPv6", RFC 3542, May 2003. 1553 [RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol 1554 (HIP) Architecture", RFC 4423, May 2006. 1556 16.2. Informative References 1558 [I-D.ietf-shim6-app-refer] 1559 Nordmark, E., "Shim6 Application Referral Issues", 1560 draft-ietf-shim6-app-refer-00 (work in progress), 1561 July 2005. 1563 [I-D.ietf-shim6-hba] 1564 Bagnulo, M., "Hash Based Addresses (HBA)", 1565 draft-ietf-shim6-hba-05 (work in progress), December 2007. 1567 [RFC2765] Nordmark, E., "Stateless IP/ICMP Translation Algorithm 1568 (SIIT)", RFC 2765, February 2000. 1570 [RFC3972] Aura, T., "Cryptographically Generated Addresses (CGA)", 1571 RFC 3972, March 2005. 1573 Appendix A. Context Forking 1575 In this section, an issue concerning context forking and its relation 1576 to the multihoming shim API are discussed. 1578 SHIM6 supports a notion of context forking. A peer may decide to 1579 fork a context for certain reason (e.g. upper layer protocol prefers 1580 to use different locator pair than the one defined in available 1581 context). The procedure of forking context is done similar to the 1582 normal context establishment, performing the 4-way message exchange. 1583 A peer who has decided to fork a context initiates the context 1584 establishment. Hereafter, we call this peer initiator. 1586 Once the forked context is established between the peers, on the 1587 initiator side, it is possible to apply forked context to the packet 1588 flow since the system maintains an association between the forked 1589 context and the socket owned by the application that has requested 1590 the context forking. How this association is maintained is 1591 implementation specific issue. However, on the responder side, there 1592 is a question on how the outbound packet can be multiplexed by the 1593 shim layer. Since there are more than one SHIM6 contexts that match 1594 with the ULID pair of the packet flow. There is a need to 1595 differentiate packet flows not only by the ULID pairs but some other 1596 information and associate a given packet flow with specific context. 1598 Figure 26 gives an example of a scenario where two communicating 1599 peers fork a context. Initially, there has been a single transaction 1600 between the peers, by the application 1 (App1). Accordingly, another 1601 transaction is started, by application 2 (App2). Both of the 1602 transactions are made based the same ULID pair. The first context 1603 pair (Ctx1) is established for the transaction of App1. Given the 1604 requests from App2, the shim layer on Peer 1 decides to fork a 1605 context. Accordingly, a forked context (Ctx2) is established between 1606 the peers, which should be exclusively applied to the transaction of 1607 App2. Ideally, multiplexing and demultiplexing of packet flows that 1608 relate to App1 and App2 should be done as illustrated in Figure 26. 1609 However, as mentioned earlier, on the responder side, there is a 1610 problem with multiplexing the outbound packet flows of App1 and App2. 1612 Peer 1 Peer 2 1613 (initiator) (responder) 1615 +----+ +----+ +----+ +----+ 1616 |App1| |App2| |App1| |App2| 1617 +----+ +----+ +----+ +----+ 1618 |^ |^ ^| ^| 1619 v| v| |v |v 1620 -----S1-------------S2----- -----S1-------------S2----- 1621 || || || || 1622 || || || || 1624 Ctx1 Ctx2 Ctx1 Ctx2 1625 ULID: ULID: ULID: ULID: 1626 Loc: Loc: Loc: Loc: 1627 FII: 0 FII: 100 FII: 0 FII: 100 1629 |^ |^ ^| ^| 1630 || || || || 1631 || || || || 1632 \..............||........................../| || 1633 \.............||.........................../ || 1634 || || 1635 \|........................................./| 1636 \........................................../ 1638 Figure 26: context forking 1640 To overcome the problem mentioned above, there are some solutions. 1642 One viable approach is to let the system implicitly maintain an 1643 association between the socket and the associated context by keeping 1644 the record of inbound packet processing. That is, the system stores 1645 the information about the context on which the inbound packet flow 1646 was demultiplexed. The information comprises the ULID pair and FII 1647 of the context and is stored in the socket instance. Later, the 1648 system can use the information to identify the associated context in 1649 outbound packet processing. This approach should be feasible as far 1650 as there is bi-directional user traffic. 1652 Another viable approach is to extend SHIM6 protocol by adding 1653 capability of exchanging additional information to identify the 1654 packet flow from others which needs to be handled by a newly forked 1655 context. The information exchange can be done during the context 1656 establishment. The initiator appends 5 tuple of the packet flow to 1657 be handled by the newly forked context. Note that the additional 1658 information provided by the 5 tuple are source and destination port 1659 numbers and upper layer protocol. The information is later used by 1660 the shim layer to multiplex the outbound packet flow on the responder 1661 side. 1663 The socket options for multihoming shim can be used by the 1664 application to trigger the context forking in implicit manner. The 1665 peer becomes an initiator in the establishment of the forked context. 1666 Once the forked context is established between the peers, application 1667 on each end can influence the preference on context by utilizing the 1668 multihoming shim API. 1670 Authors' Addresses 1672 Miika Komu 1673 Helsinki Institute for Information Technology 1674 Tammasaarenkatu 3 1675 Helsinki 1676 Finland 1678 Phone: +358503841531 1679 Fax: +35896949768 1680 Email: miika@iki.fi 1681 URI: http://www.hiit.fi/ 1682 Marcelo Bagnulo 1683 Universidad Carlos III de Madrid 1684 Av. Universidad 30 1685 Leganes 28911 1686 SPAIN 1688 Phone: +34 91 6248837 1689 Email: marcelo@it.uc3m.es 1690 URI: http://it.uc3m.es/marcelo 1692 Kristian Slavov 1693 Ericsson Research Nomadiclab 1694 Hirsalantie 11 1695 Jorvas FI-02420 1696 Finland 1698 Phone: +358 9 299 3286 1699 Email: kristian.slavov@ericsson.com 1701 Shinta Sugimoto (editor) 1702 Nippon Ericsson K.K. 1703 Koraku Mori Building 1704 1-4-14, Koraku, Bunkyo-ku 1705 Tokyo 112-0004 1706 Japan 1708 Phone: +81 3 3830 2241 1709 Email: shinta.sugimoto@ericsson.com 1711 Full Copyright Statement 1713 Copyright (C) The IETF Trust (2008). 1715 This document is subject to the rights, licenses and restrictions 1716 contained in BCP 78, and except as set forth therein, the authors 1717 retain all their rights. 1719 This document and the information contained herein are provided on an 1720 "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS 1721 OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND 1722 THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS 1723 OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF 1724 THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED 1725 WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. 1727 Intellectual Property 1729 The IETF takes no position regarding the validity or scope of any 1730 Intellectual Property Rights or other rights that might be claimed to 1731 pertain to the implementation or use of the technology described in 1732 this document or the extent to which any license under such rights 1733 might or might not be available; nor does it represent that it has 1734 made any independent effort to identify any such rights. Information 1735 on the procedures with respect to rights in RFC documents can be 1736 found in BCP 78 and BCP 79. 1738 Copies of IPR disclosures made to the IETF Secretariat and any 1739 assurances of licenses to be made available, or the result of an 1740 attempt made to obtain a general license or permission for the use of 1741 such proprietary rights by implementers or users of this 1742 specification can be obtained from the IETF on-line IPR repository at 1743 http://www.ietf.org/ipr. 1745 The IETF invites any interested party to bring to its attention any 1746 copyrights, patents or patent applications, or other proprietary 1747 rights that may cover technology that may be required to implement 1748 this standard. Please address the information to the IETF at 1749 ietf-ipr@ietf.org. 1751 Acknowledgment 1753 Funding for the RFC Editor function is provided by the IETF 1754 Administrative Support Activity (IASA).