--- 1/draft-ietf-shim6-multihome-shim-api-04.txt 2008-02-23 12:12:15.000000000 +0100 +++ 2/draft-ietf-shim6-multihome-shim-api-05.txt 2008-02-23 12:12:15.000000000 +0100 @@ -1,22 +1,22 @@ SHIM6 Working Group M. Komu Internet-Draft HIIT Intended status: Informational M. Bagnulo -Expires: August 10, 2008 UC3M +Expires: August 26, 2008 UC3M K. Slavov S. Sugimoto, Ed. Ericsson - February 7, 2008 + February 23, 2008 Socket Application Program Interface (API) for Multihoming Shim - draft-ietf-shim6-multihome-shim-api-04 + draft-ietf-shim6-multihome-shim-api-05 Status of this Memo By submitting this Internet-Draft, each author represents that any applicable patent or other IPR claims of which he or she is aware have been or will be disclosed, and any of which he or she becomes aware will be disclosed, in accordance with Section 6 of BCP 79. Internet-Drafts are working documents of the Internet Engineering Task Force (IETF), its areas, and its working groups. Note that @@ -27,21 +27,21 @@ and may be updated, replaced, or obsoleted by other documents at any time. It is inappropriate to use Internet-Drafts as reference material or to cite them other than as "work in progress." The list of current Internet-Drafts can be accessed at http://www.ietf.org/ietf/1id-abstracts.txt. The list of Internet-Draft Shadow Directories can be accessed at http://www.ietf.org/shadow.html. - This Internet-Draft will expire on August 10, 2008. + This Internet-Draft will expire on August 26, 2008. Copyright Notice Copyright (C) The IETF Trust (2008). Abstract This document specifies a socket API for the multihoming shim layer. The API aims to enable interactions between the applications and the multihoming shim layer for advanced locator management and access to @@ -60,57 +60,60 @@ 4. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 7 5. Socket Options for Multihoming Shim Layer . . . . . . . . . . 9 5.1. SHIM_ASSOCIATED . . . . . . . . . . . . . . . . . . . . . 12 5.2. SHIM_DONTSHIM . . . . . . . . . . . . . . . . . . . . . . 13 5.3. SHIM_HOT_STANDBY . . . . . . . . . . . . . . . . . . . . . 13 5.4. SHIM_PATHEXPLORE . . . . . . . . . . . . . . . . . . . . . 14 5.5. SHIM_LOC_LOCAL_PREF . . . . . . . . . . . . . . . . . . . 15 5.6. SHIM_LOC_PEER_PREF . . . . . . . . . . . . . . . . . . . . 16 5.7. SHIM_LOC_LOCAL_RECV . . . . . . . . . . . . . . . . . . . 17 5.8. SHIM_LOC_PEER_RECV . . . . . . . . . . . . . . . . . . . . 18 - 5.9. SHIM_LOCLIST_LOCAL . . . . . . . . . . . . . . . . . . . . 18 - 5.10. SHIM_LOCLIST_PEER . . . . . . . . . . . . . . . . . . . . 19 - 5.11. SHIM_APP_TIMEOUT . . . . . . . . . . . . . . . . . . . . . 19 - 5.12. SHIM_DEFERRED_CONTEXT_SETUP . . . . . . . . . . . . . . . 20 - 5.13. Error Handling . . . . . . . . . . . . . . . . . . . . . . 21 - 6. Ancillary Data for Multihoming Shim . . . . . . . . . . . . . 21 - 6.1. Get Locator Information from Incoming Packet . . . . . . . 23 - 6.2. Specify Locator Information for Outgoing Packet . . . . . 23 - 6.3. Notification from Application to Multihoming Shim . . . . 23 - 6.3.1. SHIM_FEEDBACK_POSITIVE . . . . . . . . . . . . . . . . 23 - 6.3.2. SHIM_FEEDBACK_NEGATIVE . . . . . . . . . . . . . . . . 24 - 7. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 24 - 7.1. Placeholder for Locator Information . . . . . . . . . . . 24 - 7.2. Path Exploration Parameter . . . . . . . . . . . . . . . . 25 - 8. Implications for Existing Socket API Extensions . . . . . . . 26 - 9. Resolving Conflicts with Preference Values . . . . . . . . . . 26 - 9.1. Implicit Forking . . . . . . . . . . . . . . . . . . . . . 27 - 10. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 27 - 10.1. Naming at Socket Layer . . . . . . . . . . . . . . . . . . 27 - 10.2. Additional Requirements from Application . . . . . . . . . 28 + 5.9. SHIM_LOC_LOCAL_SEND . . . . . . . . . . . . . . . . . . . 18 + 5.10. SHIM_LOC_PEER_SEND . . . . . . . . . . . . . . . . . . . . 19 + 5.11. SHIM_LOCLIST_LOCAL . . . . . . . . . . . . . . . . . . . . 20 + 5.12. SHIM_LOCLIST_PEER . . . . . . . . . . . . . . . . . . . . 22 + 5.13. SHIM_APP_TIMEOUT . . . . . . . . . . . . . . . . . . . . . 22 + 5.14. SHIM_DEFERRED_CONTEXT_SETUP . . . . . . . . . . . . . . . 23 + 5.15. Error Handling . . . . . . . . . . . . . . . . . . . . . . 24 + 6. Ancillary Data for Multihoming Shim . . . . . . . . . . . . . 24 + 6.1. Get Locator Information from Incoming Packet . . . . . . . 26 + 6.2. Specify Locator Information for Outgoing Packet . . . . . 26 + 6.3. Notification from Application to Multihoming Shim . . . . 26 + 7. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 27 + 7.1. Placeholder for Locator Information . . . . . . . . . . . 27 + 7.2. Path Exploration Parameter . . . . . . . . . . . . . . . . 28 + 7.3. Feedback Information . . . . . . . . . . . . . . . . . . . 29 + 8. Implications for Existing Socket API Extensions . . . . . . . 29 + 9. Resolving Conflicts with Preference Values . . . . . . . . . . 30 + 9.1. Implicit Forking . . . . . . . . . . . . . . . . . . . . . 30 + 10. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 31 + 10.1. Naming at Socket Layer . . . . . . . . . . . . . . . . . . 31 + 10.2. Additional Requirements from Application . . . . . . . . . 31 10.3. Issues of Header Conversion among Different Address - Family . . . . . . . . . . . . . . . . . . . . . . . . . . 28 - 10.4. Handling of Unknown Locator Provided by Application . . . 28 - 11. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 29 - 11.1. Changes from version 00 to version 01 . . . . . . . . . . 29 - 11.2. Changes from version 01 to version 02 . . . . . . . . . . 29 - 11.3. Changes from version 02 to version 03 . . . . . . . . . . 29 - 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 29 - 13. Security Considerations . . . . . . . . . . . . . . . . . . . 29 - 14. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . 30 - 15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 30 - 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 30 - 16.1. Normative References . . . . . . . . . . . . . . . . . . . 30 - 16.2. Informative References . . . . . . . . . . . . . . . . . . 31 - Appendix A. Context Forking . . . . . . . . . . . . . . . . . . . 31 - Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 33 - Intellectual Property and Copyright Statements . . . . . . . . . . 35 + Family . . . . . . . . . . . . . . . . . . . . . . . . . . 32 + 10.4. Handling of Unknown Locator Provided by Application . . . 32 + 11. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 32 + 11.1. Changes from version 00 to version 01 . . . . . . . . . . 32 + 11.2. Changes from version 01 to version 02 . . . . . . . . . . 33 + 11.3. Changes from version 02 to version 03 . . . . . . . . . . 33 + 11.4. Changes from version 03 to version 04 . . . . . . . . . . 33 + 11.5. Changes from version 04 to version 05 . . . . . . . . . . 33 + 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 33 + 13. Security Considerations . . . . . . . . . . . . . . . . . . . 33 + 14. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . 33 + 15. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 34 + 16. References . . . . . . . . . . . . . . . . . . . . . . . . . . 34 + 16.1. Normative References . . . . . . . . . . . . . . . . . . . 34 + 16.2. Informative References . . . . . . . . . . . . . . . . . . 35 + Appendix A. Context Forking . . . . . . . . . . . . . . . . . . . 35 + Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 37 + Intellectual Property and Copyright Statements . . . . . . . . . . 39 1. Introduction HIP and SHIM6 have a commonality in their protocol design separation of identifier and locator (hereafter identifier/locator separation). Both protocols aim to solve problems that are specific to multihoming environment in a host centric approach. In these protocols, a sub- layer within the IP layer maintains mappings of identifiers and locators. @@ -396,54 +399,69 @@ | | | | the socket. | | | SHIM_LOC_LOCAL_RECV | o | o | Request for the | int | | | | | destination | | | | | | locator of the | | | | | | received IP | | | | | | packet. | | | SHIM_LOC_PEER_RECV | o | o | Request for the | int | | | | | source locator | | | | | | of the received | | | | | | IP packet. | | - | SHIM_LOCLIST_LOCAL | o | o | Get or set a | *2 | + | SHIM_LOC_LOCAL_SEND | o | o | Request use of | *2 | + | | | | specific | | + | | | | locator as | | + | | | | source locator | | + | | | | of outgoing IP | | + | | | | packets. | | + | SHIM_LOC_PEER_SEND | o | o | Request use of | *2 | + | | | | specific | | + | | | | locator as | | + | | | | destination | | + | | | | locator of | | + | | | | outgoing IP | | + | | | | packets. | | + | SHIM_LOCLIST_LOCAL | o | o | Get or set a | *3 | | | | | list of | | | | | | locators | | | | | | associated with | | | | | | the local EID. | | - | SHIM_LOCLIST_PEER | o | o | Get or set a | *2 | + | SHIM_LOCLIST_PEER | o | o | Get or set a | *3 | | | | | list of | | | | | | locators | | | | | | associated with | | | | | | the peer's EID. | | | SHIM_APP_TIMEOUT | o | o | Inform the shim | int | | | | | layer of a | | | | | | timeout value | | | | | | for detecting | | | | | | failure. | | - | SHIM_PATHEXPLORE | o | o | Specify | *3 | + | SHIM_PATHEXPLORE | o | o | Specify | *4 | | | | | behavior of | | | | | | path | | | | | | exploration and | | | | | | failure | | | | | | detection. | | | SHIM_CONTEXT_DEFERRED_SETUP | o | o | Specify if the | int | | | | | context setup | | | | | | can be deferred | | | | | | or not. | | +-----------------------------+-----+-----+-----------------+-------+ Table 1: Socket options for multihoming shim *1: Pointer to a shim_locator which is defined in Section 7. - *2: Pointer to an array of shim_locator. + *2: Pointer to shim_locator data structure. - *3: Pointer to a shim_pathexplore which is defined in Section 7. + *3: Pointer to an array of shim_locator. + + *4: Pointer to a shim_pathexplore which is defined in Section 7. Figure 2 illustrates how the shim specific socket options fit into the system model of socket API. In the figure, it can be seen that the shim layer and the additional protocol components (IPv4 and IPv6) below the shim layer are new to the system model. As previously mentioned, all the shim specific socket options are defined at SOL_SHIM level. This design choice brings the following advantages: 1. It is assured that the existing socket API continue to work at the layer above the shim layer. That is, those legacy API deal @@ -770,21 +788,99 @@ See Section 6 for the procedure to access locator information stored in the ancillary data objects. An error ENOENT will be returned when there is no context associated with the socket. The usage of the option is same as that of SHIM_LOC_LOCAL_RECV option. -5.9. SHIM_LOCLIST_LOCAL +5.9. SHIM_LOC_LOCAL_SEND + + The SHIM_LOC_LOCAL_SEND option can be used to request the shim layer + to use specific locator for the source locator of IP packets to be + sent from the socket. Hence this option is effective only when there + is a shim context associated with the socket. + + Data type of option value is pointer to shim_locator data structure. + + The local locator can be specified by setsockopt() providing a valid + locator which is stored in a shim_locator data structure. When a + zero-filled locator is specified, pre-existing setting of local + locator is deactivated. + + The local locator specified can be obtained by getsockopt(). The + locator can be obtained from the option value. + + An error ENOENT will be returned when there is no context associated + with the socket. + + An error EINVALIDLOCATOR when invalid locator is specified. + + For example, a preferred local locator can be specified as follows. + + struct shim_locator locator; + struct in6_addr ia6; + + /* an IPv6 address preferred for the source locator is copied + to the parameter ia6 */ + + memset(&locator, 0, sizeof(locator)); + + /* fill shim_locator data structure */ + locator.lc_family = AF_INET6; + locator.lc_ifidx = 1; + locator.lc_flags = 0; + locator.lc_preference = 0; + memcpy(&locator.lc_addr, &ia6, sizeof(ia6)); + + setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, + sizeof(locator)); + + For example, a preferred local locator can be read as follows. + + struct shim_locator locator; + + memset(&locator, 0, sizeof(locator)); + + getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, + sizeof(locator)); + + /* check locator */ + +5.10. SHIM_LOC_PEER_SEND + + The SHIM_LOC_PEER_SEND option can be used to request the shim layer + to use specific locator for the destination locator of IP packets to + be sent from the socket. Hence this option is effective only when + there is a shim context associated with the socket. + + Data type of option value is pointer to shim_locator data structure. + + The remote locator can be specified by setsockopt() providing a valid + locator which is stored in a shim_locator data structure. When a + zero-filled locator is specified, pre-existing setting of remote + locator is deactivated. + + The remote locator specified can be obtained by getsockopt(). The + locator can be obtained from the option value. + + An error ENOENT will be returned when there is no context associated + with the socket. + + An error EINVALIDLOCATOR when invalid locator is specified. + + The usage of the option is as the same as that of SHIM_LOC_LOCAL_SEND + option. + +5.11. SHIM_LOCLIST_LOCAL The SHIM_LOCLIST_LOCAL option can be used to read or set the locator list associated with the local EID of the shim context associated with the socket. Hence this option is effective only when there is a shim context associated with the socket. Data type of option value is pointer to the buffer where a locator list is stored. See Section 7 for the data structure for storing the locator information. By default, the option value is set as NULL, meaning that the option is disabled. @@ -796,25 +892,71 @@ The locator list can be set by setsockopt(). The buffer pointed by optval argument should contain an array of locator list. An error ENOENT will be returned when there is no context associated with the socket. An error EINVALIDLOCATOR will be returned when the validation of the specified locator failed. - Example is TBD. + For example, a list of locators to be associated with the local EID + can be specified as follows: -5.10. SHIM_LOCLIST_PEER + struct shim_locator locators[SHIM_MAX_LOCATORS]; + struct sockaddr_in *sin; + struct sockaddr_in6 *sin6; - The SHIM_LOCLIST_LOCAL option can be used to read or set the locator + memset(locators, 0, sizeof(locators)); + + ... + + /* obtain local IP addresses from local interfaces */ + + ... + + /* first locator (an IPv6 address) */ + locators[0].lc_family = AF_INET6; + locators[0].lc_ifidx = 0; + locators[0].lc_flags = 0; + locators[0].lc_preference = 1; + memcpy(&locators[0].lc_addr, &sa6->sin6_addr, + sizeof(sa6->sin6_addr)); + + ... + + /* second locator (an IPv4 address) */ + locators[1].lc_family = AF_INET; + locators[1].lc_ifidx = 0; + locators[1].lc_flags = 0; + locators[1].lc_preference = 0; + memcpy(&locators[1].lc_addr, &sa->sin_addr, sizeof(sa->sin_addr)); + + setsockopt(fd, SOL_SHIM, SHIM_LOCLIST_LOCAL, locators, + sizeof(locators)); + + For example, a list of locators that are associated with the local + EID can be obtained as follows: + + struct shim_locator locators[SHIM_MAX_LOCATORS]; + + memset(locators, 0, sizeof(locators)); + + getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, locators, + sizeof(locators)); + + /* parse locators */ + ... + +5.12. SHIM_LOCLIST_PEER + + The SHIM_LOCLIST_PEER option can be used to read or set the locator list associated with the peer EID of the shim context associated with the socket. Hence this option is effective only when there is a shim context associated with the socket. Data type of option value is pointer to the buffer where a locator list is stored. See Section 7 for the data structure for storing the locator information. By default, the option value is set as NULL, meaning that the option is disabled. The locator list can be read by getsockopt(). Note that the size of @@ -826,21 +968,21 @@ optval argument should contain an array of locator list. An error ENOENT will be returned when there is no context associated with the socket. An error EINVALIDLOCATOR will be returned when the validation of the specified locator failed. The usage of the option is same as that of SHIM_LOCLIST_LOCAL. -5.11. SHIM_APP_TIMEOUT +5.13. SHIM_APP_TIMEOUT The SHIM_APP_TIMEOUT option indicates timeout value for application to detect failure. Hence this option is effective only when there is a shim context associated with the socket. Data type of the option value is integer. The value indicates the period of timeout in seconds to send a REAP Keepalive message since the last outbound traffic. By default, the option value is set as 0, meaning that the option is disabled. When the option is disabled, the REAP mechanism follows its default value of Send Timeout value as @@ -866,21 +1008,21 @@ For example, the option value namely the period of timeout can be checked by the application as follows: int optval; int len; len = sizeof(optval); getsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, &len); -5.12. SHIM_DEFERRED_CONTEXT_SETUP +5.14. SHIM_DEFERRED_CONTEXT_SETUP The SHIM_DEFERRED_CONTEXT_SETUP option indicates how initiation of context setup is made in terms of timing (before or after) the initial communication flow. Deferred context means that the establishment of context does not put additional delay for an initial transaction. Data type for the option value is integer. The option value should binary (0 or 1). By default, the value is set as 1, meaning that the context setup is deferred. In order to disable the option, the @@ -906,21 +1047,21 @@ follows: int optval; int len; len = sizeof(optval); getsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, &optval, &len); -5.13. Error Handling +5.15. Error Handling If successful, getsockopt() and setsockopt() return 0; otherwise, the functions return -1 and set errno to indicate error. The followings are errno codes newly defined for some shim specific socket options indicating that the getsockopt() or setsockopt() finished incompletely: EINVALIDLOCATOR This indicates that at least one of the necessary validations @@ -932,62 +1073,61 @@ is verifications based on given crypto identifier mechanisms [RFC3972], [I-D.ietf-shim6-hba]. 6. Ancillary Data for Multihoming Shim In this section, definition and usage of the ancillary data which is specific to multihoming shim are provided. As defined in Posix standard, sendmsg() and recvmsg() take msghdr structure as its argument and they can additionally handle control - information along with data. Figure 18 shows the msghdr structure + information along with data. Figure 22 shows the msghdr structure which is defined in . msg_control member holds a pointer to the buffer where the shim specific ancillary data objects can be stored in addition to other ancillary data objects. struct msghdr { caddr_t msg_name; /* optional address */ u_int msg_namelen; /* size of address */ struct iovec *msg_iov; /* scatter/gather array */ u_int msg_iovlen; /* # elements in msg_iov */ caddr_t msg_control; /* ancillary data, see below */ u_int msg_controllen; /* ancillary data buffer len */ int msg_flags; /* flags on received message */ }; - Figure 18: msghdr structure + Figure 22: msghdr structure The buffer pointed from the msg_control member of the msghdr structure may contain a locator information which is a single locator and it should be possible to process them with the existing macros defined in Posix and [RFC3542]. Each cmsghdr{} should be followed by data which stores a single locator. In case of non-connected socket, msg_name member stores the socket address of the peer which should be considered as an identifier rather than a locator. The locator of the peer node should be retrieved by SHIM_LOC_PEER_RECV as specified below. Table 2 is a list of the shim specific ancillary data which can be used for recvmsg() or sendmsg(). In any case, SOL_SHIM must be set as cmsg_level. - +------------------------+-----------+-----------+-------------+ + +---------------------+-----------+-----------+-----------------+ | cmsg_type | sendmsg() | recvmsg() | cmsg_data[] | - +------------------------+-----------+-----------+-------------+ + +---------------------+-----------+-----------+-----------------+ | SHIM_LOC_LOCAL_RECV | | o | *1 | | SHIM_LOC_PEER_RECV | | o | *1 | | SHIM_LOC_LOCAL_SEND | o | | *1 | | SHIM_LOC_PEER_SEND | o | | *1 | - | SHIM_FEEDBACK_POSITIVE | o | | TBD | - | SHIM_FEEDBACK_NEGATIVE | o | | TBD | - +------------------------+-----------+-----------+-------------+ + | SHIM_FEEDBACK | o | | shim_feedback{} | + +---------------------+-----------+-----------+-----------------+ Table 2: Shim specific ancillary data *1: cmsg_data[] should include padding (if necessary) and a single sockaddr_in{}/sockaddr_in6{}. It should be noted that the above ancillary data can only be handled in UDP and raw sockets, not in TCP sockets because there is no one- to-one mapping of send/receive operations and the TCP segments being transmitted/received. @@ -1017,77 +1157,71 @@ sendmsg(). If the specified locator pair seems to be valid, the shim layer overrides the locator of the IP packet as requested. An error EINVALIDLOCATOR will be returned when validation of the specified locator failed. 6.3. Notification from Application to Multihoming Shim - Application may provide feedback to the shim layer in accordance with - its communication status. The notification can be made by specifying - shim specific ancillary data in sendmsg() call. Note that this - notification is dynamic rather than static. - -6.3.1. SHIM_FEEDBACK_POSITIVE - - The application can simply inform the shim layer that its - communication is going well. + Application may provide feedback to the shim layer about the + communication status. Such feedback is particularly useful for the + shim layer in the absence of REAP mechanism to monitor the + reachability status of currently used locator pair in a given shim + context. - Data type is TBD. + The notification can be made by sendmsg() specifying a new ancillary + data called SHIM_FEEDBACK. The ancillary data can be handled by + specifying SHIM_FEEDBACK option in cmsg_type. An error ENOENT will be returned when there is no context associated with the socket. -6.3.2. SHIM_FEEDBACK_NEGATIVE - - The application can inform the shim layer that its communication is - not going well. - - Data type is TBD. - - An error ENOENT will be returned when there is no context associated - with the socket. + See Section 7.3 for details of the data structure to be used. Note + that this specification does not specify the exact behavior of the + shim layer when a feedback information is given by an application. 7. Data Structures In this section, data structures specifically defined for the - multihoming shim layer are introduced. Those data structures are + multihoming shim layer are introduced. Those data structure are + either used as a parameter for setsockopt()/getsockopt() (as + mentioned in Section 5) or a parameter for ancillary data to be + processed by sendmsg()/recvmsg() (as mentioned in Section 6). 7.1. Placeholder for Locator Information As defined in Section 5, the SHIM_LOC_LOCAL_PREF, SHIM_LOC_PEER_PREF, SHIM_LOCLIST_LOCAL, and SHIM_LOCLIST_PEER socket options need to handle one or more locator information. Locator information includes not only the locator itself but also additional information about the locator which is useful for locator management. A new data structure is defined to serve as a placeholder for the locator information. - Figure 19 illustrates the data structure called shim_locator which + Figure 23 illustrates the data structure called shim_locator which stores a locator information. struct shim_locator { uint8_t lc_family; /* address family */ uint8_t lc_ifidx; /* interface index */ uint8_t lc_flags; /* flags */ uint8_t lc_preference; /* preference value */ - uint8_t lc_addr[16]; /* locator */ + uint8_t lc_addr[16]; /* address data */ }; - Figure 19: shim locator structure + Figure 23: shim locator structure lc_family Address family of the locator (e.g. AF_INET, AF_INET6). It is required that the parameter contains non-zero value indicating the exact address family of the locator. - lc_ifidx Interface index of the network interface to which the locator is assigned. This field should be valid only in read (getsockopt()) operation. lc_flags Each bit of the flags represents a specific characteristics of the locator. HBA is defined as 0x01. CGA is defined as 0x02. The other bits are TBD. lc_preference Indicates preference of the locator. The preference is @@ -1085,44 +1219,45 @@ Interface index of the network interface to which the locator is assigned. This field should be valid only in read (getsockopt()) operation. lc_flags Each bit of the flags represents a specific characteristics of the locator. HBA is defined as 0x01. CGA is defined as 0x02. The other bits are TBD. lc_preference Indicates preference of the locator. The preference is represented by integer. + lc_addr Contains the locator. For the cases where a locator whose size is smaller than 16 bytes, encoding rule should be provided for each locator of a given address family. For instance, in case of - AF_INET (IPv4), the last 4 bytes of lc_addr should contain the + AF_INET (IPv4), the first 4 bytes of lc_addr should contain the IPv4 address. 7.2. Path Exploration Parameter As defined in Section 5, SHIM_PATHEXPLORE allows application to set or read the parameters for path exploration and failure detection. A new data structure called shim_pathexplore is defined to store the - necessary parameters. Figure 20 illustrates the data structure. The + necessary parameters. Figure 24 illustrates the data structure. The data structure can be used by getsockopt() or setsockopt() as an argument. struct shim_pathexplore { uint8_t pe_probenum; /* # of initial probe */ uint8_t pe_keepaliveto; /* Keepalive Timeout */ uint16_t pe_initprobeto; /* Initial Probe Timeout */ uint32_t pe_reserved; /* reserved */ }; - Figure 20: path explore structure + Figure 24: path explore structure pe_probenum Indicates the number of initial probe messages to be sent. Default value of this parameter should follow what is specified in [I-D.ietf-shim6-failure-detection]. pe_keepaliveto Indicates timeout value for detecting a failure when the host does not receive any packets for a certain period of time while there is outbound traffic. When the timer expires, path exploration procedure will be carried out by sending a REAP Probe message. @@ -1132,20 +1266,55 @@ pe_initprobeto Indicates retransmission timer of REAP Probe message in milliseconds. Note that this timer is applied before exponential back-off is started. A REAP Probe message for the same locator pair may be retransmitted. Default value of this parameter should follow what is specified in [I-D.ietf-shim6-failure-detection]. pe_reserved A reserved field for future extension. By default, the field should be initialized with zero. +7.3. Feedback Information + + As mentioned in Section 6.3, applications can inform the shim layer + about the status of unicast reachability of the locator pair + currently in use. The feedback information can be handled by using + ancillary data called SHIM_FEEDBACK. A new data structure named + shim_feedback is illustrated in Figure 25). + + struct shim_feedback { + uint8_t fb_direction; /* direction of traffic */ + uint8_t fb_indicator; /* indicator (1-3) */ + uint16_t fb_reserved; /* reserved */ + }; + + Figure 25: feedback information structure + + direction + Indicates direction of reachability between a locator pair in + question. A value 0 indicates outbound and a value 1 indicates + inbound. + indicator + A value indicating the degree of satisfaction of a unidirectional + reachability for a given locator pair. + * 0: Default value. Whenever this value is specified the + feedback information must not be processed by the shim layer. + * 1: Unable to connect. There is no unidirectional reachability + between the locator pair in question. + * 2: Unsatisfactory. The application is not satisfied with the + unidirectional reachability between the locator pair in + question. + * 3: Satisfactory. There is satisfactory unidirectional + reachability between the locator pair in question. + reserved + Reserved field. Must be ignored by the receiver. + 8. Implications for Existing Socket API Extensions Some of the socket options defined in this document have some overlapping with existing socket API and care should be made for the usage not to confuse the features. The socket options for requesting specific locators to be used for a given transaction (SHIM_LOC_LOCAL_PREF and SHIM_LOC_PEER_PREF) are semantically similar to the existing socket API (IPV6_PKTINFO). The socket options for obtaining the locator information from the @@ -1295,20 +1464,33 @@ o Separate normative references from informative references. o Remove texts from discussion section that are not relevant to the contents of the document. o Add section describing change history (this section). 11.3. Changes from version 02 to version 03 The followings are changes from version 02 to version 03: o Add an Appendix section describing the issue of context forking. +11.4. Changes from version 03 to version 04 + + The followings are changes from version 03 to version 04: + o Updated reference. + o Correct typo and grammatical errors. + +11.5. Changes from version 04 to version 05 + + The followings are changes from version 04 to version 05: + o Added definition of SHIM_FEEDBACK ancillary data. + o Added an example of code using the SHIM_LOCLIST_LOCAL + o Added SHIM_LOC_LOCAL_SEND and SHIM_LOC_PEER_SEND socket options. + 12. IANA Considerations This document contains no IANA consideration. 13. Security Considerations This document does not specify any security mechanism for the shim layer. Fundamentally, the shim layer has a potential to impose security threats, as it changes the source and/or destination IP addresses of the IP packet being sent or received. Therefore, the @@ -1332,21 +1514,23 @@ separation. With regard to API that relate to IP address management, it is assured that existing socket API continue to work above the shim layer dealing with identifiers, while multihoming shim API deals with locators. 15. Acknowledgments Authors would like to thank Jari Arkko who participated in the discussion that lead to the first version of this document, and Tatuya Jinmei who thoroughly reviewed the early version of this draft - and provided detailed comments on socket API related issues. + and provided detailed comments on socket API related issues. Thomas + Henderson provided valuable comments especially from HIP + perspectives. 16. References 16.1. Normative References [I-D.ietf-shim6-failure-detection] Arkko, J. and I. Beijnum, "Failure Detection and Locator Pair Exploration Protocol for IPv6 Multihoming", draft-ietf-shim6-failure-detection-10 (work in progress), January 2008. @@ -1403,31 +1587,31 @@ flow since the system maintains an association between the forked context and the socket owned by the application that has requested the context forking. How this association is maintained is implementation specific issue. However, on the responder side, there is a question on how the outbound packet can be multiplexed by the shim layer. Since there are more than one SHIM6 contexts that match with the ULID pair of the packet flow. There is a need to differentiate packet flows not only by the ULID pairs but some other information and associate a given packet flow with specific context. - Figure 21 gives an example of a scenario where two communicating + Figure 26 gives an example of a scenario where two communicating peers fork a context. Initially, there has been a single transaction between the peers, by the application 1 (App1). Accordingly, another transaction is started, by application 2 (App2). Both of the transactions are made based the same ULID pair. The first context pair (Ctx1) is established for the transaction of App1. Given the requests from App2, the shim layer on Peer 1 decides to fork a context. Accordingly, a forked context (Ctx2) is established between the peers, which should be exclusively applied to the transaction of App2. Ideally, multiplexing and demultiplexing of packet flows that - relate to App1 and App2 should be done as illustrated in Figure 21. + relate to App1 and App2 should be done as illustrated in Figure 26. However, as mentioned earlier, on the responder side, there is a problem with multiplexing the outbound packet flows of App1 and App2. Peer 1 Peer 2 (initiator) (responder) +----+ +----+ +----+ +----+ |App1| |App2| |App1| |App2| +----+ +----+ +----+ +----+ |^ |^ ^| ^| @@ -1443,21 +1627,21 @@ |^ |^ ^| ^| || || || || || || || || \..............||........................../| || \.............||.........................../ || || || \|........................................./| \........................................../ - Figure 21: context forking + Figure 26: context forking To overcome the problem mentioned above, there are some solutions. One viable approach is to let the system implicitly maintain an association between the socket and the associated context by keeping the record of inbound packet processing. That is, the system stores the information about the context on which the inbound packet flow was demultiplexed. The information comprises the ULID pair and FII of the context and is stored in the socket instance. Later, the system can use the information to identify the associated context in