idnits 2.17.1 draft-ietf-shim6-multihome-shim-api-17.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 1255 has weird spacing: '... u_int msg_...' == Line 1256 has weird spacing: '... struct iovec...' == Line 1257 has weird spacing: '... u_int msg_...' == Line 1259 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 (April 3, 2011) is 4762 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 1017 -- Looks like a reference, but probably isn't: '1' on line 1028 ** 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: October 5, 2011 UC3M 6 K. Slavov 7 S. Sugimoto, Ed. 8 Ericsson 9 April 3, 2011 11 Socket Application Program Interface (API) for Multihoming Shim 12 draft-ietf-shim6-multihome-shim-api-17 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 October 5, 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 . . . . . . . . . . . . . . . . . . . . 5 74 3. Terminology and Background . . . . . . . . . . . . . . . . . . 5 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 . . . . . . . . . . . . . . . . . . . 22 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 . . . . . . . . 29 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. Data Structure 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 . . . . . . . . . . . . . . 37 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 . . . . . . . . . . 40 133 15.17. Changes from version 16 to version 17 . . . . . . . . . . 41 134 16. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 41 135 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41 136 17.1. Normative References . . . . . . . . . . . . . . . . . . 41 137 17.2. Informative References . . . . . . . . . . . . . . . . . 42 138 Appendix A. Context Forking . . . . . . . . . . . . . . . . . . . 43 139 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 44 141 1. Introduction 143 This document defines socket API extensions by which upper layer 144 protocols may be informed about and control the way in which a 145 multihoming shim sub-layer in the IP layer manages the dynamic choice 146 of locators. Initially it applies to SHIM6 and HIP, but it is 147 defined generically. 149 The role of the multihoming shim sub-layer (hereafter called "shim 150 sub-layer" in this document) is to avoid impacts to upper layer 151 protocols which may be caused when the endhost changes its attachment 152 point to the Internet, for instance, in the case of rehoming event 153 under the multihomed environment. There is, however, a need for API 154 in the cases where 1) the upper layer protocol is particularly 155 sensitive to impacts, or 2) the upper layer protocol wants to benefit 156 from better knowledge of what is going on underneath. 158 There are various kinds of technologies that aim to solve the same 159 issue, the multihoming issue. Note that there will be conflict when 160 more than one shim sub-layer is active at the same time. The 161 assumption made in this document is that there is only a single shim 162 sub-layer (HIP or SHIM6) activated on the system. 164 The target readers of this document are application programmers who 165 develop application software which may benefit greatly from 166 multihomed environments. In addition, this document aims to provide 167 necessary information for developers of shim protocols to implement 168 API for enabling advanced locator management. 170 2. Requirements Language 172 The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", 173 "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this 174 document are to be interpreted as described in [RFC2119]. 176 3. Terminology and Background 178 This section provides terminology used in this document. Basically 179 most of the terms used in this document are taken from the following 180 documents: 182 o SHIM6 Protocol Specification[RFC5533] 183 o HIP Architecture[RFC4423] 184 o Reachability Protocol (REAP)[RFC5534] 186 In this document, the term "IP" refers to both IPv4 and IPv6, unless 187 the protocol version is specifically mentioned. The following are 188 definitions of terms frequently used in this document: 190 o Endpoint identifier (EID) - The identifier used by the application 191 to specify the endpoint of a given communication. Applications 192 may handle EIDs in various ways such as long-lived connections, 193 callbacks, and referrals[I-D.ietf-shim6-app-refer]. 194 * In the case of SHIM6, an identifier called a ULID (Upper Layer 195 Identifier) serves as an EID. A ULID is chosen from locators 196 available on the host. 197 * In the case of HIP, an identifier called a Host Identifier 198 serves as an EID. A Host Identifier is derived from the public 199 key of a given host. For the sake of backward compatibility 200 with the sockets API, the Host Identifier is represented in a 201 form of hash of public key. 202 * Note that the EID appears in the standard socket API as an 203 address, and does not appear in the extensions defined in this 204 document, which only concern locators. 205 o Locator - The IP address actually used to deliver IP packets. 206 Locators are present in the source and destination fields of the 207 IP header of a packet on the wire. Locator discussed in this 208 document could be either an IPv4 address or an IPv6 address. Note 209 that HIP can handle both IPv4 and IPv6 locators, whereas SHIM6 can 210 handle only IPv6 locators. For the HIP case, locator can be a 211 private IPv4 address when the host is behind a NAT. Section 212 Section 8.1.1 gives detailed description about handling of locator 213 behind NAT. 214 * List of locators - A list of locators associated with an EID. 215 There are two lists of locators stored in a given context. One 216 is associated with the local EID and the other is associated 217 with the remote EID. As defined in [RFC5533], the list of 218 locators associated with an EID 'A' is denoted as Ls(A). 219 * Preferred locator - The (source/destination) locator currently 220 used to send packets within a given context. 221 * Unknown locator - Any locator that does not appear in the 222 locator list of the shim context associated with the socket. 223 When there is no shim context associated with the socket, any 224 source and/or destination locator requested by the application 225 is considered to be unknown locator. 226 * Valid locator - A valid locator means that the locator is 227 considered to be valid in the security sense. More 228 specifically, the validity indicates whether the locator is 229 part of a HBA set. 230 * Verified locator - A verified locator means that the locator is 231 considered to be reachable according to the result of REAP 232 return routability check. Note that the verification applies 233 only to peer's locator. 235 o Shim - The conceptual sub-layer inside the IP layer which 236 maintains mappings between EIDs and locators. An EID can be 237 associated with more than one locator at a time when the host is 238 multihomed. The term 'shim' does not refer to a specific protocol 239 but refers to the conceptual sub-layer inside the IP layer. 240 o Identifier/locator adaptation - The adaptation performed at the 241 shim sub-layer which may end up re-writing the source and/or 242 destination addresses of an IP packet. In the outbound packet 243 processing, the EID pair is converted to the associated locator 244 pair. In the inbound packet processing, the locator pair is 245 converted to the EID pair. 246 o Context - The state information shared by a given pair of peers, 247 which stores a binding between the EID and associated locators. 248 Contexts are maintained by the shim sub-layer. Deferred context 249 setup is a scenario where a context is established after the 250 communication starts. Deferred context setup is possible if the 251 ULID is routable, such as the case of SHIM6. 252 o Reachability detection - The procedure to check reachability 253 between a given locator pair. 254 o Path - The sequence of routers that an IP packet goes through to 255 reach the destination. 256 o Path exploration - The procedure to explore available paths for a 257 given set of locator pairs. 258 o Outage - The incident that prevents IP packets to flow from the 259 source locator to the destination locator. When there is an 260 outage, it means that there is no reachability between a given 261 locator pair. The outage may be caused by various reasons, such 262 as shortage of network resources, congestion, and human error 263 (faulty operation). 264 o Working address pair - The address pair is considered to be 265 "working" if the packet can safely travel from the source to the 266 destination where the packet contains the first address from the 267 pair as the source address and the second address from the pair as 268 the destination address. If reachability is confirmed in both 269 directions, the address pair is considered to be working bi- 270 directionally. 271 o Reachability protocol (REAP) - The protocol for detecting failure 272 and exploring reachability in a multihomed environment. REAP is 273 defined in [RFC5534]. 275 In this document, syntax and semantics of the API are given in the 276 same way as in the Posix standard [POSIX]. The API specifies how to 277 use ancillary data (aka cmsg) to access the locator information with 278 recvmsg() and/or sendmsg() I/O calls. The API is described in C 279 language and data types are defined in the Posix format; intN_t means 280 a signed integer of exactly N bits (e.g. int16_t) and uintN_t means 281 an unsigned integer of exactly N bits (e.g. uint32_t). 283 The distinction between "connected" sockets and "unconnected" sockets 284 is important when discussing the applicability of the socket API 285 defined in this document. A connected socket is bound to a given 286 peer, whereas an unconnected socket is not bound to any specific 287 peers. A TCP socket becomes a connected socket when the TCP 288 connection establishment is completed. UDP sockets are unconnected, 289 unless the application uses the connect() system call. 291 4. System Overview 293 Figure 1 illustrates the system overview. The shim sub-layer and 294 REAP component exist inside the IP layer. Applications use the 295 sockets API defined in this document to interface with the shim sub- 296 layer and the transport layer for locator management, failure 297 detection, and path exploration. 299 It is also be possible that the shim sub-layer interacts with the 300 transport layer, however, such an interaction is outside the scope of 301 this document. 303 +------------------------+ 304 | Application | 305 +------------------------+ 306 ^ ^ 307 ~~~~~~~~~~~~~|~Socket Interface|~~~~~~~~~~~~~~ 308 | v 309 +-----------|------------------------------+ 310 | | Transport Layer | 311 +-----------|------------------------------+ 312 ^ | 313 +-------------|-----|-------------------------------------+ 314 | v v | 315 | +-----------------------------+ +----------+ | IP 316 | | Shim |<----->| REAP | | Layer 317 | +-----------------------------+ +----------+ | 318 | ^ ^ | 319 +-----------------------|----------------------|----------+ 320 v v 321 +------------------------------------------+ 322 | Link Layer | 323 +------------------------------------------+ 325 Figure 1: System overview 327 5. Requirements 329 The following is a list of requirements from applications: 330 o Turn on/off shim. An application should be able to request to 331 turn on or turn off the multihoming support by the shim layer: 332 * Apply shim. The application should be able to explicitly 333 request the shim sub-layer to apply multihoming support. 334 * Don't apply shim. The application should be able to request 335 the shim sub-layer not to apply the multihoming support but to 336 apply normal IP processing at the IP layer. 337 * Note that this function is also required by other types of 338 multihoming mechanisms such as SCTP and multipath TCP to avoid 339 potential conflict with the shim sub-layer. 340 o Locator management. 341 * It should be possible to set preferred source and/or 342 destination locator within a given context. 343 * It should be possible to get preferred source and/or 344 destination locator within a given context. 345 * It should be possible to set a list of source and/or 346 destination locators within a given context: Ls(local) and 347 Ls(remote). 348 * It should be possible to get a list of source and/or 349 destination locators within a given context: Ls(local) and 350 Ls(remote). 351 o Notification from applications and upper layer protocols to the 352 shim sub-layer about the status of the communication. The 353 notification occurs in an event-based manner. Applications and/or 354 upper layer protocols may provide positive feedback or negative 355 feedback to the shim sub-layer. Note that these feedback are 356 mentioned in [RFC5534]: 357 * Applications and/or upper layer protocols (e.g., TCP) may 358 provide positive feedback to the shim sub-layer informing that 359 the communication is going well. 360 * Applications and/or upper layer protocols (e.g., TCP) may 361 provide negative feedback to the shim sub-layer informing that 362 the communication status is not satisfactory. TCP may detect a 363 problem when it does not receive any expected ACK message from 364 the peer. The REAP module may be triggered by these negative 365 feedback and invoke the path exploration procedure. 366 o Feedback from applications to the shim sub-layer. Applications 367 should be able to inform the shim sub-layer of the timeout values 368 for detecting failures, sending keepalives, and starting the 369 exploration procedure. In particular, applications should be able 370 to suppress keepalives. 371 o Hot-standby. Applications may request the shim sub-layer for a 372 hot-standby capability. This means that, alternative paths are 373 known to be working in advance of a failure detection. In such a 374 case, it is possible for the shim sub-layer to immediately replace 375 the current locator pair with an alternative locator pair. 376 o Eagerness for locator exploration. An application should be able 377 to inform the shim sub-layer of how aggressively it wants the REAP 378 mechanism to perform a path exploration (e.g., by specifying the 379 number of concurrent attempts of discovery of working locator 380 pairs) when an outage occurs on the path between the locator pair 381 in use. 382 o Providing locator information to applications. An application 383 should be able to obtain information about the locator pair which 384 was actually used to send or receive packets. 385 * For inbound traffic, the application may be interested in the 386 locator pair which was actually used to receive the packet. 387 * For outbound traffic, the application may be interested in the 388 locator pair which was actually used to transmit the packet. 389 In this way, applications may have additional control on the 390 locator management. For example, an application becomes able to 391 verify if its preference for locator is actually applied to the 392 flow or not. 393 o Applications should be able to know if the shim-sublayer supports 394 deferred context setup or not. 395 o An application should be able to know if the communication is now 396 being served by the shim sub-layer or not. 397 o An application should be able to use a common interface to access 398 an IPv4 locator and an IPv6 locator. 400 6. Socket Options for Multihoming Shim Sub-layer 402 In this section, socket options that are specific to the shim sub- 403 layer are defined. 405 Table 1 shows a list of the socket options that are specific to the 406 shim sub-layer. All of these socket options are defined at the level 407 SOL_SHIM. When an application uses one of the socket options by 408 getsockopt() or setsockopt(), the second argument MUST be set as 409 SOL_SHIM. 411 The first column of Table 1 gives the name of the option. The second 412 column indicates whether the value for the socket option can be ready 413 by getsockopt() and the third column indicates whether the value for 414 the socket option can be written by setsockopt(). The fourth column 415 provides a brief description of the socket option. The fifth column 416 shows the type of data structure specified along with the socket 417 option. By default, the data structure type is an integer. 419 +-----------------------------+-----+-----+-----------------+-------+ 420 | optname | get | set | description | dtype | 421 +-----------------------------+-----+-----+-----------------+-------+ 422 | SHIM_ASSOCIATED | o | | Get the | int | 423 | | | | parameter which | | 424 | | | | indicates | | 425 | | | | whether the | | 426 | | | | socket is | | 427 | | | | associated (1) | | 428 | | | | with any shim | | 429 | | | | context or not | | 430 | | | | (0). | | 431 | SHIM_DONTSHIM | o | o | Get or set the | int | 432 | | | | parameter which | | 433 | | | | indicates | | 434 | | | | whether to | | 435 | | | | employ the | | 436 | | | | multihoming | | 437 | | | | support by the | | 438 | | | | shim sub-layer | | 439 | | | | or not. | | 440 | SHIM_HOT_STANDBY | o | o | Get or set the | int | 441 | | | | parameter to | | 442 | | | | request the | | 443 | | | | shim sub-layer | | 444 | | | | to prepare a | | 445 | | | | hot-standby | | 446 | | | | connection. | | 447 | SHIM_LOC_LOCAL_PREF | o | o | Set the | Note | 448 | | | | preference | 1 | 449 | | | | value for a | | 450 | | | | source locator | | 451 | | | | for outbound | | 452 | | | | traffic. Get | | 453 | | | | the preferred | | 454 | | | | locator for the | | 455 | | | | source locator | | 456 | | | | for outbound | | 457 | | | | traffic. | | 458 | SHIM_LOC_PEER_PREF | o | o | Set the | Note | 459 | | | | preference | 1 | 460 | | | | value for a | | 461 | | | | destination | | 462 | | | | locator for | | 463 | | | | outbound | | 464 | | | | traffic. Get | | 465 | | | | the preferred | | 466 | | | | locator for the | | 467 | | | | destination | | 468 | | | | locator for | | 469 | | | | outbound | | 470 | | | | traffic. | | 471 | SHIM_LOC_LOCAL_RECV | o | o | Request the | int | 472 | | | | shim sub-layer | | 473 | | | | to store the | | 474 | | | | destination | | 475 | | | | locator of the | | 476 | | | | received IP | | 477 | | | | packet in an | | 478 | | | | ancillary data | | 479 | | | | object. | | 480 | SHIM_LOC_PEER_RECV | o | o | Request the | int | 481 | | | | shim sub-layer | | 482 | | | | to store the | | 483 | | | | source locator | | 484 | | | | of the received | | 485 | | | | IP packet in an | | 486 | | | | ancillary data | | 487 | | | | object. | | 488 | SHIM_LOC_LOCAL_SEND | o | o | Get or set the | Note | 489 | | | | source locator | 1 | 490 | | | | of outgoing IP | | 491 | | | | packets. | | 492 | SHIM_LOC_PEER_SEND | o | o | Get or set the | Note | 493 | | | | destination | 1 | 494 | | | | locator of | | 495 | | | | outgoing IP | | 496 | | | | packets. | | 497 | SHIM_LOCLIST_LOCAL | o | o | Get or set the | Note | 498 | | | | list of | 2 | 499 | | | | locators | | 500 | | | | associated with | | 501 | | | | the local EID. | | 502 | SHIM_LOCLIST_PEER | o | o | Get or set the | Note | 503 | | | | list of | 2 | 504 | | | | locators | | 505 | | | | associated with | | 506 | | | | the peer's EID. | | 507 | SHIM_APP_TIMEOUT | o | o | Get or set the | int | 508 | | | | Send Timeout | | 509 | | | | value of the | | 510 | | | | REAP protocol. | | 511 | SHIM_PATHEXPLORE | o | o | Get or set | Note | 512 | | | | parameters for | 3 | 513 | | | | path | | 514 | | | | exploration and | | 515 | | | | failure | | 516 | | | | detection. | | 517 | SHIM_CONTEXT_DEFERRED_SETUP | o | | Get the | int | 518 | | | | parameter which | | 519 | | | | indicates | | 520 | | | | whether | | 521 | | | | deferred | | 522 | | | | context setup | | 523 | | | | is supported or | | 524 | | | | not. | | 525 +-----------------------------+-----+-----+-----------------+-------+ 527 Table 1: Socket options for multihoming shim sub-layer 529 Note 1: Pointer to a shim_locator which is defined in Section 8. 531 Note 2: Pointer to an array of shim_locator. 533 Note 3: Pointer to a shim_pathexplore which is defined in Section 8. 535 Figure 2 illustrates how the shim specific socket options fit into 536 the system model of socket API. The figure shows that the shim sub- 537 layer and the additional protocol components (IPv4 and IPv6) below 538 the shim sub-layer are new to the system model. As previously 539 mentioned, all the shim specific socket options are defined at the 540 SOL_SHIM level. This design choice brings the following advantages: 542 1. The existing sockets API continue to work at the layer above the 543 shim sub-layer. That is, those legacy API handle IP addresses as 544 identifiers. 545 2. With newly defined socket options for the shim sub-layer, the 546 application obtains additional control of locator management. 547 3. The shim specific socket options can be kept independent from 548 address family (IPPROTO_IP or IPPROTO_IPV6) and transport 549 protocol (IPPROTO_TCP or IPPROTO_UDP). 551 s1 s2 s3 s4 552 | | | | 553 +----------------|--|-------|--|----------------+ 554 | +-------+ +-------+ | 555 | IPPROTO_TCP | TCP | | UDP | | 556 | +-------+ +-------+ | 557 | | \ / | | 558 | | ----- | | 559 | | / \ | | 560 | +------+ +------+ | 561 | IPPROTO_IP | IPv4 | | IPv6 | IPPROTO_IPV6 | 562 | +------+ +------+ | 563 | \ / SOL_SOCKET 564 | +--------\-------/--------+ | 565 | SOL_SHIM | shim | | 566 | +--------/-------\--------+ | 567 | / \ | 568 | +------+ +------+ | 569 | | IPv4 | | IPv6 | | 570 | +------+ +------+ | 571 | | | | 572 +------------------|----------|-----------------+ 573 | | 574 IPv4 IPv6 575 Datagram Datagram 577 Figure 2: System model of sockets API with shim sub-layer 579 6.1. SHIM_ASSOCIATED 581 The SHIM_ASSOCIATED option is used to check whether the socket is 582 associated with any shim context or not. 584 This option is meaningful when the locator information of the 585 received IP packet does not tell whether the identifier/locator 586 adaptation is performed or not. Note that the EID pair and the 587 locator pair may be identical in some cases. 589 Note that the socket option is read-only and the option value can be 590 read by getsockopt(). The result (0/1/2) is set in the option value 591 (the fourth argument of getsockopt()). 593 When the application specifies the socket option to an unconnected 594 socket, an error code EOPNOTSUPP is returned to the application. 596 The data type of the option value is an integer. The option value 597 indicates the presence of shim context. A return value 1 means that 598 the socket is associated with a shim context at the shim sub-layer. 599 A return value 0 indicates that there is no shim context associated 600 with the socket. A return value 2 means that it is not known whether 601 the socket is associated with a shim context or not, and this MUST be 602 returned only when the socket is unconnected. In other words, the 603 returned value MUST be 0 or 1 when the socket is connected. 605 For example, the option can be used by the application as follows: 607 int optval; 608 int optlen = sizeof(optval); 610 getsockopt(fd, SOL_SHIM, SHIM_ASSOCIATED, &optval, &optlen); 612 6.2. SHIM_DONTSHIM 614 The SHIM_DONTSHIM option is used to request the shim layer not to 615 provide the multihoming support for the communication established 616 over the socket. 618 The data type of the option value is an integer, and it takes 0 or 1. 619 An option value 0 means that the shim sub-layer is employed if 620 available. An option value 1 means that the application does not 621 want the shim sub-layer to provide the multihoming support for the 622 communication established over the socket. 624 Default value is set as 0, which means that the shim sub-layer 625 performs identifier/locator adaptation if available. 627 Any attempt to disable the multihoming shim support MUST be made by 628 the application before the socket is connected. If an application 629 makes such an attempt for a connected-socket, an error code 630 EOPNOTSUPP MUST be returned. 632 For example, an application can request the system not to apply the 633 multihoming support as follows: 635 int optval; 637 optval = 1; 639 setsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, sizeof(optval)); 641 For example, the application can check the option value as follows: 643 int optval; 644 int len; 646 len = sizeof(optval); 648 getsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, &len); 650 6.3. SHIM_HOT_STANDBY 652 The SHIM_HOT_STANDBY option is used to control the shim sub-layer 653 whether to employ a hot-standby connection for the socket or not. A 654 hot-standby connection is an alternative working locator pair to the 655 current locator pair. This option is effective only when there is a 656 shim context associated with the socket. 658 The data type of the option value is an integer. 660 The option value can be set by setsockopt(). 662 The option value can be read by getsockopt(). 664 By default, the value is set to 0, meaning that hot-standby 665 connection is disabled. 667 When the application specifies the socket option to an unconnected 668 socket, an error code EOPNOTSUPP is returned to the application. 670 When there is no shim context associated with the socket, an error 671 code ENOENT is returned to the application. 673 For example, an application can request establishment of a hot- 674 standby connection by using the socket option as follows: 676 int optval; 678 optval = 1; 680 setsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, 681 sizeof(optval)); 683 For example, an application can get the option value by using the 684 socket option as follows: 686 int optval; 687 int len; 689 len = sizeof(optval); 690 getsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, &len); 692 6.4. SHIM_LOC_LOCAL_PREF 694 The SHIM_LOC_LOCAL_PREF option is used to set the preference value 695 for a source locator for outbound traffic, or to get the preference 696 value of the source locator for outbound traffic that has the highest 697 preference value. 699 This option is effective only when there is a shim context associated 700 with the socket. 702 By default, the option value is set to NULL, meaning that the option 703 is disabled. 705 The preference of a locator is defined by a combination of priority 706 and weight as per DNS SRV[RFC2782]. Note that the SHIM6 base 707 protocol defines preference of locator in the same way. 709 The data type of the option value is a pointer to a locator 710 information data structure which is defined in Section 8. 712 When an application specifies the socket option to an unconnected 713 socket, an error code EOPNOTSUPP is returned to the application. 715 When there is no shim context associated with the socket, an error 716 code ENOENT is returned to the application. 718 An error EINVALIDLOCATOR is returned when the validation of the 719 specified locator fails. 721 An application can set the preference value for a source locator for 722 outbound traffic by setsockopt() with the socket option. Note that 723 lc_ifidx and lc_flags have no effect in a set operation. Below is an 724 example of set operation. 726 struct shim_locator lc; 727 struct in6_addr ip6; 729 /* ...set the locator (ip6)... */ 731 memset(&lc, 0, sizeof(shim_locator)); 732 lc.lc_family = AF_INET6; /* IPv6 */ 733 lc.lc_ifidx = 0; 734 lc.lc_flags = 0; 735 lc.lc_prio = 1; 736 lc.lc_weight = 10; 737 memcpy(&lc.lc_addr, &ip6, sizeof(in6_addr)); 739 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, 740 sizeof(optval)); 742 An application can get the source locator for outbound traffic that 743 has the highest preference value by using the socket option. Below 744 is an example of get operation. 746 struct shim_locator lc; 747 int len; 749 len = sizeof(lc); 751 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, &len); 753 6.5. SHIM_LOC_PEER_PREF 755 The SHIM_LOC_PEER_PREF option is used to set the preference value for 756 a destination locator for outbound traffic, or to get the preference 757 value of the destination locator for outbound traffic that has the 758 highest preference value. 760 This option is effective only when there is a shim context associated 761 with the socket. 763 By default, the option value is set to NULL, meaning that the option 764 is disabled. 766 As defined earlier, the preference of a locator is defined by a 767 combination of priority and weight as per DNS SRV[RFC2782]. When 768 there are more than one candidate destination locators, the shim sub- 769 layer makes selection based on the priority and weight specified for 770 each locator. 772 The data type of the option value is a pointer to the locator 773 information data structure which is defined in Section 8. 775 When the application specifies the socket option to an unconnected 776 socket, an error code EOPNOTSUPP is returned to the application. 778 When there is no shim context associated with the socket, an error 779 code ENOENT is returned to the application. 781 An error EINVALIDLOCATOR is returned when the validation of the 782 requested locator fails. 784 An error EUNREACHABLELOCATOR is returned when the requested locator 785 is determined to be not reachable according to a reachability check. 787 The usage of the option is same as that of SHIM_LOC_LOCAL_PREF. 789 6.6. SHIM_LOC_LOCAL_RECV 791 The SHIM_LOC_LOCAL_RECV option can be used to request the shim sub- 792 layer to store the destination locator of the received IP packet in 793 an ancillary data object which can be accessed by recvmsg(). This 794 option is effective only when there is a shim context associated with 795 the socket. 797 The data type of the option value is integer. The option value MUST 798 be binary (0 or 1). By default, the option value is set to 0, 799 meaning that the option is disabled. 801 An application can set the option value by setsockopt(). 803 An application can get the option value by getsockopt(). 805 See Section 7 for the procedure to access locator information stored 806 in the ancillary data objects. 808 When the application specifies the socket option to an unconnected 809 socket, an error code EOPNOTSUPP is returned to the application. 811 When there is no shim context associated with the socket, an error 812 code ENOENT is returned to the application. 814 For example, an application can request the shim sub-layer to store 815 destination locator by using the socket option as follows. 817 int optval; 819 optval = 1; 821 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, 822 sizeof(optval)); 824 For example, an application can get the option value as follows. 826 int optval; 827 int len; 829 len = sizeof(optval); 831 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, &len); 833 6.7. SHIM_LOC_PEER_RECV 835 The SHIM_LOC_PEER_RECV option is used to request the shim sub-layer 836 to store the source locator of the received IP packet in an ancillary 837 data object which can be accessed by recvmsg(). This option is 838 effective only when there is a shim context associated with the 839 socket. 841 The data type of the option value is integer. The option value MUST 842 be binary (0 or 1). By default, the option value is set to 0, 843 meaning that the option is disabled. 845 The option value can be set by setsockopt(). 847 The option value can be read by getsockopt(). 849 See Section 7 for the procedure to access locator information stored 850 in the ancillary data objects. 852 When the application specifies the socket option to an unconnected 853 socket, an error code EOPNOTSUPP is returned to the application. 855 When there is no shim context associated with the socket, an error 856 code ENOENT is returned to the application. 858 The usage of the option is same as that of SHIM_LOC_LOCAL_RECV 859 option. 861 6.8. SHIM_LOC_LOCAL_SEND 863 The SHIM_LOC_LOCAL_SEND option is used to request the shim sub-layer 864 to use a specific locator as the source locator for the IP packets to 865 be sent from the socket. This option is effective only when there is 866 a shim context associated with the socket. 868 The data type of option value is pointer to shim_locator data 869 structure. 871 An application can set the local locator by setsockopt() providing a 872 locator which is stored in a shim_locator data structure. When a 873 zero-filled locator is specified, pre-existing setting of local 874 locator is inactivated. 876 An application can get the local locator by getsockopt(). 878 When the application specifies the socket option to an unconnected 879 socket, an error code EOPNOTSUPP is returned to the application. 881 When there is no shim context associated with the socket, an error 882 code ENOENT is returned to the application. 884 An error EINVALIDLOCATOR is returned when an invalid locator is 885 specified. 887 For example, an application can request the shim sub-layer to use a 888 specific local locator by using the socket option as follows. 890 struct shim_locator locator; 891 struct in6_addr ia6; 893 /* an IPv6 address preferred for the source locator is copied 894 to the parameter ia6 */ 896 memset(&locator, 0, sizeof(locator)); 898 /* fill shim_locator data structure */ 899 locator.lc_family = AF_INET6; 900 locator.lc_ifidx = 0; 901 locator.lc_flags = 0; 902 locator.lc_prio = 0; 903 locator.lc_weight = 0; 904 memcpy(&locator.lc_addr, &ia6, sizeof(ia6)); 906 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, 907 sizeof(locator)); 909 For example, an application can get the designated local locator by 910 using the socket option as follows: 912 struct shim_locator locator; 914 memset(&locator, 0, sizeof(locator)); 916 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, 917 sizeof(locator)); 919 /* check locator */ 921 6.9. SHIM_LOC_PEER_SEND 923 The SHIM_LOC_PEER_SEND option is used to request the shim sub-layer 924 to use a specific locator for the destination locator of IP packets 925 to be sent from the socket. This option is effective only when there 926 is a shim context associated with the socket. 928 The data type of the option value is a pointer to shim_locator data 929 structure. 931 An application can set the remote locator by setsockopt() providing a 932 locator which is stored in a shim_locator data structure. When a 933 zero-filled locator is specified, pre-existing setting of remote 934 locator is inactivated. 936 An application can get the specified remote locator by getsockopt(). 938 The difference between the SHIM_LOC_PEER_SEND option and the 939 SHIM_LOC_PEER_PREF option is that the former guarantee the use of 940 requested locator when applicable whereas the latter does not. 942 When the application specifies the socket option to an unconnected 943 socket, an error code EOPNOTSUPP is returned to the application. 945 When there is no shim context associated with the socket, an error 946 code ENOENT is returned to the application. 948 An error EINVALIDLOCATOR is returned when the validation of the 949 requested locator fails. 951 An error EUNVERIFIEDLOCATOR is returned when reachability for the 952 requested locator has not been verified yet. 954 An error EUNREACHABLELOCATOR is returned when the requested locator 955 is determined to be not reachable according to a reachability check. 957 The usage of the option is the same as that of SHIM_LOC_LOCAL_SEND 958 option. 960 6.10. SHIM_LOCLIST_LOCAL 962 The SHIM_LOCLIST_LOCAL option is used to get or set the locator list 963 associated with the local EID of the shim context associated with the 964 socket. This option is effective only when there is a shim context 965 associated with the socket. 967 The data type of the option value is a pointer to the buffer in which 968 a locator list is stored. See Section 8 for the data structure for 969 storing the locator information. By default, the option value is set 970 to NULL, meaning that the option is disabled. 972 An application can get the locator list by getsockopt(). Note that 973 the size of the buffer pointed to by the optval argument MUST be 974 large enough to store an array of locator information. The number of 975 the locator information is not known beforehand. 977 The local locator list can be set by setsockopt(). The buffer 978 pointed to by the optval argument MUST contain an array of locator 979 structures. 981 When the application specifies the socket option to an unconnected 982 socket, an error code EOPNOTSUPP is returned to the application. 984 When there is no shim context associated with the socket, an error 985 code ENOENT is returned to the application. 987 An error EINVALIDLOCATOR is returned when the validation of any of 988 the specified locators failed. 990 An error ETOOMANYLOCATORS is returned when the number of locators 991 specified exceeds the limit (SHIM_MAX_LOCATORS), or when the size of 992 the buffer provided by the application is not large enough to store 993 the locator list provided by the shim sub-layer. 995 For example, an application can set a list of locators to be 996 associated with the local EID by using the socket option as follows. 997 Note that IPv4 locator can be handled by HIP and not by SHIM6. 999 struct shim_locator locators[SHIM_MAX_LOCATORS]; 1000 struct sockaddr_in *sin; 1001 struct sockaddr_in6 *sin6; 1003 memset(locators, 0, sizeof(locators)); 1005 ... 1007 /* obtain local IP addresses from local interfaces */ 1009 ... 1011 /* first locator (an IPv6 address) */ 1012 locators[0].lc_family = AF_INET6; 1013 locators[0].lc_ifidx = 0; 1014 locators[0].lc_flags = 0; 1015 locators[0].lc_prio = 1; 1016 locators[0].lc_weight = 0; 1017 memcpy(&locators[0].lc_addr, &sa6->sin6_addr, 1018 sizeof(sa6->sin6_addr)); 1020 ... 1022 /* second locator (an IPv4 address) */ 1023 locators[1].lc_family = AF_INET; 1024 locators[1].lc_ifidx = 0; 1025 locators[1].lc_flags = 0; 1026 locators[1].lc_prio = 0; 1027 locators[1].lc_weight = 0; 1028 memcpy(&locators[1].lc_addr, &sa->sin_addr, 1029 sizeof(sa->sin_addr)); 1031 setsockopt(fd, SOL_SHIM, SHIM_LOCLIST_LOCAL, locators, 1032 sizeof(locators)); 1034 For example, an application can get a list of locators that are 1035 associated with the local EID by using the socket option as follows. 1037 struct shim_locator locators[SHIM_MAX_LOCATORS]; 1039 memset(locators, 0, sizeof(locators)); 1041 getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, locators, 1042 sizeof(locators)); 1044 /* parse locators */ 1045 ... 1047 6.11. SHIM_LOCLIST_PEER 1049 The SHIM_LOCLIST_PEER option is used to get or set the locator list 1050 associated with the peer EID of the shim context associated with the 1051 socket. This option is effective only when there is a shim context 1052 associated with the socket. 1054 The data type of the option value is a pointer to the buffer where a 1055 locator list is stored. See Section 8 for the data structure for 1056 storing the locator information. By default, the option value is set 1057 to NULL, meaning that the option is disabled. 1059 An application can get the locator list by getsockopt(). Note that 1060 the size of the buffer pointed to by the optval argument MUST be 1061 large enough to store an array of locator information. The number of 1062 the locator information is not known beforehand. 1064 An application can set the locator list by setsockopt(). The buffer 1065 pointed to by the optval argument MUST contain an array of locator 1066 list. 1068 When the application specifies the socket option to an unconnected 1069 socket, an error code EOPNOTSUPP is returned to the application. 1071 When there is no shim context associated with the socket, an error 1072 code ENOENT is returned to the application. 1074 An error EINVALIDLOCATOR is returned when the validation of any of 1075 the specified locators failed. 1077 An error EUNVERIFIEDLOCATOR is returned when reachability for the 1078 requested locator has not been verified yet. 1080 An error EUNREACHABLELOCATOR is returned when the requested locator 1081 is determined to be not reachable according to a reachability check. 1083 An error ETOOMANYLOCATORS is returned when the number of locators 1084 specified exceeds the limit (SHIM_MAX_LOCATORS), or when the size of 1085 the buffer provided by the application is not large enough to store 1086 the locator list provided by the shim sub-layer. 1088 The usage of the option is same as that of SHIM_LOCLIST_LOCAL. 1090 6.12. SHIM_APP_TIMEOUT 1092 The SHIM_APP_TIMEOUT option is used to get or set the Send Timeout 1093 value of the REAP protocol[RFC5534]. This option is effective only 1094 when there is a shim context associated with the socket. 1096 The data type of the option value is an integer. The value indicates 1097 the period of timeout in seconds to send a REAP Keepalive message 1098 since the last outbound traffic. By default, the option value is set 1099 to 0, meaning that the option is disabled. When the option is 1100 disabled, the REAP mechanism follows its default value of Send 1101 Timeout value as specified in [RFC5534] 1103 When the application specifies the socket option to an unconnected 1104 socket, an error code EOPNOTSUPP is returned to the application. 1106 When there is no shim context associated with the socket, an error 1107 code ENOENT is returned to the application. 1109 When there is no REAP protocol instance on the system, an error code 1110 EOPNOTSUPP is returned to the application. 1112 For example, an application can set the timeout value by using the 1113 socket option as follows. 1115 int optval; 1117 optval = 15; /* 15 seconds */ 1119 setsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, 1120 sizeof(optval)); 1122 For example, an application can get the timeout value by using the 1123 socket option as follows. 1125 int optval; 1126 int len; 1128 len = sizeof(optval); 1130 getsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, &len); 1132 6.13. SHIM_PATHEXPLORE 1134 The application MAY use this socket option to get or set parameters 1135 concerning path exploration. Path exploration is a procedure to find 1136 an alternative locator pair to the current locator pair. As the REAP 1137 specification defines, a peer may send Probe messages to find an 1138 alternative locator pair. 1140 This option is effective only when there is a shim context associated 1141 with the socket. 1143 The data type of the option value is a pointer to the buffer where a 1144 set of information for path exploration is stored. The data 1145 structure is defined in Section 8. 1147 By default, the option value is set to NULL, meaning that the option 1148 is disabled. 1150 When the application specifies the socket option to an unconnected 1151 socket, an error code EOPNOTSUPP is returned to the application. 1153 When there is no shim context associated with the socket, an error 1154 code ENOENT is returned to the application. 1156 For example, an application can set parameters for path exploration 1157 by using the socket option as follows. 1159 struct shim6_pathexplore pe; 1161 pe.pe_probenum = 4; /* times */ 1162 pe.pe_keepaliveto = 10; /* seconds */ 1163 pe.pe_initprobeto = 500; /* milliseconds */ 1164 pe.pe_reserved = 0; 1166 setsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, sizeof(pe)); 1168 For example, an application can get parameters for path exploration 1169 by using the socket option as follows. 1171 struct shim6_pathexplore pe; 1172 int len; 1174 len = sizeof(pe); 1176 getsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, &len); 1178 6.14. SHIM_DEFERRED_CONTEXT_SETUP 1180 The SHIM_DEFERRED_CONTEXT_SETUP option is used to check whether 1181 deferred context setup is possible or not. Deferred context setup 1182 means that the context is established in parallel with the data 1183 communication. Note that SHIM6 supports deferred context setup and 1184 HIP does not because EIDs in HIP (i.e., Host Identifiers) are non- 1185 routable. 1187 Note that the socket option is read-only and the option value can be 1188 ready by getsockopt(). 1190 The data type for the option value is an integer. The option value 1191 MUST be binary (0 or 1). The option value 1 means that the shim sub- 1192 layer supports deferred context setup. 1194 When the application specifies the socket option to an unconnected 1195 socket, an error code EOPNOTSUPP is returned to the application. 1197 For example, an application can check whether deferred context setup 1198 is possible or not as follows: 1200 int optval; 1201 int len; 1203 len = sizeof(optval); 1205 getsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, 1206 &optval, &len); 1208 6.15. Applicability 1210 All the socket options defined in this section except for the 1211 SHIM_DONTSHIM option are applicable to applications that use 1212 connected sockets. 1214 All the socket options defined in this section except for the 1215 SHIM_ASSOCIATED, SHIM_DONTSHIM and SHIM_CONTEXT_DEFERRED_SETUP 1216 options are effective only when there is a shim context associated 1217 with the socket. 1219 6.16. Error Handling 1221 If successful, getsockopt() and setsockopt() return 0; otherwise, the 1222 functions return -1 and set errno to indicate an error. 1224 The following are new error values defined for some shim specific 1225 socket options indicating that the getsockopt() or setsockopt() 1226 finished incompletely: 1228 EINVALIDLOCATOR 1229 This indicates that the locator is not part of the HBA 1230 set[RFC5535] within the shim context associated with the socket. 1231 EUNVERIFIEDLOCATOR 1232 This indicates that the reachability of the locator has not been 1233 confirmed. This error is applicable to only peer's locator. 1234 EUNREACHABLELOCATOR 1235 This indicates that the locator is not reachable according to the 1236 result of the reachability check. This error is applicable to 1237 only peer's locator. 1239 7. Ancillary Data for Multihoming Shim Sub-layer 1241 This section provides definitions of ancillary data to be used for 1242 locator management and notification from/to the shim sub-layer to/ 1243 from application. 1245 When the application performs locator management by sendmsg() or 1246 recvmsg(), a member of the msghdr structure (given in Figure 3) 1247 called msg_control holds a pointer to the buffer in which one or more 1248 shim specific ancillary data objects may be stored. An ancillary 1249 data object can store a single locator. It should be possible to 1250 process the shim specific ancillary data object by the existing 1251 macros defined in the Posix standard and [RFC3542]. 1253 struct msghdr { 1254 caddr_t msg_name; /* optional address */ 1255 u_int msg_namelen; /* size of address */ 1256 struct iovec *msg_iov; /* scatter/gather array */ 1257 u_int msg_iovlen; /* # elements in msg_iov */ 1258 caddr_t msg_control; /* ancillary data, see below */ 1259 u_int msg_controllen; /* ancillary data buffer len */ 1260 int msg_flags; /* flags on received message */ 1261 }; 1263 Figure 3: msghdr structure 1265 In the case of unconnected socket, msg_name stores the socket address 1266 of the peer. Note that the address is not a locator of the peer but 1267 the identifier of the peer. SHIM_LOC_PEER_RECV can be used to get 1268 the locator of the peer node. 1270 Table 2 is a list of the shim specific ancillary data which can be 1271 used for locator management by recvmsg() or sendmsg(). In any case, 1272 the value of cmsg_level MUST be set as SOL_SHIM. 1274 +---------------------+-----------+-----------+-----------------+ 1275 | cmsg_type | sendmsg() | recvmsg() | cmsg_data[] | 1276 +---------------------+-----------+-----------+-----------------+ 1277 | SHIM_LOC_LOCAL_RECV | | o | Note 1 | 1278 | SHIM_LOC_PEER_RECV | | o | Note 1 | 1279 | SHIM_LOC_LOCAL_SEND | o | | Note 1 | 1280 | SHIM_LOC_PEER_SEND | o | | Note 1 | 1281 | SHIM_FEEDBACK | o | | shim_feedback{} | 1282 +---------------------+-----------+-----------+-----------------+ 1284 Table 2: Shim specific ancillary data 1286 Note 1: cmsg_data[] within msg_control includes a single 1287 sockaddr_in{} or sockaddr_in6{} and padding if necessary 1289 7.1. Get Locator from Incoming Packet 1291 An application can get locator information from the received IP 1292 packet by specifying the shim specific socket options for the socket. 1293 When SHIM_LOC_LOCAL_RECV and/or SHIM_LOC_PEER_RECV socket options are 1294 set, the application can retrieve local and/or remote locator from 1295 the ancillary data. 1297 When there is no shim context associated with the socket, the shim 1298 sub-layer MUST return zero-filled locator information to the 1299 application. 1301 7.2. Set Locator for Outgoing Packet 1303 An application can specify the locators to be used for transmitting 1304 an IP packet by sendmsg(). When the ancillary data of cmsg_type 1305 SHIM_LOC_LOCAL_SEND and/or SHIM_LOC_PEER_SEND are specified, the 1306 application can explicitly specify the source and/or the destination 1307 locators to be used for the communication over the socket. If the 1308 specified locator pair is verified, the shim sub-layer overrides the 1309 locator(s) of the outgoing IP packet. Note that the effect is 1310 limited to the datagram transmitted by the sendmsg(). 1312 When there is no shim context associated with the socket, an error 1313 code ENOENT is returned to the application. 1315 An error code EINVALIDLOCATOR is returned when validation of the 1316 specified locator fails. 1318 An error EUNVERIFIEDLOCATOR is returned when reachability for the 1319 requested locator has not been verified yet. The application is 1320 recommended to use another destination locator until the reachability 1321 check for the requested locator is done. 1323 An error EUNREACHABLELOCATOR is returned when the requested locator 1324 is determined to be not reachable according to a reachability check. 1325 The application is recommended to use another destination locator 1326 when receiving the error. 1328 7.3. Notification from Application to Multihoming Shim Sub-layer 1330 An application MAY provide feedback to the shim sub-layer about the 1331 communication status. Such feedback are useful for the shim sub- 1332 layer to monitor the reachability status of the currently used 1333 locator pair in a given shim context. 1335 The notification can be made by sendmsg() specifying a new ancillary 1336 data called SHIM_FEEDBACK. The ancillary data can be handled by 1337 specifying SHIM_FEEDBACK option in cmsg_type. 1339 When there is no shim context associated with the socket, an error 1340 code ENOENT is returned to the application. 1342 See Section 8.3 for details of the data structure to be used. 1344 It is outside the scope of this document how the shim sub-layer would 1345 react when a feedback is provided by an application. 1347 7.4. Applicability 1349 All the ancillary data for the shim sub-layer is applicable to 1350 connected sockets. 1352 Care is needed when the SHIM_LOC_*_RECV socket option is used for 1353 stream-oriented sockets (e.g., TCP sockets) because there is no one- 1354 to-one mapping between a single send or receive operation and the 1355 data (e.g., a TCP segment) being received. In other words, there is 1356 no guarantee that the locator(s) set in the SHIM_LOC_*_RECV ancillary 1357 data is identical to the locator(s) that appear in the IP packets 1358 received. The shim sub-layer SHOULD provide the latest locator 1359 information to the application in response to the SHIM_LOC_*_RECV 1360 socket option. 1362 8. Data Structures 1364 This section gives data structures for the shim sub-layer. These 1365 data structures are either used as a parameter for setsockopt() or 1366 getsockopt() (as mentioned in Section 6) or as a parameter for 1367 ancillary data to be processed by sendmsg() or recvmsg() (as 1368 mentioned in Section 7). 1370 8.1. Data Structure for Locator Information 1372 As defined in Section 6, the SHIM_LOC_*_PREF, SHIM_LOC_*_SEND, and 1373 SHIM_LOCLIST_* socket options need to handle one or more locator 1374 information. Locator information includes not only the locator 1375 itself but also additional information about the locator which is 1376 useful for locator management. A new data structure is defined to 1377 serve as a placeholder for the locator information. 1379 Figure 4 illustrates the data structure called shim_locator which 1380 stores a locator information. 1382 struct shim_locator { 1383 uint8_t lc_family; /* address family */ 1384 uint8_t lc_proto; /* protocol */ 1385 uint16_t lc_port; /* port number */ 1386 uint16_t lc_prio; /* preference value */ 1387 uint16_t lc_weight; /* weight */ 1388 uint32_t lc_ifidx; /* interface index */ 1389 struct in6_addr lc_addr; /* address */ 1390 uint16_t lc_flags; /* flags */ 1391 }; 1393 Figure 4: shim locator structure 1395 lc_family 1396 Address family of the locator (e.g. AF_INET, AF_INET6). It is 1397 required that the parameter contains non-zero value indicating the 1398 exact address family of the locator. 1399 lc_proto 1400 Internet Protocol number for the protocol which is used to handle 1401 locator behind NAT. The value MUST be set to zero when there is 1402 no NAT involved. When the locator is behind NAT, the value MUST 1403 be set to IPPROTO_UDP. 1404 lc_port 1405 Port number which is used for handling locator behind NAT. 1406 lc_prio 1407 The priority of the locator. The range is 0-65535. The lowest 1408 priority value means the highest priority. 1409 lc_weight 1410 The weight value indicates a relative weight for locators with the 1411 same priority value. The range is 0-65535. A locator with higher 1412 weight value is prioritized over the other locators with lower 1413 weight values. 1414 lc_ifidx 1415 Interface index of the network interface to which the locator is 1416 assigned. This field is applicable only to local locators, and 1417 has no effect in set operation. 1418 lc_addr 1419 Contains the locator. In case of IPv4, the locator MUST be 1420 formatted in the IPv4-mapped IPv6 address as defined in [RFC4291]. 1421 The locator MUST be stored in network byte order. 1422 lc_flags 1423 Each bit of the flags represents a specific characteristics of the 1424 locator. Hash Based Address (HBA) is defined as 0x01. 1425 Cryptographically Generated Address (CGA) is defined as 0x02. 1426 This field has no effect in set operation. 1428 8.1.1. Handling Locator behind NAT 1430 Note that the locator information MAY contain a locator behind a 1431 Network Address Translator (NAT). Such a situation may arise when 1432 the host is behind the NAT and uses a local address as a source 1433 locator to communicate with the peer. Note that a NAT traversal 1434 mechanism for HIP is defined, which allows HIP host to tunnel control 1435 and data traffic over UDP[RFC5770]. Note also that the locator 1436 behind NAT is not necessarily an IPv4 address but it can be an IPv6 1437 address. Below is an example where the application sets a UDP 1438 encapsulation interface as a source locator when sending IP packets. 1440 struct shim_locator locator; 1441 struct in6_addr ia6; 1443 /* copy the private IPv4 address to the ia6 as an IPv4-mapped 1444 IPv6 address */ 1446 memset(&locator, 0, sizeof(locator)); 1448 /* fill shim_locator data structure */ 1449 locator.lc_family = AF_INET; 1450 locator.lc_proto = IPPROTO_UDP; 1451 locator.lc_port = 50500; 1452 locator.lc_ifidx = 0; 1453 locator.lc_flags = 0; 1454 locator.lc_prio = 0; 1455 locator.lc_weight = 0; 1457 memcpy(&locator.lc_addr, &ia6, sizeof(ia6)); 1459 setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, 1460 sizeof(locator)); 1462 Figure 5: Handling locator behind NAT 1464 8.2. Path Exploration Parameter 1466 As defined in Section 6, SHIM_PATHEXPLORE allows application to set 1467 or read the parameters for path exploration and failure detection. A 1468 new data structure called shim_pathexplore is defined to store the 1469 necessary parameters. Figure 6 illustrates the data structure. The 1470 data structure can be passed to getsockopt() or setsockopt() as an 1471 argument. 1473 struct shim_pathexplore { 1474 uint16_t pe_probenum; /* # of initial probes */ 1475 uint16_t pe_keepaliveto; /* Keepalive Timeout */ 1476 uint16_t pe_keepaliveint /* Keepalive Interval */ 1477 uint16_t pe_initprobeto; /* Initial Probe Timeout */ 1478 uint32_t pe_reserved; /* reserved */ 1479 }; 1481 Figure 6: path explore structure 1483 pe_probenum 1484 Indicates the number of initial probe messages to be sent. The 1485 value MUST be set as per [RFC5534]. 1486 pe_keepaliveto 1487 Indicates timeout value in seconds for detecting a failure when 1488 the host does not receive any packets for a certain period of time 1489 while there is outbound traffic. When the timer expires, path 1490 exploration procedure will be carried out by sending a REAP Probe 1491 message. The value MUST be set as per [RFC5534]. 1492 pe_keepaliveint 1493 Indicates interval of REAP keepalive messages in seconds to be 1494 sent by the host when there is no outbound traffic to the peer 1495 host. The value MUST be set as per [RFC5534]. 1496 pe_initprobeto 1497 Indicates retransmission timer of REAP Probe message in 1498 milliseconds. Note that this timer is applied before exponential 1499 back-off is started. A REAP Probe message for the same locator 1500 pair may be retransmitted. The value MUST be set as per 1501 [RFC5534]. 1502 pe_reserved 1503 A reserved field for future extension. By default, the field MUST 1504 be initialized to zero. 1506 8.3. Feedback Information 1508 As mentioned in Section 7.3, applications can inform the shim sub- 1509 layer about the status of unicast reachability of the locator pair 1510 currently in use. The feedback information can be handled by using 1511 ancillary data called SHIM_FEEDBACK. A new data structure named 1512 shim_feedback is illustrated in Figure 7. 1514 struct shim_feedback { 1515 uint8_t fb_direction; /* direction of traffic */ 1516 uint8_t fb_indicator; /* indicator (1-3) */ 1517 uint16_t fb_reserved; /* reserved */ 1518 }; 1520 Figure 7: feedback information structure 1522 direction 1523 Indicates direction of reachability between a locator pair in 1524 question. A value 0 indicates outbound and a value 1 indicates 1525 inbound direction. 1526 indicator 1527 A value indicating the degree of satisfaction of a unidirectional 1528 reachability for a given locator pair. 1529 * 0: Default value. Whenever this value is specified the 1530 feedback information MUST NOT be processed by the shim sub- 1531 layer. 1532 * 1: Unable to connect. There is no unidirectional reachability 1533 between the locator pair in question. 1534 * 2: Unsatisfactory. The application is not satisfied with the 1535 unidirectional reachability between the locator pair in 1536 question. 1537 * 3: Satisfactory. There is satisfactory unidirectional 1538 reachability between the locator pair in question. 1539 reserved 1540 Reserved field. MUST be ignored by the receiver. 1542 9. System Requirements 1544 As addressed in Section 6, most of the socket options and ancillary 1545 data defined in this document are applicable to connected sockets. 1546 It is assumed that the kernel is capable of maintaining the 1547 association between a connected socket and a shim context. This 1548 requirement is considered to be reasonable because a pair of source 1549 and destination IP addresses is bound to a connected socket. 1551 10. Relation to Existing Sockets API Extensions 1553 This section explains relation between the sockets API defined in 1554 this document and the existing sockets API extensions. 1556 As mentioned in Section 6, the basic assumption is that the existing 1557 sockets API continues to work above the shim sub-layer. This means 1558 that, the existing sockets API deals with identifiers, and the 1559 sockets API defined in this document deals with locators. 1561 SHIM_LOC_LOCAL_SEND and SHIM_LOC_PEER_SEND socket options are 1562 semantically similar to the IPV6_PKTINFO socket API in the sense that 1563 both provide a means for application to set the source IP address of 1564 outbound IP packets. 1566 SHIM_LOC_LOCAL_RECV and SHIM_LOC_PEER_RECV socket options are 1567 semantically similar to the IP_RECVDSTADDR and IPV6_PKTINFO socket 1568 APIs in the sense that both provides a means for application to get 1569 the source and/or destination IP address of inbound IP packets. 1571 getsockname() and getpeername() enable application to get 'name' of 1572 the communication endpoints which is represented by a pair of IP 1573 address and port number assigned to the socket. getsockname() gives 1574 IP address and port number assigned to the socket on the local side, 1575 and getpeername() gives IP address and port number of the peer side. 1577 11. Operational Considerations 1579 This section gives operational considerations of the sockets API 1580 defined in this document. 1582 11.1. Conflict Resolution 1584 There can be a conflicting situation when different applications 1585 specify difference preference for the same shim context. For 1586 instance, suppose if application A and B establish communication with 1587 the same EID pair while both applications have different preference 1588 in their choice of local locator. The notion of context forking in 1589 SHIM6 can resolve the conflicting situation. 1591 It is possible that socket options defined in Section 6 cause 1592 conflicting situation when the target context is shared by multiple 1593 applications. In such a case, the socket handler should inform the 1594 shim sub-layer that context forking is required. In SHIM6, when a 1595 context is forked, an unique identifier called Forked Instance 1596 Identifier (FII) is assigned to the newly forked context. The forked 1597 context is then exclusively associated with the socket through which 1598 non-default preference value was specified. The forked context is 1599 maintained by the shim sub-layer during the lifetime of associated 1600 socket instance. When the socket is closed, the shim sub-layer 1601 SHOULD delete associated context. 1603 When the application specifies SHIM_LOC_*_SEND specifying a different 1604 source or destination locator which does not have the highest 1605 priority and weight specified by the SHIM_LOC_*_PREF, the shim sub- 1606 layer SHOULD supersede the request made by SHIM_LOC_*_SEND over the 1607 preference specified by SHIM_LOC_*_PREF. 1609 When the peer provides preferences of the locators (e.g., a SHIM6 1610 peer sends a locator with a Locator Preferences Option) which 1611 conflict with preference specified by the applications either by 1612 SHIM_LOC_PEER_SEND or SHIM_LOC_PEER_PREF, the shim sub-layer SHOULD 1613 supersede the preference made by the application over the preference 1614 specified by the peer. 1616 11.2. Incompatibility between IPv4 and IPv6 1618 The shim sub-layer performs identifier/locator adaptation. 1619 Therefore, in some cases, the whole IP header can be replaced with 1620 new IP header of a different address family (e.g. conversion from 1621 IPv4 to IPv6 or vice versa). Hence, there is an issue how to make 1622 the conversion with minimum impact. Note that this issue is common 1623 in other protocol conversion techniques 1624 [RFC2765][I-D.ietf-behave-v6v4-xlate]. 1626 As studied in the previous works on protocol 1627 conversion[RFC2765][I-D.ietf-behave-v6v4-xlate], some of the features 1628 (IPv6 routing headers, hop-by-hop extension headers, and destination 1629 headers) from IPv6 are not convertible to IPv4. In addition, notion 1630 of source routing is not exactly the same in IPv4 and IPv6. This 1631 means that an error may occur during the conversion of identifier and 1632 locator. It is outside the scope of this document to describe how 1633 the shim sub-layer should behave in such erroneous cases. 1635 12. IANA Considerations 1637 There is no IANA considerations for the socket options (SHIM_*), the 1638 ancillary data, and the socket level (SOL_SHIM) that are defined in 1639 this document. All the numbers concerned are not under the control 1640 of IETF or IANA but they are platform-specific. 1642 13. Protocol Constants and Variables 1644 This section defines protocol constants and variables. 1645 SHIM_MAX_LOCATORS The maximum number of the locators to be included 1646 in a locator list. The value is set to 32. 1648 14. Security Considerations 1650 This section gives security considerations of the API defined in this 1651 document. 1653 14.1. Treatment of Unknown Locator 1655 When sending IP packets, there is a possibility that an application 1656 requests use of unknown locator for the source and/or destination 1657 locators. Note that treatment of unknown locator can be a subject of 1658 security considerations because use of invalid source and/or 1659 destination locator may cause redirection attack. 1661 14.1.1. Treatment of Unknown Source Locator 1663 The shim sub-layer checks if the requested locator is available on 1664 any of the local interface. If not, the shim sub-layer MUST reject 1665 the request and return an error message with the EINVALIDLOCATOR code 1666 to the application. If the locator is confirmed to be available, the 1667 shim sub-layer SHOULD initiate the procedure to update the locator 1668 list. 1670 Use of the following socket options and ancillary data requires 1671 treatment of unknown source locator: 1672 o SHIM_LOC_LOCAL_SEND 1673 o SHIM_LOC_LOCAL_PREF 1674 o SHIM_LOCLIST_LOCAL 1676 14.1.2. Treatment of Unknown Destination Locator 1678 If the shim sub-layer turns out to be SHIM6, the SHIM6 layer MUST 1679 reject the request for using an unknown destination locator. 1681 If the shim sub-layer turns out to be HIP, the HIP layer MUST reject 1682 the request for using an unknown destination locator. There is, 1683 however, an exceptional case where the HIP layer SHOULD accept the 1684 request provided that the HIP association is in an UNASSOCIATED 1685 state. Details of locator handling in HIP is described in section 1686 4.6 of [I-D.ietf-hip-native-api]. 1688 Use of the following socket options and ancillary data requires 1689 treatment of unknown destination locator: 1690 o SHIM_LOC_PEER_SEND 1691 o SHIM_LOC_PEER_PREF 1692 o SHIM_LOCLIST_PEER 1694 15. Changes 1696 15.1. Changes from version 00 to version 01 1698 o Define shim_locator{} data type which is a placeholder for 1699 locator. 1700 o Define shim_pathexplore{} data type in which a set of REAP 1701 parameters are stored. 1702 o Remove descriptions about "stickiness" of socket options. 1703 o Deprecate SHIM_IF_RECV and SHIM_IF_SEND socket options. 1704 o Give default value and how to disable given socket option. 1706 15.2. Changes from version 01 to version 02 1708 o Add section describing context forking. 1709 o Rephrase conclusion section. 1710 o Separate normative references from informative references. 1711 o Remove texts from discussion section that are not relevant to the 1712 contents of the document. 1713 o Add section describing change history (this section). 1715 15.3. Changes from version 02 to version 03 1717 o Add an Appendix section describing the issue of context forking. 1719 15.4. Changes from version 03 to version 04 1721 o Updated reference. 1722 o Correct typo and grammatical errors. 1724 15.5. Changes from version 04 to version 05 1726 o Added definition of SHIM_FEEDBACK ancillary data. 1727 o Added an example of code using the SHIM_LOCLIST_LOCAL 1728 o Added SHIM_LOC_LOCAL_SEND and SHIM_LOC_PEER_SEND socket options. 1730 15.6. Changes from version 05 to version 06 1732 o Updated references. 1734 15.7. Changes from version 06 to version 07 1736 o Resolved editorial issues. 1738 15.8. Changes from version 07 to version 08 1740 No changes are made except for updates of the references. 1742 15.9. Changes from version 08 to version 09 1744 o Updated texts for Section 1 and Section 5 according to the 1745 comments provided by Samu Varjonen. 1746 o Made it clear that downgrading the multihoming shim support (i.e., 1747 specifying value 1 with the SHIM_DONTSHIM socket option) is only 1748 allowed before the socket is connected. 1749 o Updated locator information (shim_locator{}) so that it can 1750 contain a locator behind NAT. 1752 15.10. Changes from version 09 to version 10 1754 o Addressed applicability of socket options and ancillary data for 1755 the shim sub-layer. 1756 o Addressed system requirements. 1757 o Removed unnecessary description about deprecated socket option 1758 (SHIM_IF_RECV). 1760 15.11. Changes from version 10 to version 11 1762 o Added short descriptions about connected sockets and unconnected 1763 sockets. 1764 o Relaxed applicability of the socket options. 1765 o Relaxed applicability of the ancillary data. 1766 o Added notification about locator change. 1768 15.12. Changes from version 11 to version 12 1770 o Reflected comments from Brian Karpenter. 1771 o Reflected comments from Michael Scharf. 1773 15.13. Changes from version 12 to version 13 1775 o Reflected comments from Sebastien Barre. 1776 o Removed the description about the notification from the shim sub- 1777 layer to applications. 1778 o Narrowed down the scope of the applicability of the socket options 1779 and the ancillary data. 1781 15.14. Changes from version 13 to version 14 1783 o No change was made. The draft was re-submitted to avoid 1784 expiration. 1786 15.15. Changes from version 14 to version 15 1788 o Addressed the difference between SHIM_LOC_PEER_SEND and 1789 SHIM_LOC_PEER_PREF. 1790 o Made clear distinction between validation of locator and 1791 verification of locator, and introduced two errors: 1792 EUNVERIFIEDLOCATOR and EUNREACHABLELOCATOR. 1793 o Addressed exceptional case for HIP in handling of unknown 1794 destination locator. 1796 15.16. Changes from version 15 to version 16 1798 Updated the documents reflecting the comments received during the 1799 IETF Last Call. 1801 o Added Keepalive Interval (pe_keepaliveint) as a member of the 1802 shim_pathexplore{} data structure. 1803 o Addressed the unit of pe_keepaliveto. 1804 o Rephrased the last sentence in Appendix A to make it clear that 1805 the addressed issue is for further study. 1806 o Corrected a typo. 1808 15.17. Changes from version 16 to version 17 1810 Updated the documents reflecting the comments received during the 1811 IESG review. 1812 o Applied the RFC 2119 terminology more strictly. 1813 o Made it clear whether each socket option can be set and/or get. 1814 o Made some adjustments to the semantics of SHIM_LOC_LOCAL_PREF. 1815 o Made the usage of lc_proto clear. 1816 o Removed a misleading sentence from the paragraph describing 1817 lc_ifidx. 1819 16. Acknowledgments 1821 Authors would like to thank Jari Arkko who participated in the 1822 discussion that lead to the first version of this document, and 1823 Tatuya Jinmei who thoroughly reviewed the early version of this draft 1824 and provided detailed comments on sockets API related issues. Thomas 1825 Henderson provided valuable comments especially from HIP 1826 perspectives. 1828 Authors sincerely thank to the following people for their helpful 1829 comments to the document: Samu Varjonen, Dmitriy Kuptsov, Brian 1830 Carpenter, Michael Scharf, Sebastien Barre, and Roni Even. 1832 17. References 1834 17.1. Normative References 1836 [POSIX] "IEEE Std. 1003.1-2001 Standard for Information Technology 1837 -- Portable Operating System Interface (POSIX). Open group 1838 Technical Standard: Base Specifications, Issue 6, 1839 http://www.opengroup.org/austin", December 2001. 1841 [RFC2119] Bradner, S., "Key words for use in RFCs to Indicate 1842 Requirement Levels", BCP 14, RFC 2119, March 1997. 1844 [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, 1845 "Advanced Sockets Application Program Interface (API) for 1846 IPv6", RFC 3542, May 2003. 1848 [RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol 1849 (HIP) Architecture", RFC 4423, May 2006. 1851 [RFC5533] Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming 1852 Shim Protocol for IPv6", RFC 5533, June 2009. 1854 [RFC5534] Arkko, J. and I. van Beijnum, "Failure Detection and 1855 Locator Pair Exploration Protocol for IPv6 Multihoming", 1856 RFC 5534, June 2009. 1858 17.2. Informative References 1860 [I-D.ietf-behave-v6v4-xlate] 1861 Li, X., Bao, C., and F. Baker, "IP/ICMP Translation 1862 Algorithm", draft-ietf-behave-v6v4-xlate-23 (work in 1863 progress), September 2010. 1865 [I-D.ietf-hip-native-api] 1866 Komu, M. and T. Henderson, "Basic Socket Interface 1867 Extensions for Host Identity Protocol (HIP)", 1868 draft-ietf-hip-native-api-12 (work in progress), 1869 January 2010. 1871 [I-D.ietf-shim6-app-refer] 1872 Nordmark, E., "Shim6 Application Referral Issues", 1873 draft-ietf-shim6-app-refer-00 (work in progress), 1874 July 2005. 1876 [RFC2765] Nordmark, E., "Stateless IP/ICMP Translation Algorithm 1877 (SIIT)", RFC 2765, February 2000. 1879 [RFC2782] Gulbrandsen, A., Vixie, P., and L. Esibov, "A DNS RR for 1880 specifying the location of services (DNS SRV)", RFC 2782, 1881 February 2000. 1883 [RFC4291] Hinden, R. and S. Deering, "IP Version 6 Addressing 1884 Architecture", RFC 4291, February 2006. 1886 [RFC5535] Bagnulo, M., "Hash-Based Addresses (HBA)", RFC 5535, 1887 June 2009. 1889 [RFC5770] Komu, M., Henderson, T., Tschofenig, H., Melen, J., and A. 1890 Keranen, "Basic Host Identity Protocol (HIP) Extensions 1891 for Traversal of Network Address Translators", RFC 5770, 1892 April 2010. 1894 Appendix A. Context Forking 1896 In this section, an issue concerning context forking and its relation 1897 to the multihoming shim API are discussed. 1899 SHIM6 supports a notion of context forking. A peer may decide to 1900 fork a context for certain reason (e.g. upper layer protocol prefers 1901 to use different locator pair than the one defined in available 1902 context). The procedure of forking context is done similar to the 1903 normal context establishment, performing the 4-way message exchange. 1904 A peer who has decided to fork a context initiates the context 1905 establishment. Hereafter, we call this peer the "initiator". The 1906 peer of the initiator is called the "responder". 1908 Once the forked context is established between the peers, on the 1909 initiator side, it is possible to apply forked context to the packet 1910 flow since the system maintains an association between the forked 1911 context and the socket owned by the application that has requested 1912 the context forking. How this association is maintained is an 1913 implementation specific issue. However, on the responder side, there 1914 is a question how the outbound packet can be multiplexed by the shim 1915 sub-layer because there are more than one SHIM6 contexts that match 1916 with the ULID pair of the packet flow. There is a need to 1917 differentiate packet flows not only by the ULID pairs but by some 1918 other information and associate a given packet flow with a specific 1919 context. 1921 Figure 8 gives an example of a scenario where two communicating peers 1922 fork a context. Initially, there has been a single transaction 1923 between the peers, by the application 1 (App1). Accordingly, another 1924 transaction is started, by application 2 (App2). Both of the 1925 transactions are made based on the same ULID pair. The first context 1926 pair (Ctx1) is established for the transaction of App1. Given the 1927 requests from App2, the shim sub-layer on Peer 1 decides to fork a 1928 context. Accordingly, a forked context (Ctx2) is established between 1929 the peers, which should be exclusively applied to the transaction of 1930 App2. Ideally, multiplexing and demultiplexing of packet flows that 1931 relate to App1 and App2 should be done as illustrated in Figure 8. 1932 However, as mentioned earlier, the responder needs to multiplex 1933 outbound flows of App1 and App2 somehow. Note that if a context 1934 forking occurs on the initiator side, a context forking needs to 1935 occur also on the responder side. 1937 Peer 1 Peer 2 1938 (initiator) (responder) 1940 +----+ +----+ +----+ +----+ 1941 |App1| |App2| |App1| |App2| 1942 +----+ +----+ +----+ +----+ 1943 |^ |^ ^| ^| 1944 v| v| |v |v 1945 -----S1-------------S2----- -----S1-------------S2----- 1946 || || || || 1947 || || || || 1949 Ctx1 Ctx2 Ctx1 Ctx2 1950 ULID: ULID: ULID: ULID: 1951 Loc: Loc: Loc: Loc: 1952 FII: 0 FII: 100 FII: 0 FII: 100 1954 |^ |^ ^| ^| 1955 || || || || 1956 || || || || 1957 \..............||....................../| || 1958 \.............||......................./ || 1959 || || 1960 \|...................................../| 1961 \....................................../ 1963 Figure 8: context forking 1965 It is for further study how to solve the issue described above. 1967 Authors' Addresses 1969 Miika Komu 1970 Helsinki Institute for Information Technology 1971 Tammasaarenkatu 3 1972 Helsinki 1973 Finland 1975 Phone: +358503841531 1976 Fax: +35896949768 1977 Email: miika@iki.fi 1978 URI: http://www.hiit.fi/ 1979 Marcelo Bagnulo 1980 Universidad Carlos III de Madrid 1981 Av. Universidad 30 1982 Leganes 28911 1983 SPAIN 1985 Phone: +34 91 6248837 1986 Email: marcelo@it.uc3m.es 1987 URI: http://it.uc3m.es/marcelo 1989 Kristian Slavov 1990 Ericsson Research Nomadiclab 1991 Hirsalantie 11 1992 Jorvas FI-02420 1993 Finland 1995 Phone: +358 9 299 3286 1996 Email: kristian.slavov@ericsson.com 1998 Shinta Sugimoto (editor) 1999 Nippon Ericsson K.K. 2000 Koraku Mori Building 2001 1-4-14, Koraku, Bunkyo-ku 2002 Tokyo 112-0004 2003 Japan 2005 Phone: +81 3 3830 2241 2006 Email: shinta@sfc.wide.ad.jp