One document matched: draft-ietf-shim6-multihome-shim-api-13.xml
<?xml version="1.0"?>
<?xml-stylesheet type='text/xsl' href='ref2629.xslt' ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<rfc category="info" docName="draft-ietf-shim6-multihome-shim-api-13"
ipr="trust200902">
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<?rfc toc="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc sortrefs="yes" ?>
<?rfc iprnotified="no" ?>
<?rfc strict="yes" ?>
<?rfc compact="yes"?>
<front>
<title abbrev="Multihoming Shim API">Socket Application Program
Interface (API) for Multihoming Shim</title>
<author initials='M' surname='Komu' fullname='Miika Komu'>
<organization abbrev="HIIT">Helsinki Institute for Information
Technology</organization>
<address>
<postal>
<street>Tammasaarenkatu 3</street>
<city>Helsinki</city>
<country>Finland</country>
</postal>
<phone>+358503841531</phone>
<facsimile>+35896949768</facsimile>
<email>miika@iki.fi</email>
<uri>http://www.hiit.fi/</uri>
</address>
</author>
<author initials='M' surname='Bagnulo' fullname='Marcelo Bagnulo'>
<organization abbrev="UC3M">Universidad Carlos III de
Madrid</organization>
<address>
<postal>
<street>Av. Universidad 30</street>
<city>Leganes</city>
<code>28911</code>
<country>SPAIN</country>
</postal>
<phone>+34 91 6248837</phone>
<email>marcelo@it.uc3m.es</email>
<uri>http://it.uc3m.es/marcelo</uri>
</address>
</author>
<author initials='K' surname='Slavov' fullname='Kristian Slavov'>
<organization abbrev="Ericsson">Ericsson Research
Nomadiclab</organization>
<address>
<postal>
<street>Hirsalantie 11</street>
<city>Jorvas</city>
<code>FI-02420</code>
<country>Finland</country>
</postal>
<phone>+358 9 299 3286</phone>
<email>kristian.slavov@ericsson.com</email>
</address>
</author>
<author initials='S' surname='Sugimoto' fullname='Shinta Sugimoto'
role="editor">
<organization abbrev="Ericsson"> Nippon Ericsson K.K.</organization>
<address>
<postal>
<street>Koraku Mori Building</street>
<street>1-4-14, Koraku, Bunkyo-ku</street>
<city>Tokyo</city>
<code>112-0004</code>
<country>Japan</country>
</postal>
<phone>+81 3 3830 2241</phone>
<email>shinta@sfc.wide.ad.jp</email>
</address>
</author>
<date month="February" day="22" year="2010"/>
<area>Internet</area>
<workgroup>SHIM6 Working Group</workgroup>
<keyword>SHIM6, HIP, identifier/locator split</keyword>
<abstract>
<t>This document specifies sockets API extensions for the
multihoming shim layer. The API aims to enable interactions
between applications and the multihoming shim layer for advanced
locator management, and access to information about failure
detection and path exploration.</t>
<t>This document is based on an assumption that a multihomed
host is equipped with a conceptual sub-layer (hereafter "shim")
inside the IP layer that maintains mappings between identifiers
and locators. Examples of the shim are SHIM6 and HIP.</t>
</abstract>
</front>
<middle>
<!--
================================================================
Introduction
================================================================
-->
<section title="Introduction" toc="include">
<t>This document defines socket API extensions by which upper
layer protocols may be informed about and control the way in
which a multihoming shim sub-layer in the IP layer manages the
dynamic choice of locators. Initially it applies to SHIM6 and
HIP, but it is defined generically.</t>
<t>The role of the multihoming shim sub-layer (hereafter called
"shim sub-layer" in this document) is to avoid impacts to upper
layer protocols which may be caused when the endhost changes its
attachment point to the Internet, for instance, in the case of
rehoming event under the multihomed environment. The key design
of the shim sub-layer is to treat identifier and locator
separately. Identifiers are presented to upper layer protocols
and used as communication endpoints. Locators represent
toplogical location of endhosts and are used to route packet
from the source to the destiantion. The shim sub-layer
maintains mapping of identifiers and locators.</t>
<t>Note that the shim sub-layer may conflict with other
multihoming mechanisms such as SCTP and multipath TCP<xref
target="I-D.ietf-shim6-applicability"/>. To avoid any conflict,
only one of SHIM6 and HIP should be in use.</t>
<t>In this document, syntax and semantics of the API are given
in the same way as the Posix standard <xref target="POSIX"/>.
The API specifies how to use ancillary data (aka cmsg) to access
the locator information with recvmsg() and/or sendmsg() I/O
calls. The API is described in C language and data types are
defined in the Posix format; intN_t means a signed integer of
exactly N bits (e.g. int16_t) and uintN_t means an unsigned
integer of exactly N bits (e.g. uint32_t).</t>
<t>The distinction between "connected" sockets and "unconnected"
sockets is important when discussing the applicability of the
socket API defined in this document. A connected socket is
bound to a given peer, whereas an unconnected socket is not
bound to any specific peers. A TCP socket becomes a connected
socket when the TCP connection establishment is completed. UDP
sockets are unconnected, unless the application uses the
connect() system call.</t>
<t>The target readers of this document are application
programmers who develop application software which may benefit
greatly from multihomed environments. In addition, this
document aims to provide necessary information for developers of
shim protocols to implement API for enabling advanced locator
management.</t>
</section>
<!--
================================================================
Terminology
================================================================
-->
<section title="Terminology" toc="include">
<t>This section provides terminology used in this document.
Basically most of the terms used in this document are taken from
the following documents:<vspace blankLines="1"/>
<list style="symbols">
<t>SHIM6 Protocol Specification<xref
target="RFC5533"/></t>
<t>HIP Architecture<xref target="RFC4423"/></t>
<t>Reachability Protocol (REAP)<xref
target="RFC5534"/></t>
</list>
<vspace blankLines="1"/>
In this document, the term "IP" refers to both IPv4 and IPv6,
unless the protocol version is specifically mentioned. The
following are definitions of terms frequently used in this
document:<vspace blankLines="1"/>
<list style="symbols">
<t>Endpoint identifier (EID) - The identifier used by the
application to specify the endpoint of a given communication.
Applications may handle EIDs in various ways such as
long-lived connections, callbacks, and referrals<xref
target="I-D.ietf-shim6-app-refer"/>.
<list style="symbols">
<t>In the case of SHIM6, an identifier called a ULID serves
as an EID. A ULID is chosen from locators available on the
host.</t>
<t>In the case of HIP, an identifier called a Host
Identifier serves as an EID. A Host Identifier is derived
from the public key of a given host. For the sake of
backward compatibility with the sockets API, the Host
Identifier is represented in a form of hash of public key.
</t>
<t>Note that the EID appears in the standard socket API as
an address, and does not appear in the extensions defined in
this document, which only concern locators.</t>
</list>
</t>
<t>Locator - The IP address actually used to deliver IP
packets. Locators are present in the source and destination
fields of the IP header of a packet on the wire. <list
style="symbols">
<t>List of locators - A list of locators associated with
an EID. There are two lists of locators stored in a given
context. One is associated with the local EID and the
other is associated with the remote EID. As defined in
<xref target="RFC5533"/>, the list of locators associated
with an EID 'A' is denoted as Ls(A).</t>
<t>Preferred locator - The (source/destination) locator
currently used to send packets within a given context. As
defined in <xref target="RFC5533"/>, the preferred locator
of a host 'A' is denoted as Lp(A).</t>
<t>Unknown locator - Any locator that does not appear in
the locator list of the shim context associated with the
socket. When there is no shim context associated with the
socket, any source and/or destination locator requested by
the application is considered to be unknown locator.</t>
</list>
</t>
<t>Shim - The conceptual sub-layer inside the IP layer which
maintains mappings between EIDs and locators. An EID can be
associated with more than one locator at a time when the host
is multihomed. The term 'shim' does not refer to a specific
protocol but refers to the conceptual sub-layer inside the IP
layer.</t>
<t>Identifier/locator adaptation - The adaptation performed at
the shim sub-layer which may end up re-writing the source
and/or destination addresses of an IP packet. In the outbound
packet processing, the EID pair is converted to the associated
locator pair. In the inbound packet processing, the locator
pair is converted to the EID pair.</t>
<t>Context - The state information shared by a given pair of
peers, which stores a binding between the EID and associated
locators. Contexts are maintained by the shim sub-layer.</t>
<t>Reachability detection - The procedure to check
reachability between a given locator pair.</t>
<t>Path - The sequence of routers that an IP packet goes
through to reach the destination.</t>
<t>Path exploration - The procedure to explore available paths
for a given set of locator pairs.</t>
<t>Outage - The incident that prevents IP packets to flow from
the source locator to the destination locator. When there is
an outage, it means that there is no reachability between a
given locator pair. The outage may be caused by various
reasons, such as shortage of network resources, congestion,
and human error (faulty operation).</t>
<t>Working address pair - The address pair is considered to be
"working" if the packet can safely travel from the source to
the destination where the packet contains the first address
from the pair as the source address and the second address
from the pair as the destination address. If reachability is
confirmed in both directions, the address pair is considered
to be working bi-directionally.</t>
<t>Reachability protocol (REAP) - The protocol for detecting
failure and exploring reachability in a multihomed
environment. REAP is defined in <xref
target="RFC5534"/>.</t>
</list>
</t>
</section>
<!--
================================================================
System Overview
================================================================
-->
<section title="System Overview" anchor="sec-system-overview"
toc="include">
<t><xref target="fig-system-overview"/> illustrates the system
overview. The shim sub-layer and REAP component exist inside
the IP layer. Applications use the sockets API defined in this
document to interface with the shim sub-layer and the transport
layer for locator management, failure detection, and path
exploration.</t>
<t>It may also be possible that the shim sub-layer interacts
with the transport layer, however, such an interaction is
outside the scope of this document.</t>
<figure anchor="fig-system-overview" title="System overview">
<artwork><![CDATA[
+------------------------+
| Application |
+------------------------+
^ ^
~~~~~~~~~~~~~|~Socket Interface|~~~~~~~~~~~~~~
| v
+-----------|------------------------------+
| | Transport Layer |
+-----------|------------------------------+
^ |
+-------------|-----|-------------------------------------+
| v v |
| +-----------------------------+ +----------+ | IP
| | Shim |<----->| REAP | | Layer
| +-----------------------------+ +----------+ |
| ^ ^ |
+-----------------------|----------------------|----------+
v v
+------------------------------------------+
| Link Layer |
+------------------------------------------+
]]></artwork>
</figure>
</section>
<!--
================================================================
Requirements
================================================================
-->
<section title="Requirements" anchor="sec-requirements" toc="include">
<t>The following is a list of requirements from applications:
<!--
<t>These requirements are mainly identified during the
discussions on SHIM6 WG mailing list. Some requirements
are derived from the REAP specification<xref
target="RFC5534"/>.<vspace
blankLines="1"/>
-->
<!--
Marcelo's email which was sent on the SHIM6 mailing list:
http://www.ops.ietf.org/lists/shim6/msg01191.html
-->
<list style="symbols">
<t>Turn on/off shim. An application should be able to request
to turn on or turn off the multihoming support by the shim
layer:
<list style="symbols">
<t>Apply shim. The application should be able to explicitly
request the shim sub-layer to apply multihoming support.</t>
<t>Don't apply shim. The application should be able to
request the shim sub-layer not to apply the multihoming
support but to apply normal IP processing at the IP
layer.</t>
<t>Note that this function is also required by other types
of multihoming mechanisms such as SCTP and multipath TCP to
avoid potential conflict with the shim sub-layer.</t>
</list>
</t>
<t>Locator management.
<list style="symbols">
<t>It should be possible to set preferred source and/or
destination locator within a given context: Lp(local) and/or
Lp(remote).</t>
<t>It should be possible to get preferred source and/or
destination locator within a given context: Lp(local) and/or
Lp(remote).</t>
<t>It should be possible to set a list of source and/or
destination locators within a given context: Ls(local) and
Ls(remote).</t>
<t>It should be possible to get a list of source and/or
destination locators within a given context: Ls(local) and
Ls(remote).</t>
</list>
</t>
<t>Notification from applications to the shim sub-layer about
the status of the communication. The notification occurs in
an event-based manner. Applications and/or upper layer
protocols may provide positive feedbacks or negative feedbacks
to the shim sub-layer. Note that these feedbacks are
mentioned in
<xref target="RFC5534"/>:
<list style="symbols">
<t>Applications and/or upper layer protocols (e.g., TCP) may
provide positive feedbacks to the shim sub-layer informing
that the communication is going well.</t>
<t>Applications and/or upper layer protocols (e.g., TCP) may
provide negative feedbacks to the shim sub-layer informing
that the communication status is not satisfactory. TCP may
detect a problem when it does not receive any expected ACK
message from the peer. The REAP module may be triggered by
these negative feedbacks and invoke the path exploration
procedure.</t> </list>
</t>
<t>Feedback from applications to the shim sub-layer.
Applications should be able to inform the shim sub-layer of
the timeout values for detecting failures, sending keepalives,
and starting the exploration procedure. In particular,
applications should be able to suppress keepalives.
</t>
<t>Hot-standby. Applications may request the shim sub-layer
for the hot-standby capability. This means that, alternative
paths are known to be working in advance of a failure
detection. In such a case, it is possible for the host to
immediately replace the current locator pair with an
alternative locator pair.
</t>
<t>Eagerness for locator exploration. An application should
be able to inform the shim sub-layer of how aggressively it
wants the REAP mechanism to perform a path exploration (e.g.,
by specifying the number of concurrent attempts of discovery
of working locator pairs) when an outage occurs on the path
between the locator pair in use.</t>
<t>Providing locator information to applications. An
application should be able to obtain information about the
locator pair which was actually used to send or receive the
packet. <list style="symbols">
<t>For inbound traffic, the application may be interested in
the locator pair which was actually used to receive the
packet.
</t>
<t>For outbound traffic, the application may be interested
in the locator pair which was actually used to transmit the
packet.</t>
</list>
In this way, applications may have additional control on the
locator management. For example, an application becomes able
to verify if its preference for locator is actually applied to
the flow or not.
</t>
<t>Applications should be able to know if the shim-sublayer
supports deferred context setup or not.</t>
<t>An application should be able to know if the communication
is now being served by the shim sub-layer or not.</t>
<t>An application should be able to use a common interface to
access an IPv4 locator and an IPv6 locator.</t>
</list>
</t>
</section>
<!--
===================================================================
Socket options for multihoming shim sub-layer
===================================================================
-->
<section title="Socket Options for Multihoming Shim Sub-layer"
anchor="sec-shim-socket-options" toc="include">
<t>In this section, socket options that are specific to the shim
sub-layer are defined.</t>
<t><xref target="tab-shim-socket-options"/> shows a list of the
socket options that are specific to the shim sub-layer. An
application may use these socket options for a given socket
either by the getsockopt() system call or by the setsockopt()
system call. All of these socket options are defined at level
SOL_SHIM.</t>
<t>The first column of <xref target="tab-shim-socket-options"/>
gives the name of the option. The second and third columns
indicate whether the option can be handled by the getsockopt()
system call and/or by the setsockopt() system call. The fourth
column provides a brief description of the socket option. The
fifth column shows the type of data structure specified along
with the socket option. By default, the data structure type is
an integer.</t>
<texttable anchor="tab-shim-socket-options"
title="Socket options for multihoming shim sub-layer">
<ttcol align='left'>optname</ttcol>
<ttcol align='left'>get</ttcol>
<ttcol align='left'>set</ttcol>
<ttcol align='left'>description</ttcol>
<ttcol align='left'>dtype</ttcol>
<c>SHIM_ASSOCIATED</c>
<c>o</c>
<c></c>
<c>Get the parameter which indicates whether the socket is
associated with any shim context or not.</c>
<c>int</c>
<c>SHIM_DONTSHIM</c>
<c>o</c>
<c>o</c>
<c>Get or set the parameter which indicates whether to employ
the multihoming support by the shim sub-layer or not.</c>
<c>int</c>
<c>SHIM_HOT_STANDBY</c>
<c>o</c>
<c>o</c>
<c>Get or set the parameter to request the shim sub-layer to
prepare a hot-standby connection.</c>
<c>int</c>
<c>SHIM_LOC_LOCAL_PREF</c>
<c>o</c>
<c>o</c>
<c>Get or set the preferred locator on the local side for the
context associated with the socket.</c>
<c>*1</c>
<c>SHIM_LOC_PEER_PREF</c>
<c>o</c>
<c>o</c>
<c>Get or set the preferred locator on the remote side for the
context associated with the socket.</c>
<c>*1</c>
<c>SHIM_LOC_LOCAL_RECV</c>
<c>o</c>
<c>o</c>
<c>Get or set the parameter which is used to request the shim
sub-layer to store the destination locator of the received IP
packet.</c>
<c>int</c>
<c>SHIM_LOC_PEER_RECV</c>
<c>o</c>
<c>o</c>
<c>Get or set the parameter which is used to request the shim
sub-layer to store the source locator of the received IP
packet.</c>
<c>int</c>
<c>SHIM_LOC_LOCAL_SEND</c>
<c>o</c>
<c>o</c>
<c>Get or set the source locator of outgoing IP packets.</c>
<c>*1</c>
<c>SHIM_LOC_PEER_SEND</c>
<c>o</c>
<c>o</c>
<c>Get or set the destination locator of outgoing IP packets.</c>
<c>*1</c>
<c>SHIM_LOCLIST_LOCAL</c>
<c>o</c>
<c>o</c>
<c>Get or set the list of locators associated with the local
EID.</c>
<c>*2</c>
<c>SHIM_LOCLIST_PEER</c>
<c>o</c>
<c>o</c>
<c>Get or set the list of locators associated with the peer's
EID.</c>
<c>*2</c>
<c>SHIM_APP_TIMEOUT</c>
<c>o</c>
<c>o</c>
<c>Get or set the timeout value for detecting failure.</c>
<c>int</c>
<c>SHIM_PATHEXPLORE</c>
<c>o</c>
<c>o</c>
<!-- marcelo: not sure what this means... is the number of
alternative paths to be explored, how many times each
path will be tried i.e. how many probe packets per
alternative path are to be sent? -->
<c>Get or set parameters for path exploration and failure
detection.</c>
<c>*3</c>
<c>SHIM_CONTEXT_DEFERRED_SETUP</c>
<c>o</c>
<c></c>
<c>Get the parameter which indicates whether deferred context
setup is supported or not.</c>
<c>int</c>
</texttable>
<t>*1: Pointer to a shim_locator which is defined in <xref
target="sec-data-structures"/>.</t>
<t>*2: Pointer to an array of shim_locator.</t>
<t>*3: Pointer to a shim_pathexplore which is defined in <xref
target="sec-data-structures"/>.</t>
<t><xref target="fig-socket-api-model"/> illustrates how the
shim specific socket options fit into the system model of socket
API. The figure shows that the shim sub-layer and the
additional protocol components (IPv4 and IPv6) below the shim
sub-layer are new to the system model. As previously mentioned,
all the shim specific socket options are defined at the SOL_SHIM
level. This design choice brings the following
advantages:<vspace blankLines="1"/>
<list style="numbers">
<t>The existing sockets API continue to work at the layer
above the shim sub-layer. That is, those legacy API handle IP
addresses as identifiers.</t>
<t>With newly defined socket options for the shim sub-layer, the
application obtains additional control of locator
management.</t>
<t>The shim specific socket options can be kept independent
from address family (IPPROTO_IP or IPPROTO_IPV6) and transport
protocol (IPPROTO_TCP or IPPROTO_UDP).</t>
</list>
</t>
<figure anchor="fig-socket-api-model"
title="System model of sockets API with shim sub-layer">
<artwork><![CDATA[
s1 s2 s3 s4
| | | |
+----------------|--|-------|--|----------------+
| +-------+ +-------+ |
| IPPROTO_TCP | TCP | | UDP | |
| +-------+ +-------+ |
| | \ / | |
| | ----- | |
| | / \ | |
| +------+ +------+ |
| IPPROTO_IP | IPv4 | | IPv6 | IPPROTO_IPV6 |
| +------+ +------+ |
| \ / SOL_SOCKET
| +--------\-------/--------+ |
| SOL_SHIM | shim | |
| +--------/-------\--------+ |
| / \ |
| +------+ +------+ |
| | IPv4 | | IPv6 | |
| +------+ +------+ |
| | | |
+------------------|----------|-----------------+
| |
IPv4 IPv6
Datagram Datagram
]]></artwork>
</figure>
<section title="SHIM_ASSOCIATED">
<t>The SHIM_ASSOCIATED option is used to check whether the
socket is associated with any shim context or not.</t>
<t>This option is meaningful when the locator information of
the received IP packet does not tell whether the
identifier/locator adaptation is performed or not. Note that
the EID pair and the locator pair may be identical in some
cases.</t>
<t>This option can be specified by getsockopt(). Thus, the
option is read-only and the result (0/1/2) is set in the
option value (the fourth argument of getsockopt()).</t>
<t>When the application specifies the socket option to an
unconnected socket, an error code EOPNOTSUPP is returned to
the application.</t>
<t>The data type of the option value is an integer. The
option value indicates the presence of shim context. A return
value 1 means that the socket is associated with a shim
context at the shim sub-layer. A return value 0 indicates
that there is no shim context associated with the socket. A
return value 2 means that it is not known whether the socket
is associated with a shim context or not, and this must be
returned only when the socket is unconnected. In other words,
the returned value must be 0 or 1 when the socket is
connected.</t>
<t>For example, the option can be used by the application as
follows:</t>
<figure>
<artwork><![CDATA[
int optval;
int optlen = sizeof(optval);
getsockopt(fd, SOL_SHIM, SHIM_ASSOCIATED, &optval, &optlen);
]]></artwork>
</figure>
</section>
<section title="SHIM_DONTSHIM">
<t>The SHIM_DONTSHIM option is used to request the shim layer
not to provide the multihoming support for the communication
established over the socket.</t>
<t>The data type of the option value is an integer, and it
takes 0 or 1. An option value 0 means that the shim sub-layer
is employed if available. An option value 1 means that the
application does not want the shim sub-layer to provide the
multihoming support for the communication established over the
socket.</t>
<t>Default value is set as 0, which means that the shim
sub-layer performs identifier/locator adaptation if
available.</t>
<t>Any attempt to disable the multihoming shim support MUST be
made by the application before the socket is connected. If an
application makes such an attempt for a connected-socket, an
error code EOPNOTSUPP MUST be returned.</t>
<t>For example, an application can request the system not to
apply the multihoming support as follows:</t>
<figure>
<artwork><![CDATA[
int optval;
optval = 1;
setsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, sizeof(optval));
]]></artwork>
</figure>
<t>For example, the application can check the option value as
follows:</t>
<figure>
<artwork><![CDATA[
int optval;
int len;
len = sizeof(optval);
getsockopt(fd, SOL_SHIM, SHIM_DONTSHIM, &optval, &len);
]]></artwork>
</figure>
</section>
<section title="SHIM_HOT_STANDBY">
<t>The SHIM_HOT_STANDBY option is used to control the shim
sub-layer whether to employ a hot-standby connection for the
socket or not. A hot-standby connection is an alternative
working locator pair to the current locator pair. This option
is effective only when there is a shim context associated with
the socket.</t>
<t>The data type of the option value is an integer.</t>
<t>The option value can be set by setsockopt().</t>
<t>The option value can be read by getsockopt().</t>
<t>By default, the value is set to 0, meaning that hot-standby
connection is disabled.</t>
<t>When the application specifies the socket option to an
unconnected socket, an error code EOPNOTSUPP is returned to
the application.</t>
<t>When there is no shim context associated with the socket,
an error code ENOENT is returned to the application.</t>
<t>For example, an application can request establishment of a
hot-standby connection by using the socket option as
follows:</t>
<figure>
<artwork><![CDATA[
int optval;
optval = 1;
setsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval,
sizeof(optval));
]]></artwork>
</figure>
<t>For example, an application can get the option value by
using the socket option as follows:</t>
<figure>
<artwork><![CDATA[
int optval;
int len;
len = sizeof(optval);
getsockopt(fd, SOL_SHIM, SHIM_HOT_STANDBY, &optval, &len);
]]></artwork>
</figure>
</section>
<section title="SHIM_LOC_LOCAL_PREF">
<t>The SHIM_LOC_LOCAL_PREF option is used to get or set
preference for a source locator for outbound traffic within a
given context. This option is effective only when there is a
shim context associated with the socket.</t>
<t>The preference of a locator is defined by a combination of
priority and weight as per DNS SRV<xref target="RFC2782"/>.
Note that the SHIM6 base protocol defines preference of
locator in the same way.</t>
<t>The data type of the option value is a pointer to a locator
information data structure which is defined in
<xref target="sec-data-structures"/>.</t>
<t>By default, the option value is set to NULL, meaning that
the option is disabled.</t>
<t>The preferred locator can be set by setsockopt(). The shim
sub-layer shall verify requested locator before it updates
the preferred locator.</t>
<t>An application can get the preferred locator by
getsockopt().</t>
<t>When the application specifies the socket option to an
unconnected socket, an error code EOPNOTSUPP is returned to
the application.</t>
<t>When there is no shim context associated with the socket,
an error code ENOENT is returned to the application.</t>
<t>An error EINVALIDLOCATOR is returned when the validation of
the specified locator fails.</t>
<t>For example, an application can set the preferred locator
by using the socket option as follows. Note that some members
of the shim_locator (lc_ifidx and lc_flags) are ignored in the
set operation.</t>
<figure>
<artwork><![CDATA[
struct shim_locator lc;
struct in6_addr ip6;
/* ...set the locator (ip6)... */
memset(&lc, 0, sizeof(shim_locator));
lc.lc_family = AF_INET6; /* IPv6 */
lc.lc_ifidx = 0;
lc.lc_flags = 0;
lc.lc_prio = 1;
lc.lc_weight = 10;
memcpy(&lc.lc_addr, &ip6, sizeof(in6_addr));
setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc,
sizeof(optval));
]]></artwork>
</figure>
<t>For example, an application can get the preferred locator
by using the socket option as follows.</t>
<figure>
<artwork><![CDATA[
struct shim_locator lc;
int len;
len = sizeof(lc);
getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_PREF, &lc, &len);
]]></artwork>
</figure>
</section>
<section title="SHIM_LOC_PEER_PREF">
<t>The SHIM_LOC_PEER_PREF option is used to get or set
preference of a destination locator for outbound traffic
within a given context. This option is effective only when
there is a shim context associated with the socket.</t>
<t>As defined earlier, the preference of a locator is defined
by a combination of priority and weight as per DNS
SRV<xref target="RFC2782"/>. When there are more than one
candidate destination locators, the shim sub-layer makes
selection based on the priority and weight specified for each
locator.</t>
<t>The data type of the option value is a pointer to the
locator information data structure which is defined in <xref
target="sec-data-structures"/>.</t>
<t>By default, the option value is set to NULL, meaning that
the option is disabled.</t>
<t>The preferred locator can be set by setsockopt(). The shim
sub-layer shall verify requested locator before it updating
the preferred locator.</t>
<t>An application can get the preferred locator by
getsockopt().</t>
<t>When the application specifies the socket option to an
unconnected socket, an error code EOPNOTSUPP is returned to
the application.</t>
<t>When there is no shim context associated with the socket,
an error code ENOENT is returned to the application.</t>
<t>An error EINVALIDLOCATOR is returned when the validation of
the requested locator fails.</t>
<t>The usage of the option is same as that of
SHIM_LOC_LOCAL_PREF. Note that some members of the
shim_locator (lc_ifidx and lc_flags) are ignored in the set
operation.</t>
</section>
<section title="SHIM_LOC_LOCAL_RECV">
<t>The SHIM_LOC_LOCAL_RECV option can be used to request the
shim sub-layer to store the destination locator of the
received IP packet in an ancillary data object which can be
accessed by recvmsg(). This option is effective only when
there is a shim context associated with the socket.</t>
<t>The data type of the option value is integer. The option
value should be binary (0 or 1). By default, the option value
is set to 0, meaning that the option is disabled.</t>
<t>An application can set the option value by
setsockopt().</t>
<t>An application can get the option value by
getsockopt().</t>
<t>See <xref target="sec-access-to-locinfo"/> for the
procedure to access locator information stored in the
ancillary data objects.</t>
<t>When the application specifies the socket option to an
unconnected socket, an error code EOPNOTSUPP is returned to
the application.</t>
<t>When there is no shim context associated with the socket,
an error code ENOENT is returned to the application.</t>
<t>For example, an application can request the shim sub-layer
to store destination locator by using the socket option as
follows.</t>
<figure>
<artwork><![CDATA[
int optval;
optval = 1;
setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval,
sizeof(optval));
]]></artwork>
</figure>
<t>For example, an application can get the option value as
follows.</t>
<figure>
<artwork><![CDATA[
int optval;
int len;
len = sizeof(optval);
getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_RECV, &optval, &len);
]]></artwork>
</figure>
</section>
<section title="SHIM_LOC_PEER_RECV">
<t>The SHIM_LOC_PEER_RECV option is used to request the shim
sub-layer to store the source locator of the received IP
packet in an ancillary data object which can be accessed by
recvmsg(). This option is effective only when there is a shim
context associated with the socket.</t>
<t>The data type of the option value is integer. The option
value should be binary (0 or 1). By default, the option value
is set to 0, meaning that the option is disabled.</t>
<t>The option value can be set by setsockopt().</t>
<t>The option value can be read by getsockopt().</t>
<t>See <xref target="sec-access-to-locinfo"/> for the
procedure to access locator information stored in the
ancillary data objects.</t>
<t>When the application specifies the socket option to an
unconnected socket, an error code EOPNOTSUPP is returned to
the application.</t>
<t>When there is no shim context associated with the socket,
an error code ENOENT is returned to the application.</t>
<t>The usage of the option is same as that of
SHIM_LOC_LOCAL_RECV option.</t>
</section>
<section title="SHIM_LOC_LOCAL_SEND">
<t>The SHIM_LOC_LOCAL_SEND option is used to request the shim
sub-layer to use a specific locator as the source locator for
the IP packets to be sent from the socket. This option is
effective only when there is a shim context associated with
the socket.</t>
<t>The data type of option value is pointer to shim_locator
data structure.</t>
<t>An application can set the local locator 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 inactivated.</t>
<t>An application can get the local locator by
getsockopt().</t>
<t>When the application specifies the socket option to an
unconnected socket, an error code EOPNOTSUPP is returned to
the application.</t>
<t>When there is no shim context associated with the socket,
an error code ENOENT is returned to the application.</t>
<t>An error EINVALIDLOCATOR is returned when an invalid
locator is specified.</t>
<t>For example, an application can request the shim sub-layer
to use a specific local locator by using the socket option as
follows.</t>
<figure>
<artwork><![CDATA[
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_prio = 0;
locator.lc_weight = 0;
memcpy(&locator.lc_addr, &ia6, sizeof(ia6));
setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator,
sizeof(locator));
]]></artwork>
</figure>
<t>For example, an application can get the preferred local
locator by using the socket option as follows.</t>
<figure>
<artwork><![CDATA[
struct shim_locator locator;
memset(&locator, 0, sizeof(locator));
getsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator,
sizeof(locator));
/* check locator */
]]></artwork>
</figure>
</section>
<section title="SHIM_LOC_PEER_SEND">
<t>The SHIM_LOC_PEER_SEND option is used to request the shim
sub-layer to use a specific locator for the destination
locator of IP packets to be sent from the socket. This option
is effective only when there is a shim context associated with
the socket.</t>
<t>The data type of the option value is a pointer to
shim_locator data structure.</t>
<t>An application can set the remote locator 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 inactivated.</t>
<t>An application can get the specified remote locator by
getsockopt().</t>
<t>When the application specifies the socket option to an
unconnected socket, an error code EOPNOTSUPP is returned to
the application.</t>
<t>When there is no shim context associated with the socket,
an error code ENOENT is returned to the application.</t>
<t>An error EINVALIDLOCATOR when invalid an locator is
specified.</t>
<t>The usage of the option is the same as that of
SHIM_LOC_LOCAL_SEND option.</t>
</section>
<section title="SHIM_LOCLIST_LOCAL">
<t>The SHIM_LOCLIST_LOCAL option is used to get or set the
locator list associated with the local EID of the shim context
associated with the socket. This option is effective only
when there is a shim context associated with the socket.</t>
<t>The data type of the option value is a pointer to the
buffer in which a locator list is stored. See <xref
target="sec-data-structures"/> for the data structure for
storing the locator information. By default, the option value
is set to NULL, meaning that the option is disabled.</t>
<t>An application can get the locator list by getsockopt().
Note that the size of the buffer pointed to by the optval
argument should be large enough to store an array of locator
information. The number of the locator information is not
known beforehand.</t>
<t>The local locator list can be set by setsockopt(). The
buffer pointed to by the optval argument should contain an
array of locator structures.</t>
<t>When the application specifies the socket option to an
unconnected socket, an error code EOPNOTSUPP is returned to
the application.</t>
<t>When there is no shim context associated with the socket,
an error code ENOENT is returned to the application.</t>
<t>An error EINVALIDLOCATOR is returned when the validation of
any of the specified locators failed.</t>
<t>An error ETOOMANYLOCATORS is returned when the number of
locators specified exceeds the limit (SHIM_MAX_LOCATORS), or
when the size of the buffer provided by the application is not
large enough to store the locator list provided by the shim
sub-layer.</t>
<t>For example, an application can set a list of locators to
be associated with the local EID by using the socket option as
follows:</t>
<figure>
<artwork><![CDATA[
struct shim_locator locators[SHIM_MAX_LOCATORS];
struct sockaddr_in *sin;
struct sockaddr_in6 *sin6;
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_prio = 1;
locators[0].lc_weight = 0;
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_prio = 0;
locators[1].lc_weight = 0;
memcpy(&locators[1].lc_addr, &sa->sin_addr,
sizeof(sa->sin_addr));
setsockopt(fd, SOL_SHIM, SHIM_LOCLIST_LOCAL, locators,
sizeof(locators));
]]></artwork>
</figure>
<t>For example, an application can get a list of locators that
are associated with the local EID by using the socket option
as follows.</t>
<figure>
<artwork><![CDATA[
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 */
...
]]></artwork>
</figure>
</section>
<section title="SHIM_LOCLIST_PEER">
<t>The SHIM_LOCLIST_PEER option is used to get or set the
locator list associated with the peer EID of the shim context
associated with the socket. This option is effective only
when there is a shim context associated with the socket.</t>
<t>The data type of the option value is a pointer to the
buffer where a locator list is stored. See <xref
target="sec-data-structures"/> for the data structure for
storing the locator information. By default, the option value
is set to NULL, meaning that the option is disabled.</t>
<t>An application can get the locator list by getsockopt().
Note that the size of the buffer pointed to by the optval
argument should be large enough to store an array of locator
information. The number of the locator information is not
known beforehand.</t>
<t>An application can set the locator list by setsockopt().
The buffer pointed to by the optval argument should contain an
array of locator list.</t>
<t>When the application specifies the socket option to an
unconnected socket, an error code EOPNOTSUPP is returned to
the application.</t>
<t>When there is no shim context associated with the socket,
an error code ENOENT is returned to the application.</t>
<t>An error EINVALIDLOCATOR is returned when the validation of
any of the specified locators failed.</t>
<t>An error ETOOMANYLOCATORS is returned when the number of
locators specified exceeds the limit (SHIM_MAX_LOCATORS), or
when the size of the buffer provided by the application is not
large enough to store the locator list provided by the shim
sub-layer.</t>
<t>The usage of the option is same as that of
SHIM_LOCLIST_LOCAL.</t>
</section>
<section title="SHIM_APP_TIMEOUT">
<t>The SHIM_APP_TIMEOUT option is used to get or set the Send
Timeout value of the REAP protocol. This option is effective
only when there is a shim context associated with the
socket.</t>
<t>The data type of the option value is an integer. The value
indicates the period of timeout in seconds to send a REAP
Keepalive message since the last outbound traffic. By
default, the option value is set to 0, meaning that the option
is disabled. When the option is disabled, the REAP mechanism
follows its default value of Send Timeout value as specified
in <xref target="RFC5534"/></t>
<t>When the application specifies the socket option to an
unconnected socket, an error code EOPNOTSUPP is returned to
the application.</t>
<t>When there is no shim context associated with the socket,
an error code ENOENT is returned to the application.</t>
<t>For example, an application can set the timeout value by
using the socket option as follows.</t>
<figure>
<artwork><![CDATA[
int optval;
optval = 15; /* 15 seconds */
setsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval,
sizeof(optval));
]]></artwork>
</figure>
<t>For example, an application can get the timeout value by
using the socket option as follows.</t>
<figure>
<artwork><![CDATA[
int optval;
int len;
len = sizeof(optval);
getsockopt(fd, SOL_SHIM, SHIM_APP_TIMEOUT, &optval, &len);
]]></artwork>
</figure>
</section>
<section title="SHIM_PATHEXPLORE">
<t>The application may use this socket option to get or set
parameters concerning path exploration. Path exploration is a
procedure to find an alternative locator pair to the current
locator pair. As the REAP specification defines, a peer may
send Probe messages to find an alternative locator pair.</t>
<!--
The REAP specification defines the default values for Initial
Probe Timeout and Initial Probe. Initial Probe Timeout = 0.5
seconds Initial Probe = 4 times
-->
<t>This option is effective only when there is a shim context
associated with the socket.</t>
<t>The data type of the option value is a pointer to the
buffer where a set of information for path exploration is
stored. The data structure is defined in <xref
target="sec-data-structures"/>.</t>
<t>By default, the option value is set to NULL, meaning that
the option is disabled.</t>
<t>When the application specifies the socket option to an
unconnected socket, an error code EOPNOTSUPP is returned to
the application.</t>
<t>When there is no shim context associated with the socket,
an error code ENOENT is returned to the application.</t>
<t>For example, an application can set parameters for path
exploration by using the socket option as follows.</t>
<figure>
<artwork><![CDATA[
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));
]]></artwork>
</figure>
<t>For example, an application can get parameters for path
exploration by using the socket option as follows.</t>
<figure>
<artwork><![CDATA[
struct shim6_pathexplore pe;
int len;
len = sizeof(pe);
getsockopt(fd, SOL_SHIM, SHIM_PATHEXPLORE, &pe, &len);
]]></artwork>
</figure>
</section>
<section title="SHIM_DEFERRED_CONTEXT_SETUP">
<t>The SHIM_DEFERRED_CONTEXT_SETUP option is used to check
whether deferred context setup is possible or not. Deferred
context setup means that the context is established in
parallel with the data communication. Note that SHIM6
supports deferred context setup and HIP does not because EIDs
in HIP (i.e., Host Identifiers) are non-routable.</t>
<t>The data type for the option value is an integer. The
option value should be binary (0 or 1). The option value 1
means that the shim sub-layer supports deferred context setup.
</t>
<t>When the application specifies the socket option to an
unconnected socket, an error code EOPNOTSUPP is returned to
the application.</t>
<t>For example, an application can check whether deferred
context setup is possible or not as follows:</t>
<figure>
<artwork><![CDATA[
int optval;
int len;
len = sizeof(optval);
getsockopt(fd, SOL_SHIM, SHIM_DEFERRED_CONTEXT_SETUP,
&optval, &len);
]]></artwork>
</figure>
</section>
<section title="Applicability"
anchor="sec-socket-options-applicability"
toc="include">
<t>All the socket options defined in this section except for
the SHIM_DONTSHIM option are applicable to applications that
use connected sockets.</t>
<t>All the socket options defined in this section except for
the SHIM_ASSOCIATED, SHIM_DONTSHIM and
SHIM_CONTEXT_DEFERRED_SETUP options are effective only when
there is a shim context associated with the socket.</t>
</section>
<section title="Error Handling">
<t>If successful, getsockopt() and setsockopt() return 0;
otherwise, the functions return -1 and set errno to indicate
an error.</t>
<t>The following are new error values defined for some shim
specific socket options indicating that the getsockopt() or
setsockopt() finished incompletely:<vspace blankLines="1"/>
<list style="hanging">
<t hangText="EINVALIDLOCATOR"><vspace blankLines="0"/>This
indicates that at least one of the necessary validations
inside the shim sub-layer for the specified locator has failed.
In case of SHIM6, there are two kinds of verifications
required for security reasons prior to sending an IP packet
to the peer's new locator; one is the return routability
(check if the peer is actually willing to receive data with
the specified locator) and the other one is the verification
based on crypto identifier mechanisms <xref
target="RFC3972"/>, <xref target="RFC5535"/>.</t>
</list>
</t>
</section>
</section>
<section title="Ancillary Data for Multihoming Shim Sub-layer"
anchor="sec-access-to-locinfo" toc="include">
<t>This section provides definitions of ancillary data to be
used for locator management and notification from/to the shim
sub-layer to/from application.</t>
<t>When the application performs locator management by sendmsg()
or recvmsg(), a member of the msghdr structure (given in
<xref target="fig-msghdr" />) called msg_control holds a pointer
to the buffer in which one ore more shim specific ancillary data
objects may be stored. An ancillary data object can store a
single locator. It should be possible to process the shim
specific ancillary data object by the existing macros defined in
the Posix standard and <xref target='RFC3542'/>.</t>
<figure anchor="fig-msghdr" title="msghdr structure">
<artwork><![CDATA[
struct msghdr {
caddr_t msg_name; /* optional address */
u_int msg_namelen; /* size of address */
struct iovec *msg_iov; /* scatter/gather array */
u_int msg_iovlen; /* # elements in msg_iov */
caddr_t msg_control; /* ancillary data, see below */
u_int msg_controllen; /* ancillary data buffer len */
int msg_flags; /* flags on received message */
};
]]></artwork>
</figure>
<t>In the case of unconnected socket, msg_name stores the socket
address of the peer which should be considered to be an
identifier rather than a locator. SHIM_LOC_PEER_RECV should be
used to get the locator of the peer node.</t>
<t><xref target="tab-shim-ancillary-data"/> is a list of the
shim specific ancillary data which can be used for locator
management by recvmsg() or sendmsg(). In any case, the value of
cmsg_level must be set as SOL_SHIM.</t>
<texttable anchor="tab-shim-ancillary-data"
title="Shim specific ancillary data">
<ttcol align='left'>cmsg_type</ttcol>
<ttcol align='center'>sendmsg()</ttcol>
<ttcol align='center'>recvmsg()</ttcol>
<ttcol align='center'>cmsg_data[]</ttcol>
<c>SHIM_LOC_LOCAL_RECV</c>
<c></c>
<c>o</c>
<c>*1</c>
<c>SHIM_LOC_PEER_RECV</c>
<c></c>
<c>o</c>
<c>*1</c>
<c>SHIM_LOC_LOCAL_SEND</c>
<c>o</c>
<c></c>
<c>*1</c>
<c>SHIM_LOC_PEER_SEND</c>
<c>o</c>
<c></c>
<c>*1</c>
<c>SHIM_FEEDBACK</c>
<c>o</c>
<c></c>
<c>shim_feedback{}</c>
</texttable>
<t>*1: cmsg_data[] includes a single sockaddr_in{} or
sockaddr_in6{} and padding if necessary</t>
<section title="Get Locator from Incoming Packet">
<t>An application can get locator information from the
received IP packet by specifying the shim specific socket
options for the socket. When SHIM_LOC_LOCAL_RECV and/or
SHIM_LOC_PEER_RECV socket options are set, the application can
retrieve local and/or remote locator from the ancillary
data.</t>
<t>When there is no shim context associated with the socket,
the shim sub-layer MUST return zero-filled locator information
to the application.</t>
</section>
<section title="Set Locator for Outgoing Packet">
<t>An application can specify the locators to be used for
transmitting an IP packet by sendmsg(). When the ancillary
data of cmsg_type SHIM_LOC_LOCAL_SEND and/or
SHIM_LOC_PEER_SEND are specified, the application can
explicitly specify the source and/or the destination locators
to be used for the communication over the socket. If the
specified locator pair is verified, the shim sub-layer
overrides the locator(s) of the outgoing IP packet. Note that
the effect is limited to the datagram transmitted by the
sendmsg().</t>
<t>When there is no shim context associated with the socket,
an error code ENOENT is returned to the application.</t>
<t>An error code EINVALIDLOCATOR is returned when validation
of the specified locator fails.</t>
</section>
<section title="Notification from Application to Multihoming Shim Sub-layer"
anchor="sec-feedback" toc="include">
<t>An application may provide feedbacks to the shim sub-layer
about the communication status. Such feedbacks are
particularly useful for the shim sub-layer in the absence of
REAP mechanism to monitor the reachability status of the
currently used locator pair in a given shim context.</t>
<t>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.</t>
<t>When there is no shim context associated with the socket,
an error code ENOENT is returned to the application.</t>
<t>See <xref target="sec-feedback-info"/> for details of the
data structure to be used.</t>
<t>It is outside the scope of this document how the shim
sub-layer would react when a feedback is provided by an
application.</t>
</section>
<!--
<section title="Notification from Multihoming Shim Sub-layer to Application" anchor="sec-notification-shimtoapp" toc="include">
<t>The shim sub-layer MAY provide notification about a locator
change within a multihome shim context to applications that
have concern with the context. Such a notification may be
useful, for example, for an application which is sensitive to
the characteristics of the current path. A locator change is
caused when either of local or peer's locator (or both) is
changed. Note that locators discussed here are the ones that
appear in the IP packet header, and not the ones that are
included in the locator list. A locator change may take place
asynchronously.</t>
<t>The notification is handled as an out-of-band data by the
application.
<list style="numbers">
<t>Application calls the select() system call by setting
non-NULL value for the fourth argument.</t>
<t>When there is a notification, the application reads
out-of-band data from the socket by calling recvmsg().</t>
<t>The application checks the flag in the msghdr (msg_flags)
to see if there is any notification about locator change
delivered. If the MSG_SHIM_LOCATOR_CHANGE flag is set,
application parses the chain of control message to read a
pair of ancillary data objects which contains the source
locator and the destination locator. Note that the
direction of locator change is distinguished by the value of
cmsg_type; SHIM_LOC_*_RECV is used for inbound locator
change, and SHIM_LOC_*_SEND is used for outbound locator
change.</t>
</list>
</t>
<t>There is no restriction in terms of applicability of the
notification about locator change. The notification can be
delivered to any type of socket (connected or unconnected,
stream-oriented or datagram-oriented).</t>
</section>
-->
<section title="Applicability"
anchor="sec-ancillary-data-applicability"
toc="include">
<t>All the ancillary data for the shim sub-layer is applicable
to connected sockets.</t>
<t>Care is needed when the SHIM_LOC_*_RECV socket option is
used for stream-oriented sockets (e.g., TCP sockets) because
there is no one-to-one mapping between a single send or
receive operation and the data (e.g., a TCP segment) being
received. In other words, there is no gurantee that the
locator(s) set in the SHIM_LOC_*_RECV ancillary data is
identical to the locator(s) that appear in the IP packets
received. The shim sub-layer SHOULD provide the latest
locator information to the application in response to the
SHIM_LOC_*_RECV socket option.
</t>
<!-- texts from ver-10
<t>It is important to note that the ancillary data specified
in this section are applicable only to datagram-oriented
sockets (e.g., UDP sockets or raw sockets) and that they are
not applicable to stream-oriented sockets (e.g., TCP sockets).
The reason behind this restriction is that there is no
one-to-one mapping between a single send or receive operation
and a TCP segment being transmitted or received.</t>
<t>Due to the above restriction and the restriction addressed
in <xref target="sec-socket-options-applicability"/>,
SHIM_LOC_LOCAL_RECV or SHIM_LOC_PEER_RECV socket options are,
in practice, applicable only to connected UDP sockets.</t>
-->
</section>
</section>
<section title="Data Structures"
anchor="sec-data-structures" toc="include">
<t>This section data structures for the shim sub-layer. These
data structures are either used as a parameter for setsockopt()
or getsockopt() (as mentioned in
<xref target="sec-shim-socket-options"/>) or as a parameter for
ancillary data to be processed by sendmsg() or recvmsg() (as
mentioned in <xref target="sec-access-to-locinfo"/>).</t>
<!--
Note: maybe we can define getlocatorinfo() system call which
returns a chain of locator information associated with a given
identifier. For instance: getlocatorinfo(const struct
sockaddr *sa_id, const struct addrinfo *hints, struct
addrinfo **result);
-->
<section title="Placeholder for Locator Information">
<t>As defined in <xref target="sec-shim-socket-options"/>, the
SHIM_LOC_*_PREF, SHIM_LOC_*_SEND, and SHIM_LOCLIST_* socket
options need to handle one or more locator information.
Locator information includes not only the locator itself but
also additional information about the locator which is useful
for locator management. A new data structure is defined to
serve as a placeholder for the locator information.</t>
<t><xref target="fig-shim-locator"/> illustrates the data
structure called shim_locator which stores a locator
information.
<figure anchor="fig-shim-locator" title="shim locator structure">
<artwork><![CDATA[
struct shim_locator {
uint8_t lc_family; /* address family */
uint8_t lc_proto; /* protocol */
uint16_t lc_port; /* port number */
uint16_t lc_prio; /* preference value */
uint16_t lc_weight; /* weight */
uint32_t lc_ifidx; /* interface index */
struct in6_addr lc_addr; /* address */
uint16_t lc_flags; /* flags */
};
]]></artwork>
</figure>
<list style="hanging">
<t hangText="lc_family"><vspace blankLines="0"/> 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.</t>
<t hangText="lc_proto"><vspace blankLines="0"/>Internet
Protocol number for the protocol which is used to handle
locator behind NAT. Typically, this value is set as UDP
(17) when the locator is a UDP encapsulation interface.</t>
<t hangText="lc_port"><vspace blankLines="0"/>Port number
which is used for handling locator behind NAT.</t>
<t hangText="lc_prio"><vspace blankLines="0"/>The priority
of the locator. The range is 0-65535. The lowest priority
value means the highest priority.</t>
<t hangText="lc_weight"><vspace blankLines="0"/>The weight
value indicates a relative weight for locators with the same
priority value. The range is 0-65535.</t>
<t hangText="lc_ifidx"><vspace blankLines="0"/>Interface
index of the network interface to which the locator is
assigned. This field should be valid only in a read
(getsockopt()) operation.</t>
<t hangText="lc_addr"><vspace blankLines="0"/>Contains the
locator. In the case where a locator whose size is smaller
than 16 bytes, an encoding rule should be provided for each
locator of a given address family. For instance, in case of
AF_INET (IPv4), the locator should be in the format of an
IPv4-mapped IPv6 address as defined in
<xref target='RFC4291'/>.</t>
<t hangText="lc_flags"><vspace blankLines="0"/>Each bit of
the flags represents a specific characteristics of the
locator. Hash Based Address (HBA) is defined as 0x01.
Cryptographically Generated Address (CGA) is defined as
0x02.</t>
</list>
</t>
<section title="Handling Locator behind NAT">
<t>Note that the locator information MAY contain a locator
behind a Network Address Translator (NAT). Such a
situation may arise when the host is behind the NAT and uses
a local address as a source locator to communicate with the
peer. Note that a NAT traversal mechanism for HIP is
defined, which allows HIP host to tunnel control and data
traffic over UDP<xref target='I-D.ietf-hip-nat-traversal'/>.
Note also that the locator behind NAT is not necessarily an
IPv4 address but it can be an IPv6 address. Below is an
example where the application sets a UDP encapsulation
interface as a source locator when sending IP packets.
<figure anchor="fig-nat-locator-handling" title="Handling
locator behind NAT"><artwork><![CDATA[
struct shim_locator locator;
struct in6_addr ia6;
/* copy the private IPv4 address to the ia6 as an IPv4-mapped
IPv6 address */
memset(&locator, 0, sizeof(locator));
/* fill shim_locator data structure */
locator.lc_family = AF_INET;
locator.lc_proto = IPPROTO_UDP;
locator.lc_port = 50500;
locator.lc_flags = 0;
locator.lc_prio = 0;
locator.lc_weight = 0;
locator.lc_ifidx = 3;
memcpy(&locator.lc_addr, &ia6, sizeof(ia6));
setsockopt(fd, SOL_SHIM, SHIM_LOC_LOCAL_SEND, &locator,
sizeof(locator));
]]></artwork>
</figure>
</t>
</section>
</section>
<section title="Path Exploration Parameter">
<t>As defined in <xref target="sec-shim-socket-options"/>,
SHIM_PATHEXPLORE allows application to set or read the
parameters for path exploration and failure detection. A new
data structure called shim_pathexplore is defined to store the
necessary parameters. <xref target="fig-path-explore"/>
illustrates the data structure. The data structure can be
passed to getsockopt() or setsockopt() as an argument.
<figure anchor="fig-path-explore" title="path explore structure">
<artwork><![CDATA[
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 */
};
]]></artwork>
</figure>
<list style="hanging">
<t hangText="pe_probenum">
<vspace blankLines="0"/>
Indicates the number of initial probe messages to be sent.
Default value of this parameter should follow what is
specified in <xref
target="RFC5534"/>.
</t>
<t hangText="pe_keepaliveto">
<vspace blankLines="0"/>
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 <xref
target="RFC5534"/>.
</t>
<t hangText="pe_initprobeto">
<vspace blankLines="0"/>
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 <xref
target="RFC5534"/>.
</t>
<t hangText="pe_reserved">
<vspace blankLines="0"/>
A reserved field for future extension. By default, the
field should be initialized to zero.
</t>
</list>
</t>
</section>
<section title="Feedback Information" anchor="sec-feedback-info">
<t>As mentioned in <xref target="sec-feedback"/>, applications
can inform the shim sub-layer about the status of unicast
reachability of the locator pair currently in use. The
feedback information can be handled by using ancillary data
called SHIM_FEEDBACK. A new data structure named
shim_feedback is illustrated in <xref
target="fig-feedback-info"/>.
<figure anchor="fig-feedback-info"
title="feedback information structure">
<artwork><![CDATA[
struct shim_feedback {
uint8_t fb_direction; /* direction of traffic */
uint8_t fb_indicator; /* indicator (1-3) */
uint16_t fb_reserved; /* reserved */
};
]]></artwork>
</figure>
<list style="hanging">
<t hangText="direction">
<vspace blankLines="0"/>
Indicates direction of reachability between a locator pair
in question. A value 0 indicates outbound and a value 1
indicates inbound direction.
</t>
<t hangText="indicator">
<vspace blankLines="0"/>
A value indicating the degree of satisfaction of a
unidirectional reachability for a given locator pair.
<list style="symbols">
<t>0: Default value. Whenever this value is specified
the feedback information must not be processed by the
shim sub-layer.</t>
<t>1: Unable to connect. There is no unidirectional
reachability between the locator pair in question.</t>
<t>2: Unsatisfactory. The application is not satisfied
with the unidirectional reachability between the locator
pair in question.</t>
<t>3: Satisfactory. There is satisfactory
unidirectional reachability between the locator pair in
question.</t>
</list>
</t>
<t hangText="reserved">
<vspace blankLines="0"/>
Reserved field. Must be ignored by the receiver.
</t>
</list>
</t>
</section>
</section>
<section title="System Requirements"
anchor="sec-system-requirements"
toc="include">
<t>As addressed in <xref target="sec-shim-socket-options"/>,
most of the socket options and ancillary data defined in this
document are applicable to connected sockets. It is assumed
that the kernel is capable of maintaining the association
between a connected socket and a shim context. This requirement
is considered to be reasonable because a pair of source and
destination IP addresses is bound to a connected socket.</t>
</section>
<section title="Relation to Existing Sockets API Extensions"
anchor="sec-implications-for-legacyapi" toc="include">
<t>This section explains relation between the sockets API
defined in this document and the existing sockets API
extensions.</t>
<t>As mentioned in <xref target="sec-shim-socket-options"/>, the
basic assumption is that the existing sockets API continues to
work above the shim sub-layer. This means that, the existing
sockets API deals with identifiers, and the sockets API defined
in this document deals with locators.</t>
<t>SHIM_LOC_LOCAL_SEND and SHIM_LOC_PEER_SEND socket options are
semantically similar to the IPV6_PKTINFO socket API in the sense
that both provide a means for application to set the source IP
address of outbound IP packets.</t>
<t>SHIM_LOC_LOCAL_RECV and SHIM_LOC_PEER_RECV socket options are
semantically similar to the IP_RECVDSTADDR and IPV6_PKTINFO
socket APIs in the sense that both provides a means for
application to get the source and/or destination IP address of
inbound IP packets.</t>
<t>getsockname() and getpeername() enable application to get
'name' of the communication endpoints which is represented by a
pair of IP address and port number assigned to the socket.
getsockname() gives IP address and port number assigned to the
socket on the local side, and getpeername() gives IP address and
port number of the peer side.</t>
</section>
<section title="Operational Considerations">
<t>This section gives operational considerations of the sockets
API defined in this document.</t>
<section title="Conflict Resolution">
<t>There may be a conflicting situation when different
applications specify difference preference for the same shim
context. For instance, application A and B may establish
communication with the same EID pair while both applications
have different preference in their choice of local locator.
The notion of context forking in SHIM6 can resolve the
conflicting situation.</t>
<!-- conflict among different applications -->
<t>Socket options defined in
<xref target="sec-shim-socket-options"/> may cause conflicting
situation when the target context is shared by multiple
applications. In such a case, the socket handler should
inform the shim sub-layer that context forking is required.
In SHIM6, when a context is forked, an unique identifier
called Forked Instance Identifier (FII) is assigned to the
newly forked context. The forked context is then exclusively
associated with the socket through which non-default
preference value was specified. The forked context is
maintained by the shim sub-layer during the lifetime of
associated socket instance. When the socket is closed, the
shim sub-layer SHOULD delete associated context.</t>
<!-- conflict among SHIM_LOC_*_SEND and SHIM_LOC_*_PREF -->
<t>When the application specifies SHIM_LOC_*_SEND specifying a
different source or destination locator which does not have
the highest priority and weight specified by the
SHIM_LOC_*_PREF, the shim sub-layer SHOULD supersede the
request made by SHIM_LOC_*_SEND over the preference specified
by SHIM_LOC_*_PREF.</t>
<!-- conflict among local and remote -->
<t>When the peer provides preferences of the locators (e.g., a
SHIM6 peer may send a locator with a Locator Preferences
Option) which conflict with preference specified by the
applications either by SHIM_LOC_PEER_SEND or
SHIM_LOC_PEER_PREF, the shim sub-layer SHOULD supersede the
preference made by the application over the preference
specified by the peer.
</t>
</section>
<!--
<section title="Explicit Forking">
<t>There is another approach to support context forking by
multihoming shim API. In this approach, it is assumed that
shim-aware application can make distinction of each shim
context that has the same EID pair and specify which context
to be used for its communication.</t>
<t>Socket option SHIM_TBD1 can be used by application to
request the shim sub-layer to fork a context. If the
context is successfully forked by the shim, the FII assigned
for the forked context is returned to the application. The
application can request the shim sub-layer to apply specific
context to its communication either by socket option or
ancillary data specifying SHIM_TBD2 socket option along with
FII value.</t>
<t>NOTE: If we decide to go with explicit forking, we probably
need to define comprehensive set of socket options that allow
application to specify adaptation of forked context to the
flow over a given socket. It seems to me that there are lots
of things to do to support explicit model.</t>
</section>
-->
<section title="Incompatiblility between IPv4 and IPv6">
<t>The shim sub-layer performs identifier/locator adaptation.
Therefore, in some cases, the whole IP header can be replaced
with new IP header of a different address family
(e.g. conversion from IPv4 to IPv6 or vice versa). Hence,
there is an issue how to make the conversion with minimum
impact. Note that this issue is common in other protocol
conversion techniques
<xref target="RFC2765"/><xref target="I-D.ietf-behave-v6v4-xlate"/>.</t>
<t>As studied in the previous works on protocol
conversion<xref target="RFC2765"/><xref target="I-D.ietf-behave-v6v4-xlate"/>,
some of the features (IPv6 routing headers, hop-by-hop
extension headers, and destination headers) from IPv6 are not
convertible to IPv4. In addition, notion of source routing is
not exactly the same in IPv4 and IPv6. This means that an
error may occur during the conversion of identifier and
locator. It is ffs exactly how the shim sub-layer should
behave in such erroneous cases.</t>
</section>
</section>
<!--
================================================================
IANA Consideration
================================================================
-->
<section title="IANA Considerations" toc="default">
<t>This document contains no IANA consideration.</t>
</section>
<section title="Protocol Constants and Variables" toc="default">
<t>This section defines protocol constants and variables.
<list style="hanging">
<t hangText="SHIM_MAX_LOCATORS">The maximum number of the
locators to be included in a locator list. 32.</t>
</list>
</t>
</section>
<!--
================================================================
Security Consideration
================================================================
-->
<section title="Security Considerations" toc="default">
<t>This section gives security considerations of the API defined
in this document.</t>
<section title="Treatment of Unknown Locator">
<t>When sending IP packets, application may request use of
unknown locator for the source and/or destination locators.
Note that treatment of unknown locator can be a subject of
security considerations because use of invalid source and/or
destination locator may cause redirection attack.</t>
<section title="Treatment of Unknown Source Locator">
<t>The shim sub-layer checks if the requested locator is
available on any of the local interface. If not, the shim
sub-layer MUST reject the request and return an error
message with the EINVALIDLOCATOR code to the application.
If the locator is confirmed to be available, the shim
sub-layer SHOULD initiate the procedure to update the
locator list.</t>
<t>Use of the following socket options and ancillary data
may require treatment of unknown source locator:
<list style="symbols">
<t>SHIM_LOC_LOCAL_SEND</t>
<t>SHIM_LOC_LOCAL_PREF</t>
<t>SHIM_LOCLIST_LOCAL</t>
</list>
</t>
</section>
<section title="Treatment of Unknown Destination Locator">
<t>If the shim sub-layer turns out to be SHIM6, the SHIM6
implementation MUST reject the request for using unknown
destination locator.</t>
<t>If the shim sub-layer turns out to be HIP, the HIP
implementation MAY accept the request for using unknown
destination locator.</t>
<t>Use of the following socket options and ancillary data
may require treatment of unknown destination locator:
<list style="symbols">
<t>SHIM_LOC_PEER_SEND</t>
<t>SHIM_LOC_PEER_PREF</t>
<t>SHIM_LOCLIST_PEER</t>
</list>
</t>
</section>
</section>
</section>
<!--
================================================================
Changes
================================================================
-->
<section title="Changes" toc="default">
<section title="Changes from version 00 to version 01">
<t>
<list style="symbols">
<t>Define shim_locator{} data type which is a placeholder for
locator.</t>
<t>Define shim_pathexplore{} data type in which a set of
REAP parameters are stored.</t>
<t>Remove descriptions about "stickiness" of socket options.</t>
<t>Deprecate SHIM_IF_RECV and SHIM_IF_SEND socket options.</t>
<t>Give default value and how to disable given socket
option.</t>
</list>
</t>
</section>
<section title="Changes from version 01 to version 02">
<t>
<list style="symbols">
<t>Add section describing context forking.</t>
<t>Rephrase conclusion section.</t>
<t>Separate normative references from informative
references.</t>
<t>Remove texts from discussion section that are not
relevant to the contents of the document.</t>
<t>Add section describing change history (this section).</t>
</list>
</t>
</section>
<section title="Changes from version 02 to version 03">
<t>
<list style="symbols">
<t>Add an Appendix section describing the issue of context
forking.</t>
</list>
</t>
</section>
<section title="Changes from version 03 to version 04">
<t>
<list style="symbols">
<t>Updated reference.</t>
<t>Correct typo and grammatical errors.</t>
</list>
</t>
</section>
<section title="Changes from version 04 to version 05">
<t>
<list style="symbols">
<t>Added definition of SHIM_FEEDBACK ancillary data.</t>
<t>Added an example of code using the SHIM_LOCLIST_LOCAL</t>
<t>Added SHIM_LOC_LOCAL_SEND and SHIM_LOC_PEER_SEND socket
options.</t>
</list>
</t>
</section>
<section title="Changes from version 05 to version 06">
<t>
<list style="symbols">
<t>Updated references.</t>
</list>
</t>
</section>
<section title="Changes from version 06 to version 07">
<t>
<list style="symbols">
<t>Resolved editorial issues.</t>
</list>
</t>
</section>
<section title="Changes from version 07 to version 08">
<t>No changes are made except for updates of the references.</t>
</section>
<section title="Changes from version 08 to version 09">
<t>
<list style="symbols">
<t>Updated texts for Section 1 and Section 5 according to
the comments provided by Samu Varjonen.</t>
<t>Made it clear that downgrading the multihoming shim
support (i.e., specifying value 1 with the SHIM_DONTSHIM
socket option) is only allowed before the socket is
connected.</t>
<t>Updated locator information (shim_locator{}) so that
it can contain a locator behind NAT.</t>
</list>
</t>
</section>
<section title="Changes from version 09 to version 10">
<t>
<list style="symbols">
<t>Addressed applicability of socket options and ancillary
data for the shim sub-layer.</t>
<t>Addressed system requirements.</t>
<t>Removed unnecessary description about deprecated socket
option (SHIM_IF_RECV).</t>
</list>
</t>
</section>
<section title="Changes from version 10 to version 11">
<t>
<list style="symbols">
<t>Added short descriptions about connected sockets and unconnected sockets.</t>
<t>Relaxed applicability of the socket options.</t>
<t>Relaxed applicability of the ancillary data.</t>
<t>Added notification about locator change.</t>
</list>
</t>
</section>
<section title="Changes from version 11 to version 12">
<t>
<list style="symbols">
<t>Reflected comments from Brian Karpenter.</t>
<t>Reflected comments from Michael Scharf.</t>
</list>
</t>
</section>
<section title="Changes from version 12 to version 13">
<t>
<list style="symbols">
<t>Reflected comments from Sebastien Barre.</t>
<t>Removed the description about the notification from the
shim sub-layer to applications.</t>
<t>Narrowed down the scope of the applicability of the
socket options and the ancillary data.</t>
</list>
</t>
</section>
</section>
<!--
================================================================
Acknowledgment
================================================================
-->
<section title ="Acknowledgments" toc="include">
<t>Authors would like to thank Jari Arkko who participated in
the discussion that lead to the first version of this document,
and Tatuya Jinmei who thoroughly reviewed the early version of
this draft and provided detailed comments on sockets API related
issues. Thomas Henderson provided valuable comments especially
from HIP perspectives.</t>
<t>Authors sincerely thank to the following people for their
helpful comments to the document: Samu Varjonen, Dmitriy
Kuptsov, Brian Carpenter, Michael Scharf, and Sebastien
Barre</t>
</section>
</middle>
<back>
<!--
================================================================
References
================================================================
-->
<references title="Normative References">
<reference anchor='RFC5533'>
<front>
<title>Level 3 multihoming shim protocol</title>
<author initials='M' surname='Bagnulo' fullname='Marcelo Bagnulo'>
<organization />
</author>
<author initials='E' surname='Nordmark' fullname='Erik Nordmark'>
<organization />
</author>
<date month='June' year='2009' />
</front>
<seriesInfo name='RFC' value='5533' />
<format type='TXT'
target='http://tools.ietf.org/rfc/rfc5533.txt' />
</reference>
<reference anchor='RFC4423'>
<front>
<title>Host Identity Protocol (HIP) Architecture</title>
<author initials='R.' surname='Moskowitz' fullname='R. Moskowitz'>
<organization /></author>
<author initials='P.' surname='Nikander' fullname='P. Nikander'>
<organization /></author>
<date year='2006' month='May' />
</front>
<seriesInfo name='RFC' value='4423' />
<format type='TXT' octets='61049' target='ftp://ftp.isi.edu/in-notes/rfc4423.txt' />
</reference>
<!--
<reference anchor='RFC3493'>
<front>
<title>Basic Socket Interface Extensions for IPv6</title>
<author initials='R.' surname='Gilligan' fullname='R. Gilligan'>
<organization /></author>
<author initials='S.' surname='Thomson' fullname='S. Thomson'>
<organization /></author>
<author initials='J.' surname='Bound' fullname='J. Bound'>
<organization /></author>
<author initials='J.' surname='McCann' fullname='J. McCann'>
<organization /></author>
<author initials='W.' surname='Stevens' fullname='W. Stevens'>
<organization /></author>
<date year='2003' month='February' /></front>
<seriesInfo name='RFC' value='3493' />
<format type='TXT' octets='82570'
target='ftp://ftp.isi.edu/in-notes/rfc3493.txt' />
</reference>
-->
<reference anchor='RFC3542'>
<front>
<title>Advanced Sockets Application Program Interface (API)
for IPv6</title>
<author initials='W.' surname='Stevens' fullname='W. Stevens'>
<organization /></author>
<author initials='M.' surname='Thomas' fullname='M. Thomas'>
<organization /></author>
<author initials='E.' surname='Nordmark' fullname='E. Nordmark'>
<organization /></author>
<author initials='T.' surname='Jinmei' fullname='T. Jinmei'>
<organization /></author>
<date year='2003' month='May' /></front>
<seriesInfo name='RFC' value='3542' />
<format type='TXT' octets='173028'
target='ftp://ftp.isi.edu/in-notes/rfc3542.txt' />
</reference>
<reference anchor='RFC5534'>
<front>
<title>Failure Detection and Locator Pair Exploration
Protocol for IPv6 Multihoming</title>
<author initials='J' surname='Arkko' fullname='Jari Arkko'>
<organization />
</author>
<author initials='I' surname='Beijnum' fullname='Iljitsch van Beijnum'>
<organization />
</author>
<date month='June' year='2009' />
</front>
<seriesInfo name='RFC' value='5534' />
<format type='TXT'
target='http://tools.ietf.org/rfc/rfc5534.txt' />
</reference>
<reference anchor='POSIX'>
<front>
<title>IEEE Std. 1003.1-2001 Standard for Information
Technology -- Portable Operating System Interface
(POSIX). Open group Technical Standard: Base Specifications,
Issue 6, http://www.opengroup.org/austin</title>
<author initials='' surname=''
fullname='IEEE Standard'>
<organization />
</author>
<date month='December' day='1' year='2001' />
</front>
<format type='TXT'
target='http://www.opengroup.org/austin' />
</reference>
<!--
<reference anchor='I-D.henderson-hip-applications'>
<front>
<title>Using HIP with Legacy Applications</title>
<author initials='T' surname='Henderson' fullname='Tom Henderson'>
<organization />
</author>
<author initials='P' surname='Nikander' fullname='Pekka Nikander'>
<organization />
</author>
<date month='May' day='17' year='2006' />
</front>
<seriesInfo name='Internet-Draft'
value='draft-henderson-hip-applications-03' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-henderson-hip-applications-03.txt' />
</reference>
-->
</references>
<references title="Informative References">
<reference anchor='I-D.ietf-shim6-applicability'>
<front>
<title>Applicability Statement for the Level 3 Multihoming
Shim Protocol (Shim6)</title>
<author initials='J' surname='Abley' fullname='Joe Abley'>
<organization />
</author>
<author initials='M' surname='Bagnulo' fullname='Marcelo Bagnulo'>
<organization />
</author>
<author initials='A' surname='Garcia-Martinez' fullname='Alberto Garcia Martinez'>
<organization />
</author>
<date month='November' day='30' year='2009' />
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-shim6-applicability-04' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ietf-shim6-applicability-04.txt' />
</reference>
<reference anchor='I-D.ietf-shim6-app-refer'>
<front>
<title>Shim6 Application Referral Issues</title>
<author initials='E' surname='Nordmark' fullname='Erik Nordmark'>
<organization />
</author>
<date month='July' day='5' year='2005' />
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-shim6-app-refer-00' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ietf-shim6-app-refer-00.txt' />
</reference>
<!--
<reference anchor='I-D.nordmark-shim6-esd'>
<front>
<title>Extended Shim6 Design for ID/loc split and Traffic
Engineering</title>
<author initials='E' surname='Nordmark' fullname='Erik Nordmark'>
<organization />
</author>
<date month='February' day='26' year='2006'/>
</front>
<seriesInfo name='Internet-Draft' value='draft-nordmark-shim6-esd-00' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-nordmark-shim6-esd-00.txt' />
</reference>
-->
<reference anchor='RFC3972'>
<front>
<title>Cryptographically Generated Addresses (CGA)</title>
<author initials='T.' surname='Aura' fullname='T. Aura'>
<organization /></author>
<date year='2005' day='11' month='March' /></front>
<seriesInfo name='RFC' value='3972' />
<format type='TXT' octets='51473'
target='ftp://ftp.isi.edu/in-notes/rfc3972.txt' />
</reference>
<reference anchor='RFC5535'>
<front>
<title>Hash Based Addresses (HBA)</title>
<author initials='M' surname='Bagnulo' fullname='Marcelo Bagnulo'>
<organization />
</author>
<date month='June' year='2009' />
</front>
<seriesInfo name='RFC' value='5535' />
<format type='TXT'
target='http://tools.ietf.org/rfc/rfc5535.txt' />
</reference>
<reference anchor='RFC2765'>
<front>
<title abbrev='SIIT'>Stateless IP/ICMP Translation Algorithm (SIIT)</title>
<author initials='E.' surname='Nordmark' fullname='Erik Nordmark'>
<organization /></author>
<date year='2000' month='February' />
</front>
<seriesInfo name='RFC' value='2765' />
<format type='TXT' octets='59465' target='ftp://ftp.isi.edu/in-notes/rfc2765.txt' />
</reference>
<reference anchor='I-D.ietf-behave-v6v4-xlate'>
<front>
<title>IP/ICMP Translation Algorithm</title>
<author initials='X' surname='Li' fullname='Xing Li'>
<organization />
</author>
<author initials='C' surname='Bao' fullname='Congxiao Bao'>
<organization />
</author>
<author initials='F' surname='Baker' fullname='Fred Baker'>
<organization />
</author>
<date month='December' day='17' year='2009' />
</front>
<seriesInfo name='Internet-Draft' value='draft-ietf-behave-v6v4-xlate-05' />
<format type='TXT'
target='http://www.ietf.org/internet-drafts/draft-ietf-behave-v6v4-xlate-05.txt' />
</reference>
<reference anchor="RFC4291">
<front>
<title>IP Version 6 Addressing Architecture</title>
<author initials='R.' surname='Hinden' fullname='R. Hinden'>
<organization /></author>
<author initials='S.' surname='Deering' fullname='S. Deering'>
<organization /></author>
<date year='2006' month='February' />
</front>
<seriesInfo name='RFC' value='4291' />
<format type='TXT' octets='52897'
target='ftp://ftp.isi.edu/in-notes/rfc4291.txt' />
</reference>
<reference anchor="I-D.ietf-hip-nat-traversal">
<front>
<title>Basic HIP Extensions for Traversal of Network Address
Translators</title>
<author initials='M' surname='Komu' fullname='Miika Komu'>
<organization /></author>
<author initials='T' surname='Henderson' fullname='Thomas Henderson'>
<organization /></author>
<author initials='H' surname='Tschofenig' fullname='Hannes Tschofenig'>
<organization /></author>
<author initials='J' surname='Melen' fullname='Jan Melen'>
<organization /></author>
<author initials='A' surname='Keranen' fullname='Ari Keranen'>
<organization /></author>
<date year='2009' month='October' />
</front>
<seriesInfo name='Internet Draft'
value='draft-ietf-hip-nat-traversal-09' />
<format type='TXT'
target='http://tools.ietf.org/html/draft-ietf-hip-nat-traversal-09'/>
</reference>
<reference anchor='RFC2782'>
<front>
<title abbrev='DNS SRV RR'>A DNS RR for specifying the location of services (DNS SRV)</title>
<author initials='A.' surname='Gulbrandsen' fullname='Arnt Gulbrandsen'>
<organization>Troll Tech</organization>
</author>
<author initials='P.' surname='Vixie' fullname='Paul Vixie'>
<organization>Internet Software Consortium</organization>
</author>
<author initials='L.' surname='Esibov' fullname='Levon Esibov'>
<organization>Microsoft Corporation</organization>
</author>
<date year='2000' month='February' />
</front>
<seriesInfo name='RFC' value='2782' />
<format type='TXT' octets='24013' target='ftp://ftp.isi.edu/in-notes/rfc2782.txt' />
</reference>
</references>
<!--
<section title="Issues with a Context Shared by Applications">
<t>A context is by definition, system-wide. This means that a
context could be shared by applications whose communications
are using the same EID pair.</t>
<t>When a context is shared by applications, there may be some
problems when the shim sub-layer needs to handle feedbacks from
the multiple applications. As mentioned in <xref
target="sec-access-to-locinfo"/>, an application may provide
the shim sub-layer feedback about timeout values from its own
settings. This implies that there is potentially a race
condition at the shim sub-layer.</t>
<t>First of all, the socket options must be used with a proper
privilege. Feedback from the application which is run under a
root privilege must always override the feedback provided by
application which is run under normal user privilege.</t>
<t>For other cases, one could rely on a kind of heuristics of
the configuration. For instance, prioritizing feedback with
higher demand (e.g. timeout value 300 seconds are more
demanding then timeout value 600 seconds) may make sense in
some cases. However, it is still an open issue what kind of
timer value could be handled in this way.</t>
<t>Further discussions are needed how the shim sub-layer can
accommodate feedbacks from multiple applications within a same
context.</t>
</section>
-->
<!--
<section title="Issues with Shim Unaware Application">
<t>In multihomed environment where either of the peers or
both of the peers have multiple locators, there are some
issues with shim unaware application which uses legacy
socket API.</t>
<section title="Initial Contact with Multiple Locator Pairs">
<t>In a connection oriented communication, the connect()
system call is used to make the initial contact to the
peer, which typically requires IP address and port number
to specify the endpoint. Hence, name-to-address
resolution should be performed prior to connect(). The
application needs to resolve the FQDN of the peer to an IP
address by any available name-to-address conversion
method.</t>
<t>In typical case, the application receives information
from the resolver. If the application ends up with
receiving multiple IP addresses to reach the peer, it
should iterate through each destination address
one-by-one. It should be noted that the host may also
have multiple source addresses.</t>
<t>The different resulting address pairs may have
different reachability status so, in order to find a
working address pair, it may be required to explore all
the available address pairs (as opposed to explore all
available destination addresses).</t>
<t>In normal case, the application issues a connect() by
specifying the resolved IP address of the peer. If the
connect() fails, it iterates through the available IP
addresses one by one sequentially until working pair is
found. Another approach is to initiate concurrent
connect() with every locator of the peer. connect() can
also be called in a sequence which would probably require
more time to find the working pair.</t>
<t>There is a case where involvement of the shim sub-layer
is expected for handling initial contact. In such case,
behavior of the shim sub-layer will depend on presence of
the required context. This case occurs when there exists
a context for the EID specified in connect(), the initial
contact can be made in accordance with the context
information. Otherwise, the shim sub-layer should invoke
context establishment with the peer EID specified in the
argument for connect().</t>
<t>Additional efforts would be required in a case where
the peer cannot be reachable through the EID (for example,
EID is non-routable or non-IP reachable) but it can be
reached through alternative locator. In particular, the
shim sub-layer should somehow discover the alternate
locator for the EID to establish context.
<xref target="I-D.nordmark-shim6-esd"/> addresses the
possible approach to perform reverse DNS lookup from EID
to FQDN, then perform forward lookup again to find the
full-set of locators and EID.</t>
<t>In HIP, resolving HITs to IP addresses using DNS is not
feasible because HITs do not contain any hierarchical
information. To mitigate this problem, there are a few
alternatives. Firstly, resolver library on end-host can
be modified to provide HIT-to-IP mappings for HIP software
module. Secondly, a distributed hash table (DHT) service
can be used for storing and looking up the mappings
because it supports non-hierarchical identifiers, such as
HITs <xref target="RFC4423"/>. Thirdly, it is possible to
use IP addresses in legacy applications as described in
<xref target="I-D.henderson-hip-applications"/>.</t>
</section>
-->
<section title="Context Forking">
<t>In this section, an issue concerning context forking and
its relation to the multihoming shim API are discussed.</t>
<t>SHIM6 supports a notion of context forking. A peer may
decide to fork a context for certain reason (e.g. upper layer
protocol prefers to use different locator pair than the one
defined in available context). The procedure of forking
context is done similar to the normal context establishment,
performing the 4-way message exchange. A peer who has decided
to fork a context initiates the context establishment.
Hereafter, we call this peer the "initiator". The peer of the
initiator is called the "responder".</t>
<t>Once the forked context is established between the peers,
on the initiator side, it is possible to apply forked context
to the packet flow since the system maintains an association
between the forked context and the socket owned by the
application that has requested the context forking. How this
association is maintained is an implementation specific issue.
However, on the responder side, there is a question how the
outbound packet can be multiplexed by the shim sub-layer
because there are more than one SHIM6 contexts that match with
the ULID pair of the packet flow. There is a need to
differentiate packet flows not only by the ULID pairs but by
some other information and associate a given packet flow with
a specific context.</t>
<t><xref target="fig-context-forking"/> gives an example of a
scenario where two communicating peers fork a context.
Initially, there has been a single transaction between the
peers, by the application 1 (App1). Accordingly, another
transaction is started, by application 2 (App2). Both of the
transactions are made based on the same ULID pair. The first
context pair (Ctx1) is established for the transaction of
App1. Given the requests from App2, the shim sub-layer on
Peer 1 decides to fork a context. Accordingly, a forked
context (Ctx2) is established between the peers, which should
be exclusively applied to the transaction of App2. Ideally,
multiplexing and demultiplexing of packet flows that relate to
App1 and App2 should be done as illustrated in
<xref target="fig-context-forking"/>. However, as mentioned
earlier, the responder needs to multiplex outbound flows of
App1 and App2 somehow. Note that if a context forking occurs
on the initiator side, a context forking needs to occur also
on the responder side.
<figure anchor="fig-context-forking" title="context forking">
<artwork><![CDATA[
Peer 1 Peer 2
(initiator) (responder)
+----+ +----+ +----+ +----+
|App1| |App2| |App1| |App2|
+----+ +----+ +----+ +----+
|^ |^ ^| ^|
v| v| |v |v
-----S1-------------S2----- -----S1-------------S2-----
|| || || ||
|| || || ||
Ctx1 Ctx2 Ctx1 Ctx2
ULID:<A1,B1> ULID:<A1,B1> ULID:<B1,A1> ULID:<B1,A1>
Loc: <A1,B2> Loc: <A1,B3> Loc: <B2,A1> Loc: <B3,A1>
FII: 0 FII: 100 FII: 0 FII: 100
|^ |^ ^| ^|
|| || || ||
|| || || ||
\..............||....................../| ||
\.............||......................./ ||
|| ||
\|...................................../|
\....................................../
]]></artwork>
</figure>
</t>
<t>Any solution is needed to overcome the problem mentioned
above.</t>
<!--
<t>One viable approach is to let the system implicitly
maintain an association between the socket and the associated
context by keeping the record of inbound packet processing.
That is, the system stores the information about the context
on which the inbound packet flow was demultiplexed. The
information comprises the ULID pair and FII of the context and
is stored in the socket instance. Later, the system can use
the information to identify the associated context in outbound
packet processing. This approach should be feasible as far as
there is bi-directional user traffic.</t>
<t>Another viable approach is to extend SHIM6 protocol by
adding capability of exchanging additional information to
identify the packet flow from others which needs to be handled
by a newly forked context. The information exchange can be
done during the context establishment. The initiator appends
5 tuple of the packet flow to be handled by the newly forked
context. Note that the additional information provided by the
5 tuple are source and destination port numbers and upper
layer protocol. The information is later used by the shim
sub-layer to multiplex the outbound packet flow on the
responder side.</t>
<t>The socket options for multihoming shim can be used by the
application to trigger the context forking in implicit manner.
The peer becomes an initiator in the establishment of the
forked context. Once the forked context is established
between the peers, application on each end can influence the
preference on context by utilizing the multihoming shim
API.</t>
-->
</section>
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 10:10:27 |