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

This html diff was produced by rfcdiff 1.34. The latest version is available from http://tools.ietf.org/tools/rfcdiff/