idnits 2.17.1 draft-ietf-shim6-multihome-shim-api-16.txt: Checking boilerplate required by RFC 5378 and the IETF Trust (see https://trustee.ietf.org/license-info): ---------------------------------------------------------------------------- No issues found here. 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 : ---------------------------------------------------------------------------- No issues found here. Miscellaneous warnings: ---------------------------------------------------------------------------- == The copyright year in the IETF Trust and authors Copyright Line does not match the current year == Line 1248 has weird spacing: '... u_int msg_...' == Line 1249 has weird spacing: '... struct iovec...' == Line 1250 has weird spacing: '... u_int msg_...' == Line 1252 has weird spacing: '... u_int msg_...' -- The document seems to contain a disclaimer for pre-RFC5378 work, and may have content which was first submitted before 10 November 2008. The disclaimer is necessary when there are original authors that you have been unable to contact, or if some do not wish to grant the BCP78 rights to the IETF Trust. If you are able to get all authors (current and original) to grant those rights, you can and should remove the disclaimer; otherwise, the disclaimer is needed and you can ignore this comment. (See the Legal Provisions document at https://trustee.ietf.org/license-info for more information.) -- The document date (February 12, 2011) is 4823 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 1013 -- Looks like a reference, but probably isn't: '1' on line 1024 ** Obsolete normative reference: RFC 4423 (Obsoleted by RFC 9063) -- Obsolete informational reference (is this intentional?): RFC 2765 (Obsoleted by RFC 6145) Summary: 1 error (**), 0 flaws (~~), 5 warnings (==), 6 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 16, 2011 UC3M 6 K. Slavov 7 S. Sugimoto, Ed. 8 Ericsson 9 February 12, 2011 11 Socket Application Program Interface (API) for Multihoming Shim 12 draft-ietf-shim6-multihome-shim-api-16 14 Abstract 16 This document specifies sockets API extensions for the multihoming 17 shim layer. The API aims to enable interactions between applications 18 and the multihoming shim layer for advanced locator management, and 19 access to information about failure detection and path exploration. 21 This document is based on an assumption that a multihomed host is 22 equipped with a conceptual sub-layer (hereafter "shim") inside the IP 23 layer that maintains mappings between identifiers and locators. 24 Examples of the shim are SHIM6 and HIP. 26 Status of this Memo 28 This Internet-Draft is submitted in full conformance with the 29 provisions of BCP 78 and BCP 79. 31 Internet-Drafts are working documents of the Internet Engineering 32 Task Force (IETF). Note that other groups may also distribute 33 working documents as Internet-Drafts. The list of current Internet- 34 Drafts is at http://datatracker.ietf.org/drafts/current/. 36 Internet-Drafts are draft documents valid for a maximum of six months 37 and may be updated, replaced, or obsoleted by other documents at any 38 time. It is inappropriate to use Internet-Drafts as reference 39 material or to cite them other than as "work in progress." 41 This Internet-Draft will expire on August 16, 2011. 43 Copyright Notice 45 Copyright (c) 2011 IETF Trust and the persons identified as the 46 document authors. All rights reserved. 48 This document is subject to BCP 78 and the IETF Trust's Legal 49 Provisions Relating to IETF Documents 50 (http://trustee.ietf.org/license-info) in effect on the date of 51 publication of this document. Please review these documents 52 carefully, as they describe your rights and restrictions with respect 53 to this document. Code Components extracted from this document must 54 include Simplified BSD License text as described in Section 4.e of 55 the Trust Legal Provisions and are provided without warranty as 56 described in the Simplified BSD License. 58 This document may contain material from IETF Documents or IETF 59 Contributions published or made publicly available before November 60 10, 2008. The person(s) controlling the copyright in some of this 61 material may not have granted the IETF Trust the right to allow 62 modifications of such material outside the IETF Standards Process. 63 Without obtaining an adequate license from the person(s) controlling 64 the copyright in such materials, this document may not be modified 65 outside the IETF Standards Process, and derivative works of it may 66 not be created outside the IETF Standards Process, except to format 67 it for publication as an RFC or to translate it into languages other 68 than English. 70 Table of Contents 72 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 73 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 6 74 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 75 4. System Overview . . . . . . . . . . . . . . . . . . . . . . . 8 76 5. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 9 77 6. Socket Options for Multihoming Shim Sub-layer . . . . . . . . 10 78 6.1. SHIM_ASSOCIATED . . . . . . . . . . . . . . . . . . . . . 14 79 6.2. SHIM_DONTSHIM . . . . . . . . . . . . . . . . . . . . . . 15 80 6.3. SHIM_HOT_STANDBY . . . . . . . . . . . . . . . . . . . . 16 81 6.4. SHIM_LOC_LOCAL_PREF . . . . . . . . . . . . . . . . . . . 17 82 6.5. SHIM_LOC_PEER_PREF . . . . . . . . . . . . . . . . . . . 18 83 6.6. SHIM_LOC_LOCAL_RECV . . . . . . . . . . . . . . . . . . . 19 84 6.7. SHIM_LOC_PEER_RECV . . . . . . . . . . . . . . . . . . . 20 85 6.8. SHIM_LOC_LOCAL_SEND . . . . . . . . . . . . . . . . . . . 20 86 6.9. SHIM_LOC_PEER_SEND . . . . . . . . . . . . . . . . . . . 22 87 6.10. SHIM_LOCLIST_LOCAL . . . . . . . . . . . . . . . . . . . 23 88 6.11. SHIM_LOCLIST_PEER . . . . . . . . . . . . . . . . . . . . 25 89 6.12. SHIM_APP_TIMEOUT . . . . . . . . . . . . . . . . . . . . 25 90 6.13. SHIM_PATHEXPLORE . . . . . . . . . . . . . . . . . . . . 26 91 6.14. SHIM_DEFERRED_CONTEXT_SETUP . . . . . . . . . . . . . . . 27 92 6.15. Applicability . . . . . . . . . . . . . . . . . . . . . . 28 93 6.16. Error Handling . . . . . . . . . . . . . . . . . . . . . 28 94 7. Ancillary Data for Multihoming Shim Sub-layer . . . . . . . . 28 95 7.1. Get Locator from Incoming Packet . . . . . . . . . . . . 30 96 7.2. Set Locator for Outgoing Packet . . . . . . . . . . . . . 30 97 7.3. Notification from Application to Multihoming Shim 98 Sub-layer . . . . . . . . . . . . . . . . . . . . . . . . 30 99 7.4. Applicability . . . . . . . . . . . . . . . . . . . . . . 31 100 8. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 31 101 8.1. Placeholder for Locator Information . . . . . . . . . . . 31 102 8.1.1. Handling Locator behind NAT . . . . . . . . . . . . . 33 103 8.2. Path Exploration Parameter . . . . . . . . . . . . . . . 33 104 8.3. Feedback Information . . . . . . . . . . . . . . . . . . 34 105 9. System Requirements . . . . . . . . . . . . . . . . . . . . . 35 106 10. Relation to Existing Sockets API Extensions . . . . . . . . . 35 107 11. Operational Considerations . . . . . . . . . . . . . . . . . . 36 108 11.1. Conflict Resolution . . . . . . . . . . . . . . . . . . . 36 109 11.2. Incompatibility between IPv4 and IPv6 . . . . . . . . . . 37 110 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 111 13. Protocol Constants and Variables . . . . . . . . . . . . . . . 37 112 14. Security Considerations . . . . . . . . . . . . . . . . . . . 37 113 14.1. Treatment of Unknown Locator . . . . . . . . . . . . . . 38 114 14.1.1. Treatment of Unknown Source Locator . . . . . . . . . 38 115 14.1.2. Treatment of Unknown Destination Locator . . . . . . . 38 116 15. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 117 15.1. Changes from version 00 to version 01 . . . . . . . . . . 38 118 15.2. Changes from version 01 to version 02 . . . . . . . . . . 39 119 15.3. Changes from version 02 to version 03 . . . . . . . . . . 39 120 15.4. Changes from version 03 to version 04 . . . . . . . . . . 39 121 15.5. Changes from version 04 to version 05 . . . . . . . . . . 39 122 15.6. Changes from version 05 to version 06 . . . . . . . . . . 39 123 15.7. Changes from version 06 to version 07 . . . . . . . . . . 39 124 15.8. Changes from version 07 to version 08 . . . . . . . . . . 39 125 15.9. Changes from version 08 to version 09 . . . . . . . . . . 39 126 15.10. Changes from version 09 to version 10 . . . . . . . . . . 40 127 15.11. Changes from version 10 to version 11 . . . . . . . . . . 40 128 15.12. Changes from version 11 to version 12 . . . . . . . . . . 40 129 15.13. Changes from version 12 to version 13 . . . . . . . . . . 40 130 15.14. Changes from version 13 to version 14 . . . . . . . . . . 40 131 15.15. Changes from version 14 to version 15 . . . . . . . . . . 40 132 15.16. Changes from version 15 to version 16 . . . . . . . . . . 41 133 16. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 41 134 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41 135 17.1. Normative References . . . . . . . . . . . . . . . . . . 41 136 17.2. Informative References . . . . . . . . . . . . . . . . . 42 137 Appendix A. Context Forking . . . . . . . . . . . . . . . . . . . 43 138 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 44 140 1. Introduction 142 This document defines socket API extensions by which upper layer 143 protocols may be informed about and control the way in which a 144 multihoming shim sub-layer in the IP layer manages the dynamic choice 145 of locators. Initially it applies to SHIM6 and HIP, but it is 146 defined generically. 148 The role of the multihoming shim sub-layer (hereafter called "shim 149 sub-layer" in this document) is to avoid impacts to upper layer 150 protocols which may be caused when the endhost changes its attachment 151 point to the Internet, for instance, in the case of rehoming event 152 under the multihomed environment. There is, however, a need for API 153 in the cases where 1) the upper layer protocol is particularly 154 sensitive to impacts, or 2) the upper layer protocol wants to benefit 155 from better knowledge of what is going on underneath. 157 There are various kinds of technologies that aim to solve the same 158 issue, the multihoming issue. Note that there will be conflict when 159 more than one shim sub-layer is active at the same time. The 160 assumption made in this document is that there is only a single shim 161 sub-layer (HIP or SHIM6) activated on the system. 163 In this document, syntax and semantics of the API are given in the 164 same way as in the Posix standard [POSIX]. The API specifies how to 165 use ancillary data (aka cmsg) to access the locator information with 166 recvmsg() and/or sendmsg() I/O calls. The API is described in C 167 language and data types are defined in the Posix format; intN_t means 168 a signed integer of exactly N bits (e.g. int16_t) and uintN_t means 169 an unsigned integer of exactly N bits (e.g. uint32_t). 171 The distinction between "connected" sockets and "unconnected" sockets 172 is important when discussing the applicability of the socket API 173 defined in this document. A connected socket is bound to a given 174 peer, whereas an unconnected socket is not bound to any specific 175 peers. A TCP socket becomes a connected socket when the TCP 176 connection establishment is completed. UDP sockets are unconnected, 177 unless the application uses the connect() system call. 179 The target readers of this document are application programmers who 180 develop application software which may benefit greatly from 181 multihomed environments. In addition, this document aims to provide 182 necessary information for developers of shim protocols to implement 183 API for enabling advanced locator management. 185 2. Requirements Language 187 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 188 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 189 document are to be interpreted as described in [RFC2119]. 191 3. Terminology 193 This section provides terminology used in this document. Basically 194 most of the terms used in this document are taken from the following 195 documents: 197 o SHIM6 Protocol Specification[RFC5533] 198 o HIP Architecture[RFC4423] 199 o Reachability Protocol (REAP)[RFC5534] 201 In this document, the term "IP" refers to both IPv4 and IPv6, unless 202 the protocol version is specifically mentioned. The following are 203 definitions of terms frequently used in this document: 205 o Endpoint identifier (EID) - The identifier used by the application 206 to specify the endpoint of a given communication. Applications 207 may handle EIDs in various ways such as long-lived connections, 208 callbacks, and referrals[I-D.ietf-shim6-app-refer]. 209 * In the case of SHIM6, an identifier called a ULID (Upper Layer 210 Identifier) serves as an EID. A ULID is chosen from locators 211 available on the host. 212 * In the case of HIP, an identifier called a Host Identifier 213 serves as an EID. A Host Identifier is derived from the public 214 key of a given host. For the sake of backward compatibility 215 with the sockets API, the Host Identifier is represented in a 216 form of hash of public key. 217 * Note that the EID appears in the standard socket API as an 218 address, and does not appear in the extensions defined in this 219 document, which only concern locators. 220 o Locator - The IP address actually used to deliver IP packets. 221 Locators are present in the source and destination fields of the 222 IP header of a packet on the wire. Locator discussed in this 223 document could be either an IPv4 address or an IPv6 address. Note 224 that HIP can handle both IPv4 and IPv6 locators, whereas SHIM6 can 225 handle only IPv6 locators. For the HIP case, locator can be a 226 private IPv4 address when the host is behind a NAT. Section 227 Section 8.1.1 gives detailed description about handling of locator 228 behind NAT. 229 * List of locators - A list of locators associated with an EID. 230 There are two lists of locators stored in a given context. One 231 is associated with the local EID and the other is associated 232 with the remote EID. As defined in [RFC5533], the list of 233 locators associated with an EID 'A' is denoted as Ls(A). 234 * Preferred locator - The (source/destination) locator currently 235 used to send packets within a given context. 236 * Unknown locator - Any locator that does not appear in the 237 locator list of the shim context associated with the socket. 238 When there is no shim context associated with the socket, any 239 source and/or destination locator requested by the application 240 is considered to be unknown locator. 241 * Valid locator - A valid locator means that the locator is 242 considered to be valid in the security sense. More 243 specifically, the validity indicates whether the locator is 244 part of a HBA set. 245 * Verified locator - A verified locator means that the locator is 246 considered to be reachable according to the result of REAP 247 return routability check. Note that the verification applies 248 only to peer's locator. 249 o Shim - The conceptual sub-layer inside the IP layer which 250 maintains mappings between EIDs and locators. An EID can be 251 associated with more than one locator at a time when the host is 252 multihomed. The term 'shim' does not refer to a specific protocol 253 but refers to the conceptual sub-layer inside the IP layer. 254 o Identifier/locator adaptation - The adaptation performed at the 255 shim sub-layer which may end up re-writing the source and/or 256 destination addresses of an IP packet. In the outbound packet 257 processing, the EID pair is converted to the associated locator 258 pair. In the inbound packet processing, the locator pair is 259 converted to the EID pair. 260 o Context - The state information shared by a given pair of peers, 261 which stores a binding between the EID and associated locators. 262 Contexts are maintained by the shim sub-layer. 263 o Reachability detection - The procedure to check reachability 264 between a given locator pair. 265 o Path - The sequence of routers that an IP packet goes through to 266 reach the destination. 267 o Path exploration - The procedure to explore available paths for a 268 given set of locator pairs. 269 o Outage - The incident that prevents IP packets to flow from the 270 source locator to the destination locator. When there is an 271 outage, it means that there is no reachability between a given 272 locator pair. The outage may be caused by various reasons, such 273 as shortage of network resources, congestion, and human error 274 (faulty operation). 275 o Working address pair - The address pair is considered to be 276 "working" if the packet can safely travel from the source to the 277 destination where the packet contains the first address from the 278 pair as the source address and the second address from the pair as 279 the destination address. If reachability is confirmed in both 280 directions, the address pair is considered to be working bi- 281 directionally. 282 o Reachability protocol (REAP) - The protocol for detecting failure 283 and exploring reachability in a multihomed environment. REAP is 284 defined in [RFC5534]. 286 4. System Overview 288 Figure 1 illustrates the system overview. The shim sub-layer and 289 REAP component exist inside the IP layer. Applications use the 290 sockets API defined in this document to interface with the shim sub- 291 layer and the transport layer for locator management, failure 292 detection, and path exploration. 294 It may also be possible that the shim sub-layer interacts with the 295 transport layer, however, such an interaction is outside the scope of 296 this document. 298 +------------------------+ 299 | Application | 300 +------------------------+ 301 ^ ^ 302 ~~~~~~~~~~~~~|~Socket Interface|~~~~~~~~~~~~~~ 303 | v 304 +-----------|------------------------------+ 305 | | Transport Layer | 306 +-----------|------------------------------+ 307 ^ | 308 +-------------|-----|-------------------------------------+ 309 | v v | 310 | +-----------------------------+ +----------+ | IP 311 | | Shim |<----->| REAP | | Layer 312 | +-----------------------------+ +----------+ | 313 | ^ ^ | 314 +-----------------------|----------------------|----------+ 315 v v 316 +------------------------------------------+ 317 | Link Layer | 318 +------------------------------------------+ 320 Figure 1: System overview 322 5. Requirements 324 The following is a list of requirements from applications: 325 o Turn on/off shim. An application should be able to request to 326 turn on or turn off the multihoming support by the shim layer: 327 * Apply shim. The application should be able to explicitly 328 request the shim sub-layer to apply multihoming support. 329 * Don't apply shim. The application should be able to request 330 the shim sub-layer not to apply the multihoming support but to 331 apply normal IP processing at the IP layer. 332 * Note that this function is also required by other types of 333 multihoming mechanisms such as SCTP and multipath TCP to avoid 334 potential conflict with the shim sub-layer. 335 o Locator management. 336 * It should be possible to set preferred source and/or 337 destination locator within a given context. 338 * It should be possible to get preferred source and/or 339 destination locator within a given context. 340 * It should be possible to set a list of source and/or 341 destination locators within a given context: Ls(local) and 342 Ls(remote). 343 * It should be possible to get a list of source and/or 344 destination locators within a given context: Ls(local) and 345 Ls(remote). 346 o Notification from applications to the shim sub-layer about the 347 status of the communication. The notification occurs in an event- 348 based manner. Applications and/or upper layer protocols may 349 provide positive feedback or negative feedback to the shim sub- 350 layer. Note that these feedback are mentioned in [RFC5534]: 351 * Applications and/or upper layer protocols (e.g., TCP) may 352 provide positive feedback to the shim sub-layer informing that 353 the communication is going well. 354 * Applications and/or upper layer protocols (e.g., TCP) may 355 provide negative feedback to the shim sub-layer informing that 356 the communication status is not satisfactory. TCP may detect a 357 problem when it does not receive any expected ACK message from 358 the peer. The REAP module may be triggered by these negative 359 feedback and invoke the path exploration procedure. 360 o Feedback from applications to the shim sub-layer. Applications 361 should be able to inform the shim sub-layer of the timeout values 362 for detecting failures, sending keepalives, and starting the 363 exploration procedure. In particular, applications should be able 364 to suppress keepalives. 365 o Hot-standby. Applications may request the shim sub-layer for the 366 hot-standby capability. This means that, alternative paths are 367 known to be working in advance of a failure detection. In such a 368 case, it is possible for the host to immediately replace the 369 current locator pair with an alternative locator pair. 371 o Eagerness for locator exploration. An application should be able 372 to inform the shim sub-layer of how aggressively it wants the REAP 373 mechanism to perform a path exploration (e.g., by specifying the 374 number of concurrent attempts of discovery of working locator 375 pairs) when an outage occurs on the path between the locator pair 376 in use. 377 o Providing locator information to applications. An application 378 should be able to obtain information about the locator pair which 379 was actually used to send or receive the packet. 380 * For inbound traffic, the application may be interested in the 381 locator pair which was actually used to receive the packet. 382 * For outbound traffic, the application may be interested in the 383 locator pair which was actually used to transmit the packet. 384 In this way, applications may have additional control on the 385 locator management. For example, an application becomes able to 386 verify if its preference for locator is actually applied to the 387 flow or not. 388 o Applications should be able to know if the shim-sublayer supports 389 deferred context setup or not. 390 o An application should be able to know if the communication is now 391 being served by the shim sub-layer or not. 392 o An application should be able to use a common interface to access 393 an IPv4 locator and an IPv6 locator. 395 6. Socket Options for Multihoming Shim Sub-layer 397 In this section, socket options that are specific to the shim sub- 398 layer are defined. 400 Table 1 shows a list of the socket options that are specific to the 401 shim sub-layer. All of these socket options are defined at the level 402 SOL_SHIM. When an application uses one of the socket options by 403 getsockopt() or setsockopt(), the second argument must be set as 404 SOL_SHIM. 406 The first column of Table 1 gives the name of the option. The second 407 and third columns indicate whether the option can be handled by the 408 getsockopt() system call and/or by the setsockopt() system call. The 409 fourth column provides a brief description of the socket option. The 410 fifth column shows the type of data structure specified along with 411 the socket option. By default, the data structure type is an 412 integer. 414 +-----------------------------+-----+-----+-----------------+-------+ 415 | optname | get | set | description | dtype | 416 +-----------------------------+-----+-----+-----------------+-------+ 417 | SHIM_ASSOCIATED | o | | Get the | int | 418 | | | | parameter (0 or | | 419 | | | | 1) which | | 420 | | | | indicates | | 421 | | | | whether the | | 422 | | | | socket is | | 423 | | | | associated (1) | | 424 | | | | with any shim | | 425 | | | | context or not | | 426 | | | | (0). | | 427 | SHIM_DONTSHIM | o | o | Get or set the | int | 428 | | | | parameter which | | 429 | | | | indicates | | 430 | | | | whether to | | 431 | | | | employ the | | 432 | | | | multihoming | | 433 | | | | support by the | | 434 | | | | shim sub-layer | | 435 | | | | or not. | | 436 | SHIM_HOT_STANDBY | o | o | Get or set the | int | 437 | | | | parameter to | | 438 | | | | request the | | 439 | | | | shim sub-layer | | 440 | | | | to prepare a | | 441 | | | | hot-standby | | 442 | | | | connection. | | 443 | SHIM_LOC_LOCAL_PREF | o | o | Get or set the | Note | 444 | | | | preferred | 1 | 445 | | | | locator on the | | 446 | | | | local side for | | 447 | | | | the context | | 448 | | | | associated with | | 449 | | | | the socket. | | 450 | SHIM_LOC_PEER_PREF | o | o | Get or set the | Note | 451 | | | | preferred | 1 | 452 | | | | locator on the | | 453 | | | | remote side for | | 454 | | | | the context | | 455 | | | | associated with | | 456 | | | | the socket. | | 457 | SHIM_LOC_LOCAL_RECV | o | o | Request the | int | 458 | | | | shim sub-layer | | 459 | | | | to store the | | 460 | | | | destination | | 461 | | | | locator of the | | 462 | | | | received IP | | 463 | | | | packet in an | | 464 | | | | ancillary data | | 465 | | | | object. | | 466 | SHIM_LOC_PEER_RECV | o | o | Request the | int | 467 | | | | shim sub-layer | | 468 | | | | to store the | | 469 | | | | source locator | | 470 | | | | of the received | | 471 | | | | IP packet in an | | 472 | | | | ancillary data | | 473 | | | | object. | | 474 | SHIM_LOC_LOCAL_SEND | o | o | Get or set the | Note | 475 | | | | source locator | 1 | 476 | | | | of outgoing IP | | 477 | | | | packets. | | 478 | SHIM_LOC_PEER_SEND | o | o | Get or set the | Note | 479 | | | | destination | 1 | 480 | | | | locator of | | 481 | | | | outgoing IP | | 482 | | | | packets. | | 483 | SHIM_LOCLIST_LOCAL | o | o | Get or set the | Note | 484 | | | | list of | 2 | 485 | | | | locators | | 486 | | | | associated with | | 487 | | | | the local EID. | | 488 | SHIM_LOCLIST_PEER | o | o | Get or set the | Note | 489 | | | | list of | 2 | 490 | | | | locators | | 491 | | | | associated with | | 492 | | | | the peer's EID. | | 493 | SHIM_APP_TIMEOUT | o | o | Get or set the | int | 494 | | | | Send Timeout | | 495 | | | | value of the | | 496 | | | | REAP protocol. | | 497 | SHIM_PATHEXPLORE | o | o | Get or set | Note | 498 | | | | parameters for | 3 | 499 | | | | path | | 500 | | | | exploration and | | 501 | | | | failure | | 502 | | | | detection. | | 503 | SHIM_CONTEXT_DEFERRED_SETUP | o | | Get the | int | 504 | | | | parameter which | | 505 | | | | indicates | | 506 | | | | whether | | 507 | | | | deferred | | 508 | | | | context setup | | 509 | | | | is supported or | | 510 | | | | not. | | 511 +-----------------------------+-----+-----+-----------------+-------+ 513 Table 1: Socket options for multihoming shim sub-layer 515 Note 1: Pointer to a shim_locator which is defined in Section 8. 517 Note 2: Pointer to an array of shim_locator. 519 Note 3: Pointer to a shim_pathexplore which is defined in Section 8. 521 Figure 2 illustrates how the shim specific socket options fit into 522 the system model of socket API. The figure shows that the shim sub- 523 layer and the additional protocol components (IPv4 and IPv6) below 524 the shim sub-layer are new to the system model. As previously 525 mentioned, all the shim specific socket options are defined at the 526 SOL_SHIM level. This design choice brings the following advantages: 528 1. The existing sockets API continue to work at the layer above the 529 shim sub-layer. That is, those legacy API handle IP addresses as 530 identifiers. 531 2. With newly defined socket options for the shim sub-layer, the 532 application obtains additional control of locator management. 533 3. The shim specific socket options can be kept independent from 534 address family (IPPROTO_IP or IPPROTO_IPV6) and transport 535 protocol (IPPROTO_TCP or IPPROTO_UDP). 537 s1 s2 s3 s4 538 | | | | 539 +----------------|--|-------|--|----------------+ 540 | +-------+ +-------+ | 541 | IPPROTO_TCP | TCP | | UDP | | 542 | +-------+ +-------+ | 543 | | \ / | | 544 | | ----- | | 545 | | / \ | | 546 | +------+ +------+ | 547 | IPPROTO_IP | IPv4 | | IPv6 | IPPROTO_IPV6 | 548 | +------+ +------+ | 549 | \ / SOL_SOCKET 550 | +--------\-------/--------+ | 551 | SOL_SHIM | shim | | 552 | +--------/-------\--------+ | 553 | / \ | 554 | +------+ +------+ | 555 | | IPv4 | | IPv6 | | 556 | +------+ +------+ | 557 | | | | 558 +------------------|----------|-----------------+ 559 | | 560 IPv4 IPv6 561 Datagram Datagram 563 Figure 2: System model of sockets API with shim sub-layer 565 6.1. SHIM_ASSOCIATED 567 The SHIM_ASSOCIATED option is used to check whether the socket is 568 associated with any shim context or not. 570 This option is meaningful when the locator information of the 571 received IP packet does not tell whether the identifier/locator 572 adaptation is performed or not. Note that the EID pair and the 573 locator pair may be identical in some cases. 575 This option can be specified by getsockopt(). Thus, the option is 576 read-only and the result (0/1/2) is set in the option value (the 577 fourth argument of getsockopt()). 579 When the application specifies the socket option to an unconnected 580 socket, an error code EOPNOTSUPP is returned to the application. 582 The data type of the option value is an integer. The option value 583 indicates the presence of shim context. A return value 1 means that 584 the socket is associated with a shim context at the shim sub-layer. 585 A return value 0 indicates that there is no shim context associated 586 with the socket. A return value 2 means that it is not known whether 587 the socket is associated with a shim context or not, and this must be 588 returned only when the socket is unconnected. In other words, the 589 returned value must be 0 or 1 when the socket is connected. 591 For example, the option can be used by the application as follows: 593 int optval; 594 int optlen = sizeof(optval); 596 getsockopt(fd, SOL_SHIM, SHIM_ASSOCIATED, &optval, &optlen); 598 6.2. SHIM_DONTSHIM 600 The SHIM_DONTSHIM option is used to request the shim layer not to 601 provide the multihoming support for the communication established 602 over the socket. 604 The data type of the option value is an integer, and it takes 0 or 1. 605 An option value 0 means that the shim sub-layer is employed if 606 available. An option value 1 means that the application does not 607 want the shim sub-layer to provide the multihoming support for the 608 communication established over the socket. 610 Default value is set as 0, which means that the shim sub-layer 611 performs identifier/locator adaptation if available. 613 Any attempt to disable the multihoming shim support MUST be made by 614 the application before the socket is connected. If an application 615 makes such an attempt for a connected-socket, an error code 616 EOPNOTSUPP MUST be returned. 618 For example, an application can request the system not to apply the 619 multihoming support as follows: 621 int optval; 623 optval = 1; 625 setsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, sizeof(optval)); 627 For example, the application can check the option value as follows: 629 int optval; 630 int len; 632 len = sizeof(optval); 634 getsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, &len); 636 6.3. SHIM_HOT_STANDBY 638 The SHIM_HOT_STANDBY option is used to control the shim sub-layer 639 whether to employ a hot-standby connection for the socket or not. A 640 hot-standby connection is an alternative working locator pair to the 641 current locator pair. This option is effective only when there is a 642 shim context associated with the socket. 644 The data type of the option value is an integer. 646 The option value can be set by setsockopt(). 648 The option value can be read by getsockopt(). 650 By default, the value is set to 0, meaning that hot-standby 651 connection is disabled. 653 When the application specifies the socket option to an unconnected 654 socket, an error code EOPNOTSUPP is returned to the application. 656 When there is no shim context associated with the socket, an error 657 code ENOENT is returned to the application. 659 For example, an application can request establishment of a hot- 660 standby connection by using the socket option as follows: 662 int optval; 664 optval = 1; 666 setsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, 667 sizeof(optval)); 669 For example, an application can get the option value by using the 670 socket option as follows: 672 int optval; 673 int len; 675 len = sizeof(optval); 676 getsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, &len); 678 6.4. SHIM_LOC_LOCAL_PREF 680 The SHIM_LOC_LOCAL_PREF option is used to get or set preference for a 681 source locator for outbound traffic within a given context. This 682 option is effective only when there is a shim context associated with 683 the socket. 685 The preference of a locator is defined by a combination of priority 686 and weight as per DNS SRV[RFC2782]. Note that the SHIM6 base 687 protocol defines preference of locator in the same way. 689 The data type of the option value is a pointer to a locator 690 information data structure which is defined in Section 8. 692 By default, the option value is set to NULL, meaning that the option 693 is disabled. 695 The preferred locator can be set by setsockopt(). The shim sub-layer 696 shall verify requested locator before it updates the preferred 697 locator. 699 An application can get the preferred locator by getsockopt(). 701 An application needs to get or set preference for each address, one 702 by one. 704 When the application specifies the socket option to an unconnected 705 socket, an error code EOPNOTSUPP is returned to the application. 707 When there is no shim context associated with the socket, an error 708 code ENOENT is returned to the application. 710 An error EINVALIDLOCATOR is returned when the validation of the 711 specified locator fails. 713 For example, an application can set the preferred locator by using 714 the socket option as follows. Note that some members of the 715 shim_locator (lc_ifidx and lc_flags) are ignored in the set 716 operation. 718 struct shim_locator lc; 719 struct in6_addr ip6; 721 /* ...set the locator (ip6)... */ 723 memset(&lc, 0, sizeof(shim_locator)); 724 lc.lc_family = AF_INET6; /* IPv6 */ 725 lc.lc_ifidx = 0; 726 lc.lc_flags = 0; 727 lc.lc_prio = 1; 728 lc.lc_weight = 10; 729 memcpy(&lc.lc_addr, &ip6, sizeof(in6_addr)); 731 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, 732 sizeof(optval)); 734 For example, an application can get the preferred locator by using 735 the socket option as follows. 737 struct shim_locator lc; 738 int len; 740 len = sizeof(lc); 742 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, &len); 744 6.5. SHIM_LOC_PEER_PREF 746 The SHIM_LOC_PEER_PREF option is used to get or set preference of a 747 destination locator for outbound traffic within a given context. 748 This option is effective only when there is a shim context associated 749 with the socket. 751 As defined earlier, the preference of a locator is defined by a 752 combination of priority and weight as per DNS SRV[RFC2782]. When 753 there are more than one candidate destination locators, the shim sub- 754 layer makes selection based on the priority and weight specified for 755 each locator. 757 The data type of the option value is a pointer to the locator 758 information data structure which is defined in Section 8. 760 By default, the option value is set to NULL, meaning that the option 761 is disabled. 763 The preferred locator can be set by setsockopt(). The shim sub-layer 764 shall verify requested locator before it updating the preferred 765 locator. 767 An application can get the preferred locator by getsockopt(). 769 When the application specifies the socket option to an unconnected 770 socket, an error code EOPNOTSUPP is returned to the application. 772 When there is no shim context associated with the socket, an error 773 code ENOENT is returned to the application. 775 An error EINVALIDLOCATOR is returned when the validation of the 776 requested locator fails. 778 An error EUNREACHABLELOCATOR is returned when the requested locator 779 is determined to be not reachable according to a reachability check. 781 The usage of the option is same as that of SHIM_LOC_LOCAL_PREF. Note 782 that some members of the shim_locator (lc_ifidx and lc_flags) are 783 ignored in the set operation. 785 6.6. SHIM_LOC_LOCAL_RECV 787 The SHIM_LOC_LOCAL_RECV option can be used to request the shim sub- 788 layer to store the destination locator of the received IP packet in 789 an ancillary data object which can be accessed by recvmsg(). This 790 option is effective only when there is a shim context associated with 791 the socket. 793 The data type of the option value is integer. The option value 794 should be binary (0 or 1). By default, the option value is set to 0, 795 meaning that the option is disabled. 797 An application can set the option value by setsockopt(). 799 An application can get the option value by getsockopt(). 801 See Section 7 for the procedure to access locator information stored 802 in the ancillary data objects. 804 When the application specifies the socket option to an unconnected 805 socket, an error code EOPNOTSUPP is returned to the application. 807 When there is no shim context associated with the socket, an error 808 code ENOENT is returned to the application. 810 For example, an application can request the shim sub-layer to store 811 destination locator by using the socket option as follows. 813 int optval; 815 optval = 1; 817 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, 818 sizeof(optval)); 820 For example, an application can get the option value as follows. 822 int optval; 823 int len; 825 len = sizeof(optval); 827 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, &len); 829 6.7. SHIM_LOC_PEER_RECV 831 The SHIM_LOC_PEER_RECV option is used to request the shim sub-layer 832 to store the source locator of the received IP packet in an ancillary 833 data object which can be accessed by recvmsg(). This option is 834 effective only when there is a shim context associated with the 835 socket. 837 The data type of the option value is integer. The option value 838 should be binary (0 or 1). By default, the option value is set to 0, 839 meaning that the option is disabled. 841 The option value can be set by setsockopt(). 843 The option value can be read by getsockopt(). 845 See Section 7 for the procedure to access locator information stored 846 in the ancillary data objects. 848 When the application specifies the socket option to an unconnected 849 socket, an error code EOPNOTSUPP is returned to the application. 851 When there is no shim context associated with the socket, an error 852 code ENOENT is returned to the application. 854 The usage of the option is same as that of SHIM_LOC_LOCAL_RECV 855 option. 857 6.8. SHIM_LOC_LOCAL_SEND 859 The SHIM_LOC_LOCAL_SEND option is used to request the shim sub-layer 860 to use a specific locator as the source locator for the IP packets to 861 be sent from the socket. This option is effective only when there is 862 a shim context associated with the socket. 864 The data type of option value is pointer to shim_locator data 865 structure. 867 An application can set the local locator by setsockopt() providing a 868 locator which is stored in a shim_locator data structure. When a 869 zero-filled locator is specified, pre-existing setting of local 870 locator is inactivated. 872 An application can get the local locator by getsockopt(). 874 When the application specifies the socket option to an unconnected 875 socket, an error code EOPNOTSUPP is returned to the application. 877 When there is no shim context associated with the socket, an error 878 code ENOENT is returned to the application. 880 An error EINVALIDLOCATOR is returned when an invalid locator is 881 specified. 883 For example, an application can request the shim sub-layer to use a 884 specific local locator by using the socket option as follows. 886 struct shim_locator locator; 887 struct in6_addr ia6; 889 /* an IPv6 address preferred for the source locator is copied 890 to the parameter ia6 */ 892 memset(&locator, 0, sizeof(locator)); 894 /* fill shim_locator data structure */ 895 locator.lc_family = AF_INET6; 896 locator.lc_ifidx = 1; 897 locator.lc_flags = 0; 898 locator.lc_prio = 0; 899 locator.lc_weight = 0; 900 memcpy(&locator.lc_addr, &ia6, sizeof(ia6)); 902 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, 903 sizeof(locator)); 905 For example, an application can get the designated local locator by 906 using the socket option as follows: 908 struct shim_locator locator; 910 memset(&locator, 0, sizeof(locator)); 912 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, 913 sizeof(locator)); 915 /* check locator */ 917 6.9. SHIM_LOC_PEER_SEND 919 The SHIM_LOC_PEER_SEND option is used to request the shim sub-layer 920 to use a specific locator for the destination locator of IP packets 921 to be sent from the socket. This option is effective only when there 922 is a shim context associated with the socket. 924 The data type of the option value is a pointer to shim_locator data 925 structure. 927 An application can set the remote locator by setsockopt() providing a 928 locator which is stored in a shim_locator data structure. When a 929 zero-filled locator is specified, pre-existing setting of remote 930 locator is inactivated. 932 An application can get the specified remote locator by getsockopt(). 934 The difference between the SHIM_LOC_PEER_SEND option and the 935 SHIM_LOC_PEER_PREF option is that the former guarantee the use of 936 requested locator when applicable whereas the latter does not. 938 When the application specifies the socket option to an unconnected 939 socket, an error code EOPNOTSUPP is returned to the application. 941 When there is no shim context associated with the socket, an error 942 code ENOENT is returned to the application. 944 An error EINVALIDLOCATOR is returned when the validation of the 945 requested locator fails. 947 An error EUNVERIFIEDLOCATOR is returned when reachability for the 948 requested locator has not been verified yet. 950 An error EUNREACHABLELOCATOR is returned when the requested locator 951 is determined to be not reachable according to a reachability check. 953 The usage of the option is the same as that of SHIM_LOC_LOCAL_SEND 954 option. 956 6.10. SHIM_LOCLIST_LOCAL 958 The SHIM_LOCLIST_LOCAL option is used to get or set the locator list 959 associated with the local EID of the shim context associated with the 960 socket. This option is effective only when there is a shim context 961 associated with the socket. 963 The data type of the option value is a pointer to the buffer in which 964 a locator list is stored. See Section 8 for the data structure for 965 storing the locator information. By default, the option value is set 966 to NULL, meaning that the option is disabled. 968 An application can get the locator list by getsockopt(). Note that 969 the size of the buffer pointed to by the optval argument should be 970 large enough to store an array of locator information. The number of 971 the locator information is not known beforehand. 973 The local locator list can be set by setsockopt(). The buffer 974 pointed to by the optval argument should contain an array of locator 975 structures. 977 When the application specifies the socket option to an unconnected 978 socket, an error code EOPNOTSUPP is returned to the application. 980 When there is no shim context associated with the socket, an error 981 code ENOENT is returned to the application. 983 An error EINVALIDLOCATOR is returned when the validation of any of 984 the specified locators failed. 986 An error ETOOMANYLOCATORS is returned when the number of locators 987 specified exceeds the limit (SHIM_MAX_LOCATORS), or when the size of 988 the buffer provided by the application is not large enough to store 989 the locator list provided by the shim sub-layer. 991 For example, an application can set a list of locators to be 992 associated with the local EID by using the socket option as follows. 993 Note that IPv4 locator can be handled by HIP and not by SHIM6. 995 struct shim_locator locators[SHIM_MAX_LOCATORS]; 996 struct sockaddr_in *sin; 997 struct sockaddr_in6 *sin6; 999 memset(locators, 0, sizeof(locators)); 1001 ... 1003 /* obtain local IP addresses from local interfaces */ 1005 ... 1007 /* first locator (an IPv6 address) */ 1008 locators[0].lc_family = AF_INET6; 1009 locators[0].lc_ifidx = 0; 1010 locators[0].lc_flags = 0; 1011 locators[0].lc_prio = 1; 1012 locators[0].lc_weight = 0; 1013 memcpy(&locators[0].lc_addr, &sa6->sin6_addr, 1014 sizeof(sa6->sin6_addr)); 1016 ... 1018 /* second locator (an IPv4 address) */ 1019 locators[1].lc_family = AF_INET; 1020 locators[1].lc_ifidx = 0; 1021 locators[1].lc_flags = 0; 1022 locators[1].lc_prio = 0; 1023 locators[1].lc_weight = 0; 1024 memcpy(&locators[1].lc_addr, &sa->sin_addr, 1025 sizeof(sa->sin_addr)); 1027 setsockopt(fd, SOL_SHIM, SHIM_LOCLIST_LOCAL, locators, 1028 sizeof(locators)); 1030 For example, an application can get a list of locators that are 1031 associated with the local EID by using the socket option as follows. 1033 struct shim_locator locators[SHIM_MAX_LOCATORS]; 1035 memset(locators, 0, sizeof(locators)); 1037 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, locators, 1038 sizeof(locators)); 1040 /* parse locators */ 1041 ... 1043 6.11. SHIM_LOCLIST_PEER 1045 The SHIM_LOCLIST_PEER option is used to get or set the locator list 1046 associated with the peer EID of the shim context associated with the 1047 socket. This option is effective only when there is a shim context 1048 associated with the socket. 1050 The data type of the option value is a pointer to the buffer where a 1051 locator list is stored. See Section 8 for the data structure for 1052 storing the locator information. By default, the option value is set 1053 to NULL, meaning that the option is disabled. 1055 An application can get the locator list by getsockopt(). Note that 1056 the size of the buffer pointed to by the optval argument should be 1057 large enough to store an array of locator information. The number of 1058 the locator information is not known beforehand. 1060 An application can set the locator list by setsockopt(). The buffer 1061 pointed to by the optval argument should contain an array of locator 1062 list. 1064 When the application specifies the socket option to an unconnected 1065 socket, an error code EOPNOTSUPP is returned to the application. 1067 When there is no shim context associated with the socket, an error 1068 code ENOENT is returned to the application. 1070 An error EINVALIDLOCATOR is returned when the validation of any of 1071 the specified locators failed. 1073 An error EUNVERIFIEDLOCATOR is returned when reachability for the 1074 requested locator has not been verified yet. 1076 An error EUNREACHABLELOCATOR is returned when the requested locator 1077 is determined to be not reachable according to a reachability check. 1079 An error ETOOMANYLOCATORS is returned when the number of locators 1080 specified exceeds the limit (SHIM_MAX_LOCATORS), or when the size of 1081 the buffer provided by the application is not large enough to store 1082 the locator list provided by the shim sub-layer. 1084 The usage of the option is same as that of SHIM_LOCLIST_LOCAL. 1086 6.12. SHIM_APP_TIMEOUT 1088 The SHIM_APP_TIMEOUT option is used to get or set the Send Timeout 1089 value of the REAP protocol[RFC5534]. This option is effective only 1090 when there is a shim context associated with the socket. 1092 The data type of the option value is an integer. The value indicates 1093 the period of timeout in seconds to send a REAP Keepalive message 1094 since the last outbound traffic. By default, the option value is set 1095 to 0, meaning that the option is disabled. When the option is 1096 disabled, the REAP mechanism follows its default value of Send 1097 Timeout value as specified in [RFC5534] 1099 When the application specifies the socket option to an unconnected 1100 socket, an error code EOPNOTSUPP is returned to the application. 1102 When there is no shim context associated with the socket, an error 1103 code ENOENT is returned to the application. 1105 When there is no REAP protocol instance on the system, an error code 1106 EOPNOTSUPP is returned to the application. 1108 For example, an application can set the timeout value by using the 1109 socket option as follows. 1111 int optval; 1113 optval = 15; /* 15 seconds */ 1115 setsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, 1116 sizeof(optval)); 1118 For example, an application can get the timeout value by using the 1119 socket option as follows. 1121 int optval; 1122 int len; 1124 len = sizeof(optval); 1126 getsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, &len); 1128 6.13. SHIM_PATHEXPLORE 1130 The application may use this socket option to get or set parameters 1131 concerning path exploration. Path exploration is a procedure to find 1132 an alternative locator pair to the current locator pair. As the REAP 1133 specification defines, a peer may send Probe messages to find an 1134 alternative locator pair. 1136 This option is effective only when there is a shim context associated 1137 with the socket. 1139 The data type of the option value is a pointer to the buffer where a 1140 set of information for path exploration is stored. The data 1141 structure is defined in Section 8. 1143 By default, the option value is set to NULL, meaning that the option 1144 is disabled. 1146 When the application specifies the socket option to an unconnected 1147 socket, an error code EOPNOTSUPP is returned to the application. 1149 When there is no shim context associated with the socket, an error 1150 code ENOENT is returned to the application. 1152 For example, an application can set parameters for path exploration 1153 by using the socket option as follows. 1155 struct shim6_pathexplore pe; 1157 pe.pe_probenum = 4; /* times */ 1158 pe.pe_keepaliveto = 10; /* seconds */ 1159 pe.pe_initprobeto = 500; /* milliseconds */ 1160 pe.pe_reserved = 0; 1162 setsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, sizeof(pe)); 1164 For example, an application can get parameters for path exploration 1165 by using the socket option as follows. 1167 struct shim6_pathexplore pe; 1168 int len; 1170 len = sizeof(pe); 1172 getsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, &len); 1174 6.14. SHIM_DEFERRED_CONTEXT_SETUP 1176 The SHIM_DEFERRED_CONTEXT_SETUP option is used to check whether 1177 deferred context setup is possible or not. Deferred context setup 1178 means that the context is established in parallel with the data 1179 communication. Note that SHIM6 supports deferred context setup and 1180 HIP does not because EIDs in HIP (i.e., Host Identifiers) are non- 1181 routable. 1183 The data type for the option value is an integer. The option value 1184 should be binary (0 or 1). The option value 1 means that the shim 1185 sub-layer supports deferred context setup. 1187 When the application specifies the socket option to an unconnected 1188 socket, an error code EOPNOTSUPP is returned to the application. 1190 For example, an application can check whether deferred context setup 1191 is possible or not as follows: 1193 int optval; 1194 int len; 1196 len = sizeof(optval); 1198 getsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, 1199 &optval, &len); 1201 6.15. Applicability 1203 All the socket options defined in this section except for the 1204 SHIM_DONTSHIM option are applicable to applications that use 1205 connected sockets. 1207 All the socket options defined in this section except for the 1208 SHIM_ASSOCIATED, SHIM_DONTSHIM and SHIM_CONTEXT_DEFERRED_SETUP 1209 options are effective only when there is a shim context associated 1210 with the socket. 1212 6.16. Error Handling 1214 If successful, getsockopt() and setsockopt() return 0; otherwise, the 1215 functions return -1 and set errno to indicate an error. 1217 The following are new error values defined for some shim specific 1218 socket options indicating that the getsockopt() or setsockopt() 1219 finished incompletely: 1221 EINVALIDLOCATOR 1222 This indicates that the locator is not part of the HBA 1223 set[RFC5535] within the shim context associated with the socket. 1224 EUNVERIFIEDLOCATOR 1225 This indicates that the reachability of the locator has not been 1226 confirmed. This error is applicable to only peer's locator. 1227 EUNREACHABLELOCATOR 1228 This indicates that the locator is not reachable according to the 1229 result of the reachability check. This error is applicable to 1230 only peer's locator. 1232 7. Ancillary Data for Multihoming Shim Sub-layer 1234 This section provides definitions of ancillary data to be used for 1235 locator management and notification from/to the shim sub-layer to/ 1236 from application. 1238 When the application performs locator management by sendmsg() or 1239 recvmsg(), a member of the msghdr structure (given in Figure 3) 1240 called msg_control holds a pointer to the buffer in which one or more 1241 shim specific ancillary data objects may be stored. An ancillary 1242 data object can store a single locator. It should be possible to 1243 process the shim specific ancillary data object by the existing 1244 macros defined in the Posix standard and [RFC3542]. 1246 struct msghdr { 1247 caddr_t msg_name; /* optional address */ 1248 u_int msg_namelen; /* size of address */ 1249 struct iovec *msg_iov; /* scatter/gather array */ 1250 u_int msg_iovlen; /* # elements in msg_iov */ 1251 caddr_t msg_control; /* ancillary data, see below */ 1252 u_int msg_controllen; /* ancillary data buffer len */ 1253 int msg_flags; /* flags on received message */ 1254 }; 1256 Figure 3: msghdr structure 1258 In the case of unconnected socket, msg_name stores the socket address 1259 of the peer which should be considered to be an identifier rather 1260 than a locator. SHIM_LOC_PEER_RECV should be used to get the locator 1261 of the peer node. 1263 Table 2 is a list of the shim specific ancillary data which can be 1264 used for locator management by recvmsg() or sendmsg(). In any case, 1265 the value of cmsg_level must be set as SOL_SHIM. 1267 +---------------------+-----------+-----------+-----------------+ 1268 | cmsg_type | sendmsg() | recvmsg() | cmsg_data[] | 1269 +---------------------+-----------+-----------+-----------------+ 1270 | SHIM_LOC_LOCAL_RECV | | o | Note 1 | 1271 | SHIM_LOC_PEER_RECV | | o | Note 1 | 1272 | SHIM_LOC_LOCAL_SEND | o | | Note 1 | 1273 | SHIM_LOC_PEER_SEND | o | | Note 1 | 1274 | SHIM_FEEDBACK | o | | shim_feedback{} | 1275 +---------------------+-----------+-----------+-----------------+ 1277 Table 2: Shim specific ancillary data 1279 Note 1: cmsg_data[] within msg_control includes a single 1280 sockaddr_in{} or sockaddr_in6{} and padding if necessary 1282 7.1. Get Locator from Incoming Packet 1284 An application can get locator information from the received IP 1285 packet by specifying the shim specific socket options for the socket. 1286 When SHIM_LOC_LOCAL_RECV and/or SHIM_LOC_PEER_RECV socket options are 1287 set, the application can retrieve local and/or remote locator from 1288 the ancillary data. 1290 When there is no shim context associated with the socket, the shim 1291 sub-layer MUST return zero-filled locator information to the 1292 application. 1294 7.2. Set Locator for Outgoing Packet 1296 An application can specify the locators to be used for transmitting 1297 an IP packet by sendmsg(). When the ancillary data of cmsg_type 1298 SHIM_LOC_LOCAL_SEND and/or SHIM_LOC_PEER_SEND are specified, the 1299 application can explicitly specify the source and/or the destination 1300 locators to be used for the communication over the socket. If the 1301 specified locator pair is verified, the shim sub-layer overrides the 1302 locator(s) of the outgoing IP packet. Note that the effect is 1303 limited to the datagram transmitted by the sendmsg(). 1305 When there is no shim context associated with the socket, an error 1306 code ENOENT is returned to the application. 1308 An error code EINVALIDLOCATOR is returned when validation of the 1309 specified locator fails. 1311 An error EUNVERIFIEDLOCATOR is returned when reachability for the 1312 requested locator has not been verified yet. The application is 1313 recommended to use another destination locator until the reachability 1314 check for the requested locator is done. 1316 An error EUNREACHABLELOCATOR is returned when the requested locator 1317 is determined to be not reachable according to a reachability check. 1318 The application is recommended to use another destination locator 1319 when receiving the error. 1321 7.3. Notification from Application to Multihoming Shim Sub-layer 1323 An application may provide feedback to the shim sub-layer about the 1324 communication status. Such feedback are useful for the shim sub- 1325 layer to monitor the reachability status of the currently used 1326 locator pair in a given shim context. 1328 The notification can be made by sendmsg() specifying a new ancillary 1329 data called SHIM_FEEDBACK. The ancillary data can be handled by 1330 specifying SHIM_FEEDBACK option in cmsg_type. 1332 When there is no shim context associated with the socket, an error 1333 code ENOENT is returned to the application. 1335 See Section 8.3 for details of the data structure to be used. 1337 It is outside the scope of this document how the shim sub-layer would 1338 react when a feedback is provided by an application. 1340 7.4. Applicability 1342 All the ancillary data for the shim sub-layer is applicable to 1343 connected sockets. 1345 Care is needed when the SHIM_LOC_*_RECV socket option is used for 1346 stream-oriented sockets (e.g., TCP sockets) because there is no one- 1347 to-one mapping between a single send or receive operation and the 1348 data (e.g., a TCP segment) being received. In other words, there is 1349 no gurantee that the locator(s) set in the SHIM_LOC_*_RECV ancillary 1350 data is identical to the locator(s) that appear in the IP packets 1351 received. The shim sub-layer SHOULD provide the latest locator 1352 information to the application in response to the SHIM_LOC_*_RECV 1353 socket option. 1355 8. Data Structures 1357 This section gives data structures for the shim sub-layer. These 1358 data structures are either used as a parameter for setsockopt() or 1359 getsockopt() (as mentioned in Section 6) or as a parameter for 1360 ancillary data to be processed by sendmsg() or recvmsg() (as 1361 mentioned in Section 7). 1363 8.1. Placeholder for Locator Information 1365 As defined in Section 6, the SHIM_LOC_*_PREF, SHIM_LOC_*_SEND, and 1366 SHIM_LOCLIST_* socket options need to handle one or more locator 1367 information. Locator information includes not only the locator 1368 itself but also additional information about the locator which is 1369 useful for locator management. A new data structure is defined to 1370 serve as a placeholder for the locator information. 1372 Figure 4 illustrates the data structure called shim_locator which 1373 stores a locator information. 1375 struct shim_locator { 1376 uint8_t lc_family; /* address family */ 1377 uint8_t lc_proto; /* protocol */ 1378 uint16_t lc_port; /* port number */ 1379 uint16_t lc_prio; /* preference value */ 1380 uint16_t lc_weight; /* weight */ 1381 uint32_t lc_ifidx; /* interface index */ 1382 struct in6_addr lc_addr; /* address */ 1383 uint16_t lc_flags; /* flags */ 1384 }; 1386 Figure 4: shim locator structure 1388 lc_family 1389 Address family of the locator (e.g. AF_INET, AF_INET6). It is 1390 required that the parameter contains non-zero value indicating the 1391 exact address family of the locator. 1392 lc_proto 1393 Internet Protocol number for the protocol which is used to handle 1394 locator behind NAT. Typically, this value is set as UDP (17) when 1395 the locator is a UDP encapsulation interface. 1396 lc_port 1397 Port number which is used for handling locator behind NAT. 1398 lc_prio 1399 The priority of the locator. The range is 0-65535. The lowest 1400 priority value means the highest priority. 1401 lc_weight 1402 The weight value indicates a relative weight for locators with the 1403 same priority value. The range is 0-65535. A locator with higher 1404 weight value is prioritized over the other locators with lower 1405 weight values. 1406 lc_ifidx 1407 Interface index of the network interface to which the locator is 1408 assigned. This field is only used in a read (getsockopt()) 1409 operation. 1410 lc_addr 1411 Contains the locator. In the case where a locator whose size is 1412 smaller than 16 bytes, an encoding rule should be provided for 1413 each locator of a given address family. For instance, in case of 1414 AF_INET (IPv4), the locator should be in the format of an IPv4- 1415 mapped IPv6 address as defined in [RFC4291]. 1416 lc_flags 1417 Each bit of the flags represents a specific characteristics of the 1418 locator. Hash Based Address (HBA) is defined as 0x01. 1419 Cryptographically Generated Address (CGA) is defined as 0x02. 1421 8.1.1. Handling Locator behind NAT 1423 Note that the locator information MAY contain a locator behind a 1424 Network Address Translator (NAT). Such a situation may arise when 1425 the host is behind the NAT and uses a local address as a source 1426 locator to communicate with the peer. Note that a NAT traversal 1427 mechanism for HIP is defined, which allows HIP host to tunnel control 1428 and data traffic over UDP[RFC5770]. Note also that the locator 1429 behind NAT is not necessarily an IPv4 address but it can be an IPv6 1430 address. Below is an example where the application sets a UDP 1431 encapsulation interface as a source locator when sending IP packets. 1433 struct shim_locator locator; 1434 struct in6_addr ia6; 1436 /* copy the private IPv4 address to the ia6 as an IPv4-mapped 1437 IPv6 address */ 1439 memset(&locator, 0, sizeof(locator)); 1441 /* fill shim_locator data structure */ 1442 locator.lc_family = AF_INET; 1443 locator.lc_proto = IPPROTO_UDP; 1444 locator.lc_port = 50500; 1445 locator.lc_flags = 0; 1446 locator.lc_prio = 0; 1447 locator.lc_weight = 0; 1448 locator.lc_ifidx = 3; 1450 memcpy(&locator.lc_addr, &ia6, sizeof(ia6)); 1452 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, 1453 sizeof(locator)); 1455 Figure 5: Handling locator behind NAT 1457 8.2. Path Exploration Parameter 1459 As defined in Section 6, SHIM_PATHEXPLORE allows application to set 1460 or read the parameters for path exploration and failure detection. A 1461 new data structure called shim_pathexplore is defined to store the 1462 necessary parameters. Figure 6 illustrates the data structure. The 1463 data structure can be passed to getsockopt() or setsockopt() as an 1464 argument. 1466 struct shim_pathexplore { 1467 uint16_t pe_probenum; /* # of initial probes */ 1468 uint16_t pe_keepaliveto; /* Keepalive Timeout */ 1469 uint16_t pe_keepaliveint /* Keepalive Interval */ 1470 uint16_t pe_initprobeto; /* Initial Probe Timeout */ 1471 uint32_t pe_reserved; /* reserved */ 1472 }; 1474 Figure 6: path explore structure 1476 pe_probenum 1477 Indicates the number of initial probe messages to be sent. 1478 Default value of this parameter should follow what is specified in 1479 [RFC5534]. 1480 pe_keepaliveto 1481 Indicates timeout value in seconds for detecting a failure when 1482 the host does not receive any packets for a certain period of time 1483 while there is outbound traffic. When the timer expires, path 1484 exploration procedure will be carried out by sending a REAP Probe 1485 message. Default value of this parameter should follow what is 1486 specified in [RFC5534]. 1487 pe_keepaliveint 1488 Indicates interval of REAP keepalive messages in seconds to be 1489 sent by the host when there is no outbound traffic to the peer 1490 host. The value shall be set according to the recommendation 1491 given in [RFC5534]. 1492 pe_initprobeto 1493 Indicates retransmission timer of REAP Probe message in 1494 milliseconds. Note that this timer is applied before exponential 1495 back-off is started. A REAP Probe message for the same locator 1496 pair may be retransmitted. Default value of this parameter should 1497 follow what is specified in [RFC5534]. 1498 pe_reserved 1499 A reserved field for future extension. By default, the field 1500 should be initialized to zero. 1502 8.3. Feedback Information 1504 As mentioned in Section 7.3, applications can inform the shim sub- 1505 layer about the status of unicast reachability of the locator pair 1506 currently in use. The feedback information can be handled by using 1507 ancillary data called SHIM_FEEDBACK. A new data structure named 1508 shim_feedback is illustrated in Figure 7. 1510 struct shim_feedback { 1511 uint8_t fb_direction; /* direction of traffic */ 1512 uint8_t fb_indicator; /* indicator (1-3) */ 1513 uint16_t fb_reserved; /* reserved */ 1514 }; 1516 Figure 7: feedback information structure 1518 direction 1519 Indicates direction of reachability between a locator pair in 1520 question. A value 0 indicates outbound and a value 1 indicates 1521 inbound direction. 1522 indicator 1523 A value indicating the degree of satisfaction of a unidirectional 1524 reachability for a given locator pair. 1525 * 0: Default value. Whenever this value is specified the 1526 feedback information must not be processed by the shim sub- 1527 layer. 1528 * 1: Unable to connect. There is no unidirectional reachability 1529 between the locator pair in question. 1530 * 2: Unsatisfactory. The application is not satisfied with the 1531 unidirectional reachability between the locator pair in 1532 question. 1533 * 3: Satisfactory. There is satisfactory unidirectional 1534 reachability between the locator pair in question. 1535 reserved 1536 Reserved field. Must be ignored by the receiver. 1538 9. System Requirements 1540 As addressed in Section 6, most of the socket options and ancillary 1541 data defined in this document are applicable to connected sockets. 1542 It is assumed that the kernel is capable of maintaining the 1543 association between a connected socket and a shim context. This 1544 requirement is considered to be reasonable because a pair of source 1545 and destination IP addresses is bound to a connected socket. 1547 10. Relation to Existing Sockets API Extensions 1549 This section explains relation between the sockets API defined in 1550 this document and the existing sockets API extensions. 1552 As mentioned in Section 6, the basic assumption is that the existing 1553 sockets API continues to work above the shim sub-layer. This means 1554 that, the existing sockets API deals with identifiers, and the 1555 sockets API defined in this document deals with locators. 1557 SHIM_LOC_LOCAL_SEND and SHIM_LOC_PEER_SEND socket options are 1558 semantically similar to the IPV6_PKTINFO socket API in the sense that 1559 both provide a means for application to set the source IP address of 1560 outbound IP packets. 1562 SHIM_LOC_LOCAL_RECV and SHIM_LOC_PEER_RECV socket options are 1563 semantically similar to the IP_RECVDSTADDR and IPV6_PKTINFO socket 1564 APIs in the sense that both provides a means for application to get 1565 the source and/or destination IP address of inbound IP packets. 1567 getsockname() and getpeername() enable application to get 'name' of 1568 the communication endpoints which is represented by a pair of IP 1569 address and port number assigned to the socket. getsockname() gives 1570 IP address and port number assigned to the socket on the local side, 1571 and getpeername() gives IP address and port number of the peer side. 1573 11. Operational Considerations 1575 This section gives operational considerations of the sockets API 1576 defined in this document. 1578 11.1. Conflict Resolution 1580 There may be a conflicting situation when different applications 1581 specify difference preference for the same shim context. For 1582 instance, application A and B may establish communication with the 1583 same EID pair while both applications have different preference in 1584 their choice of local locator. The notion of context forking in 1585 SHIM6 can resolve the conflicting situation. 1587 Socket options defined in Section 6 may cause conflicting situation 1588 when the target context is shared by multiple applications. In such 1589 a case, the socket handler should inform the shim sub-layer that 1590 context forking is required. In SHIM6, when a context is forked, an 1591 unique identifier called Forked Instance Identifier (FII) is assigned 1592 to the newly forked context. The forked context is then exclusively 1593 associated with the socket through which non-default preference value 1594 was specified. The forked context is maintained by the shim sub- 1595 layer during the lifetime of associated socket instance. When the 1596 socket is closed, the shim sub-layer SHOULD delete associated 1597 context. 1599 When the application specifies SHIM_LOC_*_SEND specifying a different 1600 source or destination locator which does not have the highest 1601 priority and weight specified by the SHIM_LOC_*_PREF, the shim sub- 1602 layer SHOULD supersede the request made by SHIM_LOC_*_SEND over the 1603 preference specified by SHIM_LOC_*_PREF. 1605 When the peer provides preferences of the locators (e.g., a SHIM6 1606 peer may send a locator with a Locator Preferences Option) which 1607 conflict with preference specified by the applications either by 1608 SHIM_LOC_PEER_SEND or SHIM_LOC_PEER_PREF, the shim sub-layer SHOULD 1609 supersede the preference made by the application over the preference 1610 specified by the peer. 1612 11.2. Incompatibility between IPv4 and IPv6 1614 The shim sub-layer performs identifier/locator adaptation. 1615 Therefore, in some cases, the whole IP header can be replaced with 1616 new IP header of a different address family (e.g. conversion from 1617 IPv4 to IPv6 or vice versa). Hence, there is an issue how to make 1618 the conversion with minimum impact. Note that this issue is common 1619 in other protocol conversion techniques 1620 [RFC2765][I-D.ietf-behave-v6v4-xlate]. 1622 As studied in the previous works on protocol 1623 conversion[RFC2765][I-D.ietf-behave-v6v4-xlate], some of the features 1624 (IPv6 routing headers, hop-by-hop extension headers, and destination 1625 headers) from IPv6 are not convertible to IPv4. In addition, notion 1626 of source routing is not exactly the same in IPv4 and IPv6. This 1627 means that an error may occur during the conversion of identifier and 1628 locator. It is outside the scope of this document to describe how 1629 the shim sub-layer should behave in such erroneous cases. 1631 12. IANA Considerations 1633 There is no IANA considerations for the socket options (SHIM_*), the 1634 ancillary data, and the socket level (SOL_SHIM) that are defined in 1635 this document. All the numbers concerned are not under the control 1636 of IETF or IANA but they are platform-specific. 1638 13. Protocol Constants and Variables 1640 This section defines protocol constants and variables. 1641 SHIM_MAX_LOCATORS The maximum number of the locators to be included 1642 in a locator list. The value is set to 32. 1644 14. Security Considerations 1646 This section gives security considerations of the API defined in this 1647 document. 1649 14.1. Treatment of Unknown Locator 1651 When sending IP packets, application may request use of unknown 1652 locator for the source and/or destination locators. Note that 1653 treatment of unknown locator can be a subject of security 1654 considerations because use of invalid source and/or destination 1655 locator may cause redirection attack. 1657 14.1.1. Treatment of Unknown Source Locator 1659 The shim sub-layer checks if the requested locator is available on 1660 any of the local interface. If not, the shim sub-layer MUST reject 1661 the request and return an error message with the EINVALIDLOCATOR code 1662 to the application. If the locator is confirmed to be available, the 1663 shim sub-layer SHOULD initiate the procedure to update the locator 1664 list. 1666 Use of the following socket options and ancillary data may require 1667 treatment of unknown source locator: 1668 o SHIM_LOC_LOCAL_SEND 1669 o SHIM_LOC_LOCAL_PREF 1670 o SHIM_LOCLIST_LOCAL 1672 14.1.2. Treatment of Unknown Destination Locator 1674 If the shim sub-layer turns out to be SHIM6, the SHIM6 layer MUST 1675 reject the request for using an unknown destination locator. 1677 If the shim sub-layer turns out to be HIP, the HIP layer MUST reject 1678 the request for using an unknown destination locator. There is, 1679 however, an exceptional case where the HIP layer SHOULD accept the 1680 request provided that the HIP association is in an UNASSOCIATED 1681 state. Details of locator handling in HIP is described in section 1682 4.6 of [I-D.ietf-hip-native-api]. 1684 Use of the following socket options and ancillary data may require 1685 treatment of unknown destination locator: 1686 o SHIM_LOC_PEER_SEND 1687 o SHIM_LOC_PEER_PREF 1688 o SHIM_LOCLIST_PEER 1690 15. Changes 1692 15.1. Changes from version 00 to version 01 1693 o Define shim_locator{} data type which is a placeholder for 1694 locator. 1695 o Define shim_pathexplore{} data type in which a set of REAP 1696 parameters are stored. 1697 o Remove descriptions about "stickiness" of socket options. 1698 o Deprecate SHIM_IF_RECV and SHIM_IF_SEND socket options. 1699 o Give default value and how to disable given socket option. 1701 15.2. Changes from version 01 to version 02 1703 o Add section describing context forking. 1704 o Rephrase conclusion section. 1705 o Separate normative references from informative references. 1706 o Remove texts from discussion section that are not relevant to the 1707 contents of the document. 1708 o Add section describing change history (this section). 1710 15.3. Changes from version 02 to version 03 1712 o Add an Appendix section describing the issue of context forking. 1714 15.4. Changes from version 03 to version 04 1716 o Updated reference. 1717 o Correct typo and grammatical errors. 1719 15.5. Changes from version 04 to version 05 1721 o Added definition of SHIM_FEEDBACK ancillary data. 1722 o Added an example of code using the SHIM_LOCLIST_LOCAL 1723 o Added SHIM_LOC_LOCAL_SEND and SHIM_LOC_PEER_SEND socket options. 1725 15.6. Changes from version 05 to version 06 1727 o Updated references. 1729 15.7. Changes from version 06 to version 07 1731 o Resolved editorial issues. 1733 15.8. Changes from version 07 to version 08 1735 No changes are made except for updates of the references. 1737 15.9. Changes from version 08 to version 09 1738 o Updated texts for Section 1 and Section 5 according to the 1739 comments provided by Samu Varjonen. 1740 o Made it clear that downgrading the multihoming shim support (i.e., 1741 specifying value 1 with the SHIM_DONTSHIM socket option) is only 1742 allowed before the socket is connected. 1743 o Updated locator information (shim_locator{}) so that it can 1744 contain a locator behind NAT. 1746 15.10. Changes from version 09 to version 10 1748 o Addressed applicability of socket options and ancillary data for 1749 the shim sub-layer. 1750 o Addressed system requirements. 1751 o Removed unnecessary description about deprecated socket option 1752 (SHIM_IF_RECV). 1754 15.11. Changes from version 10 to version 11 1756 o Added short descriptions about connected sockets and unconnected 1757 sockets. 1758 o Relaxed applicability of the socket options. 1759 o Relaxed applicability of the ancillary data. 1760 o Added notification about locator change. 1762 15.12. Changes from version 11 to version 12 1764 o Reflected comments from Brian Karpenter. 1765 o Reflected comments from Michael Scharf. 1767 15.13. Changes from version 12 to version 13 1769 o Reflected comments from Sebastien Barre. 1770 o Removed the description about the notification from the shim sub- 1771 layer to applications. 1772 o Narrowed down the scope of the applicability of the socket options 1773 and the ancillary data. 1775 15.14. Changes from version 13 to version 14 1777 o No change was made. The draft was re-submitted to avoid 1778 expiration. 1780 15.15. Changes from version 14 to version 15 1782 o Addressed the difference between SHIM_LOC_PEER_SEND and 1783 SHIM_LOC_PEER_PREF. 1785 o Made clear distinction between validation of locator and 1786 verification of locator, and introduced two errors: 1787 EUNVERIFIEDLOCATOR and EUNREACHABLELOCATOR. 1788 o Addressed exceptional case for HIP in handling of unknown 1789 destination locator. 1791 15.16. Changes from version 15 to version 16 1793 Updated the documents reflecting the comments received during the 1794 IETF Last Call. 1795 o Added Keepalive Interval (pe_keepaliveint) as a member of the 1796 shim_pathexplore{} data structure. 1797 o Addressed the unit of pe_keepaliveto. 1798 o Rephrased the last sentence in Appendix A to make it clear that 1799 the addressed issue is for further study. 1800 o Corrected a typo. 1802 16. Acknowledgments 1804 Authors would like to thank Jari Arkko who participated in the 1805 discussion that lead to the first version of this document, and 1806 Tatuya Jinmei who thoroughly reviewed the early version of this draft 1807 and provided detailed comments on sockets API related issues. Thomas 1808 Henderson provided valuable comments especially from HIP 1809 perspectives. 1811 Authors sincerely thank to the following people for their helpful 1812 comments to the document: Samu Varjonen, Dmitriy Kuptsov, Brian 1813 Carpenter, Michael Scharf, Sebastien Barre, and Roni Even. 1815 17. References 1817 17.1. Normative References 1819 [POSIX] "IEEE Std. 1003.1-2001 Standard for Information Technology 1820 -- Portable Operating System Interface (POSIX). Open group 1821 Technical Standard: Base Specifications, Issue 6, 1822 http://www.opengroup.org/austin", December 2001. 1824 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1825 Requirement Levels", BCP 14, RFC 2119, March 1997. 1827 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 1828 "Advanced Sockets Application Program Interface (API) for 1829 IPv6", RFC 3542, May 2003. 1831 [RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol 1832 (HIP) Architecture", RFC 4423, May 2006. 1834 [RFC5533] Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming 1835 Shim Protocol for IPv6", RFC 5533, June 2009. 1837 [RFC5534] Arkko, J. and I. van Beijnum, "Failure Detection and 1838 Locator Pair Exploration Protocol for IPv6 Multihoming", 1839 RFC 5534, June 2009. 1841 17.2. Informative References 1843 [I-D.ietf-behave-v6v4-xlate] 1844 Li, X., Bao, C., and F. Baker, "IP/ICMP Translation 1845 Algorithm", draft-ietf-behave-v6v4-xlate-23 (work in 1846 progress), September 2010. 1848 [I-D.ietf-hip-native-api] 1849 Komu, M. and T. Henderson, "Basic Socket Interface 1850 Extensions for Host Identity Protocol (HIP)", 1851 draft-ietf-hip-native-api-12 (work in progress), 1852 January 2010. 1854 [I-D.ietf-shim6-app-refer] 1855 Nordmark, E., "Shim6 Application Referral Issues", 1856 draft-ietf-shim6-app-refer-00 (work in progress), 1857 July 2005. 1859 [RFC2765] Nordmark, E., "Stateless IP/ICMP Translation Algorithm 1860 (SIIT)", RFC 2765, February 2000. 1862 [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for 1863 specifying the location of services (DNS SRV)", RFC 2782, 1864 February 2000. 1866 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 1867 Architecture", RFC 4291, February 2006. 1869 [RFC5535] Bagnulo, M., "Hash-Based Addresses (HBA)", RFC 5535, 1870 June 2009. 1872 [RFC5770] Komu, M., Henderson, T., Tschofenig, H., Melen, J., and A. 1873 Keranen, "Basic Host Identity Protocol (HIP) Extensions 1874 for Traversal of Network Address Translators", RFC 5770, 1875 April 2010. 1877 Appendix A. Context Forking 1879 In this section, an issue concerning context forking and its relation 1880 to the multihoming shim API are discussed. 1882 SHIM6 supports a notion of context forking. A peer may decide to 1883 fork a context for certain reason (e.g. upper layer protocol prefers 1884 to use different locator pair than the one defined in available 1885 context). The procedure of forking context is done similar to the 1886 normal context establishment, performing the 4-way message exchange. 1887 A peer who has decided to fork a context initiates the context 1888 establishment. Hereafter, we call this peer the "initiator". The 1889 peer of the initiator is called the "responder". 1891 Once the forked context is established between the peers, on the 1892 initiator side, it is possible to apply forked context to the packet 1893 flow since the system maintains an association between the forked 1894 context and the socket owned by the application that has requested 1895 the context forking. How this association is maintained is an 1896 implementation specific issue. However, on the responder side, there 1897 is a question how the outbound packet can be multiplexed by the shim 1898 sub-layer because there are more than one SHIM6 contexts that match 1899 with the ULID pair of the packet flow. There is a need to 1900 differentiate packet flows not only by the ULID pairs but by some 1901 other information and associate a given packet flow with a specific 1902 context. 1904 Figure 8 gives an example of a scenario where two communicating peers 1905 fork a context. Initially, there has been a single transaction 1906 between the peers, by the application 1 (App1). Accordingly, another 1907 transaction is started, by application 2 (App2). Both of the 1908 transactions are made based on the same ULID pair. The first context 1909 pair (Ctx1) is established for the transaction of App1. Given the 1910 requests from App2, the shim sub-layer on Peer 1 decides to fork a 1911 context. Accordingly, a forked context (Ctx2) is established between 1912 the peers, which should be exclusively applied to the transaction of 1913 App2. Ideally, multiplexing and demultiplexing of packet flows that 1914 relate to App1 and App2 should be done as illustrated in Figure 8. 1915 However, as mentioned earlier, the responder needs to multiplex 1916 outbound flows of App1 and App2 somehow. Note that if a context 1917 forking occurs on the initiator side, a context forking needs to 1918 occur also on the responder side. 1920 Peer 1 Peer 2 1921 (initiator) (responder) 1923 +----+ +----+ +----+ +----+ 1924 |App1| |App2| |App1| |App2| 1925 +----+ +----+ +----+ +----+ 1926 |^ |^ ^| ^| 1927 v| v| |v |v 1928 -----S1-------------S2----- -----S1-------------S2----- 1929 || || || || 1930 || || || || 1932 Ctx1 Ctx2 Ctx1 Ctx2 1933 ULID: ULID: ULID: ULID: 1934 Loc: Loc: Loc: Loc: 1935 FII: 0 FII: 100 FII: 0 FII: 100 1937 |^ |^ ^| ^| 1938 || || || || 1939 || || || || 1940 \..............||....................../| || 1941 \.............||......................./ || 1942 || || 1943 \|...................................../| 1944 \....................................../ 1946 Figure 8: context forking 1948 It is for further study how to solve the issue described above. 1950 Authors' Addresses 1952 Miika Komu 1953 Helsinki Institute for Information Technology 1954 Tammasaarenkatu 3 1955 Helsinki 1956 Finland 1958 Phone: +358503841531 1959 Fax: +35896949768 1960 Email: miika@iki.fi 1961 URI: http://www.hiit.fi/ 1962 Marcelo Bagnulo 1963 Universidad Carlos III de Madrid 1964 Av. Universidad 30 1965 Leganes 28911 1966 SPAIN 1968 Phone: +34 91 6248837 1969 Email: marcelo@it.uc3m.es 1970 URI: http://it.uc3m.es/marcelo 1972 Kristian Slavov 1973 Ericsson Research Nomadiclab 1974 Hirsalantie 11 1975 Jorvas FI-02420 1976 Finland 1978 Phone: +358 9 299 3286 1979 Email: kristian.slavov@ericsson.com 1981 Shinta Sugimoto (editor) 1982 Nippon Ericsson K.K. 1983 Koraku Mori Building 1984 1-4-14, Koraku, Bunkyo-ku 1985 Tokyo 112-0004 1986 Japan 1988 Phone: +81 3 3830 2241 1989 Email: shinta@sfc.wide.ad.jp