draft-ietf-hip-native-api-04.txt   draft-ietf-hip-native-api-05.txt 
Host Identity Protocol M. Komu Host Identity Protocol M. Komu
Internet-Draft Helsinki Institute for Information Internet-Draft Helsinki Institute for Information
Intended status: Experimental Technology Intended status: Experimental Technology
Expires: August 28, 2008 Henderson Expires: January 14, 2009 Henderson
The Boeing Company The Boeing Company
February 25, 2008 July 13, 2008
Basic Socket Interface Extensions for Host Identity Protocol (HIP) Basic Socket Interface Extensions for Host Identity Protocol (HIP)
draft-ietf-hip-native-api-04 draft-ietf-hip-native-api-05
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79. aware will be disclosed, in accordance with Section 6 of BCP 79.
This document may not be modified, and derivative works of it may not This document may not be modified, and derivative works of it may not
be created, except to publish it as an RFC and to translate it into be created, except to publish it as an RFC and to translate it into
languages other than English. languages other than English.
skipping to change at page 1, line 39 skipping to change at page 1, line 39
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on August 28, 2008. This Internet-Draft will expire on January 14, 2009.
Copyright Notice
Copyright (C) The IETF Trust (2008).
Abstract Abstract
This document defines extensions to the current sockets API for Host This document defines extensions to the current sockets API for Host
Identity Protocol (HIP). The extensions focus on the use of public- Identity Protocol (HIP). The extensions focus on the use of public-
key based identifiers discovered via DNS resolution, but define also key based identifiers discovered via DNS resolution, but define also
interfaces for manual bindings between HITs and locators. With the interfaces for manual bindings between HITs and locators. With the
extensions, the application can also support more relaxed security extensions, the application can also support more relaxed security
models where the communication can be non-HIP based, according to models where the communication can be non-HIP based, according to
local policies. The extensions in document are experimental and local policies. The extensions in document are experimental and
skipping to change at page 2, line 35 skipping to change at page 2, line 31
4.4. Validating HITs . . . . . . . . . . . . . . . . . . . . . 10 4.4. Validating HITs . . . . . . . . . . . . . . . . . . . . . 10
4.5. Source HIT Selection by the System . . . . . . . . . . . . 11 4.5. Source HIT Selection by the System . . . . . . . . . . . . 11
4.6. Explicit Handling of Locators . . . . . . . . . . . . . . 12 4.6. Explicit Handling of Locators . . . . . . . . . . . . . . 12
5. Summary of New Definitions . . . . . . . . . . . . . . . . . . 14 5. Summary of New Definitions . . . . . . . . . . . . . . . . . . 14
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15
7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 15
9. Normative References . . . . . . . . . . . . . . . . . . . . . 16 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15
10. Normative References . . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17
Intellectual Property and Copyright Statements . . . . . . . . . . 18 Intellectual Property and Copyright Statements . . . . . . . . . . 18
1. Introduction 1. Introduction
This document defines C-based sockets Application Programming This document defines C-based sockets Application Programming
Interface (API) extensions for handling HIP-based identifiers Interface (API) extensions for handling HIP-based identifiers
explicitly in HIP-aware applications. It is up to the applications, explicitly in HIP-aware applications. It is up to the applications,
or high-level programming languages or libraries, to manage the or high-level programming languages or libraries, to manage the
identifiers. The extensions in this document are mainly related to identifiers. The extensions in this document are mainly related to
the use case in which a DNS resolution step has occurred prior to the 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 creation of a new socket, and assumes that the system has cached or
is otherwise able to resolve identifiers to locators (IP addresses). is otherwise able to resolve identifiers to locators (IP addresses).
The DNS extensions for HIP are described in [I-D.ietf-hip-dns]. The The DNS extensions for HIP are described in [RFC5205]. The
extensions also cover the case in which an application may want to extensions also cover the case in which an application may want to
explicitly provide suggested locators with the identifiers, including explicitly provide suggested locators with the identifiers, including
supporting the opportunistic case in which the system does not know supporting the opportunistic case in which the system does not know
the peer host identity. the peer host identity.
The Host Identity Protocol (HIP) [RFC4423] proposes a new The Host Identity Protocol (HIP) [RFC4423] proposes a new
cryptographic namespace by separating the roles of end-point cryptographic namespace by separating the roles of end-point
identifiers and locators by introducing a new namespace to the TCP/IP identifiers and locators by introducing a new namespace to the TCP/IP
stack. SHIM6 [I-D.ietf-shim6-proto] is another protocol based on stack. SHIM6 [I-D.ietf-shim6-proto] is another protocol based on
identity-locator split. Note that the APIs specified in this identity-locator split. Note that the APIs specified in this
document are specific to HIP. However, the APIs here have been 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 designed as much as possible so as not to preclude its use with other
protocols. The use of these APIs with other protocols is, protocols. The use of these APIs with other protocols is,
nevertheless, for further study. nevertheless, for further study.
Applications can observe the HIP layer and its identifiers in the Applications can observe the HIP layer and its identifiers in the
networking stacks with varying degrees of visibility. networking stacks with varying degrees of visibility.
[I-D.ietf-hip-applications] discusses the lowest levels of visibility [I-D.ietf-hip-applications] discusses the lowest levels of visibility
in which applications are completely unaware of the underlying HIP in which applications are completely unaware of the underlying HIP
layer. Such HIP-unaware applications use HIP-based identifiers, such layer. Such HIP-unaware applications in some circumstances use HIP-
as LSIs or HITs, instead of IPv4 or IPv6 addresses and cannot observe based identifiers, such as LSIs or HITs, instead of IPv4 or IPv6
the identifier-locator bindings. addresses and cannot observe the identifier-locator bindings.
This document specifies extensions to [RFC3493] to define a new This document specifies extensions to [RFC3493] to define a new
socket address family, AF_HIP. The macro PF_HIP is used as an alias socket address family, AF_HIP. The macro AF_HIP is used as an alias
for AF_HIP in this document because the distinction between PF and AF 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 has been lost in practice. The extensions also describe a new socket
address structure for sockets using Host Identity Tags (HITs) address structure for sockets using Host Identity Tags (HITs)
explicitly and describe how the socket calls in [RFC3493] are adapted explicitly and describe how the socket calls in [RFC3493] are adapted
or extended as a result. or extended as a result.
Some applications may accept incoming communications from any Some applications may accept incoming communications from any
identifier. Other applications may initiate outgoing communications identifier. Other applications may initiate outgoing communications
without the knowledge of the peer identifier in Opportunistic Mode without the knowledge of the peer identifier in Opportunistic Mode
[I-D.ietf-hip-base] by just relying on a peer locator. This document [RFC5201] by just relying on a peer locator. This document describes
describes how to address both situations using "wildcards" as how to address both situations using "wildcards" as described later
described later in this document. in this document.
There are two related API documents. Multihoming and explicit There are two related API documents. Multihoming and explicit
locator-handling related APIs are defined in locator-handling related APIs are defined in
[I-D.ietf-shim6-multihome-shim-api]. IPsec related policy attributes [I-D.ietf-shim6-multihome-shim-api]. IPsec related policy attributes
and channel bindings APIs are defined in [I-D.ietf-btns-c-api]. Most and channel bindings APIs are defined in [I-D.ietf-btns-c-api]. Most
of the extensions defined in this document can be used independently of the extensions defined in this document can be used independently
of the two mentioned related API documents. of the two mentioned related API documents.
The identity-locator split introduced by HIP introduces some policy The identity-locator split introduced by HIP introduces some policy
related challenges with datagram oriented sockets, opportunistic related challenges with datagram oriented sockets, opportunistic
skipping to change at page 6, line 25 skipping to change at page 6, line 25
In this section, we describe the native HIP APIs using the syntax of In this section, we describe the native HIP APIs using the syntax of
the C programming language. We limit the description to the the C programming language. We limit the description to the
interfaces and data structures that are either modified or completely interfaces and data structures that are either modified or completely
new, because the native HIP APIs are otherwise identical to the new, because the native HIP APIs are otherwise identical to the
sockets API [POSIX]. sockets API [POSIX].
4.1. Socket Family and Address Structure Extensions 4.1. Socket Family and Address Structure Extensions
The sockets API extensions define a new protocol family, PF_HIP, and 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 a new address family, AF_HIP. The AF_HIP and PF_HIP are aliases to
each other. The use of the PF_HIP constant is mandatory with the each other. These definition shall be defined as a result of
socket() function when application uses the native HIP APIs. The including <sys/socket.h>.
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) application gives the PF_HIP constant as the first argument (domain)
to the socket() function. The system returns a positive integer to the socket() function. The system returns a positive integer
representing a socket descriptor when the system supports HIP. representing a socket descriptor when the system supports HIP.
Otherwise, the system returns -1 and sets errno to EAFNOSUPPORT. Otherwise, the system returns -1 and sets errno to EAFNOSUPPORT.
A HIT is contained in a sockaddr_hip structure, which is shown in Figure 2 shows socket address structure for HIP.
Figure 2 in 4.4BSD format. The family of the socket, ship_family, is
set to PF_HIP. The port number ship_port is two octets and the
ship_hit is 16 octets.
#include <netinet/in.h> #include <netinet/in.h>
typedef struct in6_addr hip_hit_t; typedef struct in6_addr hip_hit_t;
struct sockaddr_hip { struct sockaddr_hip {
uint8_t ship_len; sa_family_t ship_family;
uint8_t ship_family; in_port_t ship_port;
uint16_t ship_port; uint32_t ship_pad;
uint64_t ship_flags; uint64_t ship_flags;
hip_hit_t ship_hit; hip_hit_t ship_hit;
uint8_t reserved[16]; uint8_t ship_reserved[16];
} };
Figure 2 Figure 2
Figure 2 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.
The application usually sets the ship_hit field using the resolver. The application usually sets the ship_hit field using the resolver.
However, the application can use three special wildcard macros to set However, the application can use three special wildcard macros to set
a value directly into the ship_hit field. The macros are 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 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 first three equal to a HIT value associated with a wildcard HIT of
any, public, or anonymous type. The fourth macro, HIP_ADDR_ANY, any, public, or anonymous type. The fourth macro, HIP_ADDR_ANY,
denotes both HIP_HIT_ANY or any IPv4 or IPv6 address. The 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 HIP_HIT_ANY equals to HIP_HIT_ANY_PUB or HIP_HIT_ANY_TMP. The
anonymous identifiers refer to the use anonymous identifiers as anonymous identifiers refer to the use anonymous identifiers as
specified in [RFC4423]. The system may designate anonymous specified in [RFC4423]. The system may designate anonymous
skipping to change at page 7, line 31 skipping to change at page 7, line 37
recvfrom() and recvmsg(). The HIP_HIT_* macros are similar to the recvfrom() and recvmsg(). The HIP_HIT_* macros are similar to the
sockets API macros INADDR_ANY and IN6ADDR_ANY_INIT, but they are sockets API macros INADDR_ANY and IN6ADDR_ANY_INIT, but they are
applicable to HITs only. After initial contact with the peer, the applicable to HITs only. After initial contact with the peer, the
application can discover the local and peer HITs using getsockname() application can discover the local and peer HITs using getsockname()
and getpeername() calls in the context of connection oriented and getpeername() calls in the context of connection oriented
sockets. The difference between the use of the HIP_HIT_* and sockets. The difference between the use of the HIP_HIT_* and
HIP_ADDR_ANY macros here is that the former allows only HIP-based HIP_ADDR_ANY macros here is that the former allows only HIP-based
communications but the latter also allows communications without HIP. communications but the latter also allows communications without HIP.
The application also uses the HIP_HIT_ANY macro in ship_hit field to The application also uses the HIP_HIT_ANY macro in ship_hit field to
establish outgoing communications in Opportunistic mode establish outgoing communications in Opportunistic mode [RFC5201],
[I-D.ietf-hip-base], i.e., when the application knows the remote peer i.e., when the application knows the remote peer locator but not the
locator but not the HIT. Outgoing communications refers here to the HIT. Outgoing communications refers here to the use of functions
use of functions such as connect(), sendto() and sendmsg(). However, such as connect(), sendto() and sendmsg(). However, the application
the application must first associate the socket with at least one IP must first associate the socket with at least one IP address of the
address of the peer using SHIM_LOCLIST_PEER_PREF socket option. peer using SHIM_LOCLIST_PEER_PREF socket option.
The use of HIP_ADDR_ANY macro in the context of outgoing The use of HIP_ADDR_ANY macro in the context of outgoing
communications is left for further experimentation. It could be used communications is left for further experimentation. It could be used
for establishing a non-HIP based connectivity when HIP-based for establishing a non-HIP based connectivity when HIP-based
connectivity was unsuccessful. connectivity was unsuccessful.
Some applications rely on system level access control, either Some applications rely on system level access control, either
implicit or explicit (such as accept_filter() function found on BSD- implicit or explicit (such as accept_filter() function found on BSD-
based systems), but such discussion is out of scope. Other based systems), but such discussion is out of scope. Other
applications implement access control themselves by using the HITs. applications implement access control themselves by using the HITs.
skipping to change at page 8, line 17 skipping to change at page 8, line 22
The HIP APIs introduce a new addrinfo flag, HIP_PREFER_ORCHID, to be 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 used by application to query for both HIT and locator information via
the getaddrinfo() resolver function [RFC3493]. The getaddrinfo() the getaddrinfo() resolver function [RFC3493]. The getaddrinfo()
function uses a data structure used for both input to and output from function uses a data structure used for both input to and output from
the resolver. The data structure is illustrated in Figure 3. the resolver. The data structure is illustrated in Figure 3.
#include <netdb.h> #include <netdb.h>
struct addrinfo { struct addrinfo {
int ai_flags; /* e.g. AI_EXTFLAGS */ int ai_flags; /* e.g. AI_EXTFLAGS */
int ai_family; /* e.g. PF_HIP */ int ai_family; /* e.g. AF_HIP */
int ai_socktype; /* e.g. SOCK_STREAM */ int ai_socktype; /* e.g. SOCK_STREAM */
int ai_protocol; /* 0 or IPPROTO_HIP */ int ai_protocol; /* 0 or IPPROTO_HIP */
size_t ai_addrlen; /* size of *ai_addr */ socklen_t ai_addrlen; /* size of *ai_addr */
struct sockaddr *ai_addr; /* sockaddr_hip */ struct sockaddr *ai_addr; /* sockaddr_hip */
char *ai_canonname; /* canon. name of the host */ char *ai_canonname; /* canon. name of the host */
struct addrinfo *ai_next; /* next endpoint */ struct addrinfo *ai_next; /* next endpoint */
int ai_eflags; /* RFC5014 extension */ int ai_eflags; /* RFC5014 extension */
}; };
Figure 3 Figure 3
Application must set both the flag AI_EXTFLAGS [RFC5014] in ai_flags Application must set both the flag AI_EXTFLAGS [RFC5014] in ai_flags
and HIP_PREFER_ORCHID in the ai_eflags, or otherwise the resolver and HIP_PREFER_ORCHID in the ai_eflags, or otherwise the resolver
skipping to change at page 8, line 48 skipping to change at page 9, line 5
resolver returns both public and anonymous HITs. resolver returns both public and anonymous HITs.
The simultaneous use of both HIP_PREFER_ORCHID and The simultaneous use of both HIP_PREFER_ORCHID and
HIP_PREFER_PASSIVE_* flags produces a single sockaddr_hip structure HIP_PREFER_PASSIVE_* flags produces a single sockaddr_hip structure
containing a wildcard address that the application can use either for containing a wildcard address that the application can use either for
incoming (node argument is NULL in getaddrinfo) or outgoing incoming (node argument is NULL in getaddrinfo) or outgoing
communications (node argument is non-NULL). For example, communications (node argument is non-NULL). For example,
HIP_PREFER_PASSIVE_HIT_TMP flag produces one sockaddr_hip structure HIP_PREFER_PASSIVE_HIT_TMP flag produces one sockaddr_hip structure
that contains a HIP_HIT_ANY_TMP in the ship_hit field. that contains a HIP_HIT_ANY_TMP in the ship_hit field.
The resolver sets the ai_family field to PF_HIP in the addrinfo The resolver sets the ai_family field to AF_HIP in the addrinfo
structure when ai_addr points to a sockaddr_hip structure. structure when ai_addr points to a sockaddr_hip structure.
When ai_protocol field is set to zero, the resolver also returns When ai_protocol field is set to zero, the resolver also returns
locators in sockaddr_in and sockaddr_in6 structures in addition to locators in sockaddr_in and sockaddr_in6 structures in addition to
sockaddr_hip structures. The resolver returns only sockaddr_hip sockaddr_hip structures. The resolver returns only sockaddr_hip
structures when the application has set the ai_protocol field to structures when the application has set the ai_protocol field to
IPPROTO_HIP or a sockaddr_hip structure is given as the hint argument IPPROTO_HIP or a sockaddr_hip structure is given as the hint argument
to the resolver. to the resolver.
4.2.1. Resolver Usage 4.2.1. Resolver Usage
skipping to change at page 10, line 23 skipping to change at page 10, line 28
provide the mapping, it returns -1 in the called sockets API function provide the mapping, it returns -1 in the called sockets API function
to the application and sets errno to EADDRNOTAVAIL. to the application and sets errno to EADDRNOTAVAIL.
4.3. The Use of getsockname and getpeername Functions 4.3. The Use of getsockname and getpeername Functions
The application usually discovers the local or peer HITs from the The application usually discovers the local or peer HITs from the
sockaddr_hip structures returned by getaddrinfo(). However, the sockaddr_hip structures returned by getaddrinfo(). However, the
sockaddr_hip structure does not contain a HIT when the application sockaddr_hip structure does not contain a HIT when the application
uses the HIP_HIT_ANY_* macros. In such a case, the application uses the HIP_HIT_ANY_* macros. In such a case, the application
discovers the local and peer HITs using the getsockname() and discovers the local and peer HITs using the getsockname() and
getpeername() functions. The functions return sockadd_hip structures getpeername() functions. The functions return sockaddr_hip
when the family of the socket is PF_HIP. structures when the family of the socket is AF_HIP.
4.4. Validating HITs 4.4. Validating HITs
An application that uses the HIP_ADDR_ANY macro may want to check if An application that uses the HIP_ADDR_ANY macro may want to check if
the local or peer address is an orchid-based HIT [RFC4843]. Also, the local or peer address is an orchid-based HIT [RFC4843]. Also,
the application may want to verify whether a HIT is public or the application may want to verify whether a HIT is public or
anonymous. The application accomplishes these using a new function anonymous. The application accomplishes these using a new function
called sockaddr_is_srcaddr() which is illustrated in Figure 5. called sockaddr_is_srcaddr() which is illustrated in Figure 5.
#include <netinet/in.h> #include <netinet/in.h>
skipping to change at page 11, line 35 skipping to change at page 11, line 38
+-----------------+------------+-------+ +-----------------+------------+-------+
| Anonymous DSA | 110 | 5 | | Anonymous DSA | 110 | 5 |
| Anonymous RSA | 120 | 6 | | Anonymous RSA | 120 | 6 |
| Public DSA | 130 | 7 | | Public DSA | 130 | 7 |
| Public RSA | 140 | 8 | | Public RSA | 140 | 8 |
| [RFC3484] rules | 50-100 | 7 | | [RFC3484] rules | 50-100 | 7 |
+-----------------+------------+-------+ +-----------------+------------+-------+
Table 3 Table 3
When application using a PF_HIP-based socket does not specify the When application using a AF_HIP-based socket does not specify the
source identifier, the system selects the source identifier on the source identifier, the system selects the source identifier on the
behalf of the application according to the precedence in the above behalf of the application according to the precedence in the above
table. For example, the system prefers public (published) keys table. For example, the system prefers public (published) keys
before anonymous keys because they work better for referral purposes. before anonymous keys because they work better for referral purposes.
RSA-based keys are preferred over DSA based because RSA is the RSA-based keys are preferred over DSA based because RSA is the
default algorithm in HIP. default algorithm in HIP.
When system provides multiple keys of same type, but with different When system provides multiple keys of same type, but with different
key lengths, the longer keys should have a higher preference. As key lengths, the longer keys should have a higher preference. As
example, system providing two public RSA keys of different size would example, system providing two public RSA keys of different size would
give the smaller key preference value 140 and 145 for the larger. give the smaller key preference value 140 and 145 for the larger.
The preference value should not exceed 150. Systems supporting more The preference value should not exceed 150. Systems supporting more
than 10 keys of same key size may use digits to further fragment the than 10 keys of same key size may use digits to further fragment the
precedence namespace. IPv6 addresses have the lowest presedence precedence namespace. IPv6 addresses have the lowest precedence
value to denote that HITs have a higher precedence when operating on value to denote that HITs have a higher precedence when operating on
PF_HIP-based sockets. AF_HIP-based sockets.
[RFC5014] specifies flags for the getaddrinfo resolver and socket [RFC5014] specifies flags for the getaddrinfo resolver and socket
options for MobileIPv6. The resolver, operating under options for MobileIPv6. The resolver, operating under
HIP_PREFER_ORCHID flag, or the socket handler, operating on a PF_HIP- 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 based socket, may encounter such flags or options. In such a case
the resolver or socket handler should silenty ignore the flags or the resolver or socket handler should silenty ignore the flags or
options without returning an error. However, a HIP-aware application options without returning an error. However, a HIP-aware application
may use the HIP-specific flags HIP_PREFER_ORCHID, HIP_PREFER_SRC_TMP may use the HIP-specific flags HIP_PREFER_ORCHID, HIP_PREFER_SRC_TMP
or HIP_PREFER_SRC_PUBLIC in getsockopt(), setsockopt(), getaddrinfo() or HIP_PREFER_SRC_PUBLIC in getsockopt(), setsockopt(), getaddrinfo()
calls and in the anchillary data of datagram packets as specified in calls and in the anchillary data of datagram packets as specified in
[RFC5014]. The level of the socket options should be set to SOL_SHIM [RFC5014]. The level of the socket options should be set to SOL_SHIM
[I-D.ietf-shim6-multihome-shim-api] and the option name should be [I-D.ietf-shim6-multihome-shim-api] and the option name should be
HIP_HIT_PREFERENCES. HIP_HIT_PREFERENCES.
4.6. Explicit Handling of Locators 4.6. Explicit Handling of Locators
The system resolver, or the HIP module, maps HITs to locators The system resolver, or the HIP module, maps HITs to locators
implicitly. However, some applications may want to specify initial implicitly. However, some applications may want to specify initial
locator mappings explicitly. In such a case, the application first locator mappings explicitly. In such a case, the application first
creates a socket with PF_HIP as the domain argument. Second, the creates a socket with AF_HIP as the domain argument. Second, the
application may set locator information with one of the following application may set locator information with one of the following
shim socket options as defined in the multihoming extensions in shim socket options as defined in the multihoming extensions in
[I-D.ietf-shim6-multihome-shim-api]: [I-D.ietf-shim6-multihome-shim-api]:
+-----------------------------+-----+-----+-----------------+-------+ +-----------------------------+-----+-----+-----------------+-------+
| optname | get | set | description | dtype | | optname | get | set | description | dtype |
+-----------------------------+-----+-----+-----------------+-------+ +-----------------------------+-----+-----+-----------------+-------+
| SHIM_LOC_LOCAL_PREF | o | o | Get or set the | *1 | | SHIM_LOC_LOCAL_PREF | o | o | Get or set the | *1 |
| | | | preferred | | | | | | preferred | |
| | | | locator on the | | | | | | locator on the | |
skipping to change at page 14, line 11 skipping to change at page 14, line 11
Figure 6 Figure 6
Finally, the application creates a valid sockaddr_hip structure and Finally, the application creates a valid sockaddr_hip structure and
associates the socket also with the sockaddr_hip structure by calling associates the socket also with the sockaddr_hip structure by calling
some socket-related function, such as connect() or bind(). some socket-related function, such as connect() or bind().
The usage and semantics for typical use cases are as follows: The usage and semantics for typical use cases are as follows:
An application that initiates a connection using a connection An application that initiates a connection using a connection
oriented socket to a particular host at a known address or set of oriented socket to a particular host at a known address or set of
addresses can call SHIM_LOCLIST_PEER socket option. The HIP module addresses can invoke SHIM_LOCLIST_PEER socket option. The HIP module
uses the the first address (if multiple are provided, or else the uses the first address (if multiple are provided, or else the
application can override this by setting SHIM_LOC_PEER_PREF to one of application can override this by setting SHIM_LOC_PEER_PREF to one of
the addresses in SHIM_LOCLIST_PEER. The application later provides a the addresses in SHIM_LOCLIST_PEER. The application later provides a
specific HIT in the ship_hit field of the sockaddr_hip in the specific HIT in the ship_hit field of the sockaddr_hip in the
connect() system call. If the application provides one or more connect() system call. If the application provides one or more
addresses in SHIM_LOCLIST_PEER setsockopt call, the system should not addresses in SHIM_LOCLIST_PEER setsockopt call, the system should not
connect to the host via another destination address, in case the connect to the host via another destination address, in case the
application intends to restrict the range of addresses permissable as application intends to restrict the range of addresses permissible as
a policy choice. If the system cannot reach the provided HIT at one a policy choice. If the system cannot reach the provided HIT at one
of the addresses provided, the outbound socket API functions of the addresses provided, the outbound socket API functions
(connect, sendmsg, etc.) return -1 and set errno to EINVALIDLOCATOR. (connect, sendmsg, etc.) return -1 and set errno to EINVALIDLOCATOR.
Another common use case is to set up an association in opportunistic Another common use case is to set up an association in opportunistic
mode, when the destination HIT is specified as a wildcard. This can mode, when the destination HIT is specified as a wildcard. This can
be accomplished by setting one or more destination addresses using be accomplished by setting one or more destination addresses using
the SHIM_LOCLIST_PEER socket option as described above and then the SHIM_LOCLIST_PEER socket option as described above and then
calling connect() with the wildcard HIT. The connect() call returns calling connect() with the wildcard HIT. The connect() call returns
-1 and sets errno to EADDRNOTAVAIL when the application connected to -1 and sets errno to EADDRNOTAVAIL when the application connects to a
a wildcard without specifying any destination address. wildcard without specifying any destination address.
Applications may also choose to associate local addresses with Applications may also choose to associate local addresses with
sockets. The procedures specified in sockets. The procedures specified in
[I-D.ietf-shim6-multihome-shim-api] are followed in this case. [I-D.ietf-shim6-multihome-shim-api] are followed in this case.
5. Summary of New Definitions 5. Summary of New Definitions
Table 4 summarizes the new macro and structures defined in this Table 4 summarizes the new macro and structures defined in this
document. document.
+-----------------+-----------------------------+ +-----------------+-----------------------------+
| Header | Definition | | Header | Definition |
+-----------------+-----------------------------+ +-----------------+-----------------------------+
| <sys/socket.h> | PF_HIP |
| <sys/socket.h> | AF_HIP | | <sys/socket.h> | AF_HIP |
| <sys/socket.h> | PF_HIP |
| <netinet/in.h> | IPPROTO_HIP | | <netinet/in.h> | IPPROTO_HIP |
| <netinet/hip.h> | HIP_HIT_ANY | | <netinet/hip.h> | HIP_HIT_ANY |
| <netinet/hip.h> | HIP_HIT_ANY_PUB | | <netinet/hip.h> | HIP_HIT_ANY_PUB |
| <netinet/hip.h> | HIP_HIT_ANY_TMP | | <netinet/hip.h> | HIP_HIT_ANY_TMP |
| <netinet/hip.h> | HIP_ADDR_ANY | | <netinet/hip.h> | HIP_ADDR_ANY |
| <netinet/hip.h> | HIP_HIT_PREFERENCES | | <netinet/hip.h> | HIP_HIT_PREFERENCES |
| <netinet/hip.h> | hip_hit_t | | <netinet/hip.h> | hip_hit_t |
| <netdb.h> | HIP_PREFER_ORCHID | | <netdb.h> | HIP_PREFER_ORCHID |
| <netdb.h> | HIP_PREFER_SRC_TMP | | <netdb.h> | HIP_PREFER_SRC_TMP |
| <netdb.h> | HIP_PREFER_SRC_PUBLIC | | <netdb.h> | HIP_PREFER_SRC_PUBLIC |
| <netdb.h> | HIP_PREFER_PASSIVE_HIT_TMP | | <netdb.h> | HIP_PREFER_PASSIVE_HIT_TMP |
| <netdb.h> | HIP_PREFER_PASSIVE_HIT_PUB | | <netdb.h> | HIP_PREFER_PASSIVE_HIT_PUB |
| <netdb.h> | HIP_PREFER_PASSIVE_HIT_ANY | | <netdb.h> | HIP_PREFER_PASSIVE_HIT_ANY |
| <netdb.h> | HIP_PREFER_PASSIVE_ADDR_ANY | | <netdb.h> | HIP_PREFER_PASSIVE_ADDR_ANY |
| <netinet/in.h> | sockaddr_hip | | <netinet/hip.h> | sockaddr_hip |
| <netinet/in.h> | sockaddr_is_srcaddr | | <netinet/hip.h> | sockaddr_is_srcaddr |
+-----------------+-----------------------------+ +-----------------+-----------------------------+
Table 4 Table 4
6. IANA Considerations 6. IANA Considerations
No IANA considerations. No IANA considerations.
7. Security Considerations 7. Security Considerations
No security considerations currently. No security considerations currently.
8. Acknowledgements 8. Contributors
Jukka Ylitalo and Pekka Nikander have contributed many ideas, time Thanks for Jukka Ylitalo and Pekka Nikander for their original
and effort to the native HIP APIs. Kristian Slavov, Julien Laganier, contribution, time and effort to the native HIP APIs. Thanks for
Jaakko Kangasharju, Mika Kousa, Jan Melen, Andrew McGregor, Sasu Yoshifuji Hideaki for his contributions to this document.
Tarkoma, Lars Eggert, Joe Touch, Antti Jaervinen, Anthony Joseph,
Teemu Koponen, Jari Arkko, Ari Keraenen, Juha-Matti Tapio, Shinta
Sugimoto, Philip Matthews, Jan Melen and Gonzalo Camarillo have also
provided valuable ideas or feedback. Thanks for the APPS area folks,
Stephane Bortzmeyer, Chris Newman, Tony Finch, "der Mouse" and Keith
Moore for comments.
9. Normative References 9. Acknowledgements
Kristian Slavov, Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan
Melen, Andrew McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti
Jaervinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari Keraenen,
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.
10. Normative References
[I-D.ietf-btns-c-api] [I-D.ietf-btns-c-api]
Richardson, M., Williams, N., Komu, M., and S. Tarkoma, Richardson, M., Williams, N., Komu, M., and S. Tarkoma,
"IPsec Application Programming Interfaces", "IPsec Application Programming Interfaces",
draft-ietf-btns-c-api-03 (work in progress), draft-ietf-btns-c-api-03 (work in progress),
February 2008. February 2008.
[I-D.ietf-hip-applications] [I-D.ietf-hip-applications]
Henderson, T., Nikander, P., and M. Komu, "Using the Host Henderson, T., Nikander, P., and M. Komu, "Using the Host
Identity Protocol with Legacy Applications", Identity Protocol with Legacy Applications",
draft-ietf-hip-applications-02 (work in progress), draft-ietf-hip-applications-04 (work in progress),
November 2007. July 2008.
[I-D.ietf-hip-base]
Moskowitz, R., Nikander, P., Jokela, P., and T. Henderson,
"Host Identity Protocol", draft-ietf-hip-base-10 (work in
progress), October 2007.
[I-D.ietf-hip-dns]
Nikander, P. and J. Laganier, "Host Identity Protocol
(HIP) Domain Name System (DNS) Extensions",
draft-ietf-hip-dns-09 (work in progress), April 2007.
[I-D.ietf-shim6-multihome-shim-api] [I-D.ietf-shim6-multihome-shim-api]
Komu, M., Bagnulo, M., Slavov, K., and S. Sugimoto, Komu, M., Bagnulo, M., Slavov, K., and S. Sugimoto,
"Socket Application Program Interface (API) for "Socket Application Program Interface (API) for
Multihoming Shim", draft-ietf-shim6-multihome-shim-api-05 Multihoming Shim", draft-ietf-shim6-multihome-shim-api-05
(work in progress), February 2008. (work in progress), February 2008.
[I-D.ietf-shim6-proto] [I-D.ietf-shim6-proto]
Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming
Shim Protocol for IPv6", draft-ietf-shim6-proto-10 (work Shim Protocol for IPv6", draft-ietf-shim6-proto-10 (work
skipping to change at page 17, line 13 skipping to change at page 17, line 9
(HIP) Architecture", RFC 4423, May 2006. (HIP) Architecture", RFC 4423, May 2006.
[RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix [RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix
for Overlay Routable Cryptographic Hash Identifiers for Overlay Routable Cryptographic Hash Identifiers
(ORCHID)", RFC 4843, April 2007. (ORCHID)", RFC 4843, April 2007.
[RFC5014] Nordmark, E., Chakrabarti, S., and J. Laganier, "IPv6 [RFC5014] Nordmark, E., Chakrabarti, S., and J. Laganier, "IPv6
Socket API for Source Address Selection", RFC 5014, Socket API for Source Address Selection", RFC 5014,
September 2007. September 2007.
[RFC5201] Moskowitz, R., Nikander, P., Jokela, P., and T. Henderson,
"Host Identity Protocol", RFC 5201, April 2008.
[RFC5205] Nikander, P. and J. Laganier, "Host Identity Protocol
(HIP) Domain Name System (DNS) Extensions", RFC 5205,
April 2008.
Authors' Addresses Authors' Addresses
Miika Komu Miika Komu
Helsinki Institute for Information Technology Helsinki Institute for Information Technology
Metsaenneidonkuja 4 Metsaenneidonkuja 4
Helsinki Helsinki
Finland Finland
Phone: +358503841531 Phone: +358503841531
Fax: +35896949768 Fax: +35896949768
skipping to change at page 18, line 44 skipping to change at line 792
attempt made to obtain a general license or permission for the use of attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr. http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at this standard. Please address the information to the IETF at
ietf-ipr@ietf.org. ietf-ipr@ietf.org.
Acknowledgment
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
 End of changes. 37 change blocks. 
77 lines changed or deleted 82 lines changed or added

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