One document matched: draft-ietf-hip-native-api-07.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="yes"?>
<?rfc toc="yes" ?>
<?rfc tocdepth="2"?>
<?rfc sortrefs="yes" ?>
<?rfc symrefs="yes" ?>
<?rfc comments="yes" ?>
<!--<?rfc editing="yes" ?>-->
<rfc category="exp" ipr="noModificationTrust200902" docName="draft-ietf-hip-native-api-07">
<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>Metsanneidonkuja 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="2009"/>
<area>Internet Area</area>
<workgroup>Host Identity Protocol</workgroup>
<abstract>
<t>This document defines extensions to the current sockets API for
the 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
further 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>
-->
<!--
XX FIXME: reverse queries. Should we do something with them?
-->
</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.
The APIs specified in this document are specific to HIP, but
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>
The APIs in this document are based on IPv6 addresses with the ORCHID prefix
<xref target="RFC4843" />. ORCHIDs are derived from Host Identifiers
using a hash and fitting the result into an IPv6 address. Such addresses are
called Host Identity Tags (HITs) and they can be distinguished from other
IPv6 addresses with the ORCHID prefix.
</t>
<t>
Applications can observe the HIP layer and its identifiers in the
networking stacks with varying degrees of visibility. <xref
target="RFC5338" /> 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. Similarly to other address
families, AF_HIP can used as an alias for PF_HIP. The extensions also
describe a new socket address structure for sockets using
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 (section 4.1.6 in <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 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 an 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 illustrate how
HIP-aware applications can use the SHIM API
<xref target="I-D.ietf-shim6-multihome-shim-api" /> to manually
map locators to 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
to HIT(s). The resolver queries the DNS in step (b) to
map the FQDN to a host identifier and locator (A and
AAAA records). It should be noticed that the FQDN may map to
multiple host identifiers and
locators, and this step may involve multiple DNS transactions,
including queries for A, AAAA, HI and possibly other resource records.
The DNS server responds with a list of HIP resource records
in step (c). Optionally in step (d), the
resolver caches the HIT to locator mapping with the HIP
module. The resolver converts the HIP records to HITs and
returns the HITs to the application contained in
HIP socket address structures
in step (e). Depending on the parameters for the resolver call,
the resolver may return also other socket address structures
to the application.
Finally, the application receives the socket address structure(s)
from the resolver and uses them in socket calls such as connect()
in step (f).
</t>
<figure anchor="fig:resolver_path">
<artwork><![CDATA[
+----------+
| |
| DNS |
| |
+----------+
^ |
b. QNAME=FQDN | | c. HIP and
| | A/AAAA
| v RR(s)
+-------------+ a. getaddrinfo(<FQDN>) +----------+
| |------------------------>| |
| Application | | Resolver |
| |<------------------------| |
+-------------+ e. <HITs> +----------+
| |
| | d. HIP and
| f. connect(<HIT>) | A/AAAA
| or any other socket call | RR(s)
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 HIP-aware interposing agent.
</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 may implicitly associate a HIT with the corresponding
locator(s) by 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="sec:explicit" />. Full support for all of
the extensions defined in this draft requires a number of shim socket options
<xref target="I-D.ietf-shim6-multihome-shim-api" /> 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
constants to set a wildcard value manually into the ship_hit
field. The constants are HIP_HIT_ANY, HIP_HIT_ANY_PUB,
HIP_HIT_ANY_TMP and HIP_ENDPOINT_ANY. The first three equal to a
HIT value associated with a wildcard HIT of any type, public type, or
anonymous type. The fourth constant, HIP_ENDPOINT_ANY, denotes that
the application accepts both HIT and any other type of addresses.
The HIP_HIT_ANY denotes that the application accepts any type of
HIT. The anonymous identifiers
refer to the use of 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 protocol perspective.
</t>
<t>The application can use the HIP_HIT_ANY_* and HIP_ENDPOINT_ANY
constants to accept incoming communications to all of the HITs of
the local host. Incoming communications refers here to
functions such as bind(), recvfrom() and recvmsg(). The
HIP_HIT_* constants are similar to the sockets API constants
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_ENDPOINT_ANY constants 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 constant 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 should first associate the socket with at least
one IP address of the peer using SHIM_LOCLIST_PEER_PREF socket
option. The use of the HIP_HIT_ANY constant guarantees that the
communications will be based on HIP or none at all.
</t>
<t>The use of HIP_ENDPOINT_ANY constant in the context of outgoing
communications is left for further experimentation in the context
of opportunistic mode. It can result in a data flow with or
without HIP.
</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 contained in the ship_hit field using
memcmp() or similar function. It
should be noted 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 address family, AF_HIP, that HIP
aware applications can use to control the address type returned
from getaddrinfo() function <xref target="RFC3493" />.
The getaddrinfo() function uses a data structure called addrinfo
in its "hints" and "res" argument which are described in more
detail in the next section. The addrinfo 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>
<!-- XX FIXME: what about IPPROTO_HIP -->
<t>
An application resolving with the ai_family field set to
AF_UNSPEC in the hints argument may receive any kind of socket
address structures, including sockaddr_hip. When the
application wants to receive only HITs contained in
sockaddr_hip structures, it should set the ai_family field to
AF_HIP.
Otherwise, the resolver does not return any sockaddr_hip structures.
The resolver returns EAI_FAMILY when AF_HIP is not supported.
</t>
<t>The resolver ignores the AI_PASSIVE flag when the application sets the family
in hints to AF_HIP.
</t>
<t>
The system may have a HIP-aware interposing DNS agent as
described in section 3.2 in <xref target="RFC5338" />. In
such a case, the DNS agent may, according to local policy, return
transparently LSIs or HITs
in sockaddr_in and sockaddr_in6 structures when available.
A HIP-aware application can override this local policy in two ways.
First, the application can set the family to AF_HIP in the hints
argument of getaddrinfo() when it requests only sockaddr_hip
structures. Second, the application can set AI_EXTFLAGS and
AI_NO_HIT flags to prevent the resolver from returning HITs in
any kind of data structures.
</t>
<t>
When getaddrinfo() returns resolved outputs the results
to res argument, it sets the family to AF_HIP when the related structure is
sockaddr_hip.
</t>
<section anchor="sec:resolver_usage" title="Resolver Usage">
<t>A HIP-aware application creates the sockaddr_hip structures
manually 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 output 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 HITs of 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 at the same time.</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 the 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 family set to AF_HIP. When the family is zero,
the list contains
sockaddr_hip structures before sockaddr_in and sockaddr_in6
structures.
</t>
<t>Resolver can return a HIT which maps to multiple
locators. The resolver may cache the locator mappings with
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 noted 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_* constants. 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:sockopt" title="Selection of Source HIT Type">
<t>
The Socket API for Source Address Selection <xref target="RFC5014" />
defines socket options to allow applications to influence source address
selection mechanisms. In some cases, HIP-aware applications may
want to influence source HIT selection; in particular, whether
an outbound connection should use a published or anonymous HIT.
Similar to IPV6_ADDR_PREFERENCES defined in RFC 5014, the
following socket option HIT_PREFERENCES is defined for
HIP-based sockets. This socket option can be used with
setsockopt() and getsockopt() calls to set and get the HIT
selection preferences affecting a HIP-enabled socket. The
socket option value (optval) is a 32-bit unsigned integer
argument. The argument consists of a number of flags where each
flag indicates an address selection preference that modifies one
of the rules in the default HIT selection; these flags are shown in
<xref target="tbl:src_hit" />.
</t>
<texttable anchor="tbl:src_hit">
<ttcol align="left">Socket Option</ttcol>
<ttcol align="left">Purpose</ttcol>
<c>HIP_PREFER_SRC_HIT_TMP</c><c>Prefer an anonymous HIT</c>
<c>HIP_PREFER_SRC_HIT_PUBLIC</c><c>Prefer a public HIT</c>
</texttable>
<t>
If the system is unable to assign the type of HIT that is
requested, at HIT selection time, the socket call (connect (),
sendto(), or sendmsg()) will fail and errno will be set to
EINVAL. If the application tries to set both of the above flags
for the same socket, this also results in the error EINVAL.
</t>
</section> <!-- Selection of Source HIT Type -->
<section anchor="sec:types" title="Verification of Source HIT Type">
<t>An application that uses the HIP_ENDPOINT_ANY constant may want to
check whether the actual communications was based on HIP or not.
Also, the application may want
to verify whether a local 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
local host. The difference is that the sockaddr_is_srcaddr()
function handles sockaddr_hip structures in addition to
sockaddr_in6, and possibly some other socket structures in
further extensions. The flags argument is also 64 bit instead
of 32 bits because new function handles the same flags as
defined in <xref target="RFC5014" /> in addition to
two HIP-specific flags,
HIP_PREFER_SRC_HIT_TMP and HIP_PREFER_SRC_HIT_PUBLIC. With these
two flags, the application can distinguish
anonymous HITs from public HITs.
</t>
<t>When given an AF_INET6 socket, sockaddr_is_srcaddr() behaves as
inet6_is_srcaddr() function as described in <xref target="RFC5014" />.
With AF_HIP socket, the function returns 1 when the HIT contained in the socket
address structure corresponds to a valid HIT of the local host and
the HIT satisfies the given flags. The function returns -1 when
the HIT does not belong to the local host or the flags are not valid.
The function returns 0 when the preference flags are valid but the
HIT does not match the given flags.
</t>
<!--
<t>The same flags can also be used with getaddrinfo() when the
application asks the resolver to assign a local wildcard HIT to be used with
the bind() socket call. In such a case, the node argument for getaddrinfo() must
be NULL and input flags must include the AI_PASSIVE flag.
When the AI_EXTFLAGS is unset,
the resolver returns a sockaddr_hip structure with ship_hit field
prefilled with the HIP_HIT_ANY constant that was described in
<xref target="sec:syntax" />. When AI_EXTFLAGS is set,
the resolver prefills the returned sockaddr_hip structure for the
conveniency of the application as listed in
<xref target="tbl:prefer_flags" />.
</t>
<texttable anchor="tbl:prefer_flags">
<ttcol align="left">Flags</ttcol>
<ttcol align="left">Corresponding constant</ttcol>
<c>Neither</c><c>HIP_ENDPOINT_ANY</c>
<c>HIP_PREFER_SRC_HIT_TMP</c><c>HIP_HIT_ANY_TMP</c>
<c>HIP_PREFER_SRC_HIT_PUBLIC</c><c>HIP_HIT_ANY_PUB</c>
<c>Both</c><c>HIP_HIT_ANY</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 identifier. In the case of a single source identifier,
the choice is obvious, but multiple identifiers bring policy issues.
When the system selects the source HIT, the system
should apply the rules specified in <xref target="RFC3484"
/> according to the default policy table as 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>DSA</c><c>110</c><c>10</c>
<c>RSA</c><c>100</c><c>11</c>
<c><xref target="RFC3484" /> rules</c><c>10-50</c><c>0-4</c>
</texttable>
<t>
When application using an 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.
In the context of HITs, RFC3483 scope comparisons are based the HIT
type rather than prefixes.
The system prefers public (published) keys before
anonymous keys because they work better for referral
purposes.
</t>
<t>
When system provides multiple keys of the 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 100 and 105 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_HIT flag, or the socket handler, operating
on an AF_HIP-based socket, may encounter such flags or
options. In such a case the resolver or socket handler
should silently ignore the flags or options without
returning an error. However, a HIP-aware application may
use the HIP-specific flags
HIP_PREFER_HIT_TMP or HIP_PREFER_HIT_PUBLIC in
getsockopt(), setsockopt(), getaddrinfo() calls and in the
ancillary 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 get or 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" />. The related socket
options are summarized briefly in <xref target="tbl:shim" />.
</t>
<texttable anchor="tbl:shim">
<ttcol align="left">optname</ttcol>
<ttcol align="left">description</ttcol>
<c>SHIM_LOC_LOCAL_PREF</c>
<c>Get or set the preferred locator on the local side for the context
associated with the socket.</c>
<c>SHIM_LOC_PEER_PREF</c>
<c>Get or set the preferred locator on the remote side for the context
associated with the socket.</c>
<c>SHIM_LOCLIST_LOCAL</c>
<c>Get or set a list of locators associated with the local EID.</c>
<c>SHIM_LOCLIST_PEER</c>
<c>Get or set a list of locators associated with the peer's EID.</c>
<c>SHIM_LOC_LOCAL_SEND</c>
<c>Set or get the default source locator of outgoing IP packets.</c>
<c>SHIM_LOC_PEER_SEND</c>
<c>Set or get the default destination locator of outgoing IP packets.</c>
</texttable>
<t>As an example of locator mappings, a connection-oriented
application creates a HIP-based socket and sets the
SHIM_LOCLIST_PEER socket option to the socket. The HIP module uses
the first address contained in the option if multiple are provided.
If the application provides one or more addresses in the
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. The application can override the default peer locator by
setting the SHIM_LOC_PEER_PREF socket option if necessary. Finally,
the application provides a specific HIT in the ship_hit field of
the sockaddr_hip in the connect() system call. If the system
cannot reach the HIT at one of the addresses provided, the outbound
socket API functions (connect, sendmsg, etc.) return -1 and set
errno to EINVALIDLOCATOR.
</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>
<t>
Another use case is to use the opportunistic mode
when the destination HIT is specified as a wildcard. The application
sets one or more destination addresses using the
SHIM_LOCLIST_PEER socket option as described above and then calls
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 using datagram-oriented sockets can use ancillary data
to control the locators. This described in detail in <xref
target="I-D.ietf-shim6-multihome-shim-api" />.
</t>
</section> <!-- locators -->
</section> <!-- syntax -->
<section title="Summary of New Definitions">
<t>
<xref target="tbl:defs" /> summarizes the new constants 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_ENDPOINT_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>AI_NO_HIT</c>
<!--
<c><netdb.h></c><c>HIP_PREFER_SRC_HIT_TMP</c>
<c><netdb.h></c><c>HIP_PREFER_SRC_HIT_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 Jarvinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari
Keranen, Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews,
Joakim Koskela, Jeff Ahrenholz 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.RFC.5338" ?>
<!-- <?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:34:00 |