--- 1/draft-ietf-shim6-multihome-shim-api-16.txt 2011-04-03 12:16:25.000000000 +0200 +++ 2/draft-ietf-shim6-multihome-shim-api-17.txt 2011-04-03 12:16:25.000000000 +0200 @@ -1,22 +1,22 @@ SHIM6 Working Group M. Komu Internet-Draft HIIT Intended status: Informational M. Bagnulo -Expires: August 16, 2011 UC3M +Expires: October 5, 2011 UC3M K. Slavov S. Sugimoto, Ed. Ericsson - February 12, 2011 + April 3, 2011 Socket Application Program Interface (API) for Multihoming Shim - draft-ietf-shim6-multihome-shim-api-16 + draft-ietf-shim6-multihome-shim-api-17 Abstract This document specifies sockets API extensions for the multihoming shim layer. The API aims to enable interactions between applications and the multihoming shim layer for advanced locator management, and access to information about failure detection and path exploration. This document is based on an assumption that a multihomed host is equipped with a conceptual sub-layer (hereafter "shim") inside the IP @@ -31,21 +31,21 @@ Internet-Drafts are working documents of the Internet Engineering Task Force (IETF). Note that other groups may also distribute working documents as Internet-Drafts. The list of current Internet- Drafts is at http://datatracker.ietf.org/drafts/current/. Internet-Drafts are draft documents valid for a maximum of six months 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." - This Internet-Draft will expire on August 16, 2011. + This Internet-Draft will expire on October 5, 2011. Copyright Notice Copyright (c) 2011 IETF Trust and the persons identified as the document authors. All rights reserved. This document is subject to BCP 78 and the IETF Trust's Legal Provisions Relating to IETF Documents (http://trustee.ietf.org/license-info) in effect on the date of publication of this document. Please review these documents @@ -63,80 +63,81 @@ Without obtaining an adequate license from the person(s) controlling the copyright in such materials, this document may not be modified outside the IETF Standards Process, and derivative works of it may not be created outside the IETF Standards Process, except to format it for publication as an RFC or to translate it into languages other than English. Table of Contents 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 5 - 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 6 - 3. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 6 + 2. Requirements Language . . . . . . . . . . . . . . . . . . . . 5 + 3. Terminology and Background . . . . . . . . . . . . . . . . . . 5 4. System Overview . . . . . . . . . . . . . . . . . . . . . . . 8 5. Requirements . . . . . . . . . . . . . . . . . . . . . . . . . 9 6. Socket Options for Multihoming Shim Sub-layer . . . . . . . . 10 6.1. SHIM_ASSOCIATED . . . . . . . . . . . . . . . . . . . . . 14 6.2. SHIM_DONTSHIM . . . . . . . . . . . . . . . . . . . . . . 15 6.3. SHIM_HOT_STANDBY . . . . . . . . . . . . . . . . . . . . 16 6.4. SHIM_LOC_LOCAL_PREF . . . . . . . . . . . . . . . . . . . 17 6.5. SHIM_LOC_PEER_PREF . . . . . . . . . . . . . . . . . . . 18 6.6. SHIM_LOC_LOCAL_RECV . . . . . . . . . . . . . . . . . . . 19 6.7. SHIM_LOC_PEER_RECV . . . . . . . . . . . . . . . . . . . 20 6.8. SHIM_LOC_LOCAL_SEND . . . . . . . . . . . . . . . . . . . 20 6.9. SHIM_LOC_PEER_SEND . . . . . . . . . . . . . . . . . . . 22 - 6.10. SHIM_LOCLIST_LOCAL . . . . . . . . . . . . . . . . . . . 23 + 6.10. SHIM_LOCLIST_LOCAL . . . . . . . . . . . . . . . . . . . 22 6.11. SHIM_LOCLIST_PEER . . . . . . . . . . . . . . . . . . . . 25 6.12. SHIM_APP_TIMEOUT . . . . . . . . . . . . . . . . . . . . 25 6.13. SHIM_PATHEXPLORE . . . . . . . . . . . . . . . . . . . . 26 6.14. SHIM_DEFERRED_CONTEXT_SETUP . . . . . . . . . . . . . . . 27 6.15. Applicability . . . . . . . . . . . . . . . . . . . . . . 28 6.16. Error Handling . . . . . . . . . . . . . . . . . . . . . 28 - 7. Ancillary Data for Multihoming Shim Sub-layer . . . . . . . . 28 + 7. Ancillary Data for Multihoming Shim Sub-layer . . . . . . . . 29 7.1. Get Locator from Incoming Packet . . . . . . . . . . . . 30 7.2. Set Locator for Outgoing Packet . . . . . . . . . . . . . 30 7.3. Notification from Application to Multihoming Shim Sub-layer . . . . . . . . . . . . . . . . . . . . . . . . 30 7.4. Applicability . . . . . . . . . . . . . . . . . . . . . . 31 8. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 31 - 8.1. Placeholder for Locator Information . . . . . . . . . . . 31 + 8.1. Data Structure for Locator Information . . . . . . . . . 31 8.1.1. Handling Locator behind NAT . . . . . . . . . . . . . 33 8.2. Path Exploration Parameter . . . . . . . . . . . . . . . 33 8.3. Feedback Information . . . . . . . . . . . . . . . . . . 34 9. System Requirements . . . . . . . . . . . . . . . . . . . . . 35 10. Relation to Existing Sockets API Extensions . . . . . . . . . 35 11. Operational Considerations . . . . . . . . . . . . . . . . . . 36 11.1. Conflict Resolution . . . . . . . . . . . . . . . . . . . 36 11.2. Incompatibility between IPv4 and IPv6 . . . . . . . . . . 37 12. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 37 13. Protocol Constants and Variables . . . . . . . . . . . . . . . 37 14. Security Considerations . . . . . . . . . . . . . . . . . . . 37 - 14.1. Treatment of Unknown Locator . . . . . . . . . . . . . . 38 + 14.1. Treatment of Unknown Locator . . . . . . . . . . . . . . 37 14.1.1. Treatment of Unknown Source Locator . . . . . . . . . 38 14.1.2. Treatment of Unknown Destination Locator . . . . . . . 38 15. Changes . . . . . . . . . . . . . . . . . . . . . . . . . . . 38 15.1. Changes from version 00 to version 01 . . . . . . . . . . 38 15.2. Changes from version 01 to version 02 . . . . . . . . . . 39 15.3. Changes from version 02 to version 03 . . . . . . . . . . 39 15.4. Changes from version 03 to version 04 . . . . . . . . . . 39 15.5. Changes from version 04 to version 05 . . . . . . . . . . 39 15.6. Changes from version 05 to version 06 . . . . . . . . . . 39 15.7. Changes from version 06 to version 07 . . . . . . . . . . 39 15.8. Changes from version 07 to version 08 . . . . . . . . . . 39 15.9. Changes from version 08 to version 09 . . . . . . . . . . 39 15.10. Changes from version 09 to version 10 . . . . . . . . . . 40 15.11. Changes from version 10 to version 11 . . . . . . . . . . 40 15.12. Changes from version 11 to version 12 . . . . . . . . . . 40 15.13. Changes from version 12 to version 13 . . . . . . . . . . 40 15.14. Changes from version 13 to version 14 . . . . . . . . . . 40 15.15. Changes from version 14 to version 15 . . . . . . . . . . 40 - 15.16. Changes from version 15 to version 16 . . . . . . . . . . 41 + 15.16. Changes from version 15 to version 16 . . . . . . . . . . 40 + 15.17. Changes from version 16 to version 17 . . . . . . . . . . 41 16. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 41 17. References . . . . . . . . . . . . . . . . . . . . . . . . . . 41 17.1. Normative References . . . . . . . . . . . . . . . . . . 41 17.2. Informative References . . . . . . . . . . . . . . . . . 42 Appendix A. Context Forking . . . . . . . . . . . . . . . . . . . 43 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 44 1. Introduction This document defines socket API extensions by which upper layer @@ -153,49 +154,33 @@ in the cases where 1) the upper layer protocol is particularly sensitive to impacts, or 2) the upper layer protocol wants to benefit from better knowledge of what is going on underneath. There are various kinds of technologies that aim to solve the same issue, the multihoming issue. Note that there will be conflict when more than one shim sub-layer is active at the same time. The assumption made in this document is that there is only a single shim sub-layer (HIP or SHIM6) activated on the system. - In this document, syntax and semantics of the API are given in the - same way as in the Posix standard [POSIX]. The API specifies how to - use ancillary data (aka cmsg) to access the locator information with - recvmsg() and/or sendmsg() I/O calls. The API is described in C - language and data types are defined in the Posix format; intN_t means - a signed integer of exactly N bits (e.g. int16_t) and uintN_t means - an unsigned integer of exactly N bits (e.g. uint32_t). - - The distinction between "connected" sockets and "unconnected" sockets - is important when discussing the applicability of the socket API - defined in this document. A connected socket is bound to a given - peer, whereas an unconnected socket is not bound to any specific - peers. A TCP socket becomes a connected socket when the TCP - connection establishment is completed. UDP sockets are unconnected, - unless the application uses the connect() system call. - The target readers of this document are application programmers who develop application software which may benefit greatly from multihomed environments. In addition, this document aims to provide necessary information for developers of shim protocols to implement API for enabling advanced locator management. 2. Requirements Language The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD", "SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be interpreted as described in [RFC2119]. -3. Terminology +3. Terminology and Background This section provides terminology used in this document. Basically most of the terms used in this document are taken from the following documents: o SHIM6 Protocol Specification[RFC5533] o HIP Architecture[RFC4423] o Reachability Protocol (REAP)[RFC5534] In this document, the term "IP" refers to both IPv4 and IPv6, unless @@ -252,21 +238,24 @@ multihomed. The term 'shim' does not refer to a specific protocol but refers to the conceptual sub-layer inside the IP layer. o Identifier/locator adaptation - The adaptation performed at the shim sub-layer which may end up re-writing the source and/or destination addresses of an IP packet. In the outbound packet processing, the EID pair is converted to the associated locator pair. In the inbound packet processing, the locator pair is converted to the EID pair. o Context - The state information shared by a given pair of peers, which stores a binding between the EID and associated locators. - Contexts are maintained by the shim sub-layer. + Contexts are maintained by the shim sub-layer. Deferred context + setup is a scenario where a context is established after the + communication starts. Deferred context setup is possible if the + ULID is routable, such as the case of SHIM6. o Reachability detection - The procedure to check reachability between a given locator pair. o Path - The sequence of routers that an IP packet goes through to reach the destination. o Path exploration - The procedure to explore available paths for a given set of locator pairs. o Outage - The incident that prevents IP packets to flow from the source locator to the destination locator. When there is an outage, it means that there is no reachability between a given locator pair. The outage may be caused by various reasons, such @@ -276,29 +265,45 @@ "working" if the packet can safely travel from the source to the destination where the packet contains the first address from the pair as the source address and the second address from the pair as the destination address. If reachability is confirmed in both directions, the address pair is considered to be working bi- directionally. o Reachability protocol (REAP) - The protocol for detecting failure and exploring reachability in a multihomed environment. REAP is defined in [RFC5534]. + In this document, syntax and semantics of the API are given in the + same way as in the Posix standard [POSIX]. The API specifies how to + use ancillary data (aka cmsg) to access the locator information with + recvmsg() and/or sendmsg() I/O calls. The API is described in C + language and data types are defined in the Posix format; intN_t means + a signed integer of exactly N bits (e.g. int16_t) and uintN_t means + an unsigned integer of exactly N bits (e.g. uint32_t). + + The distinction between "connected" sockets and "unconnected" sockets + is important when discussing the applicability of the socket API + defined in this document. A connected socket is bound to a given + peer, whereas an unconnected socket is not bound to any specific + peers. A TCP socket becomes a connected socket when the TCP + connection establishment is completed. UDP sockets are unconnected, + unless the application uses the connect() system call. + 4. System Overview Figure 1 illustrates the system overview. The shim sub-layer and REAP component exist inside the IP layer. Applications use the sockets API defined in this document to interface with the shim sub- layer and the transport layer for locator management, failure detection, and path exploration. - It may also be possible that the shim sub-layer interacts with the + It is also be possible that the shim sub-layer interacts with the transport layer, however, such an interaction is outside the scope of this document. +------------------------+ | Application | +------------------------+ ^ ^ ~~~~~~~~~~~~~|~Socket Interface|~~~~~~~~~~~~~~ | v +-----------|------------------------------+ @@ -336,54 +341,54 @@ * It should be possible to set preferred source and/or destination locator within a given context. * It should be possible to get preferred source and/or destination locator within a given context. * It should be possible to set a list of source and/or destination locators within a given context: Ls(local) and Ls(remote). * It should be possible to get a list of source and/or destination locators within a given context: Ls(local) and Ls(remote). - o Notification from applications to the shim sub-layer about the - status of the communication. The notification occurs in an event- - based manner. Applications and/or upper layer protocols may - provide positive feedback or negative feedback to the shim sub- - layer. Note that these feedback are mentioned in [RFC5534]: + o Notification from applications and upper layer protocols to the + shim sub-layer about the status of the communication. The + notification occurs in an event-based manner. Applications and/or + upper layer protocols may provide positive feedback or negative + feedback to the shim sub-layer. Note that these feedback are + mentioned in [RFC5534]: * Applications and/or upper layer protocols (e.g., TCP) may provide positive feedback to the shim sub-layer informing that the communication is going well. * Applications and/or upper layer protocols (e.g., TCP) may provide negative feedback to the shim sub-layer informing that the communication status is not satisfactory. TCP may detect a problem when it does not receive any expected ACK message from the peer. The REAP module may be triggered by these negative feedback and invoke the path exploration procedure. o Feedback from applications to the shim sub-layer. Applications should be able to inform the shim sub-layer of the timeout values for detecting failures, sending keepalives, and starting the exploration procedure. In particular, applications should be able to suppress keepalives. - o Hot-standby. Applications may request the shim sub-layer for the + o Hot-standby. Applications may request the shim sub-layer for a hot-standby capability. This means that, alternative paths are known to be working in advance of a failure detection. In such a - case, it is possible for the host to immediately replace the - current locator pair with an alternative locator pair. - + case, it is possible for the shim sub-layer to immediately replace + the current locator pair with an alternative locator pair. o Eagerness for locator exploration. An application should be able to inform the shim sub-layer of how aggressively it wants the REAP mechanism to perform a path exploration (e.g., by specifying the number of concurrent attempts of discovery of working locator pairs) when an outage occurs on the path between the locator pair in use. o Providing locator information to applications. An application should be able to obtain information about the locator pair which - was actually used to send or receive the packet. + was actually used to send or receive packets. * For inbound traffic, the application may be interested in the locator pair which was actually used to receive the packet. * For outbound traffic, the application may be interested in the locator pair which was actually used to transmit the packet. In this way, applications may have additional control on the locator management. For example, an application becomes able to verify if its preference for locator is actually applied to the flow or not. o Applications should be able to know if the shim-sublayer supports deferred context setup or not. @@ -393,37 +398,36 @@ an IPv4 locator and an IPv6 locator. 6. Socket Options for Multihoming Shim Sub-layer In this section, socket options that are specific to the shim sub- layer are defined. Table 1 shows a list of the socket options that are specific to the shim sub-layer. All of these socket options are defined at the level SOL_SHIM. When an application uses one of the socket options by - getsockopt() or setsockopt(), the second argument must be set as + getsockopt() or setsockopt(), the second argument MUST be set as SOL_SHIM. The first column of Table 1 gives the name of the option. The second - and third columns indicate whether the option can be handled by the - getsockopt() system call and/or by the setsockopt() system call. The - fourth column provides a brief description of the socket option. The - fifth column shows the type of data structure specified along with - the socket option. By default, the data structure type is an - integer. + column indicates whether the value for the socket option can be ready + by getsockopt() and the third column indicates whether the value for + the socket option can be written by setsockopt(). The fourth column + provides a brief description of the socket option. The fifth column + shows the type of data structure specified along with the socket + option. By default, the data structure type is an integer. +-----------------------------+-----+-----+-----------------+-------+ | optname | get | set | description | dtype | +-----------------------------+-----+-----+-----------------+-------+ | SHIM_ASSOCIATED | o | | Get the | int | - | | | | parameter (0 or | | - | | | | 1) which | | + | | | | parameter which | | | | | | indicates | | | | | | whether the | | | | | | socket is | | | | | | associated (1) | | | | | | with any shim | | | | | | context or not | | | | | | (0). | | | SHIM_DONTSHIM | o | o | Get or set the | int | | | | | parameter which | | | | | | indicates | | @@ -433,34 +437,44 @@ | | | | support by the | | | | | | shim sub-layer | | | | | | or not. | | | SHIM_HOT_STANDBY | o | o | Get or set the | int | | | | | parameter to | | | | | | request the | | | | | | shim sub-layer | | | | | | to prepare a | | | | | | hot-standby | | | | | | connection. | | - | SHIM_LOC_LOCAL_PREF | o | o | Get or set the | Note | - | | | | preferred | 1 | - | | | | locator on the | | - | | | | local side for | | - | | | | the context | | - | | | | associated with | | - | | | | the socket. | | - | SHIM_LOC_PEER_PREF | o | o | Get or set the | Note | - | | | | preferred | 1 | - | | | | locator on the | | - | | | | remote side for | | - | | | | the context | | - | | | | associated with | | - | | | | the socket. | | + | SHIM_LOC_LOCAL_PREF | o | o | Set the | Note | + | | | | preference | 1 | + | | | | value for a | | + | | | | source locator | | + | | | | for outbound | | + | | | | traffic. Get | | + | | | | the preferred | | + | | | | locator for the | | + | | | | source locator | | + | | | | for outbound | | + | | | | traffic. | | + | SHIM_LOC_PEER_PREF | o | o | Set the | Note | + | | | | preference | 1 | + | | | | value for a | | + | | | | destination | | + | | | | locator for | | + | | | | outbound | | + | | | | traffic. Get | | + | | | | the preferred | | + | | | | locator for the | | + | | | | destination | | + | | | | locator for | | + | | | | outbound | | + | | | | traffic. | | | SHIM_LOC_LOCAL_RECV | o | o | Request the | int | | | | | shim sub-layer | | | | | | to store the | | | | | | destination | | | | | | locator of the | | | | | | received IP | | | | | | packet in an | | | | | | ancillary data | | | | | | object. | | | SHIM_LOC_PEER_RECV | o | o | Request the | int | @@ -565,35 +579,35 @@ 6.1. SHIM_ASSOCIATED The SHIM_ASSOCIATED option is used to check whether the socket is associated with any shim context or not. This option is meaningful when the locator information of the received IP packet does not tell whether the identifier/locator adaptation is performed or not. Note that the EID pair and the locator pair may be identical in some cases. - This option can be specified by getsockopt(). Thus, the option is - read-only and the result (0/1/2) is set in the option value (the - fourth argument of getsockopt()). + Note that the socket option is read-only and the option value can be + read by getsockopt(). The result (0/1/2) is set in the option value + (the fourth argument of getsockopt()). When the application specifies the socket option to an unconnected socket, an error code EOPNOTSUPP is returned to the application. The data type of the option value is an integer. The option value indicates the presence of shim context. A return value 1 means that the socket is associated with a shim context at the shim sub-layer. A return value 0 indicates that there is no shim context associated with the socket. A return value 2 means that it is not known whether - the socket is associated with a shim context or not, and this must be + the socket is associated with a shim context or not, and this MUST be returned only when the socket is unconnected. In other words, the - returned value must be 0 or 1 when the socket is connected. + returned value MUST be 0 or 1 when the socket is connected. For example, the option can be used by the application as follows: int optval; int optlen = sizeof(optval); getsockopt(fd, SOL_SHIM, SHIM_ASSOCIATED, &optval, &optlen); 6.2. SHIM_DONTSHIM @@ -670,135 +684,125 @@ socket option as follows: int optval; int len; len = sizeof(optval); getsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, &len); 6.4. SHIM_LOC_LOCAL_PREF - The SHIM_LOC_LOCAL_PREF option is used to get or set preference for a - source locator for outbound traffic within a given context. This - option is effective only when there is a shim context associated with - the socket. + The SHIM_LOC_LOCAL_PREF option is used to set the preference value + for a source locator for outbound traffic, or to get the preference + value of the source locator for outbound traffic that has the highest + preference value. + + This option is effective only when there is a shim context associated + with the socket. + + By default, the option value is set to NULL, meaning that the option + is disabled. The preference of a locator is defined by a combination of priority and weight as per DNS SRV[RFC2782]. Note that the SHIM6 base protocol defines preference of locator in the same way. The data type of the option value is a pointer to a locator information data structure which is defined in Section 8. - By default, the option value is set to NULL, meaning that the option - is disabled. - - The preferred locator can be set by setsockopt(). The shim sub-layer - shall verify requested locator before it updates the preferred - locator. - - An application can get the preferred locator by getsockopt(). - - An application needs to get or set preference for each address, one - by one. - - When the application specifies the socket option to an unconnected + When an application specifies the socket option to an unconnected socket, an error code EOPNOTSUPP is returned to the application. When there is no shim context associated with the socket, an error code ENOENT is returned to the application. An error EINVALIDLOCATOR is returned when the validation of the specified locator fails. - For example, an application can set the preferred locator by using - the socket option as follows. Note that some members of the - shim_locator (lc_ifidx and lc_flags) are ignored in the set - operation. + An application can set the preference value for a source locator for + outbound traffic by setsockopt() with the socket option. Note that + lc_ifidx and lc_flags have no effect in a set operation. Below is an + example of set operation. struct shim_locator lc; struct in6_addr ip6; /* ...set the locator (ip6)... */ memset(&lc, 0, sizeof(shim_locator)); lc.lc_family = AF_INET6; /* IPv6 */ lc.lc_ifidx = 0; lc.lc_flags = 0; lc.lc_prio = 1; lc.lc_weight = 10; memcpy(&lc.lc_addr, &ip6, sizeof(in6_addr)); setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, sizeof(optval)); - For example, an application can get the preferred locator by using - the socket option as follows. + An application can get the source locator for outbound traffic that + has the highest preference value by using the socket option. Below + is an example of get operation. struct shim_locator lc; int len; len = sizeof(lc); getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, &len); 6.5. SHIM_LOC_PEER_PREF - The SHIM_LOC_PEER_PREF option is used to get or set preference of a - destination locator for outbound traffic within a given context. + The SHIM_LOC_PEER_PREF option is used to set the preference value for + a destination locator for outbound traffic, or to get the preference + value of the destination locator for outbound traffic that has the + highest preference value. + This option is effective only when there is a shim context associated with the socket. + By default, the option value is set to NULL, meaning that the option + is disabled. + As defined earlier, the preference of a locator is defined by a combination of priority and weight as per DNS SRV[RFC2782]. When there are more than one candidate destination locators, the shim sub- layer makes selection based on the priority and weight specified for each locator. The data type of the option value is a pointer to the locator information data structure which is defined in Section 8. - By default, the option value is set to NULL, meaning that the option - is disabled. - - The preferred locator can be set by setsockopt(). The shim sub-layer - shall verify requested locator before it updating the preferred - locator. - - An application can get the preferred locator by getsockopt(). - When the application specifies the socket option to an unconnected socket, an error code EOPNOTSUPP is returned to the application. When there is no shim context associated with the socket, an error code ENOENT is returned to the application. An error EINVALIDLOCATOR is returned when the validation of the requested locator fails. An error EUNREACHABLELOCATOR is returned when the requested locator is determined to be not reachable according to a reachability check. - The usage of the option is same as that of SHIM_LOC_LOCAL_PREF. Note - that some members of the shim_locator (lc_ifidx and lc_flags) are - ignored in the set operation. + The usage of the option is same as that of SHIM_LOC_LOCAL_PREF. 6.6. SHIM_LOC_LOCAL_RECV The SHIM_LOC_LOCAL_RECV option can be used to request the shim sub- layer to store the destination locator of the received IP packet in an ancillary data object which can be accessed by recvmsg(). This option is effective only when there is a shim context associated with the socket. - The data type of the option value is integer. The option value - should be binary (0 or 1). By default, the option value is set to 0, + The data type of the option value is integer. The option value MUST + be binary (0 or 1). By default, the option value is set to 0, meaning that the option is disabled. An application can set the option value by setsockopt(). An application can get the option value by getsockopt(). See Section 7 for the procedure to access locator information stored in the ancillary data objects. When the application specifies the socket option to an unconnected @@ -827,22 +831,22 @@ getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, &len); 6.7. SHIM_LOC_PEER_RECV The SHIM_LOC_PEER_RECV option is used to request the shim sub-layer to store the source locator of the received IP packet in an ancillary data object which can be accessed by recvmsg(). This option is effective only when there is a shim context associated with the socket. - The data type of the option value is integer. The option value - should be binary (0 or 1). By default, the option value is set to 0, + The data type of the option value is integer. The option value MUST + be binary (0 or 1). By default, the option value is set to 0, meaning that the option is disabled. The option value can be set by setsockopt(). The option value can be read by getsockopt(). See Section 7 for the procedure to access locator information stored in the ancillary data objects. When the application specifies the socket option to an unconnected @@ -886,21 +890,21 @@ 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_ifidx = 0; locator.lc_flags = 0; locator.lc_prio = 0; locator.lc_weight = 0; memcpy(&locator.lc_addr, &ia6, sizeof(ia6)); setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, sizeof(locator)); For example, an application can get the designated local locator by using the socket option as follows: @@ -959,26 +963,26 @@ associated with the local EID of the shim context associated with the socket. This option is effective only when there is a shim context associated with the socket. The data type of the option value is a pointer to the buffer in which a locator list is stored. See Section 8 for the data structure for storing the locator information. By default, the option value is set to NULL, meaning that the option is disabled. An application can get the locator list by getsockopt(). Note that - the size of the buffer pointed to by the optval argument should be + the size of the buffer pointed to by the optval argument MUST be large enough to store an array of locator information. The number of the locator information is not known beforehand. The local locator list can be set by setsockopt(). The buffer - pointed to by the optval argument should contain an array of locator + pointed to by the optval argument MUST contain an array of locator structures. When the application specifies the socket option to an unconnected socket, an error code EOPNOTSUPP is returned to the application. When there is no shim context associated with the socket, an error code ENOENT is returned to the application. An error EINVALIDLOCATOR is returned when the validation of any of the specified locators failed. @@ -1046,26 +1050,26 @@ associated with the peer EID of the shim context associated with the socket. This option is effective only when there is a shim context associated with the socket. The data type of the option value is a pointer to the buffer where a locator list is stored. See Section 8 for the data structure for storing the locator information. By default, the option value is set to NULL, meaning that the option is disabled. An application can get the locator list by getsockopt(). Note that - the size of the buffer pointed to by the optval argument should be + the size of the buffer pointed to by the optval argument MUST be large enough to store an array of locator information. The number of the locator information is not known beforehand. An application can set the locator list by setsockopt(). The buffer - pointed to by the optval argument should contain an array of locator + pointed to by the optval argument MUST contain an array of locator list. When the application specifies the socket option to an unconnected socket, an error code EOPNOTSUPP is returned to the application. When there is no shim context associated with the socket, an error code ENOENT is returned to the application. An error EINVALIDLOCATOR is returned when the validation of any of the specified locators failed. @@ -1120,21 +1124,21 @@ int optval; int len; len = sizeof(optval); getsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, &len); 6.13. SHIM_PATHEXPLORE - The application may use this socket option to get or set parameters + The application MAY use this socket option to get or set parameters concerning path exploration. Path exploration is a procedure to find an alternative locator pair to the current locator pair. As the REAP specification defines, a peer may send Probe messages to find an alternative locator pair. This option is effective only when there is a shim context associated with the socket. The data type of the option value is a pointer to the buffer where a set of information for path exploration is stored. The data @@ -1173,23 +1177,26 @@ 6.14. SHIM_DEFERRED_CONTEXT_SETUP The SHIM_DEFERRED_CONTEXT_SETUP option is used to check whether deferred context setup is possible or not. Deferred context setup means that the context is established in parallel with the data communication. Note that SHIM6 supports deferred context setup and HIP does not because EIDs in HIP (i.e., Host Identifiers) are non- routable. + Note that the socket option is read-only and the option value can be + ready by getsockopt(). + The data type for the option value is an integer. The option value - should be binary (0 or 1). The option value 1 means that the shim - sub-layer supports deferred context setup. + MUST be binary (0 or 1). The option value 1 means that the shim sub- + layer supports deferred context setup. When the application specifies the socket option to an unconnected socket, an error code EOPNOTSUPP is returned to the application. For example, an application can check whether deferred context setup is possible or not as follows: int optval; int len; @@ -1249,27 +1256,27 @@ 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 3: msghdr structure In the case of unconnected socket, msg_name stores the socket address - of the peer which should be considered to be an identifier rather - than a locator. SHIM_LOC_PEER_RECV should be used to get the locator - of the peer node. + of the peer. Note that the address is not a locator of the peer but + the identifier of the peer. SHIM_LOC_PEER_RECV can be used to get + the locator of the peer node. Table 2 is a list of the shim specific ancillary data which can be used for locator management by recvmsg() or sendmsg(). In any case, - the value of cmsg_level must be set as SOL_SHIM. + the value of cmsg_level MUST be set as SOL_SHIM. +---------------------+-----------+-----------+-----------------+ | cmsg_type | sendmsg() | recvmsg() | cmsg_data[] | +---------------------+-----------+-----------+-----------------+ | SHIM_LOC_LOCAL_RECV | | o | Note 1 | | SHIM_LOC_PEER_RECV | | o | Note 1 | | SHIM_LOC_LOCAL_SEND | o | | Note 1 | | SHIM_LOC_PEER_SEND | o | | Note 1 | | SHIM_FEEDBACK | o | | shim_feedback{} | +---------------------+-----------+-----------+-----------------+ @@ -1313,21 +1320,21 @@ recommended to use another destination locator until the reachability check for the requested locator is done. An error EUNREACHABLELOCATOR is returned when the requested locator is determined to be not reachable according to a reachability check. The application is recommended to use another destination locator when receiving the error. 7.3. Notification from Application to Multihoming Shim Sub-layer - An application may provide feedback to the shim sub-layer about the + An application MAY provide feedback to the shim sub-layer about the communication status. Such feedback are useful for the shim sub- layer to monitor the reachability status of the currently used locator pair in a given shim context. 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. When there is no shim context associated with the socket, an error code ENOENT is returned to the application. @@ -1339,35 +1346,35 @@ 7.4. Applicability All the ancillary data for the shim sub-layer is applicable to connected sockets. Care is needed when the SHIM_LOC_*_RECV socket option is used for stream-oriented sockets (e.g., TCP sockets) because there is no one- to-one mapping between a single send or receive operation and the data (e.g., a TCP segment) being received. In other words, there is - no gurantee that the locator(s) set in the SHIM_LOC_*_RECV ancillary + no guarantee that the locator(s) set in the SHIM_LOC_*_RECV ancillary data is identical to the locator(s) that appear in the IP packets received. The shim sub-layer SHOULD provide the latest locator information to the application in response to the SHIM_LOC_*_RECV socket option. 8. Data Structures This section gives data structures for the shim sub-layer. These data structures are either used as a parameter for setsockopt() or getsockopt() (as mentioned in Section 6) or as a parameter for ancillary data to be processed by sendmsg() or recvmsg() (as mentioned in Section 7). -8.1. Placeholder for Locator Information +8.1. Data Structure for Locator Information As defined in Section 6, the SHIM_LOC_*_PREF, SHIM_LOC_*_SEND, and SHIM_LOCLIST_* 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 4 illustrates the data structure called shim_locator which stores a locator information. @@ -1384,46 +1391,46 @@ }; Figure 4: 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_proto Internet Protocol number for the protocol which is used to handle - locator behind NAT. Typically, this value is set as UDP (17) when - the locator is a UDP encapsulation interface. + locator behind NAT. The value MUST be set to zero when there is + no NAT involved. When the locator is behind NAT, the value MUST + be set to IPPROTO_UDP. lc_port Port number which is used for handling locator behind NAT. lc_prio The priority of the locator. The range is 0-65535. The lowest priority value means the highest priority. lc_weight The weight value indicates a relative weight for locators with the same priority value. The range is 0-65535. A locator with higher weight value is prioritized over the other locators with lower weight values. lc_ifidx Interface index of the network interface to which the locator is - assigned. This field is only used in a read (getsockopt()) - operation. + assigned. This field is applicable only to local locators, and + has no effect in set operation. lc_addr - Contains the locator. In the case where a locator whose size is - smaller than 16 bytes, an encoding rule should be provided for - each locator of a given address family. For instance, in case of - AF_INET (IPv4), the locator should be in the format of an IPv4- - mapped IPv6 address as defined in [RFC4291]. + Contains the locator. In case of IPv4, the locator MUST be + formatted in the IPv4-mapped IPv6 address as defined in [RFC4291]. + The locator MUST be stored in network byte order. lc_flags Each bit of the flags represents a specific characteristics of the locator. Hash Based Address (HBA) is defined as 0x01. Cryptographically Generated Address (CGA) is defined as 0x02. + This field has no effect in set operation. 8.1.1. Handling Locator behind NAT Note that the locator information MAY contain a locator behind a Network Address Translator (NAT). Such a situation may arise when the host is behind the NAT and uses a local address as a source locator to communicate with the peer. Note that a NAT traversal mechanism for HIP is defined, which allows HIP host to tunnel control and data traffic over UDP[RFC5770]. Note also that the locator behind NAT is not necessarily an IPv4 address but it can be an IPv6 @@ -1435,24 +1442,24 @@ /* copy the private IPv4 address to the ia6 as an IPv4-mapped IPv6 address */ memset(&locator, 0, sizeof(locator)); /* fill shim_locator data structure */ locator.lc_family = AF_INET; locator.lc_proto = IPPROTO_UDP; locator.lc_port = 50500; + locator.lc_ifidx = 0; locator.lc_flags = 0; locator.lc_prio = 0; locator.lc_weight = 0; - locator.lc_ifidx = 3; memcpy(&locator.lc_addr, &ia6, sizeof(ia6)); setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator, sizeof(locator)); Figure 5: Handling locator behind NAT 8.2. Path Exploration Parameter @@ -1467,44 +1474,41 @@ uint16_t pe_probenum; /* # of initial probes */ uint16_t pe_keepaliveto; /* Keepalive Timeout */ uint16_t pe_keepaliveint /* Keepalive Interval */ uint16_t pe_initprobeto; /* Initial Probe Timeout */ uint32_t pe_reserved; /* reserved */ }; Figure 6: 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 - [RFC5534]. + Indicates the number of initial probe messages to be sent. The + value MUST be set as per [RFC5534]. pe_keepaliveto Indicates timeout value in seconds 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. Default value of this parameter should follow what is - specified in [RFC5534]. + message. The value MUST be set as per [RFC5534]. pe_keepaliveint Indicates interval of REAP keepalive messages in seconds to be sent by the host when there is no outbound traffic to the peer - host. The value shall be set according to the recommendation - given in [RFC5534]. + host. The value MUST be set as per [RFC5534]. 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 [RFC5534]. + pair may be retransmitted. The value MUST be set as per + [RFC5534]. pe_reserved - A reserved field for future extension. By default, the field - should be initialized to zero. + A reserved field for future extension. By default, the field MUST + be initialized to zero. 8.3. Feedback Information As mentioned in Section 7.3, applications can inform the shim sub- 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 7. struct shim_feedback { @@ -1516,31 +1520,31 @@ Figure 7: 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 direction. 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 sub- + feedback information MUST NOT be processed by the shim sub- 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. + Reserved field. MUST be ignored by the receiver. 9. System Requirements As addressed in Section 6, most of the socket options and ancillary data defined in this document are applicable to connected sockets. It is assumed that the kernel is capable of maintaining the association between a connected socket and a shim context. This requirement is considered to be reasonable because a pair of source and destination IP addresses is bound to a connected socket. @@ -1570,47 +1574,47 @@ IP address and port number assigned to the socket on the local side, and getpeername() gives IP address and port number of the peer side. 11. Operational Considerations This section gives operational considerations of the sockets API defined in this document. 11.1. Conflict Resolution - There may be a conflicting situation when different applications + There can be a conflicting situation when different applications specify difference preference for the same shim context. For - instance, application A and B may establish communication with the - same EID pair while both applications have different preference in - their choice of local locator. The notion of context forking in + instance, suppose if application A and B establish communication with + the same EID pair while both applications have different preference + in their choice of local locator. The notion of context forking in SHIM6 can resolve the conflicting situation. - Socket options defined in Section 6 may cause conflicting situation - when the target context is shared by multiple applications. In such - a case, the socket handler should inform the shim sub-layer that - context forking is required. In SHIM6, when a context is forked, an - unique identifier called Forked Instance Identifier (FII) is assigned - to the newly forked context. The forked context is then exclusively - associated with the socket through which non-default preference value - was specified. The forked context is maintained by the shim sub- - layer during the lifetime of associated socket instance. When the - socket is closed, the shim sub-layer SHOULD delete associated - context. + It is possible that socket options defined in Section 6 cause + conflicting situation when the target context is shared by multiple + applications. In such a case, the socket handler should inform the + shim sub-layer that context forking is required. In SHIM6, when a + context is forked, an unique identifier called Forked Instance + Identifier (FII) is assigned to the newly forked context. The forked + context is then exclusively associated with the socket through which + non-default preference value was specified. The forked context is + maintained by the shim sub-layer during the lifetime of associated + socket instance. When the socket is closed, the shim sub-layer + SHOULD delete associated context. When the application specifies SHIM_LOC_*_SEND specifying a different source or destination locator which does not have the highest priority and weight specified by the SHIM_LOC_*_PREF, the shim sub- layer SHOULD supersede the request made by SHIM_LOC_*_SEND over the preference specified by SHIM_LOC_*_PREF. When the peer provides preferences of the locators (e.g., a SHIM6 - peer may send a locator with a Locator Preferences Option) which + peer sends a locator with a Locator Preferences Option) which conflict with preference specified by the applications either by SHIM_LOC_PEER_SEND or SHIM_LOC_PEER_PREF, the shim sub-layer SHOULD supersede the preference made by the application over the preference specified by the peer. 11.2. Incompatibility between IPv4 and IPv6 The shim sub-layer performs identifier/locator adaptation. Therefore, in some cases, the whole IP header can be replaced with new IP header of a different address family (e.g. conversion from @@ -1641,62 +1645,63 @@ SHIM_MAX_LOCATORS The maximum number of the locators to be included in a locator list. The value is set to 32. 14. Security Considerations This section gives security considerations of the API defined in this document. 14.1. Treatment of Unknown Locator - When sending IP packets, application may request use of unknown - locator for the source and/or destination locators. Note that - treatment of unknown locator can be a subject of security - considerations because use of invalid source and/or destination - locator may cause redirection attack. + When sending IP packets, there is a possibility that an application + requests use of unknown locator for the source and/or destination + locators. Note that treatment of unknown locator can be a subject of + security considerations because use of invalid source and/or + destination locator may cause redirection attack. 14.1.1. Treatment of Unknown Source Locator The shim sub-layer checks if the requested locator is available on any of the local interface. If not, the shim sub-layer MUST reject the request and return an error message with the EINVALIDLOCATOR code to the application. If the locator is confirmed to be available, the shim sub-layer SHOULD initiate the procedure to update the locator list. - Use of the following socket options and ancillary data may require + Use of the following socket options and ancillary data requires treatment of unknown source locator: o SHIM_LOC_LOCAL_SEND o SHIM_LOC_LOCAL_PREF o SHIM_LOCLIST_LOCAL 14.1.2. Treatment of Unknown Destination Locator If the shim sub-layer turns out to be SHIM6, the SHIM6 layer MUST reject the request for using an unknown destination locator. If the shim sub-layer turns out to be HIP, the HIP layer MUST reject the request for using an unknown destination locator. There is, however, an exceptional case where the HIP layer SHOULD accept the request provided that the HIP association is in an UNASSOCIATED state. Details of locator handling in HIP is described in section 4.6 of [I-D.ietf-hip-native-api]. - Use of the following socket options and ancillary data may require + Use of the following socket options and ancillary data requires treatment of unknown destination locator: o SHIM_LOC_PEER_SEND o SHIM_LOC_PEER_PREF o SHIM_LOCLIST_PEER 15. Changes 15.1. Changes from version 00 to version 01 + o Define shim_locator{} data type which is a placeholder for locator. o Define shim_pathexplore{} data type in which a set of REAP parameters are stored. o Remove descriptions about "stickiness" of socket options. o Deprecate SHIM_IF_RECV and SHIM_IF_SEND socket options. o Give default value and how to disable given socket option. 15.2. Changes from version 01 to version 02 @@ -1785,27 +1790,39 @@ o Made clear distinction between validation of locator and verification of locator, and introduced two errors: EUNVERIFIEDLOCATOR and EUNREACHABLELOCATOR. o Addressed exceptional case for HIP in handling of unknown destination locator. 15.16. Changes from version 15 to version 16 Updated the documents reflecting the comments received during the IETF Last Call. + o Added Keepalive Interval (pe_keepaliveint) as a member of the shim_pathexplore{} data structure. o Addressed the unit of pe_keepaliveto. o Rephrased the last sentence in Appendix A to make it clear that the addressed issue is for further study. o Corrected a typo. +15.17. Changes from version 16 to version 17 + + Updated the documents reflecting the comments received during the + IESG review. + o Applied the RFC 2119 terminology more strictly. + o Made it clear whether each socket option can be set and/or get. + o Made some adjustments to the semantics of SHIM_LOC_LOCAL_PREF. + o Made the usage of lc_proto clear. + o Removed a misleading sentence from the paragraph describing + lc_ifidx. + 16. 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 sockets API related issues. Thomas Henderson provided valuable comments especially from HIP perspectives. Authors sincerely thank to the following people for their helpful