draft-ietf-shim6-multihome-shim-api-00.txt   draft-ietf-shim6-multihome-shim-api-01.txt 
skipping to change at page 1, line 13 skipping to change at page 1, line 13
SHIM6 Working Group M. Komu SHIM6 Working Group M. Komu
Internet-Draft HIIT Internet-Draft HIIT
Expires: August 5, 2006 M. Bagnulo Expires: August 5, 2006 M. Bagnulo
UC3M UC3M
K. Slavov K. Slavov
S. Sugimoto, Ed. S. Sugimoto, Ed.
Ericsson Ericsson
February 2006 February 2006
Socket Application Program Interface (API) for Multihoming Shim Socket Application Program Interface (API) for Multihoming Shim
draft-ietf-shim6-multihome-shim-api-00 draft-ietf-shim6-multihome-shim-api-01
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 2, line 21 skipping to change at page 3, line 16
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5
3. System Overview . . . . . . . . . . . . . . . . . . . . . . . 6 3. System Overview . . . . . . . . . . . . . . . . . . . . . . . 6
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 . . . . . . . . . . . . . . . . . . . 14 5.5. SHIM_LOC_LOCAL_PREF . . . . . . . . . . . . . . . . . . . 15
5.6. SHIM_LOC_PEER_PREF . . . . . . . . . . . . . . . . . . . . 15 5.6. SHIM_LOC_PEER_PREF . . . . . . . . . . . . . . . . . . . . 16
5.7. SHIM_LOC_LOCAL_RECV . . . . . . . . . . . . . . . . . . . 15 5.7. SHIM_LOC_LOCAL_RECV . . . . . . . . . . . . . . . . . . . 17
5.8. SHIM_LOC_PEER_RECV . . . . . . . . . . . . . . . . . . . . 16 5.8. SHIM_LOC_PEER_RECV . . . . . . . . . . . . . . . . . . . . 18
5.9. SHIM_LOCLIST_LOCAL . . . . . . . . . . . . . . . . . . . . 16 5.9. SHIM_LOCLIST_LOCAL . . . . . . . . . . . . . . . . . . . . 18
5.10. SHIM_LOCLIST_PEER . . . . . . . . . . . . . . . . . . . . 17 5.10. SHIM_LOCLIST_PEER . . . . . . . . . . . . . . . . . . . . 19
5.11. SHIM_APP_TIMEOUT . . . . . . . . . . . . . . . . . . . . . 17 5.11. SHIM_APP_TIMEOUT . . . . . . . . . . . . . . . . . . . . . 19
5.12. SHIM_DEFERRED_CONTEXT_SETUP . . . . . . . . . . . . . . . 18 5.12. SHIM_DEFERRED_CONTEXT_SETUP . . . . . . . . . . . . . . . 20
5.13. Error Handling . . . . . . . . . . . . . . . . . . . . . . 19 5.13. Error Handling . . . . . . . . . . . . . . . . . . . . . . 21
6. Ancillary Data for Multihoming Shim . . . . . . . . . . . . . 19 6. Ancillary Data for Multihoming Shim . . . . . . . . . . . . . 21
6.1. Get Locator Information from Incoming Packet . . . . . . . 21 6.1. Get Locator Information from Incoming Packet . . . . . . . 23
6.2. Specify Locator Information for Outgoing Packet . . . . . 21 6.2. Specify Locator Information for Outgoing Packet . . . . . 23
6.3. Notification from Application to Multihomign Shim . . . . 21 6.3. Notification from Application to Multihoming Shim . . . . 23
6.3.1. SHIM_FEEDBACK_POSITIVE . . . . . . . . . . . . . . . . 21 6.3.1. SHIM_FEEDBACK_POSITIVE . . . . . . . . . . . . . . . . 24
6.3.2. SHIM_FEEDBACK_NEGATIVE . . . . . . . . . . . . . . . . 22 6.3.2. SHIM_FEEDBACK_NEGATIVE . . . . . . . . . . . . . . . . 24
7. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 22 7. Data Structures . . . . . . . . . . . . . . . . . . . . . . . 24
7.1. Placeholder for Locator Information . . . . . . . . . . . 22 7.1. Placeholder for Locator Information . . . . . . . . . . . 24
7.1.1. Locator Information Stored in Control Message . . . . 22 7.2. Path Exploration Parameter . . . . . . . . . . . . . . . . 25
7.1.2. Locator Information Handled by getsockopt() and 8. Implications for Existing Socket API Extensions . . . . . . . 26
setsockopt() . . . . . . . . . . . . . . . . . . . . . 22 9. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 27
7.2. Parameters of Path Exploration . . . . . . . . . . . . . . 23 9.1. Issues with a Context Shared by Applications . . . . . . . 27
8. Implications for Existing Socket API Extensions . . . . . . . 23 9.2. Issues with Shim Unaware Application . . . . . . . . . . . 27
9. Discussion . . . . . . . . . . . . . . . . . . . . . . . . . . 23 9.2.1. Initial Contact with Multiple Locator Pairs . . . . . 27
9.1. Issues with a Context Shared by Applications . . . . . . . 23 9.2.2. Naming at Socket Layer . . . . . . . . . . . . . . . . 29
9.2. Issues with Shim Unaware Application . . . . . . . . . . . 24 9.3. Additional Requirements from Application . . . . . . . . . 29
9.2.1. Initial Contact with Multiple Locator Pairs . . . . . 24
9.2.2. Naming at Socket Layer . . . . . . . . . . . . . . . . 25
9.3. Additional Requirements from Application . . . . . . . . . 26
9.4. Issues of Header Conversion among Different Address 9.4. Issues of Header Conversion among Different Address
Family . . . . . . . . . . . . . . . . . . . . . . . . . . 26 Family . . . . . . . . . . . . . . . . . . . . . . . . . . 29
9.5. Handling of Unknown Locator Provided by Application . . . 26 9.5. Handling of Unknown Locator Provided by Application . . . 30
10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 27 10. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 30
11. Security Considerations . . . . . . . . . . . . . . . . . . . 27 11. Security Considerations . . . . . . . . . . . . . . . . . . . 30
12. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . 27 12. Conclusion . . . . . . . . . . . . . . . . . . . . . . . . . . 30
13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 27 13. Acknowledgments . . . . . . . . . . . . . . . . . . . . . . . 31
14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 28 14. References . . . . . . . . . . . . . . . . . . . . . . . . . . 31
14.1. Normative References . . . . . . . . . . . . . . . . . . . 28 14.1. Normative References . . . . . . . . . . . . . . . . . . . 31
14.2. Informative References . . . . . . . . . . . . . . . . . . 28 14.2. Informative References . . . . . . . . . . . . . . . . . . 32
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 30 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 33
Intellectual Property and Copyright Statements . . . . . . . . . . 31 Intellectual Property and Copyright Statements . . . . . . . . . . 34
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 7, line 47 skipping to change at page 7, line 47
characteristics of path. From the application's perspective: characteristics of path. From the application's perspective:
* It should be possible to obtain the lists of locators of a * It should be possible to obtain the lists of locators of a
given context: Ls(local) and Ls(remote). given context: Ls(local) and Ls(remote).
* It should be possible to obtain the preferred locators of a * It should be possible to obtain the preferred locators of a
given context: Lp(local) and Lp(remote). given context: Lp(local) and Lp(remote).
o Notification from the application to the shim layer about the o Notification from the application to the shim layer about the
status of the communication. Note that the notification is made status of the communication. Note that the notification is made
in an event based manner. There are mainly two aspects of the in an event based manner. There are mainly two aspects of the
feedback that application or upper layer protocol may provide for feedback that application or upper layer protocol may provide for
the shim layer, positive and negative feedbacks [NOTE: These the shim layer, positive and negative feedbacks [NOTE: These
feedbacks are addressed in section 4.3 and section 5.2 of REAP feedbacks are mentioned in [I-D.ietf-shim6-failure-detection]]:
specification]:
* Positive feedback could be given by the application or upper * Positive feedback could be given by the application or upper
layer protocol (e.g. TCP) to the shim layer informing that the layer protocol (e.g. TCP) to the shim layer informing that the
communication is going well. communication is going well.
* Negative feedback could be given by the application or upper * Negative feedback could be given by the application or upper
layer protocol (e.g. TCP) to the shim layer informing that the layer protocol (e.g. TCP) to the shim layer informing that the
communication status is not satisfactory. TCP could detect a communication status is not satisfactory. TCP could detect a
problem when it does not receive expected ACK from the peer. problem when it does not receive expected ACK from the peer.
ICMP error messages delivered to the upper layer protocol could ICMP error messages delivered to the upper layer protocol could
be a clue for application to detect potential problems. REAP be a clue for application to detect potential problems. REAP
module may be triggered by these negative feedbacks and invoke module may be triggered by these negative feedbacks and invoke
procedure of path exploration. procedure of path exploration.
o Feedback from application to shim layer. The application should o Feedback from application to shim layer. The application should
be able to inform the shim layer of the timeout values for be able to inform the shim layer of the timeout values for
skipping to change at page 10, line 42 skipping to change at page 10, line 42
| SHIM_LOCLIST_PEER | o | o | Get or set a | *2 | | SHIM_LOCLIST_PEER | o | o | Get or set a | *2 |
| | | | 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 how | *3 | | SHIM_PATHEXPLORE | o | o | Specify | *3 |
| | | | behavior of | |
| | | | path | | | | | | path | |
| | | | exploration | | | | | | exploration and | |
| | | | should be | | | | | | failure | |
| | | | performed in | | | | | | detection. | |
| | | | case of | |
| | | | failure. | |
| 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: Shim specific socket options for getsockopt() and Table 1: Shim specific socket options for getsockopt() and
setsockopt() setsockopt()
*1: Pointer to the buffer (TBD) in which a single locator information *1: Pointer to a shim_locator which is defined in Section 7.
is stored.
*2: Pointer to the buffer (TBD) in which a list of locator *2: Pointer to an array of shim_locator.
information is stored.
*3: Pointer to the buffer (TBD) in which a set of parameters of path *3: Pointer to a shim_pathexplore which is defined in Section 7.
exploration is stored.
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 12, line 35 skipping to change at page 12, line 35
| | | | | | | |
+------------------|----------|-----------------+ +------------------|----------|-----------------+
| | | |
IPv4 IPv6 IPv4 IPv6
Datagram Datagram Datagram Datagram
Figure 2: System model of socket API with shim layer Figure 2: System model of socket API with shim layer
5.1. SHIM_ASSOCIATED 5.1. SHIM_ASSOCIATED
This option can be specified by getsockopt() to check if the socket The SHIM_ASSOCIATED option can be used to check whether the socket is
is associated with a shim context or not. Thus, the option is read- associated with any shim context or not.
only and the result (0 or 1) is set in the option value (the fourth
argument of getsockopt()). A returned value 1 means that the socket
is associated with a certain shim context at the shim layer, while a
return value 0 indicates that there is no context associated with the
socket.
This option is particularly meaningful in a case where the locator This option is particularly meaningful in a case where the locator
information of the received IP packet does not tell whether the information of the received IP packet does not tell whether the
identifier/locator adaptation is performed or not. Note that the EID identifier/locator adaptation is performed or not. Note that the EID
pair and locator pair may be identical in some case. pair and locator pair may be identical in some case.
This option can be specified by getsockopt(). Thus, the option is
read-only and the result (0 or 1) is set in the option value (the
fourth argument of getsockopt()).
Data type of the option value is integer. The option value indicates
presence of shim context. A returned value 1 means that the socket
is associated with a certain shim context at the shim layer, while a
return value 0 indicates that there is no context associated with the
socket.
For example, the option can be used by the application as follows: For example, the option can be used by the application as follows:
int optval; int optval;
int optlen = sizeof(optval); int optlen = sizeof(optval);
getsockopt(fd, SOL_SHIM, SHIM_ASSOCIATED, &optval, &optlen); getsockopt(fd, SOL_SHIM, SHIM_ASSOCIATED, &optval, &optlen);
5.2. SHIM_DONTSHIM 5.2. SHIM_DONTSHIM
This option indicates whether the shim layer applies the multihoming The SHIM_DONTSHIM option can be used to request the shim layer to not
support for the communication established over the socket or not. apply the multihoming support for the communication established over
The option value can be overwritten by setsockopt() and can be the socket.
checked by getsockopt(). The optval should be binary (0 or 1). By
default, the value is set to 0, meaning that the shim layer applies Data type of the option value is integer. The option value indicates
identifier/locator adaptation for the communication. In order to whether the multihoming shim support is deprecated or not. The
disable the socket option, the application should call setsockopt() option value is binary (0 or 1). By default, the value is set to 0,
with optval set as 0. meaning that the shim layer applies identifier/locator adaptation for
the communication. In order to disable the socket option, the
application should call setsockopt() with optval set as 0.
For example, the option can be disabled by the application as For example, the option can be disabled by the application as
follows: follows.
int optval; int optval;
optval = 0; optval = 0;
setsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, sizeof(optval)); setsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, sizeof(optval));
For example, the option value can be checked by the application as For example, the option value can be checked by the application as
follows: follows.
int optval; int optval;
int len; int len;
len = sizeof(optval); len = sizeof(optval);
getsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, &len); getsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, &len);
5.3. SHIM_HOT_STANDBY 5.3. SHIM_HOT_STANDBY
The option indicates whether the shim layer uses hot-standby The SHIM_HOT_STANDBY option can be used to check if the shim layer
connection or not for the communication established over the socket. uses hot-standby connection or not for the communication established
Hence this option is effective only when there is a shim context over the socket. Hot-standby connection is another working locator
associated with the socket. another working locator pair than the pair than the current locator pair. Hence this option is effective
current locator pair. The option value can be overwritten by only when there is a shim context associated with the socket.
setsockopt() and can be checked by getsockopt(). By default, the
value is set to 0, meaning that hot-standby connection is disabled. Data type of the option value is integer.
The option value can be set by setsockopt().
The option value can be read by getsockopt().
By default, the value is set to 0, meaning that hot-standby
connection is disabled.
For example, the option can be activated by the application as For example, the option can be activated by the application as
follows: follows.
int optval; int optval;
optval = 1; optval = 1;
setsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, setsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval,
sizeof(optval)); sizeof(optval));
For example, the option value can be checked by the application as For example, the option value can be checked by the application as
follows: follows.
int optval; int optval;
int len; int len;
len = sizeof(optval); len = sizeof(optval);
getsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, &len); getsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, &len);
5.4. SHIM_PATHEXPLORE 5.4. SHIM_PATHEXPLORE
The option indicates how aggressive the application wants path This option can be used to specify behavior of path exploration to be
exploration to be performed in case of failure. Hence this option is carried out. Path exploration is a procedure to find an alternative
effective only when there is a shim context associated with the locator pair when the host finds any problem with current locator
socket. The option value can be overwritten by setsockopt() and can pair. A message used for finding an alternative locator pair is
be checked by getsockopt(). The option value contains a pointer to called a Probe message and it is sent per locator pair. Default
the buffer where information of path exploration (the number of value is defined for Initial Probe Timeout (0.5 seconds) and Initial
attempts for path exploration, frequency of the path exploration, and Probe (4 times) in the REAP specification.
so on) is stored. By default, the option value is set as NULL,
meaning that the option is disabled. The option is effective only when there is a shim context associated
with the socket.
Data type of the option value is a pointer to the buffer where a set
of information for path exploration is stored. The data structure is
defined in Section 7.
By default, the option value is set as NULL, meaning that the option
is disabled.
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.
Example is TBD. For example, the parameters for the path exploration can be set as
follows.
struct shim6_pathexplore pe;
pe.pe_probenum = 4; /* times */
pe.pe_keepaliveto = 10; /* seconds */
pe.pe_initprobeto = 500; /* milliseconds */
pe.pe_reserved = 0;
setsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, sizeof(pe));
For example, the parameters for the path exploration can be read as
follows.
struct shim6_pathexplore pe;
int len;
len = sizeof(pe);
getsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, &len);
5.5. SHIM_LOC_LOCAL_PREF 5.5. SHIM_LOC_LOCAL_PREF
The option value contains the preferred locator on local side within The SHIM_LOC_LOCAL_PREF option can be used to read or set preferred
a context associated with the socket. Hence this option is effective locator on local side within a given context. Hence this option is
only when there is a shim context associated with the socket. The effective only when there is a shim context associated with the
option value holds a single locator information. The option value socket.
can be overwritten by setsockopt() and can be checked by
getsockopt(). When the option value is changed by the application by Data type of the option value is a pointer to the a specific data
setsockopt(), the shim layer shall accordingly update the preferred structure which stores the locator information. The data structure
locator within the context associated with the socket. By default, is defined in Section 7.
the option value is set as NULL, meaning that the option is disabled.
By default, the option value is set as NULL, meaning that the option
is disabled.
The preferred locator can be set by setsockopt(). Verification of
the locator shall be done by the shim layer before updating the
preferred locator.
The preferred locator can be read by getsockopt().
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 preferred locator can be set as follows. It should be
noted that some members of the shim_locator (lc_ifidx and lc_flags)
are ignored in the write operation.
struct shim_locator lc;
struct in6_addr ip6;
/* ...set the locator (ip6)... */
bzero(&lc, sizeof(shim_locator));
lc.lc_family = AF_INET6; /* IPv6 */
lc.lc_ifidx = 0;
lc.lc_flags = 0;
lc.lc_preference = 255;
memcpy(lc.lc_addr, &ip6, sizeof(in6_addr));
setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc,
sizeof(optval));
For example, the preferred locator of the context can be read by
application as follows.
struct shim_locator lc;
int len;
len = sizeof(lc);
getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, &len);
5.6. SHIM_LOC_PEER_PREF 5.6. SHIM_LOC_PEER_PREF
The option value contains the preferred locator on remote side within The SHIM_LOC_PEER_PREF option can be used to read or set preferred
a context associated with the socket. Hence this option is effective locator on peer side within a given context. Hence this option is
only when there is a shim context associated with the socket. The effective only when there is a shim context associated with the
option value holds a single locator information. The option value socket.
can be overwritten by setsockopt() and can be checked by
getsockopt(). When the option value is changed by the application by Data type of the option value is a pointer to the a specific data
setsockopt(), the shim layer shall accordingly update the preferred structure which stores the locator information. The data structure
locator within the context associated with the socket. By default, is defined in Section 7.
the option value is set as NULL, meaning that the option is disabled.
By default, the option value is set as NULL, meaning that the option
is disabled.
The preferred locator can be set by setsockopt(). Necessary
verification of the locator shall be done by the shim layer before
updating the preferred locator.
The preferred locator can be read by getsockopt().
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 preferred locator can be set as follows. It should be
noted that some members of the shim_locator (lc_ifidx and lc_flags)
are ignored in the write operation.
The usage of the option is same as that of SHIM_LOC_LOCAL_PREF.
5.7. SHIM_LOC_LOCAL_RECV 5.7. SHIM_LOC_LOCAL_RECV
With this option, the application can request the shim layer to store The SHIM_LOC_LOCAL_RECV option can be used to request the shim layer
the destination locator of the received IP packet in an ancillary to store the destination locator of the received IP packet in an
data object which can be accessed by recvmsg(). Hence this option is ancillary data object which can be accessed by recvmsg(). Hence this
effective only when there is a shim context associated with the option is effective only when there is a shim context associated with
socket. The option value should be binary (0 or 1). By default, the the socket.
option value is set to 0, meaning that the option is disabled. The
option value can be overwritten by setsockopt() and can be checked by Data type of the option value is integer. The option value should be
getsockopt(). See section Section 7 for the data structure for binary (0 or 1). By default, the option value is set to 0, meaning
storing the locator information. that the option is disabled.
The option value can be set by setsockopt().
The option value can be read by getsockopt().
See section Section 6 for the procedure to access locator information
stored in the ancillary data objects.
An error ENOENT will be returned when there is no context associated An error ENOENT will be returned when there is no context associated
with the socket. with the socket.
For example, the option can be activated by the application as For example, the option can be activated by the application as
follows: follows:
int optval; int optval;
optval = 1; optval = 1;
skipping to change at page 16, line 18 skipping to change at page 18, line 14
int optval; int optval;
int len; int len;
len = sizeof(optval); len = sizeof(optval);
getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, &len); getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, &len);
5.8. SHIM_LOC_PEER_RECV 5.8. SHIM_LOC_PEER_RECV
With this option, the application can request the shim layer to store The SHIM_LOC_PEER_RECV option can be used to request the shim layer
the source locator of the received IP packet in an ancillary data to store the source locator of the received IP packet in an ancillary
object which can be accessed by recvmsg(). Hence this option is data object which can be accessed by recvmsg(). Hence this option is
effective only when there is a shim context associated with the effective only when there is a shim context associated with the
socket. The option value should be binary (0 or 1). By default, the socket.
option value is set to 0, meaning that the option is disabled. The
option value can be overwritten by setsockopt() and can be checked by Data type of the option value is integer. The option value should be
getsockopt(). See section Section 7 for the data structure for binary (0 or 1). By default, the option value is set to 0, meaning
storing the locator information. that the option is disabled.
The option value can be set by setsockopt().
The option value can be read by getsockopt().
See section Section 6 for the procedure to access locator information
stored in the ancillary data objects.
An error ENOENT will be returned when there is no context associated An error ENOENT will be returned when there is no context associated
with the socket. with the socket.
The usage of the option is almost identical to that of The usage of the option is same as that of SHIM_LOC_LOCAL_RECV
SHIM_LOC_LOCAL_RECV option. option.
5.9. SHIM_LOCLIST_LOCAL 5.9. SHIM_LOCLIST_LOCAL
With this option, the application can request the shim layer for a The SHIM_LOCLIST_LOCAL option can be used to read or set the locator
list of locators which is currently associated with the local EID list associated with the local EID of the shim context associated
within a shim context. Hence this option is effective only when with the socket. Hence this option is effective only when there is a
there is a shim context associated with the socket. The option value shim context associated with the socket.
contains a pointer to the buffer where the locator list is stored.
By default, the option value is set as NULL, meaning that the option Data type of option value is pointer to the buffer where a locator
is disabled. By getsockopt(), the application can get the locator list is stored. See section Section 7 for the data structure for
list. By setsockopt(), the application can request the shim layer to storing the locator information. By default, the option value is set
update its locator list that is associated with a local EID. See as NULL, meaning that the option is disabled.
section Section 7 for the data structure for storing the locator
information. The locator list can be read by getsockopt(). Note that the size of
the buffer pointed by optval argument should be large enough to store
an array of locator information. The number of the locator
information is not known beforehand.
The locator list can be set by setsockopt(). The buffer pointed by
optval argument should contain an array of locator list.
An error ENOENT will be returned when there is no context associated 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. Example is TBD.
5.10. SHIM_LOCLIST_PEER 5.10. SHIM_LOCLIST_PEER
With this option, the application can request the shim layer for a The SHIM_LOCLIST_LOCAL option can be used to read or set the locator
list of locators which is currently associated with the remote EID list associated with the peer EID of the shim context associated with
within a shim context. Hence this option is effective only when the socket. Hence this option is effective only when there is a shim
there is a shim context associated with the socket. The option value context associated with the socket.
contains a pointer to the buffer where the locator list is stored.
By default, the option value is set as NULL, meaning that the option Data type of option value is pointer to the buffer where a locator
is disabled. By getsockopt(), the application can get the locator list is stored. See section Section 7 for the data structure for
list. By setsockopt(), the application can request the shim layer to storing the locator information. By default, the option value is set
update its locator list that is associated with a remote EID. See as NULL, meaning that the option is disabled.
section Section 7 for the data structure for storing the locator
information. The locator list can be read by getsockopt(). Note that the size of
the buffer pointed by optval argument should be large enough to store
an array of locator information. The number of the locator
information is not known beforehand.
The locator list can be set by setsockopt(). The buffer pointed by
optval argument should contain an array of locator list.
An error ENOENT will be returned when there is no context associated 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. The usage of the option is same as that of SHIM_LOCLIST_LOCAL.
5.11. SHIM_APP_TIMEOUT 5.11. SHIM_APP_TIMEOUT
The option indicates period of timeout for application to detect The SHIM_APP_TIMEOUT option indicates timeout value for application
failure. Hence this option is effective only when there is a shim to detect failure. Hence this option is effective only when there is
context associated with the socket. The option value contains the a shim context associated with the socket.
period of timeout in seconds. Accordingly, the shim layer shall
update the strategy for reachability test. In particular, this is Data type of the option value is integer. The value indicates the
efficient in a case where the informed timeout value is shorter than period of timeout in seconds to send a REAP Keepalive message since
the period of the keepalive timer. In such case, keepalives to be the last outbound traffic. By default, the option value is set as 0,
performed by REAP may be suppressed. By default, the option value is meaning that the option is disabled. When the option is disabled,
set to 0, meaning that the option is disabled. the REAP mechanism follows its default value of Send Timeout value as
specified in [I-D.ietf-shim6-failure-detection]
If the timeout value specified is longer than the Send Timeout
configured in the REAP component, the REAP Keepalive message should
be suppressed.
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.
For example, a specific timeout value can be configured by the For example, a specific timeout value can be configured by the
application as follows: application as follows:
int optval; int optval;
optval = 4; /* 4 seconds */ optval = 15; /* 15 seconds */
setsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, setsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval,
sizeof(optval)); sizeof(optval));
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.12. SHIM_DEFERRED_CONTEXT_SETUP
The option indicates how initiation of context setup is made in terms The SHIM_DEFERRED_CONTEXT_SETUP option indicates how initiation of
of timing (before or after) the initial communication flow. Deferred context setup is made in terms of timing (before or after) the
context means that the establishment of context does not put initial communication flow. Deferred context means that the
additional delay for an initial transaction. The option value should establishment of context does not put additional delay for an initial
bi binary (0 or 1). By default, the value is set to 1, meaning that transaction.
the context setup is deferred. In order to disable the option, the
application should call setsockopt() with option value set to 0. Data type for the option value is integer. The option value should
binary (0 or 1). By default, the value is set as 1, meaning that the
context setup is deferred. In order to disable the option, the
application should call setsockopt() with option value set as 0.
However, it should be noted that in some case, deferred context setup However, it should be noted that in some case, deferred context setup
is not possible; given EID is non-routable address and there is no is not possible; given EID is non-routable address and there is no
way to transmit any IP packet unless there is a context providing the way to transmit any IP packet unless there is a context providing the
locators. In such case, context establishment should be made prior locators. In such case, context should be established prior to the
to the communication. communication.
For example, the option can be disabled by the application as For example, the option can be disabled by the application as
follows: follows:
int optval; int optval;
optval = 0; optval = 0;
setsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP, setsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP,
&optval, sizeof(optval)); &optval, sizeof(optval));
skipping to change at page 19, line 35 skipping to change at page 21, line 49
case of SHIM6, there are two kinds of verifications required for case of SHIM6, there are two kinds of verifications required for
security reasons prior to sending an IP packet to the peer's new security reasons prior to sending an IP packet to the peer's new
locator; one is return routability (check if the peer is actually locator; one is return routability (check if the peer is actually
willing to receive data with the specified locator) and the other willing to receive data with the specified locator) and the other
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 multihiming 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 14 shows the msghdr structure information along with data. Figure 18 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 14: msghdr structure Figure 18: 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
skipping to change at page 21, line 36 skipping to change at page 23, line 43
Note that the effect is limited to the datagram transmitted by the Note that the effect is limited to the datagram transmitted by the
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 Multihomign 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 in accordance with
its communication status. The notification can be made by specifying its communication status. The notification can be made by specifying
shim specific ancillary data in sendmsg() call. Note that this shim specific ancillary data in sendmsg() call. Note that this
notification is dynamic rather than static. notification is dynamic rather than static.
6.3.1. SHIM_FEEDBACK_POSITIVE 6.3.1. SHIM_FEEDBACK_POSITIVE
The application can simply inform the shim layer that its The application can simply inform the shim layer that its
communication is going well. communication is going well.
Ancillary data object is TBD. Data type is TBD.
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 6.3.2. SHIM_FEEDBACK_NEGATIVE
The application can inform the shim layer that its communication is The application can inform the shim layer that its communication is
not going well. not going well.
Ancillary data object is TBD. Data type is TBD.
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.
7. Data Structures 7. Data Structures
In this section, data structures newly defined for socket options for In this section, data structures specifically defined for the
multihoming shim layer are introduced. multihoming shim layer are introduced. Those data structures are
7.1. Placeholder for Locator Information 7.1. Placeholder for Locator Information
Some of the socket options defined in this document handle locator As defined in Section 5, the SHIM_LOC_LOCAL_PREF, SHIM_LOC_PEER_PREF,
information. Locator information could be a single locator or an SHIM_LOCLIST_LOCAL, and SHIM_LOCLIST_PEER socket options need to
array of locators. An important requirement is that the locator handle one or more locator information. Locator information includes
information should be handled in a protocol independent manner. In not only the locator itself but also additional information about the
other words, an interface to the locator information should not be locator which is useful for locator management. A new data structure
dependent on any address family. is defined to serve as a placeholder for the locator information.
7.1.1. Locator Information Stored in Control Message Figure 19 illustrates the data structure called shim_locator which
stores a locator information.
When either SHIM_LOC_LOCAL_* or SHIM_LOC_PEER_* socket option is struct shim_locator {
specified, sendmsg() or recvmsg() should handle locator information uint8_t lc_family; /* address family */
as a control message. The locator information is stored in an uint8_t lc_ifidx; /* interface index */
ancillary data object which consists of a common header (cmsghdr{}), uint8_t lc_flags; /* flags */
the data, and the padding if necessary. In the case when the locator uint8_t lc_preference; /* preference value */
is IPv4, the cmsg_data[] should contain sockaddr_in{}. In the case uint8_t lc_addr[16]; /* locator */
when the locator is IPv6, the cmsg_data[] should contain };
sockaddr_in6{}.
7.1.2. Locator Information Handled by getsockopt() and setsockopt() Figure 19: shim locator structure
lc_family
Address family of the locator (e.g. AF_INET, AF_INET6). It is
required that the parameter contains non-zero value indicating the
exact address family of the locator.
lc_ifidx
Interface index of the network interface to which the locator is
assigned. This field should be valid only in read (getsockopt())
operation.
lc_flags
Each bit of the flags represents a specific characteristics of the
locator. HBA is defined as 0x01. CGA is defined as 0x02. The
other bits are TBD.
lc_preference
Indicates preference of the locator. The preference is
represented by integer.
lc_addr
Contains the locator. For the cases where a locator whose size is
smaller than 16 bytes, encoding rule should be provided for each
locator of a given address family. For instance, in case of
AF_INET (IPv4), the last 4 bytes of lc_addr should contain the
IPv4 address.
SHIM_LOC_LOCAL_PREF and SHIM_LOC_PEER_PREF socket options defined in 7.2. Path Exploration Parameter
Section Section 5 () require getsockopt() or setsockopt() to handle a
single locator information. The data structure for storing the
locator information is TBD.
SHIM_LOCLIST_LOCAL and SHIM_LOCLIST_PEER defined in Section Section 5 As defined in Section 5, SHIM_PATHEXPLORE allows application to set
() require getsockopt() or setsockopt() to handle a set of locator or read the parameters for path exploration and failure detection. A
information (aka locator list). The data structure for storing the new data structure called shim_pathexplore is defined to store the
locator information is TBD. necessary parameters. Figure 20 illustrates the data structure. The
data structure can be used by getsockopt() or setsockopt() as an
argument.
7.2. Parameters of Path Exploration struct shim_pathexplore {
uint8_t pe_probenum; /* # of initial probe */
uint8_t pe_keepaliveto; /* Keepalive Timeout */
uint16_t pe_initprobeto; /* Initial Probe Timeout */
uint32_t pe_reserved; /* reserved */
};
SHIM_PATHEXPLORE requires getsockopt() or setsockopt() to handle a Figure 20: path explore structure
set of parameters for the path exploration. The data structure is
TBD. pe_probenum
Indicates the number of initial probe messages to be sent.
Default value of this parameter should follow what is specified in
[I-D.ietf-shim6-failure-detection].
pe_keepaliveto
Indicates timeout value for detecting a failure when the host does
not receive any packets for a certain period of time while there
is outbound traffic. When the timer expires, path exploration
procedure will be carried out by sending a REAP Probe message.
Default value of this parameter should follow what is specified in
[I-D.ietf-shim6-failure-detection].
pe_initprobeto
Indicates retransmission timer of REAP Probe message in
milliseconds. Note that this timer is applied before exponential
back-off is started. A REAP Probe message for the same locator
pair may be retransmitted. Default value of this parameter should
follow what is specified in [I-D.ietf-shim6-failure-detection].
pe_reserved
A reserved field for future extension. By default, the field
should be initialized with zero.
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
skipping to change at page 28, line 22 skipping to change at page 31, line 30
in progress), May 2006. in progress), May 2006.
[I-D.ietf-hip-arch] [I-D.ietf-hip-arch]
Moskowitz, R. and P. Nikander, "Host Identity Protocol Moskowitz, R. and P. Nikander, "Host Identity Protocol
Architecture", draft-ietf-hip-arch-03 (work in progress), Architecture", draft-ietf-hip-arch-03 (work in progress),
August 2005. August 2005.
[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-03 (work in progress), draft-ietf-shim6-failure-detection-06 (work in progress),
December 2005. September 2006.
[I-D.ietf-shim6-proto] [I-D.ietf-shim6-proto]
Bagnulo, M. and E. Nordmark, "Level 3 multihoming shim Bagnulo, M. and E. Nordmark, "Level 3 multihoming shim
protocol", draft-ietf-shim6-proto-03 (work in progress), protocol", draft-ietf-shim6-proto-05 (work in progress),
December 2005. May 2006.
[POSIX] "IEEE Std. 1003.1-2001 Standard for Information Technology [POSIX] "IEEE Std. 1003.1-2001 Standard for Information Technology
-- Portable Operating System Interface (POSIX). Open group -- Portable Operating System Interface (POSIX). Open group
Technical Standard: Base Specifications, Issue 6, Technical Standard: Base Specifications, Issue 6,
http://www.opengroup.org/austin", December 2001. http://www.opengroup.org/austin", December 2001.
[RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei, [RFC3542] Stevens, W., Thomas, M., Nordmark, E., and T. Jinmei,
"Advanced Sockets Application Program Interface (API) for "Advanced Sockets Application Program Interface (API) for
IPv6", RFC 3542, May 2003. IPv6", RFC 3542, May 2003.
14.2. Informative References 14.2. Informative References
[I-D.ietf-shim6-app-refer] [I-D.ietf-shim6-app-refer]
Nordmark, E., "Shim6 Application Referral Issues", Nordmark, E., "Shim6 Application Referral Issues",
draft-ietf-shim6-app-refer-00 (work in progress), draft-ietf-shim6-app-refer-00 (work in progress),
July 2005. July 2005.
[I-D.ietf-shim6-hba] [I-D.ietf-shim6-hba]
Bagnulo, M., "Hash Based Addresses (HBA)", Bagnulo, M., "Hash Based Addresses (HBA)",
draft-ietf-shim6-hba-01 (work in progress), October 2005. draft-ietf-shim6-hba-02 (work in progress), October 2006.
[I-D.nordmark-shim6-esd] [I-D.nordmark-shim6-esd]
Nordmark, E., "Extended Shim6 Design for ID/loc split and Nordmark, E., "Extended Shim6 Design for ID/loc split and
Traffic Engineering", draft-nordmark-shim6-esd-00 (work in Traffic Engineering", draft-nordmark-shim6-esd-00 (work in
progress), February 2006. progress), February 2006.
[RFC2765] Nordmark, E., "Stateless IP/ICMP Translation Algorithm [RFC2765] Nordmark, E., "Stateless IP/ICMP Translation Algorithm
(SIIT)", RFC 2765, February 2000. (SIIT)", RFC 2765, February 2000.
[RFC3972] Aura, T., "Cryptographically Generated Addresses (CGA)", [RFC3972] Aura, T., "Cryptographically Generated Addresses (CGA)",
 End of changes. 53 change blocks. 
213 lines changed or deleted 373 lines changed or added

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