One document matched: draft-ietf-hip-native-api-05.xml
<?xml version="1.0"?>
<?xml-stylesheet type="text/xsl" href="rfc2629.xslt" ?>
<!DOCTYPE rfc SYSTEM "rfc2629.dtd">
<?rfc strict="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>
<?rfc tocompact="no"?>
<?rfc toc="yes" ?>
<?rfc tocdepth="6"?>
<?rfc sortrefs="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc comments="yes" ?>
<!--<?rfc editing="yes" ?>-->
<rfc category="exp" ipr="noModification3978" docName="draft-ietf-hip-native-api-05">
<front>
<title abbrev="Basic API Extensions for HIP">Basic Socket Interface Extensions for Host Identity Protocol (HIP)</title>
<author fullname="Miika Komu" initials="M.K.T." surname="Komu">
<organization>Helsinki Institute for Information Technology</organization>
<address>
<postal>
<street>Metsänneidonkuja 4</street>
<city>Helsinki</city>
<country>Finland</country>
</postal>
<phone>+358503841531</phone>
<facsimile>+35896949768</facsimile>
<email>miika@iki.fi</email>
<uri>http://www.iki.fi/miika/</uri>
</address>
</author>
<author fullname="Thomas Henderson" surname="Henderson">
<organization>The Boeing Company</organization>
<address>
<postal>
<street>P.O. Box 3707</street>
<city>Seattle, WA</city>
<country>USA</country>
</postal>
<email>thomas.r.henderson@boeing.com</email>
</address>
</author>
<date year="2008"/>
<area>Internet Area</area>
<workgroup>Host Identity Protocol</workgroup>
<abstract>
<t>This document defines extensions to the current sockets API for
Host Identity Protocol (HIP). The extensions focus on the use of
public-key based identifiers discovered via DNS resolution, but
define also interfaces for manual bindings between HITs and
locators. With the extensions, the application can also support
more relaxed security models where the communication can be
non-HIP based, according to local policies. The extensions in
document are experimental and provide basic tools for
futher experimentation with policies.</t>
</abstract>
<!--
<note title="Requirements Language">
<t>The key words "MUST", "MUST NOT",
"REQUIRED", "SHALL", "SHALL NOT",
"SHOULD", "SHOULD NOT", "RECOMMENDED",
"MAY", and "OPTIONAL" in this document are to be
interpreted as described in <xref target="RFC2119">RFC 2119</xref>.
</t>
</note>
-->
</front>
<middle>
<section anchor="sec:intro" title="Introduction">
<t>
This document defines C-based sockets Application Programming
Interface (API) extensions for handling HIP-based identifiers
explicitly in HIP-aware applications. It is up to the applications, or
high-level programming languages or libraries, to manage the
identifiers. The extensions in this document are mainly related to the
use case in which a DNS resolution step has occurred prior to the
creation of a new socket, and assumes that the system has cached
or is otherwise able to resolve identifiers to locators (IP addresses).
The DNS extensions for HIP are described in <xref
target="RFC5205" />.
The extensions also cover the case in which an application may want
to explicitly provide suggested locators with the identifiers, including
supporting the opportunistic case in which the system does not know
the peer host identity.
</t>
<t>The Host Identity Protocol (HIP) <xref target="RFC4423" /> proposes
a new cryptographic namespace by separating the roles of end-point
identifiers and locators by introducing a new namespace to the
TCP/IP stack. SHIM6 <xref target="I-D.ietf-shim6-proto" /> is another
protocol based on identity-locator split.
Note that the APIs specified in this document are specific to HIP. However,
the APIs here have been designed as much as possible so
as not to preclude its use with other protocols. The use of these APIs with
other protocols is, nevertheless, for further study.
</t>
<t>
Applications can observe the HIP layer and its identifiers in the
networking stacks with varying degrees of visibility. <xref
target="I-D.ietf-hip-applications" /> discusses the lowest levels
of visibility in which applications are completely unaware of
the underlying HIP layer. Such HIP-unaware applications in some circumstances use HIP-based
identifiers, such as LSIs or HITs, instead of IPv4 or IPv6 addresses
and cannot observe the identifier-locator bindings.
</t>
<t>
This document specifies extensions to <xref target="RFC3493" /> to
define a new socket address family, AF_HIP. The macro AF_HIP is used
as an alias for PF_HIP in this document because the distinction
between AF and PF has been lost in practice. The extensions also
describe a new socket address structure for sockets using Host
Identity Tags (HITs) explicitly and describe how the socket calls
in <xref target="RFC3493" /> are adapted or extended as a result.
</t>
<t>Some applications may accept incoming communications from any
identifier. Other applications may initiate outgoing communications
without the knowledge of the peer identifier in Opportunistic Mode <xref
target="RFC5201" /> by just relying on a peer locator. This
document describes how to address both situations using "wildcards"
as described later in this document.
</t>
<t>There are two related API documents. Multihoming and explicit
locator-handling related APIs are defined in <xref
target="I-D.ietf-shim6-multihome-shim-api" />. IPsec related policy
attributes and channel bindings APIs are defined in <xref
target="I-D.ietf-btns-c-api" />. Most of the extensions defined in this
document can be used independently of the two mentioned related API
documents.
</t>
<t>
The identity-locator split introduced by HIP introduces some policy
related challenges with datagram oriented sockets, opportunistic mode,
and manual bindings between HITs and locators. The extensions in this
document are of experimental nature and provide basic tools for
experimenting with policies. Policy related issues are left for
further experimentation.
</t>
<t>
To recap, the extensions in this document have three goals. The first goal
is to allow HIP-aware applications to open sockets to other hosts based on
the HITs alone, presuming that the underlying system can resolve the HITs
to addresses used for initial contact. The second
goal is that applications can explicitly initiate communications
with unknown peer identifiers. The third goal is to define how HIP-aware
applications may provide suggested initial contact addresses along
with the HITs.
</t>
</section> <!-- intro -->
<section anchor="sec:terminology" title="Terminology">
<t>The terms used in this document are summarized in <xref
target="tbl:terms" />.</t>
<!-- XX FIXME: REMOVE REFERENCE TO BTNS DRAFT ?? -->
<texttable anchor="tbl:terms">
<ttcol align="left">Term</ttcol><ttcol align="left">Explanation</ttcol>
<!--
<c>ULID</c>
<c>Upper Layer IDentifier equals to the identity part of the
identity-locator split. It is the identifier used by the
application to name a peer for the transport layer.</c>
-->
<c>HIP</c><c>Host Identity Protocol</c>
<!--
<c>FQDN</c>
<c>Fully Qualified Domain Name</c>
-->
<c>HIT</c>
<c>Host Identity Tag, a 100-bit hash of a public key with a 28 bit prefix</c>
<c>LSI</c><c>Local Scope Identifier, a local, 32-bit descriptor for a given
public key.</c>
<c>Locator</c>
<c>Routable IPv4 or IPv6 address used at the lower layers</c>
</texttable>
</section> <!-- terminology -->
<!--
<section anchor="sec:architecture" title="Design Model">
<t>In this section, the native HIP APIs is described from a
design point of view. We first describe the namespace
model and conclude the discussion with a description of the
resolver model.</t>
-->
<!--
<section anchor="sec:layering" title="Layering Model">
<t>The application layer accesses the transport layer via the socket
5~ interface. The application layer uses the traditional TCP/IP IPv4 or
IPv6 interface, or the new native HIP APIs interface provided by the
socket layer. The layering model is illustrated in <xref
target="fig:layering" />. For simplicity, the IPsec layer has been
excluded from the figure.</t>
<figure anchor="fig:layering">
<artwork>
+--------------------------------+
Application Layer | Application |
+----------+----------+----------+
Socket Layer | IPv4 API | IPv6 API | HIP API |
+----------+----+-----+----------+
Transport Layer | TCP | UDP |
+---------------+----------------+
HIP Layer | HIP |
+---------------+----------------+
Network Layer | IPv4 | IPv6 |
+---------------+----------------+
Link Layer | Ethernet | Etc |
+---------------+----------------+
</artwork>
</figure>
<t>The HIP layer is as a shim/wedge layer between the transport and
network layers. The datagrams delivered between the transport and
network layers are intercepted by the system for
transformation from from identifiers to locators or vice
versa.</t>
</section>
<section anchor="sec:namespace" title="Namespace Model">
<t>The namespace model is shown in <xref target="tbl:identifiers" /> from
HIP point of view. The namespace identifiers are described in this
section.</t>
<texttable anchor="tbl:identifiers">
<ttcol align="left">Layer</ttcol><ttcol align="left">Identifier</ttcol>
<c>User Interface</c> <c>Relative hostname or FQDN</c>
<c>Application Layer</c> <c>HIT, port and protocol</c>
<c>Transport Layer</c> <c>HIT, port</c>
<c>HIP Layer</c> <c>HIT or HI</c>
<c>Network Layer</c> <c>Locator</c>
</texttable>
<t>User interfaces input human-readable names and translate them
to machine-readable names. In native APIs for HIP, the machine
readable names are HITs. The HITs are present at the application
layer, and transport-layer pseudo checksums are based on HITs.
The HIP layer transforms the HITs to locators for the network layer
and vice versa.
</t>
</section>
-->
<section anchor="sec:api_overview" title="API Overview">
<t>This section provides an overview of how the API can be used. First,
the case in which a resolver is involved in name resolution is
described, and then the case in which no resolver is involved
is described.
</t>
<section anchor="sec:resolver" title="Interaction with the Resolver">
<t>Before an application can establish network communications with
the entity named by a given FQDN or relative host name, the
application must translate the name into the corresponding
identifier(s). DNS-based hostname-to-identifier translation is
illustrated in <xref target="fig:resolver_path" />. The
application calls the resolver in step a to resolve an FQDN
step b. The DNS server responds with a list of HITs and a
set of locators step c. Optionally in step d, the
resolver caches the HIT to locator mapping to the HIP
module. The resolver returns the HITs to the application
step e. Finally, the application selects one HIT and uses it in
a socket call such as connect() in step f.
</t>
<figure anchor="fig:resolver_path">
<artwork><![CDATA[
+----------+
| |
| DNS |
| |
+----------+
^ |
b. <FQDN> | | c. <HITs+locators
| v = HITs+locs>
+-------------+ a. getaddrinfo(<FQDN>) +----------+
| |------------------------>| |
| Application | | Resolver |
| |<------------------------| |
+-------------+ e. <HITs> +----------+
| |
| |
| f. connect(<HIT>) | d. <HITs+locs>
v v
+----------+ +----------+
| | | |
| TCP/IP | | HIP |
| Stack | | |
+----------+ +----------+
]]></artwork>
</figure>
<t>
In practice, the resolver functionality can be implemented in different
ways. For example, it may be implemented in existing resolver
libraries or as a DNS proxy.
</t>
<!-- </section> -->
</section> <!-- design model -->
<section anchor="sec:no-resolver" title="Interaction without a Resolver">
<t>
The extensions in this document focus on the use of the resolver to
map host names to HITs and locators in HIP-aware applications. The
resolver associates implicitly the HIT with the
locator(s) by e.g. communicating the HIT-to-IP mapping to the HIP daemon.
However, it is possible that an application operates
directly on a peer HIT without interacting with the resolver. In
such a case, the application may resort to the system to map the peer
HIT to an IP address. Alternatively, the application can explicitly
map the HIT to an IP address using socket options as specified in <xref
target="I-D.ietf-shim6-multihome-shim-api" />. Full support for all of
the extensions defined in this draft requires shim socket options
to be implemented by the system.
</t>
</section>
</section> <!-- Overview -->
<section anchor="sec:syntax" title="API Syntax and Semantics">
<t>In this section, we describe the native HIP APIs using the
syntax of the C programming language. We limit the description
to the interfaces and data structures that are either modified
or completely new, because the native HIP APIs are otherwise
identical to the sockets API <xref target="POSIX" />.
</t>
<section anchor="sec:sock" title="Socket Family and Address Structure Extensions">
<t>The sockets API extensions define a new protocol family, PF_HIP, and
a new address family, AF_HIP. The AF_HIP and PF_HIP are aliases to
each other. These definition shall be defined as a result of including
<sys/socket.h>.</t>
<t>The use of the PF_HIP constant is mandatory with the socket()
function when an application uses the native HIP APIs. The
application gives the PF_HIP constant as the first argument (domain)
to the socket() function. The system returns a positive integer
representing a socket descriptor when the system supports HIP.
Otherwise, the system returns -1 and sets errno to EAFNOSUPPORT.</t>
<t><xref target="fig:sockaddr_hip"/> shows socket address
structure for HIP.</t>
<figure anchor="fig:sockaddr_hip">
<artwork>
#include <netinet/in.h>
typedef struct in6_addr hip_hit_t;
struct sockaddr_hip {
sa_family_t ship_family;
in_port_t ship_port;
uint32_t ship_pad;
uint64_t ship_flags;
hip_hit_t ship_hit;
uint8_t ship_reserved[16];
};
</artwork>
</figure>
<t><xref target="fig:sockaddr_hip" /> is in in 4.3BSD format. The family of the socket, ship_family, is
set to AF_HIP. The port number ship_port is two octets in network byte
order. and the ship_hit is 16 octets in network byte order.
An implementation may have extra member(s) in this structure.</t>
<t>
The application usually sets the ship_hit field using the
resolver. However, the application can use three special
wildcard macros to set a value directly into the ship_hit
field. The macros are HIP_HIT_ANY, HIP_HIT_ANY_PUB,
HIP_HIT_ANY_TMP and HIP_ADDR_ANY. The first three equal to a
HIT value associated with a wildcard HIT of any, public, or
anonymous type. The fourth macro, HIP_ADDR_ANY, denotes both
HIP_HIT_ANY or any IPv4 or IPv6 address. The HIP_HIT_ANY equals to
HIP_HIT_ANY_PUB or HIP_HIT_ANY_TMP. The anonymous identifiers
refer to the use anonymous identifiers as specified in <xref
target="RFC4423" />. The system may designate anonymous
identifiers as meta data associated with a HIT depending on
whether it has been published or not. However,
there is no difference in the classes of HITs
from the HIP protocol perspective,
</t>
<t>The application can use the HIP_HIT_ANY_* and HIP_ADDR_ANY
macros to accept incoming communications to all of the HITs of
the local host. Incoming communications refers here to the
functions such as bind(), recvfrom() and recvmsg(). The
HIP_HIT_* macros are similar to the sockets API macros
INADDR_ANY and IN6ADDR_ANY_INIT, but they are applicable to HITs only.
After initial contact with the peer, the
application can discover the local and peer HITs
using getsockname() and getpeername() calls in the context of
connection oriented sockets. The difference between the use of
the HIP_HIT_* and HIP_ADDR_ANY macros here is that the former
allows only HIP-based communications but the latter also
allows communications without HIP.
</t>
<t>The application also uses the HIP_HIT_ANY macro in ship_hit
field to establish outgoing communications in Opportunistic
mode <xref target="RFC5201" />, i.e., when the
application knows the remote peer locator but not the
HIT. Outgoing communications refers here to the use of
functions such as connect(), sendto() and sendmsg(). However,
the application must first associate the socket with at least
one IP address of the peer using SHIM_LOCLIST_PEER_PREF socket
option.
</t>
<t>The use of HIP_ADDR_ANY macro in the context of outgoing
communications is left for further experimentation. It could
be used for establishing a non-HIP based connectivity when HIP-based
connectivity was unsuccessful.
</t>
<t>Some applications rely on system level access control, either
implicit or explicit (such as accept_filter() function found on
BSD-based systems), but such discussion is out of scope.
Other applications implement access control
themselves by using the HITs. In such a case, the application
can compare two HITs using memcmp() or similar function. It
should be noticed that different connection attempts between
the same two hosts can result in different HITs because a host
is allowed to have multiple HITs.
</t>
</section> <!-- socket -->
<section anchor="sec:getaddrinfo" title="Extensions to Resolver Data Structures">
<t>The HIP APIs introduce a new addrinfo flag,
HIP_PREFER_ORCHID, to be used by application to query for
both HIT and locator information via the getaddrinfo()
resolver function <xref target="RFC3493" />. The
getaddrinfo() function uses a data structure used for both
input to and output from the resolver. The data structure is
illustrated in <xref target="fig:addrinfo" />.
</t>
<figure anchor="fig:addrinfo">
<artwork>
#include <netdb.h>
struct addrinfo {
int ai_flags; /* e.g. AI_EXTFLAGS */
int ai_family; /* e.g. AF_HIP */
int ai_socktype; /* e.g. SOCK_STREAM */
int ai_protocol; /* 0 or IPPROTO_HIP */
socklen_t ai_addrlen; /* size of *ai_addr */
struct sockaddr *ai_addr; /* sockaddr_hip */
char *ai_canonname; /* canon. name of the host */
struct addrinfo *ai_next; /* next endpoint */
int ai_eflags; /* RFC5014 extension */
};
</artwork>
</figure>
<t>Application must set both the flag AI_EXTFLAGS <xref
target="RFC5014" /> in ai_flags and HIP_PREFER_ORCHID in the
ai_eflags, or otherwise the resolver does not return
sockaddr_hip data structures. The resolver returns
EAI_BADFLAGS when it does not support HIP_PREFER_ORCHID or
AI_EXTFLAGS flags.
</t>
<t>
Application denotes its preference for public and anonymous
types of HITs using HIP_PREFER_SRC_PUBLIC and
HIP_PREFER_SRC_TMP flags in the ai_eflags field. If the
application sets neither of the flags, the resolver returns
both public and anonymous HITs.
</t>
<t>The simultaneous use of both HIP_PREFER_ORCHID and
HIP_PREFER_PASSIVE_* flags produces a single sockaddr_hip
structure containing a wildcard address that the application
can use either for incoming (node argument is NULL in
getaddrinfo) or outgoing communications (node argument is
non-NULL). For example, HIP_PREFER_PASSIVE_HIT_TMP flag
produces one sockaddr_hip structure that contains a
HIP_HIT_ANY_TMP in the ship_hit field.</t>
<t>The resolver sets the ai_family field to AF_HIP in the addrinfo structure
when ai_addr points to a sockaddr_hip structure.</t>
<t>
When ai_protocol field is set to zero, the resolver also
returns locators in sockaddr_in and sockaddr_in6 structures
in addition to sockaddr_hip structures. The resolver returns
only sockaddr_hip structures when the application has set the
ai_protocol field to IPPROTO_HIP or a sockaddr_hip structure is
given as the hint argument to the resolver.
</t>
<section anchor="sec:resolver_usage" title="Resolver Usage">
<t>A HIP-aware application creates the sockaddr_hip structures
explicitly or obtains them from the resolver. The explicit
configuration of locators is described in <xref
target="I-D.ietf-shim6-multihome-shim-api" />. This document
defines "automated" resolver extensions for getaddrinfo()
resolver <xref target="RFC3493". Other resolver calls, such
as gethostbyname() and getservbyname() are not defined in this
document. The getaddrinfo resolver interface is shown in
<xref target="fig:getaddrinfo" />.</t>
<figure anchor="fig:getaddrinfo">
<artwork>
#include <netdb.h>
int getaddrinfo(const char *nodename,
const char *servname,
const struct addrinfo *hints,
struct addrinfo **res)
void free_addrinfo(struct addrinfo *res)
</artwork>
</figure>
<t>As described in <xref target="RFC3493" />, the getaddrinfo
function takes the nodename, servname, and hints as its
input arguments. It places the result of the query into the
res argument. The return value is zero on success, or a
non-zero error value on error. The nodename argument
specifies the host name to be resolved; a NULL argument
denotes the local host. The servname parameter declares the
port number to be set in the socket addresses in the res
output argument. Both the nodename and servname cannot be
NULL.</t>
<t>The input argument "hints" acts like a filter that defines
the attributes required from the resolved endpoints. A NULL
hints argument indicates that any kind of endpoints are
acceptable.</t>
<t>The output argument "res" is dynamically allocated by the
resolver. The application frees res argument with the
free_addrinfo function. The res argument contains a linked
list of the resolved endpoints. The linked list contains
sockaddr_hip structures only when the input argument has
the HIP_PREFER_ORCHID flag set in ai_eflags. The resolver
inserts HITs before any locators. When the
HIP_PREFER_ORCHID flag is set, the resolver does not return
LSIs or HITs encapsulated into sockaddr_in or sockaddr_in6
data structures as described in <xref
target="I-D.ietf-hip-applications" />.
</t>
<t>Resolver can return a HIT which maps to multiple
locators. The resolver may cache the locator mappings to
the HIP module. The HIP module manages the multiple
locators according to system policies of the host. The
multihoming document <xref
target="I-D.ietf-shim6-multihome-shim-api" /> describes how
an application can override system default policies.
</t>
<t>
It should be noticed that the application can
configure the HIT explicitly without setting the locator or
the resolver can fail to resolve any locator. In this
scenario, the application relies on the system to map the
HIT to an IP address. When the system fails to provide the
mapping, it returns -1 in the called sockets API
function to the application and sets errno to EADDRNOTAVAIL.
</t>
</section> <!-- resolver usage -->
</section> <!-- resolver -->
<section anchor="sec:getsock" title="The Use of getsockname and getpeername Functions">
<t>The application usually discovers the local or peer HITs from
the sockaddr_hip structures returned by getaddrinfo(). However,
the sockaddr_hip structure does not contain a HIT when the
application uses the HIP_HIT_ANY_* macros. In such a case, the
application discovers the local and peer HITs using the
getsockname() and getpeername() functions. The functions return
sockaddr_hip structures when the family of the socket is AF_HIP.
</t>
</section> <!-- getsockname section -->
<section anchor="sec:validate" title="Validating HITs">
<t>An application that uses the HIP_ADDR_ANY macro may want to
check if the local or peer address is an orchid-based HIT
<xref target="RFC4843" />. Also, the application may want
to verify whether a HIT is public or anonymous. The
application accomplishes these using a new function called
sockaddr_is_srcaddr() which is illustrated in <xref
target="fig:sockaddr_is_srcaddr"/>.
</t>
<figure anchor="fig:sockaddr_is_srcaddr">
<artwork>
#include <netinet/in.h>
short sockaddr_is_srcaddr(struct sockaddr *srcaddr
uint64_t flags);
</artwork>
</figure>
<t>The sockaddr_is_srcaddr() function operates in the same way as
inet6_is_srcaddr() function <xref target="RFC5014" /> which
can be used to verify the type of an address belonging to the
localhost. The difference is that sockaddr_is_srcaddr()
function handles sockaddr_hip structures in addition to
sockaddr_in6, and possibly some other socket structures in
further extensions. The function has also 64 bit flags instead
of 32 bits. This new function handles the same flags as
defined in <xref target="RFC5014" /> in addition to some
HIP-specific flags listed in <xref
target="tbl:sockaddr_is_src_addr" />.
</t>
<texttable anchor="tbl:sockaddr_is_src_addr">
<ttcol align="left">Flag</ttcol><ttcol align="left">Purpose</ttcol>
<c>HIP_PREFER_ORCHID</c><c>The identifier is a HIT </c>
<c>HIP_PREFER_SRC_TMP</c><c>Anonymous HIT</c>
<c>HIP_PREFER_SRC_PUBLIC</c><c>Public HIT</c>
<!--
XX FIXME: should these be here?
<c>HIP_PREFER_SRC_RSA</c><c>RSA-based HIT</c>
<c>HIP_PREFER_SRC_DSA</c><c>DSA-based HIT</c>
-->
<!-- <c></c><c></c> -->
</texttable>
</section> <!-- "Validating HIT Type -->
<section title="Source HIT Selection by the System">
<t>Some applications initiate communications by specifying
only the destination identifier and let the underlying system specify
the source. When the system selects the source HIT, the system
should apply the rules specified in <xref target="RFC3484"
/> according to the default policy table for HITs shown in
<xref target="tbl:policy_table" />.
</t>
<texttable anchor="tbl:policy_table">
<ttcol align="left">HIT Type</ttcol><ttcol align="left">Precedence</ttcol><ttcol align="left">Label</ttcol>
<c>Anonymous DSA</c><c>110</c><c>5</c>
<c>Anonymous RSA</c><c>120</c><c>6</c>
<c>Public DSA</c><c>130</c><c>7</c>
<c>Public RSA</c><c>140</c><c>8</c>
<c><xref target="RFC3484" /> rules</c><c>50-100</c><c>7</c>
</texttable>
<t>
When application using a AF_HIP-based socket does not specify the
source identifier, the system selects the source identifier on the
behalf of the application according to the precedence in the above
table. For example, the system prefers public (published) keys before
anonymous keys because they work better for referral
purposes. RSA-based keys are preferred over DSA based because RSA is
the default algorithm in HIP.
</t>
<t>
When system provides multiple keys of same type, but with different
key lengths, the longer keys should have a higher preference. As
example, system providing two public RSA keys of different size would
give the smaller key preference value 140 and 145 for the larger. The
preference value should not exceed 150. Systems supporting more than
10 keys of same key size may use digits to further fragment the
precedence namespace. IPv6 addresses have the lowest precedence value
to denote that HITs have a higher precedence when operating on
AF_HIP-based sockets.
</t>
<t><xref target="RFC5014" /> specifies flags for the
getaddrinfo resolver and socket options for
Mobile IPv6. The resolver, operating under
HIP_PREFER_ORCHID flag, or the socket handler, operating
on a AF_HIP-based socket, may encounter such flags or
options. In such a case the resolver or socket handler
should silenty ignore the flags or options without
returning an error. However, a HIP-aware application may
use the HIP-specific flags HIP_PREFER_ORCHID,
HIP_PREFER_SRC_TMP or HIP_PREFER_SRC_PUBLIC in
getsockopt(), setsockopt(), getaddrinfo() calls and in the
anchillary data of datagram packets as specified in <xref
target="RFC5014" />. The level of the socket options
should be set to SOL_SHIM <xref
target="I-D.ietf-shim6-multihome-shim-api" /> and the
option name should be HIP_HIT_PREFERENCES.
</t>
<!-- XX FIXME: UDP-based sockets? the draft does not prefer it -->
<!-- XX FIXME: what about dst selection ? -->
</section> <!-- Source Address Selection -->
<section anchor="sec:explicit" title="Explicit Handling of Locators">
<t>
The system resolver, or the HIP module, maps HITs to locators
implicitly. However, some applications may want to specify
initial locator mappings explicitly. In such a case, the
application first creates a socket with AF_HIP as the domain
argument. Second, the application may set locator information
with one of the following shim socket options
as defined in the multihoming extensions in <xref
target="I-D.ietf-shim6-multihome-shim-api" />:
</t>
<figure anchor="fig:socket_opts">
<artwork>
+-----------------------------+-----+-----+-----------------+-------+
| optname | get | set | description | dtype |
+-----------------------------+-----+-----+-----------------+-------+
| SHIM_LOC_LOCAL_PREF | o | o | Get or set the | *1 |
| | | | preferred | |
| | | | locator on the | |
| | | | local side for | |
| | | | the context | |
| | | | associated with | |
| | | | the socket. | |
| SHIM_LOC_PEER_PREF | o | o | Get or set the | *1 |
| | | | preferred | |
| | | | locator on the | |
| | | | remote side for | |
| | | | the context | |
| | | | associated with | |
| | | | the socket. | |
| SHIM_LOCLIST_LOCAL | o | o | Get or set a | *2 |
| | | | list of | |
| | | | locators | |
| | | | associated with | |
| | | | the local EID. | |
| SHIM_LOCLIST_PEER | o | o | Get or set a | *2 |
| | | | list of | |
| | | | locators | |
| | | | associated with | |
| | | | the peer's EID. | |
| SHIM_LOC_LOCAL_SEND | o | o | Request use of | *2 |
| | | | specific | |
| | | | locator as | |
| | | | source locator | |
| | | | of outgoing IP | |
| | | | packets. | |
| SHIM_LOC_PEER_SEND | o | o | Request use of | *2 |
| | | | specific | |
| | | | locator as | |
| | | | destination | |
| | | | locator of | |
| | | | outgoing IP | |
| | | | packets. | |
+-----------------------------+-----+-----+-----------------+-------+
*1: Pointer to a shim_locator which is defined in Section 7 of
draft-ietf-shim6-multihome-shim-api.
*2: Pointer to an array of shim_locator.
</artwork>
</figure>
<t>
Finally, the application creates a valid sockaddr_hip
structure and associates the socket
also with the sockaddr_hip structure by calling some
socket-related function, such as connect() or bind().</t>
<t>
The usage and semantics for typical use cases are as follows:
</t>
<t>An application that initiates a connection using a connection
oriented socket to a particular host at a known address or set of
addresses can invoke SHIM_LOCLIST_PEER socket option. The HIP module
uses the first address (if multiple are provided, or else the
application can override this by setting SHIM_LOC_PEER_PREF to one of
the addresses in SHIM_LOCLIST_PEER. The application later provides a
specific HIT in the ship_hit field of the sockaddr_hip in the
connect() system call. If the application provides one or more
addresses in SHIM_LOCLIST_PEER setsockopt call, the system should not
connect to the host via another destination address, in case the
application intends to restrict the range of addresses permissible as
a policy choice. If the system cannot reach the provided HIT at one
of the addresses provided, the outbound socket API functions (connect,
sendmsg, etc.) return -1 and set errno to EINVALIDLOCATOR.
</t>
<t>
Another common use case is to set up an association in opportunistic
mode, when the destination HIT is specified as a wildcard. This can
be accomplished by setting one or more destination addresses using the
SHIM_LOCLIST_PEER socket option as described above and then calling
connect() with the wildcard HIT. The connect() call returns -1 and
sets errno to EADDRNOTAVAIL when the application connects to a
wildcard without specifying any destination address.
</t>
<t>
Applications may also choose to associate local addresses with
sockets. The procedures specified in <xref
target="I-D.ietf-shim6-multihome-shim-api" /> are followed in this
case.
</t>
</section> <!-- locators -->
</section> <!-- syntax -->
<section title="Summary of New Definitions">
<t>
<xref target="tbl:defs" /> summarizes the new macro and
structures defined in this document.
</t>
<texttable anchor="tbl:defs">
<ttcol align="left">Header</ttcol><ttcol align="left">Definition</ttcol>
<c><sys/socket.h></c><c>AF_HIP</c>
<c><sys/socket.h></c><c>PF_HIP</c>
<c><netinet/in.h></c><c>IPPROTO_HIP</c>
<c><netinet/hip.h></c><c>HIP_HIT_ANY</c>
<c><netinet/hip.h></c><c>HIP_HIT_ANY_PUB</c>
<c><netinet/hip.h></c><c>HIP_HIT_ANY_TMP</c>
<c><netinet/hip.h></c><c>HIP_ADDR_ANY</c>
<c><netinet/hip.h></c><c>HIP_HIT_PREFERENCES</c>
<c><netinet/hip.h></c><c>hip_hit_t</c>
<c><netdb.h></c><c>HIP_PREFER_ORCHID</c>
<c><netdb.h></c><c>HIP_PREFER_SRC_TMP</c>
<c><netdb.h></c><c>HIP_PREFER_SRC_PUBLIC</c>
<c><netdb.h></c><c>HIP_PREFER_PASSIVE_HIT_TMP</c>
<c><netdb.h></c><c>HIP_PREFER_PASSIVE_HIT_PUB</c>
<c><netdb.h></c><c>HIP_PREFER_PASSIVE_HIT_ANY</c>
<c><netdb.h></c><c>HIP_PREFER_PASSIVE_ADDR_ANY</c>
<c><netinet/hip.h></c><c>sockaddr_hip</c>
<c><netinet/hip.h></c><c>sockaddr_is_srcaddr</c>
</texttable>
</section> <!-- new defs -->
<section anchor="sec:iana" title="IANA Considerations">
<t>No IANA considerations.</t>
</section> <!-- iana -->
<section anchor="sec:security" title="Security Considerations">
<!-- Poisoning of mappings, app. spec. id access priviledges -->
<t>No security considerations currently.</t>
</section>
<section title="Contributors">
<t>Thanks for Jukka Ylitalo and Pekka Nikander for their original
contribution, time and effort to the native HIP APIs. Thanks for
Yoshifuji Hideaki for his contributions to this document.
</t>
</section> <!-- Contributors -->
<section anchor="sec:acknowledgements" title="Acknowledgements">
<t>
Kristian Slavov, Julien Laganier, Jaakko Kangasharju, Mika Kousa,
Jan Melen, Andrew McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch,
Antti Järvinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari
Keränen, Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews, Jan
Melen and Gonzalo Camarillo have also provided valuable ideas or
feedback. Thanks also for the APPS area folks, including Stephane
Bortzmeyer, Chris Newman, Tony Finch, "der Mouse" and Keith Moore.
</t>
</section> <!-- acknowledgements -->
</middle>
<back>
<references title="Normative References">
<reference anchor="POSIX">
<front>
<title>IEEE Std. 1003.1-2001 Standard for Information Technology -
Portable Operating System Interface (POSIX)</title>
<author>
<organization>Institute of Electrical and Electronics Engineers
</organization>
</author>
<date month="Dec" year="2001" />
</front>
</reference>
<?rfc include="reference.RFC.3484" ?>
<?rfc include="reference.RFC.5014" ?>
<?rfc include="reference.RFC.3493" ?>
<?rfc include="reference.RFC.4843" ?>
<!-- <?rfc include="reference.RFC.3041" ?> -->
<?rfc include="reference.RFC.4423" ?>
<?rfc include="reference.RFC.5201" ?>
<?rfc include="reference.RFC.5205" ?>
<?rfc include="reference.I-D.ietf-hip-applications" ?>
<?rfc include="reference.I-D.ietf-btns-c-api" ?>
<?rfc include="reference.I-D.ietf-shim6-multihome-shim-api" ?>
<?rfc include="reference.I-D.ietf-shim6-proto" ?>
</references>
<!--
<references title="Informative References">
</references>
-->
</back>
</rfc>
| PAFTECH AB 2003-2026 | 2026-04-23 20:33:59 |