draft-ietf-hip-native-api-12.txt   rfc6317.txt 
Host Identity Protocol M. Komu Internet Engineering Task Force (IETF) M. Komu
Internet-Draft Helsinki Institute for Information Request for Comments: 6317 Aalto University
Intended status: Experimental Technology Category: Experimental T. Henderson
Expires: July 15, 2010 T. Henderson ISSN: 2070-1721 The Boeing Company
The Boeing Company July 2011
January 11, 2010
Basic Socket Interface Extensions for Host Identity Protocol (HIP) Basic Socket Interface Extensions for
draft-ietf-hip-native-api-12 the Host Identity Protocol (HIP)
Abstract Abstract
This document defines extensions to the current sockets API for the This document defines extensions to the current sockets API for the
Host Identity Protocol (HIP). The extensions focus on the use of Host Identity Protocol (HIP). The extensions focus on the use of
public-key based identifiers discovered via DNS resolution, but public-key-based identifiers discovered via DNS resolution, but also
define also interfaces for manual bindings between HITs and locators. define interfaces for manual bindings between Host Identity Tags
With the extensions, the application can also support more relaxed (HITs) and locators. With the extensions, the application can also
security models where the communication can be non-HIP based, support more relaxed security models where communication can be non-
according to local policies. The extensions in this document are HIP-based, according to local policies. The extensions in this
experimental and provide basic tools for further experimentation with document are experimental and provide basic tools for further
policies. experimentation with policies.
Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months Status of This Memo
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at This document is not an Internet Standards Track specification; it is
http://www.ietf.org/ietf/1id-abstracts.txt. published for examination, experimental implementation, and
evaluation.
The list of Internet-Draft Shadow Directories can be accessed at This document defines an Experimental Protocol for the Internet
http://www.ietf.org/shadow.html. community. This document is a product of the Internet Engineering
Task Force (IETF). It represents the consensus of the IETF
community. It has received public review and has been approved for
publication by the Internet Engineering Steering Group (IESG). Not
all documents approved by the IESG are a candidate for any level of
Internet Standard; see Section 2 of RFC 5741.
This Internet-Draft will expire on July 15, 2010. Information about the current status of this document, any errata,
and how to provide feedback on it may be obtained at
http://www.rfc-editor.org/info/rfc6317.
Copyright Notice Copyright Notice
Copyright (c) 2010 IETF Trust and the persons identified as the
Copyright (c) 2011 IETF Trust and the persons identified as the
document authors. All rights reserved. document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents Provisions Relating to IETF Documents
(http://trustee.ietf.org/license-info) in effect on the date of (http://trustee.ietf.org/license-info) in effect on the date of
publication of this document. Please review these documents publication of this document. Please review these documents
carefully, as they describe your rights and restrictions with respect carefully, as they describe your rights and restrictions with respect
to this document. Code Components extracted from this document must to this document. Code Components extracted from this document must
include Simplified BSD License text as described in Section 4.e of include Simplified BSD License text as described in Section 4.e of
the Trust Legal Provisions and are provided without warranty as the Trust Legal Provisions and are provided without warranty as
described in the BSD License. described in the Simplified BSD License.
This document may contain material from IETF Documents or IETF This document may contain material from IETF Documents or IETF
Contributions published or made publicly available before November Contributions published or made publicly available before November
10, 2008. The person(s) controlling the copyright in some of this 10, 2008. The person(s) controlling the copyright in some of this
material may not have granted the IETF Trust the right to allow material may not have granted the IETF Trust the right to allow
modifications of such material outside the IETF Standards Process. modifications of such material outside the IETF Standards Process.
Without obtaining an adequate license from the person(s) controlling Without obtaining an adequate license from the person(s) controlling
the copyright in such materials, this document may not be modified the copyright in such materials, this document may not be modified
outside the IETF Standards Process, and derivative works of it may outside the IETF Standards Process, and derivative works of it may
not be created outside the IETF Standards Process, except to format not be created outside the IETF Standards Process, except to format
it for publication as an RFC or to translate it into languages other it for publication as an RFC or to translate it into languages other
than English. than English.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 4 1. Introduction ....................................................3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 5 2. Terminology .....................................................5
3. Name Resolution Process . . . . . . . . . . . . . . . . . . . 6 3. Name Resolution Process .........................................5
3.1. Interaction with the Resolver . . . . . . . . . . . . . . 6 3.1. Interaction with the Resolver ..............................5
3.2. Interaction without a Resolver . . . . . . . . . . . . . . 7 3.2. Interaction without a Resolver .............................6
4. API Syntax and Semantics . . . . . . . . . . . . . . . . . . . 8 4. API Syntax and Semantics ........................................7
4.1. Socket Family and Address Structure Extensions . . . . . . 8 4.1. Socket Family and Address Structure Extensions .............7
4.2. Extensions to Resolver Data Structures . . . . . . . . . . 10 4.2. Extensions to Resolver Data Structures .....................9
4.3. The Use of getsockname and getpeername Functions . . . . . 12 4.3. The Use of getsockname() and getpeername() Functions ......12
4.4. Selection of Source HIT Type . . . . . . . . . . . . . . . 13 4.4. Selection of Source HIT Type ..............................12
4.5. Verification of HIT Type . . . . . . . . . . . . . . . . . 13 4.5. Verification of HIT Type ..................................13
4.6. Explicit Handling of Locators . . . . . . . . . . . . . . 15 4.6. Explicit Handling of Locators .............................14
5. Summary of New Definitions . . . . . . . . . . . . . . . . . . 16 5. Summary of New Definitions .....................................16
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16 6. Security Considerations ........................................16
7. Security Considerations . . . . . . . . . . . . . . . . . . . 17 7. Contributors ...................................................17
8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 17 8. Acknowledgments ................................................17
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17 9. References .....................................................17
10. References . . . . . . . . . . . . . . . . . . . . . . . . . . 18 9.1. Normative References ......................................17
10.1. Normative References . . . . . . . . . . . . . . . . . . . 18 9.2. Informative References ....................................18
10.2. Informative References . . . . . . . . . . . . . . . . . . 18
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 18
1. Introduction 1. Introduction
This document defines the C-based sockets Application Programming This document defines the C-based sockets Application Programming
Interface (API) extensions for handling Host Identity Protocol (HIP)- Interface (API) extensions for handling HIP-based identifiers
based identifiers explicitly in HIP-aware applications. It is up to explicitly in HIP-aware applications. It is up to the applications,
the applications, or high-level programming languages or libraries, or high-level programming languages or libraries, to manage the
to manage the identifiers. The extensions in this document are identifiers. The extensions in this document are mainly related to
mainly related to the use case in which a DNS resolution step has the use case in which a DNS resolution step has occurred prior to the
occurred prior to the creation of a new socket, and assumes that the creation of a new socket, and assumes that the system has cached or
system has cached or is otherwise able to resolve identifiers to is otherwise able to resolve identifiers to locators (IP addresses).
locators (IP addresses). The DNS extensions for HIP are described in The DNS extension for HIP is described in [RFC5205]. The extensions
[RFC5205]. The extensions also cover the case in which an also cover the case in which an application may want to explicitly
application may want to explicitly provide suggested locators with provide suggested locators with the identifiers, including supporting
the identifiers, including supporting the opportunistic case in which the opportunistic case in which the system does not know the peer
the system does not know the peer host identity. 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 endpoint
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 [RFC5533] is another protocol based on an identity- stack. Shim6 [RFC5533] is another protocol based on an identity-
locator split. The APIs specified in this document are specific to 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 HIP, but have been designed as much as possible to not preclude its
its use with other protocols. The use of these APIs with other use with other protocols. The use of these APIs with other protocols
protocols is, nevertheless, for further study. is, nevertheless, for further study.
The APIs in this document are based on HITs that are defined as IPv6 The APIs in this document are based on Host Identity Tags (HITs) that
addresses with the Overlay Routable Cryptographic Host Identifiers are defined as IPv6 addresses with the Overlay Routable Cryptographic
(ORCHID) prefix [RFC4843]. ORCHIDs are derived from Host Identifiers Hash Identifiers (ORCHID) prefix [RFC4843]. ORCHIDs are derived from
using a hash and fitting the result into an IPv6 address. Such Host Identifiers using a hash and fitting the result into an IPv6
addresses are called Host Identity Tags (HITs) and they can be address. Such addresses are called HITs, and they can be
distinguished from other IPv6 addresses via the ORCHID prefix. Note distinguished from other IPv6 addresses via the ORCHID prefix. Note
that ORCHIDs are presently an experimental allocation by IANA. If that ORCHIDs are presently an experimental allocation by IANA. If
the ORCHID allocation were to expire and HIT generation were to use a the ORCHID allocation were to expire and HIT generation were to use a
different prefix in the future, most users of the API would not be different prefix in the future, most users of the API would not be
impacted, unless they explicitly checked the ORCHID prefix on impacted, unless they explicitly checked the ORCHID prefix on
returned HITs. Users who check (for consistency) that HITs have a returned HITs. Users who check (for consistency) that HITs have a
valid ORCHID prefix must monitor the IANA allocation for ORCHIDs and valid ORCHID prefix must monitor the IANA allocation for ORCHIDs and
adapt their software in case the ORCHID allocation were to be removed adapt their software in case the ORCHID allocation were to be removed
at a future date. at a future date.
skipping to change at page 5, line 14 skipping to change at page 4, line 14
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. Similarly to other address families, socket address family, AF_HIP. Similarly to other address families,
AF_HIP can be used as an alias for PF_HIP. The extensions also AF_HIP can be used as an alias for PF_HIP. The extensions also
describe a new socket address structure for sockets using HITs describe a new socket address structure for sockets using 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
(section 4.1.6 in [RFC5201]) by just relying on a peer locator. This (Section 4.1.6 of [RFC5201]) by just relying on a peer locator. This
document describes how to address both situations using "wildcards" document describes how to address both situations using "wildcards"
as described in Section 4.1.1. as described in Section 4.1.1.
This document references one additional API document that handles This document references one additional API document [RFC6316] that
multihoming and explicit-locator handling, defined in defines multihoming and explicit-locator handling. Most of the
[I-D.ietf-shim6-multihome-shim-api]. Most of the extensions defined extensions defined in this document can be used independently of the
in this document can be used independently of the above document. above document.
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
mode, and manual bindings between HITs and locators. The extensions mode, and manual bindings between HITs and locators. The extensions
in this document are of an experimental nature and provide basic in this document are of an experimental nature and provide basic
tools for experimenting with policies. Policy related issues are tools for experimenting with policies. Policy-related issues are
left for further experimentation. left for further experimentation.
To recap, the extensions in this document have three goals. The To recap, the extensions in this document have three goals. The
first goal is to allow HIP-aware applications to open sockets to first goal is to allow HIP-aware applications to open sockets to
other hosts based on the HITs alone, presuming that the underlying other hosts based on the HITs alone, presuming that the underlying
system can resolve the HITs to addresses used for initial contact. system can resolve the HITs to addresses used for initial contact.
The second goal is that applications can explicitly initiate The second goal is that applications can explicitly initiate
communications with unknown peer identifiers. The third goal is to communications with unknown peer identifiers. The third goal is to
illustrate how HIP-aware applications can use the SHIM API illustrate how HIP-aware applications can use the Shim API [RFC6316]
[I-D.ietf-shim6-multihome-shim-api] to manually map locators to HITs. to manually map locators to HITs.
This document was published as experimental because a number of its This document was published as experimental because a number of its
normative references had experimental status. The success of this normative references had experimental status. The success of this
experiment can be evaluated by a thorough implementation of the APIs experiment can be evaluated by a thorough implementation of the APIs
defined. defined.
2. Terminology 2. Terminology
The terms used in this document are summarized in Table 1. The terms used in this document are summarized in Table 1.
+---------+---------------------------------------------------------+ +---------+--------------------------------------------------------+
| Term | Explanation | | Term | Explanation |
+---------+---------------------------------------------------------+ +---------+--------------------------------------------------------+
| FQDN | Fully Qualified Domain Name | | FQDN | Fully Qualified Domain Name |
| HIP | Host Identity Protocol | | HIP | Host Identity Protocol |
| HI | Host Identity | | HI | Host Identifier |
| HIT | Host Identity Tag, a 100-bit hash of a public key with | | HIT | Host Identity Tag, a 100-bit hash of a public key with |
| | a 28 bit prefix | | | a 28-bit prefix |
| LSI | Local Scope Identifier, a local, 32-bit descriptor for | | LSI | Local Scope Identifier, a local, 32-bit descriptor for |
| | a given public key. | | | a given public key |
| Locator | Routable IPv4 or IPv6 address used at the lower layers | | Locator | Routable IPv4 or IPv6 address used at the lower layers |
| RR | Return Routability | | RR | Resource Record |
+---------+---------------------------------------------------------+ +---------+--------------------------------------------------------+
Table 1 Table 1
3. Name Resolution Process 3. Name Resolution Process
This section provides an overview of how the API can be used. First, 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 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, and then the case in which no resolver is involved is
described. described.
3.1. Interaction with the Resolver 3.1. Interaction with the Resolver
Before an application can establish network communications with the Before an application can establish network communications with the
entity named by a given FQDN or relative host name, the application entity named by a given FQDN or relative hostname, the application
must translate the name into the corresponding identifier(s). DNS- must translate the name into the corresponding identifier(s). DNS-
based hostname-to-identifier translation is illustrated in Figure 1. based hostname-to-identifier translation is illustrated in Figure 1.
The application calls the resolver in step (a) to resolve an FQDN to The application calls the resolver in step (a) to resolve an FQDN to
one or more socket addresses within the PF_HIP family. The resolver, one or more socket addresses within the PF_HIP family. The resolver,
in turn, queries the DNS in step (b) to map the FQDN to one or more in turn, queries the DNS in step (b) to map the FQDN to one or more
HIP RRs with the HIT and HI and possibly rendezvous server of the HIP RRs with the HIT and HI and possibly the rendezvous server of the
Responder, and also (in parallel or sequentially) to resolve the FQDN Responder, and also (in parallel or sequentially) to resolve the FQDN
into possibly one or more A and AAAA records. It should be noted into possibly one or more A and AAAA records. It should be noted
that the FQDN may map to multiple host identifiers and locators, and that the FQDN may map to multiple Host Identifiers and locators, and
this step may involve multiple DNS transactions, including queries this step may involve multiple DNS transactions, including queries
for A, AAAA, HI and possibly other resource records. The DNS server for A, AAAA, HI, and possibly other resource records. The DNS server
responds with a list of HIP resource records in step (c). Optionally responds with a list of HIP resource records in step (c).
in step (d), the resolver caches the HIT-to-locator mapping with the Optionally, in step (d), the resolver caches the HIT-to-locator
HIP module. The resolver converts the HIP records to HITs and mapping with the HIP module. The resolver converts the HIP records
returns the HITs to the application contained in HIP socket address to HITs and returns the HITs to the application contained in HIP
structures in step (e). Depending on the parameters for the resolver socket address structures in step (e). Depending on the parameters
call, the resolver may return also other socket address structures to for the resolver call, the resolver may also return other socket
the application. Finally, the application receives the socket address structures to the application. Finally, the application
address structure(s) from the resolver and uses them in socket calls receives the socket address structure(s) from the resolver and uses
such as connect() in step (f). them in socket calls such as connect() in step (f).
+----------+ +----------+
| | | |
| DNS | | DNS |
| | | |
+----------+ +----------+
^ | ^ |
b. QNAME=FQDN | | c. HIP and b. QNAME=FQDN | | c. HIP and
| | A/AAAA | | A/AAAA
| v RR(s) | v RR(s)
skipping to change at page 7, line 39 skipping to change at page 6, line 42
Figure 1 Figure 1
In practice, the resolver functionality can be implemented in In practice, the resolver functionality can be implemented in
different ways. For example, it may be implemented in existing different ways. For example, it may be implemented in existing
resolver libraries or as a HIP-aware interposing agent. resolver libraries or as a HIP-aware interposing agent.
3.2. Interaction without a Resolver 3.2. Interaction without a Resolver
The extensions in this document focus on the use of the resolver to 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 map hostnames to HITs and locators in HIP-aware applications. The
resolver may implicitly associate a HIT with the corresponding resolver may implicitly associate a HIT with the corresponding
locator(s) by communicating the HIT-to-IP mapping to the HIP daemon. locator(s) by communicating the HIT-to-IP mapping to the HIP daemon.
However, it is possible that an application operates directly on a However, it is possible that an application operates directly on a
peer HIT without interacting with the resolver. In such a case, the 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 application may resort to the system to map the peer HIT to an IP
address. Alternatively, the application can explicitly map the HIT address. Alternatively, the application can explicitly map the HIT
to an IP address using socket options as specified in Section 4.6. to an IP address using socket options as specified in Section 4.6.
Full support for all of the extensions defined in this draft requires Full support for all of the extensions defined in this document
a number of shim socket options [I-D.ietf-shim6-multihome-shim-api] requires a number of shim socket options [RFC6316] to be implemented
to be implemented by the system. by the system.
4. API Syntax and Semantics 4. API Syntax and Semantics
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 constants are a new address family, AF_HIP. The AF_HIP and PF_HIP constants are
aliases to each other. These definitions shall be defined as a aliases to each other. These definitions shall be defined as a
result of including <sys/socket.h>. result of including <sys/socket.h>.
When the socket() function is called with PF_HIP as the first When the socket() function is called with PF_HIP as the first
argument (domain), it attempts to create a socket for HIP argument (domain), it attempts to create a socket for HIP
communication. If HIP is not supported, socket() follows its default communication. If HIP is not supported, socket() follows its default
behaviour and returns -1 and sets errno to EAFNOSUPPORT. behavior and returns -1, and sets errno to EAFNOSUPPORT.
Figure 2 shows the recommended implementation of the socket address Figure 2 shows the recommended implementation of the socket address
structure for HIP in POSIX format. structure for HIP in Portable Operating System Interface (POSIX)
format.
#include <netinet/hip.h> #include <netinet/hip.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; uint8_t ship_len;
sa_family_t ship_family; sa_family_t ship_family;
in_port_t ship_port; in_port_t ship_port;
uint32_t ship_flags; uint32_t ship_flags;
hip_hit_t ship_hit; hip_hit_t ship_hit;
}; };
Figure 2 Figure 2
uint8_t ship_len: This field defines the length of the structure. uint8_t ship_len: This field defines the length of the structure.
Implementations that do not define this field typically embed the Implementations that do not define this field typically embed the
information in the following ship_family field. information in the following ship_family field.
sa_family_t ship_family: This mandatory field identifies this as a sa_family_t ship_family: This mandatory field identifies the
sockaddr_hip structure. It overlays the sa_family field of the structure as a sockaddr_hip structure. It overlays the sa_family
sockaddr structure. Its value must be AF_HIP. field of the sockaddr structure. Its value must be AF_HIP.
in_port_t ship_port: This mandatory field contains the transport in_port_t ship_port: This mandatory field contains the transport
protocol port number. It is handled in the same way as the sin_port protocol port number. It is handled in the same way as the sin_port
field of the sockaddr_in structure. The port number is stored in field of the sockaddr_in structure. The port number is stored in
network byte order. network byte order.
uint32_t ship_flags: This mandatory bit field contains auxiliary uint32_t ship_flags: This mandatory bit field contains auxiliary
flags. This document does not define any flags. This field is flags. This document does not define any flags. This field is
included for future extensions. included for future extensions.
hip_hit_t ship_hit: This mandatory field contains the end-point hip_hit_t ship_hit: This mandatory field contains the endpoint
identifier. When the system passes a sockaddr_hip structure to the identifier. When the system passes a sockaddr_hip structure to the
application, the value of this field is set to a valid HIT, IPv4, or application, the value of this field is set to a valid HIT, IPv4, or
IPv6 address, as discussed in Section 4.5. When the application IPv6 address, as discussed in Section 4.5. When the application
passes a sockaddr_hip structure to the system, this field must be set passes a sockaddr_hip structure to the system, this field must be set
to a HIT or a wildcard address as discussed in Section 4.1.1. to a HIT or a wildcard address as discussed in Section 4.1.1.
Some applications rely on system level access control, either Some applications rely on system-level access control, either
implicit or explicit (such as the accept_filter() function found on implicit or explicit (such as the accept_filter() function found on
BSD-based systems), but such discussion is out of scope. Other BSD-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.
Applications operating on sockaddr_hip structures can use memcmp() or Applications operating on sockaddr_hip structures can use memcmp() or
similar function to compare the ship_hit fields. It should be also a similar function to compare the ship_hit fields. It should also be
noted that different connection attempts between the same two hosts noted that different connection attempts between the same two hosts
can result in different HITs because a host is allowed to have can result in different HITs, because a host is allowed to have
multiple HITs. multiple HITs.
4.1.1. HIP Wildcard Addresses 4.1.1. HIP Wildcard Addresses
HIP wildcard addresses are similar to IPv4 and IPv6 wildcard HIP wildcard addresses are similar to IPv4 and IPv6 wildcard
addresses. They can be used instead of specific HITs in the ship_hit addresses. They can be used instead of specific HITs in the ship_hit
field for local and remote end-points in socket API calls such as field for local and remote endpoints in sockets API calls such as
bind(), connect(), sendto(), sendmsg(). bind(), connect(), sendto(), or sendmsg().
In order to bind to all local IPv4 and IPv6 addresses and HIP HITs, In order to bind to all local IPv4 and IPv6 addresses and HIP HITs,
the ship_hit field must be set to HIP_ENDPOINT_ANY. In order to bind the ship_hit field must be set to HIP_ENDPOINT_ANY. In order to bind
to all local HITs, ship_hit must contain HIP_HIT_ANY. To only bind to all local HITs, ship_hit must contain HIP_HIT_ANY. To only bind
to all local public HITs, the ship_hit field must be HIP_HIT_ANY_PUB. to all local public HITs, the ship_hit field must be HIP_HIT_ANY_PUB.
The value HIP_HIT_ANY_TMP binds a socket to all local anonymous The value HIP_HIT_ANY_TMP binds a socket to all local anonymous
identifiers only as specified in [RFC4423]. The system may label identifiers only as specified in [RFC4423]. The system may label
anonymous identifiers as such depending on whether they have been anonymous identifiers as such depending on whether they have been
published or not. After binding a socket via one of the published or not. After binding a socket via one of the
HIP_HIT_ANY_* wildcard addresses, the application is guaranteed to HIP_HIT_ANY_* wildcard addresses, the application is guaranteed to
receive only HIP-based data flows. With the HIP_ENDPOINT_ANY receive only HIP-based data flows. With the HIP_ENDPOINT_ANY
wildcard address, the socket accepts HIP, IPv6, and IPv4-based data wildcard address, the socket accepts HIP, IPv6, and IPv4-based data
flows. flows.
When a socket is bound or connected via a sockaddr_hip structure, When a socket is bound or connected via a sockaddr_hip structure,
i.e. the PF_HIP protocol family, the system returns only addresses of i.e., the PF_HIP protocol family, the system returns only addresses
the AF_HIP family, i.e. sockaddr_hip structures, for this socket. of the AF_HIP family, i.e., sockaddr_hip structures, for this socket.
This applies to all functions which provide addresses to the This applies to all functions that provide addresses to the
application, such as accept() or recvfrom(). If the data flow is application, such as accept() or recvfrom(). If the data flow is
based on HIP, the ship_hit field contains the peer's HIT. For a non- based on HIP, the ship_hit field contains the peer's HIT. For a
HIP IPv6 data flow, the field contains the peer's IPv6 address. For non-HIP IPv6 data flow, the field contains the peer's IPv6 address.
a non-HIP IPv4 data flow, the field contains the peer's IPv4 address For a non-HIP IPv4 data flow, the field contains the peer's IPv4
in IPv4-mapped IPv6 address format as described in section 3.7 of address in IPv4-mapped IPv6 address format as described in
[RFC3493]. Section 4.5 describes how the application can verify the Section 3.7 of [RFC3493]. Section 4.5 describes how the application
type of the address returned by the socket API calls. can verify the type of address returned by the sockets API calls.
An application uses the socket API as follows to set up a connection An application uses the sockets API as follows to set up a connection
or to send messages in HIP Opportunistic Mode (cf. [RFC5201]). or to send messages in HIP opportunistic mode (cf. [RFC5201]).
First, the application associates a socket with at least one IP First, the application associates a socket with at least one IP
address of the destination peer via setting the address of the destination peer via setting the
SHIM_LOCLIST_PEER_PREF socket option. It then uses outgoing socket SHIM_LOCLIST_PEER_PREF socket option. It then uses outgoing socket
functions such as connect(), sendto(), or sendmsg() with the functions such as connect(), sendto(), or sendmsg() with the
HIP_ENDPOINT_ANY or HIP_HIT_ANY wildcard address in the ship_hit HIP_ENDPOINT_ANY or HIP_HIT_ANY wildcard address in the ship_hit
field of the sockaddr_hip structure. With the HIP_HIT_ANY address, field of the sockaddr_hip structure. With the HIP_HIT_ANY address,
the underlying system allows only HIP-based data flows with the the underlying system allows only HIP-based data flows with the
corresponding socket. For incoming packets, the system discards all corresponding socket. For incoming packets, the system discards all
non-HIP-related traffic arriving at the socket. For outgoing non-HIP-related traffic arriving at the socket. For outgoing
packets, the system returns -1 in the socket call and sets errno to packets, the system returns -1 in the socket call and sets errno to
an appropriate error type when the system failed to deliver the an appropriate error type when the system failed to deliver the
packet over a HIP-based data channel. The semantics of using the packet over a HIP-based data channel. The semantics of using
HIP_ENDPOINT_ANY are the subject of further experimentation in the HIP_ENDPOINT_ANY are the subject of further experimentation in the
context of opportunistic mode. Such use may result in a data flow context of opportunistic mode. Such use may result in a data flow
either with or without HIP. either with or without HIP.
4.2. Extensions to Resolver Data Structures 4.2. Extensions to Resolver Data Structures
The HIP APIs introduce a new address family, AF_HIP, that HIP-aware The HIP APIs introduce a new address family, AF_HIP, that HIP-aware
applications can use to control the address type returned from the applications can use to control the address type returned from the
getaddrinfo() function [RFC3493], [POSIX]. The getaddrinfo() getaddrinfo() function [RFC3493] [POSIX]. The getaddrinfo() function
function uses a data structure called addrinfo in its "hints" and uses a data structure called addrinfo in its "hints" and "res"
"res" argument which is described in more detail in the next section. arguments, which are described in more detail in the next section.
The addrinfo data structure is illustrated in Figure 3. The addrinfo data structure is illustrated in Figure 3.
#include <netdb.h> #include <netdb.h>
struct addrinfo {
int ai_flags; /* e.g., AI_CANONNAME */
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; /* RFC 5014 extension */
};
struct addrinfo {
int ai_flags; /* e.g. AI_CANONNAME */
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 */
};
Figure 3 Figure 3
An application resolving with the ai_family field set to AF_UNSPEC in An application resolving with the ai_family field set to AF_UNSPEC in
the hints argument may receive any kind of socket address structures, the hints argument may receive any kind of socket address structures,
including sockaddr_hip. When the application wants to receive only including sockaddr_hip. When the application wants to receive only
HITs contained in sockaddr_hip structures, it should set the HITs contained in sockaddr_hip structures, it should set the
ai_family field to AF_HIP. Otherwise, the resolver does not return ai_family field to AF_HIP. Otherwise, the resolver does not return
any sockaddr_hip structures. The resolver returns EAI_FAMILY when any sockaddr_hip structures. The resolver returns EAI_FAMILY when
AF_HIP is requested but not supported. AF_HIP is requested but not supported.
The resolver ignores the AI_PASSIVE flag when the application sets The resolver ignores the AI_PASSIVE flag when the application sets
the family in hints to AF_HIP. the family in hints to AF_HIP.
The system may have a HIP-aware interposing DNS agent as described in The system may have a HIP-aware interposing DNS agent as described in
section 3.2 in [RFC5338]. In such a case, the DNS agent may, Section 3.2 of [RFC5338]. In such a case, the DNS agent may,
according to local policy, return transparently LSIs or HITs in according to local policy, transparently return LSIs or HITs in
sockaddr_in and sockaddr_in6 structures when available. A HIP-aware sockaddr_in and sockaddr_in6 structures when available. A HIP-aware
application can override this local policy in two ways. First, the application can override this local policy in two ways. First, the
application can set the family to AF_HIP in the hints argument of application can set the family to AF_HIP in the hints argument of
getaddrinfo() when it requests only sockaddr_hip structures. Second, getaddrinfo() when it requests only sockaddr_hip structures. Second,
the application can set AI_NO_HIT flag to prevent the resolver from the application can set the AI_NO_HIT flag to prevent the resolver
returning HITs in any kind of data structures. from returning HITs in any kind of data structures.
When getaddrinfo() returns resolved outputs in the output "res" When getaddrinfo() returns resolved outputs in the output "res"
argument, it sets the family to AF_HIP when the related structure is argument, it sets the family to AF_HIP when the related structure is
sockaddr_hip. sockaddr_hip.
4.2.1. Resolver Usage 4.2.1. Resolver Usage
A HIP-aware application creates the sockaddr_hip structures manually A HIP-aware application creates the sockaddr_hip structures manually
or obtains them from the resolver. The explicit configuration of or obtains them from the resolver. The explicit configuration of
locators is described in [I-D.ietf-shim6-multihome-shim-api]. This locators is described in [RFC6316]. This document defines
document defines "automated" resolver extensions for getaddrinfo() "automated" resolver extensions for the getaddrinfo() resolver
resolver [RFC3493]. Other resolver calls, such as gethostbyname() [RFC3493]. Other resolver calls, such as gethostbyname() and
and getservbyname() are not defined in this document. The getservbyname(), are not defined in this document. The getaddrinfo()
getaddrinfo resolver interface is shown in Figure 4. resolver interface is shown in Figure 4.
#include <netdb.h> #include <netdb.h>
int getaddrinfo(const char *nodename, int getaddrinfo(const char *nodename,
const char *servname, const char *servname,
const struct addrinfo *hints, const struct addrinfo *hints,
struct addrinfo **res) struct addrinfo **res)
void free_addrinfo(struct addrinfo *res) void free_addrinfo(struct addrinfo *res)
Figure 4 Figure 4
As described in [RFC3493], the getaddrinfo() function takes the As described in [RFC3493], the getaddrinfo() function takes nodename,
nodename, servname, and hints as its input arguments. It places the servname, and hints as its input arguments. It places the result of
result of the query into the res output argument. The return value the query into the res output argument. The return value is zero on
is zero on success, or a non-zero error value on error. The nodename success, or a non-zero error value on error. The nodename argument
argument specifies the host name to be resolved; a NULL argument specifies the hostname to be resolved; a NULL argument denotes the
denotes the HITs of the local host. The servname parameter declares HITs of the local host. The servname parameter declares the port
the port number to be set in the socket addresses in the res output number to be set in the socket addresses in the res output argument.
argument. Both the nodename and servname cannot be NULL at the same The nodename and servname arguments cannot both be NULL at the same
time. time.
The input argument "hints" acts like a filter that defines the The input argument "hints" acts like a filter that defines the
attributes required from the resolved endpoints. A NULL hints attributes required from the resolved endpoints. A NULL hints
argument indicates that any kind of endpoints are acceptable. argument indicates that any kind of endpoint is acceptable.
The output argument "res" is dynamically allocated by the resolver. The output argument "res" is dynamically allocated by the resolver.
The application frees the res argument with the free_addrinfo The application frees the res argument with the free_addrinfo
function. The res argument contains a linked list of the resolved function. The res argument contains a linked list of the resolved
endpoints. The linked list contains only sockaddr_hip structures endpoints. The linked list contains only sockaddr_hip structures
when the input argument has the family set to AF_HIP. When the when the input argument has the family set to AF_HIP. When the
family is zero, the list contains sockaddr_hip structures before family is zero, the list contains sockaddr_hip structures before
sockaddr_in and sockaddr_in6 structures. sockaddr_in and sockaddr_in6 structures.
The resolver can return a HIT which maps to multiple locators. The The resolver can return a HIT that maps to multiple locators. The
resolver may cache the locator mappings with the HIP module. The HIP resolver may cache the locator mappings with the HIP module. The HIP
module manages the multiple locators according to system policies of module manages the multiple locators according to system policies of
the host. The multihoming document the host. The multihoming document [RFC6316] describes how an
[I-D.ietf-shim6-multihome-shim-api] describes how an application can application can override system default policies.
override system default policies.
It should be noted that the application can configure the HIT It should be noted that the application can configure the HIT
explicitly without setting the locator or the resolver can fail to explicitly without setting the locator, or the resolver can fail to
resolve any locator. In this scenario, the application relies on the 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 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 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 sockaddr_hip structure does not contain a HIT when the The sockaddr_hip structure does not contain a HIT when the
application uses the HIP_HIT_ANY_* or HIP_ENDPOINT_ANY constants. In application uses the HIP_HIT_ANY_* or HIP_ENDPOINT_ANY constants. In
such a case, the application can discover the local and peer HITs such a case, the application can discover the local and peer HITs
using the getsockname() and getpeername() functions after the socket using the getsockname() and getpeername() functions after the socket
is connected. The functions getsockname() and getpeername() always is connected. The functions getsockname() and getpeername() always
output a sockaddr_hip structure when the family of the socket is output a sockaddr_hip structure when the family of the socket is
AF_HIP. The application should be prepared to handle also IPv4 and AF_HIP. The application should be prepared to also handle IPv4 and
IPv6 addresses in the ship_hit field as described in Section 4.1 in IPv6 addresses in the ship_hit field, as described in Section 4.1, in
the context of the HIP_ENDPOINT_ANY constant. the context of the HIP_ENDPOINT_ANY constant.
4.4. Selection of Source HIT Type 4.4. Selection of Source HIT Type
A client-side application can choose its source HIT by e.g. querying A client-side application can choose its source HIT by, for example,
all of the local HITs with getaddrinfo() and associating one of them querying all of the local HITs with getaddrinfo() and associating one
with the socket using bind(). This section describes another method of them with the socket using bind(). This section describes another
for a client-side application to affect the selection of the source method for a client-side application to affect the selection of the
HIT type where the application does not call bind() explicitly. source HIT type where the application does not call bind()
Instead, the application just specifies the preferred requirements explicitly. Instead, the application just specifies the preferred
for the source HIT type. requirements for the source HIT type.
The Socket API for Source Address Selection [RFC5014] defines socket The sockets API for source address selection [RFC5014] defines socket
options to allow applications to influence source address selection options to allow applications to influence source address selection
mechanisms. In some cases, HIP-aware applications may want to mechanisms. In some cases, HIP-aware applications may want to
influence source HIT selection; in particular, whether an outbound influence source HIT selection, in particular whether an outbound
connection should use a published or anonymous HIT. Similar to connection should use a published or anonymous HIT. Similar to
IPV6_ADDR_PREFERENCES defined in [RFC5014], the socket option IPV6_ADDR_PREFERENCES defined in [RFC5014], the socket option
HIT_PREFERENCES is defined for HIP-based sockets. This 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 can be used with setsockopt() and getsockopt() calls to set and get
the HIT selection preferences affecting a HIP-enabled socket. The the HIT selection preferences affecting a HIP-enabled socket. The
socket option value (optval) is a 32-bit unsigned integer argument. socket option value (optval) is a 32-bit unsigned integer argument.
The argument consists of a number of flags where each flag indicates The argument consists of a number of flags where each flag indicates
an address selection preference that modifies one of the rules in the an address selection preference that modifies one of the rules in the
default HIT selection; these flags are shown in Table 2. default HIT selection; these flags are shown in Table 2.
skipping to change at page 13, line 40 skipping to change at page 13, line 16
| Socket Option | Purpose | | Socket Option | Purpose |
+---------------------------+-------------------------+ +---------------------------+-------------------------+
| HIP_PREFER_SRC_HIT_TMP | Prefer an anonymous HIT | | HIP_PREFER_SRC_HIT_TMP | Prefer an anonymous HIT |
| HIP_PREFER_SRC_HIT_PUBLIC | Prefer a public HIT | | HIP_PREFER_SRC_HIT_PUBLIC | Prefer a public HIT |
+---------------------------+-------------------------+ +---------------------------+-------------------------+
Table 2 Table 2
If the system is unable to assign the type of HIT that is requested, If the system is unable to assign the type of HIT that is requested,
at HIT selection time, the socket call (connect(), sendto(), or at HIT selection time, the socket call (connect(), sendto(), or
sendmsg()) will fail and errno will be set to EINVAL. If the 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, application tries to set both of the above flags for the same socket,
this also results in the error EINVAL. this also results in the error EINVAL.
4.5. Verification of HIT Type 4.5. Verification of HIT Type
An application that uses the HIP_ENDPOINT_ANY constant may want to An application that uses the HIP_ENDPOINT_ANY constant may want to
check whether the actual communications was based on HIP or not. check whether the actual communication was based on HIP or not.
Also, the application may want to verify whether a HIT belonging to Also, the application may want to verify whether a HIT belonging to
the local host is public or anonymous. The application accomplishes the local host is public or anonymous. The application accomplishes
this using a new function called sockaddr_is_srcaddr() which is this using a new function called sockaddr_is_srcaddr(), which is
illustrated in Figure 5. illustrated in Figure 5.
#include <netinet/hip.h> #include <netinet/hip.h>
short sockaddr_is_srcaddr(struct sockaddr *srcaddr, short sockaddr_is_srcaddr(struct sockaddr *srcaddr,
uint64_t flags); uint64_t flags);
Figure 5 Figure 5
The sockaddr_is_srcaddr() function operates in the same way as the The sockaddr_is_srcaddr() function operates in the same way as the
inet6_is_srcaddr() function [RFC5014] which can be used to verify the inet6_is_srcaddr() function [RFC5014], which can be used to verify
type of an address belonging to the local host. The difference is the type of an address belonging to the local host. The difference
that the sockaddr_is_srcaddr() function handles sockaddr_hip is that the sockaddr_is_srcaddr() function handles sockaddr_hip
structures in addition to sockaddr_in6, and possibly other socket structures in addition to sockaddr_in6, and possibly other socket
structures in further extensions. Also, the length of the flags structures in further extensions. Also, the length of the flags
argument is 64-bits instead of 32 bits because the new function argument is 64 bits instead of 32 bits, because the new function
handles the same flags as defined in [RFC5014] in addition to two handles the same flags as defined in [RFC5014], in addition to two
HIP-specific flags, HIP_PREFER_SRC_HIT_TMP and HIP-specific flags, HIP_PREFER_SRC_HIT_TMP and
HIP_PREFER_SRC_HIT_PUBLIC. With these two flags, the application can HIP_PREFER_SRC_HIT_PUBLIC. With these two flags, the application can
distinguish anonymous HITs from public HITs. distinguish anonymous HITs from public HITs.
When given an AF_INET6 socket, sockaddr_is_srcaddr() behaves as When given an AF_INET6 socket, sockaddr_is_srcaddr() behaves the same
inet6_is_srcaddr() function as described in [RFC5014]. With an way as the inet6_is_srcaddr() function as described in [RFC5014].
AF_HIP socket, the function returns 1 when the HIT contained in the With an AF_HIP socket, the function returns 1 when the HIT contained
socket address structure corresponds to a valid HIT of the local host in the socket address structure corresponds to a valid HIT of the
and the HIT satisfies the given flags. The function returns -1 when local host and the HIT satisfies the given flags. The function
the HIT does not belong to the local host or the flags are not valid. returns -1 when the HIT does not belong to the local host or the
The function returns 0 when the preference flags are valid but the flags are not valid. The function returns 0 when the preference
HIT does not match the given flags. The function also returns 0 on a flags are valid but the HIT does not match the given flags. The
sockaddr_hip structure containing a HIP_ENDPOINT_ANY or HIP_HIT_ANY_* function also returns 0 on a sockaddr_hip structure containing a
wildcard. HIP_ENDPOINT_ANY or HIP_HIT_ANY_* wildcard.
The sockaddr_is_srcaddr() interface applies only to local HITs. The sockaddr_is_srcaddr() interface applies only to local HITs.
Applications can call the function hip_is_hit() to verify that the Applications can call the function hip_is_hit() to verify that the
given hit_hit_t pointer has the HIT prefix. The function is given hit_hit_t pointer has the HIT prefix. The function is
illustrated in Figure 6. illustrated in Figure 6.
#include <netinet/hip.h> #include <netinet/hip.h>
short hip_is_hit(hip_hit_t *hit); short hip_is_hit(hip_hit_t *hit);
skipping to change at page 15, line 13 skipping to change at page 14, line 35
is a HIP_ENDPOINT_ANY or HIP_HIT_ANY_* wildcard. is a HIP_ENDPOINT_ANY or HIP_HIT_ANY_* wildcard.
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 AF_HIP as the domain argument. Second, the creates a socket with AF_HIP as the domain argument. Second, the
application may get or set locator information with one of the application may get or set locator information with one of the
following shim socket options as defined in the multihoming following shim socket options as defined in the multihoming
extensions in [I-D.ietf-shim6-multihome-shim-api]. The related extensions in [RFC6316]. The related socket options are summarized
socket options are summarized briefly in Table 3. briefly in Table 3.
+---------------------+---------------------------------------------+ +---------------------+---------------------------------------------+
| optname | description | | optname | description |
+---------------------+---------------------------------------------+ +---------------------+---------------------------------------------+
| SHIM_LOC_LOCAL_PREF | Get or set the preferred locator on the | | SHIM_LOC_LOCAL_PREF | Get or set the preferred locator on the |
| | local side for the context associated with | | | local side for the context associated with |
| | the socket. | | | the socket. |
| SHIM_LOC_PEER_PREF | Get or set the preferred locator on the | | SHIM_LOC_PEER_PREF | Get or set the preferred locator on the |
| | remote side for the context associated with | | | remote side for the context associated with |
| | the socket. | | | the socket. |
| SHIM_LOCLIST_LOCAL | Get or set a list of locators associated | | SHIM_LOCLIST_LOCAL | Get or set a list of locators associated |
| | with the local EID. | | | with the local Endpoint Identifier (EID). |
| SHIM_LOCLIST_PEER | Get or set a list of locators associated | | SHIM_LOCLIST_PEER | Get or set a list of locators associated |
| | with the peer's EID. | | | with the peer's EID. |
| SHIM_LOC_LOCAL_SEND | Set or get the default source locator of | | SHIM_LOC_LOCAL_SEND | Set or get the default source locator of |
| | outgoing IP packets. | | | outgoing IP packets. |
| SHIM_LOC_PEER_SEND | Set or get the default destination locator | | SHIM_LOC_PEER_SEND | Set or get the default destination locator |
| | of outgoing IP packets. | | | of outgoing IP packets. |
+---------------------+---------------------------------------------+ +---------------------+---------------------------------------------+
Table 3 Table 3
As an example of locator mappings, a connection-oriented application As an example of locator mappings, a connection-oriented application
creates a HIP-based socket and sets the SHIM_LOCLIST_PEER socket creates a HIP-based socket and sets the SHIM_LOCLIST_PEER socket
option on the socket. The HIP module uses the first address option on the socket. The HIP module uses the first address
contained in the option if multiple are provided. If the application contained in the option if multiple addresses are provided. If the
provides one or more addresses in the SHIM_LOCLIST_PEER setsockopt application provides one or more addresses in the SHIM_LOCLIST_PEER
call, the system should not connect to the host via another setsockopt call, the system should not connect to the host via
destination address, in case the application intends to restrict the another destination address, in case the application intends to
range of addresses permissible as a policy choice. The application restrict the range of addresses permissible as a policy choice. The
can override the default peer locator by setting the application can override the default peer locator by setting the
SHIM_LOC_PEER_PREF socket option if necessary. Finally, the SHIM_LOC_PEER_PREF socket option if necessary. Finally, the
application provides a specific HIT in the ship_hit field of the application provides a specific HIT in the ship_hit field of the
sockaddr_hip in the connect() system call. If the system cannot sockaddr_hip in the connect() system call. If the system cannot
reach the HIT at one of the addresses provided, the outbound socket reach the HIT at one of the addresses provided, the outbound sockets
API functions (connect, sendmsg, etc.) return -1 and set errno to API functions (connect(), sendmsg(), etc.) return -1 and set errno to
EINVALIDLOCATOR. EINVALIDLOCATOR.
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 [RFC6316] are followed in this
[I-D.ietf-shim6-multihome-shim-api] are followed in this case. case.
Another use case is to use the opportunistic mode when the Another use case is to use the opportunistic mode when the
destination HIT is specified as a wildcard. The application sets one destination HIT is specified as a wildcard. The application sets one
or more destination addresses using the SHIM_LOCLIST_PEER socket or more destination addresses using the SHIM_LOCLIST_PEER socket
option as described earlier in this section and then calls connect() option as described earlier in this section, and then calls connect()
with the wildcard HIT. The connect() call returns -1 and sets errno with the wildcard HIT. The connect() call returns -1 and sets errno
to EADDRNOTAVAIL when the application connects to a wildcard without to EADDRNOTAVAIL when the application connects to a wildcard without
specifying any destination address. specifying any destination address.
Applications using datagram-oriented sockets can use ancillary data Applications using datagram-oriented sockets can use ancillary data
to control the locators, as described in detail in to control the locators, as described in detail in [RFC6316].
[I-D.ietf-shim6-multihome-shim-api].
5. Summary of New Definitions 5. Summary of New Definitions
Table 4 summarizes the new constants and structures defined in this Table 4 summarizes the new constants and structures defined in this
document. document.
+-----------------+-----------------------+ +-----------------+-----------------------+
| Header | Definition | | Header | Definition |
+-----------------+-----------------------+ +-----------------+-----------------------+
| <sys/socket.h> | AF_HIP | | <sys/socket.h> | AF_HIP |
skipping to change at page 16, line 46 skipping to change at page 16, line 33
| <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> | AI_NO_HIT | | <netdb.h> | AI_NO_HIT |
| <netinet/hip.h> | sockaddr_hip | | <netinet/hip.h> | sockaddr_hip |
| <netinet/hip.h> | sockaddr_is_srcaddr() | | <netinet/hip.h> | sockaddr_is_srcaddr() |
| <netinet/hip.h> | hip_is_hit() | | <netinet/hip.h> | hip_is_hit() |
+-----------------+-----------------------+ +-----------------+-----------------------+
Table 4 Table 4
6. IANA Considerations 6. Security Considerations
No IANA considerations.
7. Security Considerations
This document describes an API for HIP and therefore depends on the This document describes an API for HIP and therefore depends on the
mechanisms defined in the HIP protocol suite. Security concerns mechanisms defined in the HIP protocol suite. Security concerns
associated with HIP itself are specified in [RFC4423], [RFC4843], associated with HIP itself are specified in [RFC4423], [RFC4843],
[RFC5201], [RFC5205], and [RFC5338]. [RFC5201], [RFC5205], and [RFC5338].
The HIP_ENDPOINT_ANY constant can be used to accept incoming or The HIP_ENDPOINT_ANY constant can be used to accept incoming data
create outgoing data flows without HIP. The application should use flows or create outgoing data flows without HIP. The application
the sockaddr_is_srcaddr() function to validate the type of the should use the sockaddr_is_srcaddr() function to validate the type of
connection in order to e.g. inform the user of the lack of HIP-based connection in order to, for example, inform the user of the lack of
security. The use of the HIP_HIT_ANY_* constants is recommended in HIP-based security. The use of the HIP_HIT_ANY_* constants is
security-critical applications and systems. recommended in security-critical applications and systems.
It should be noted that the wildcards described in this document are It should be noted that the wildcards described in this document are
not suitable for identifying end-hosts. Instead, applications should not suitable for identifying end hosts. Instead, applications should
use getsockname() and getpeername() as described in Section 4.3 to use getsockname() and getpeername() as described in Section 4.3 to
identify an end-host. identify an end host.
Future proofing of HITs was discussed during the design of this API. Future proofing of HITs was discussed during the design of this API.
If HITs longer than 128-bits are required at the application layer, If HITs longer than 128 bits are required at the application layer,
this will require explicit support from the applications because they this will require explicit support from the applications, because
can store or cache HITs with their explicit sizes. To support longer they can store or cache HITs with their explicit sizes. To support
HITs, further extensions of this API may define an additional flag longer HITs, further extensions of this API may define an additional
for getaddrinfo() to generate different kind of socket address flag for getaddrinfo() to generate different kinds of socket address
structures for HIP. structures for HIP.
8. Contributors 7. Contributors
Thanks for Jukka Ylitalo and Pekka Nikander for their original Thanks to Jukka Ylitalo and Pekka Nikander for their original
contribution, time and effort to the native HIP APIs. Thanks for contributions, time, and effort to the native HIP APIs. Thanks to
Yoshifuji Hideaki and Stefan Goetz for their contributions to this Yoshifuji Hideaki and Stefan Goetz for their contributions to this
document. document.
9. Acknowledgements 8. Acknowledgments
Kristian Slavov, Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan Kristian Slavov, Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan
Melen, Andrew McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti Melen, Andrew McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti
Jarvinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari Keranen, Jarvinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari Keranen,
Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews, Joakim Koskela, Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews, Joakim Koskela,
Jeff Ahrenholz, Tobias Heer and Gonzalo Camarillo have provided Jeff Ahrenholz, Tobias Heer, and Gonzalo Camarillo have provided
valuable ideas and feedback. Thanks for Nick Stoughton from the valuable ideas and feedback. Thanks to Nick Stoughton from the
Austin group for POSIX-related comments. Thanks also for the APPS Austin group for POSIX-related comments. Thanks also to the APPS
area folks, including Stephane Bortzmeyer, Chris Newman, Tony Finch, area folks, including Stephane Bortzmeyer, Chris Newman, Tony Finch,
"der Mouse" and Keith Moore. "der Mouse", and Keith Moore.
10. References 9. References
10.1. Normative References 9.1. Normative References
[I-D.ietf-shim6-multihome-shim-api] [POSIX] "IEEE Std. 1003.1-2008 Standard for Information
Komu, M., Bagnulo, M., Slavov, K., and S. Sugimoto, Technology -- Portable Operating System Interface
"Socket Application Program Interface (API) for (POSIX). Open group Technical Standard: Base
Multihoming Shim", draft-ietf-shim6-multihome-shim-api-12 Specifications, Issue 7", September 2008,
(work in progress), January 2010. <http://www.opengroup.org/austin>.
[POSIX] Institute of Electrical and Electronics Engineers, "IEEE [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W.
Std. 1003.1-2008 Standard for Information Technology - Stevens, "Basic Socket Interface Extensions for IPv6",
Portable Operating System Interface (POSIX)", Dec 2001. RFC 3493, February 2003.
[RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. [RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol
Stevens, "Basic Socket Interface Extensions for IPv6", (HIP) Architecture", RFC 4423, May 2006.
RFC 3493, February 2003.
[RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol [RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6
(HIP) Architecture", RFC 4423, May 2006. Prefix for Overlay Routable Cryptographic Hash
Identifiers (ORCHID)", RFC 4843, April 2007.
[RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix [RFC5014] Nordmark, E., Chakrabarti, S., and J. Laganier, "IPv6
for Overlay Routable Cryptographic Hash Identifiers Socket API for Source Address Selection", RFC 5014,
(ORCHID)", RFC 4843, April 2007. September 2007.
[RFC5014] Nordmark, E., Chakrabarti, S., and J. Laganier, "IPv6 [RFC5201] Moskowitz, R., Nikander, P., Jokela, P., Ed., and T.
Socket API for Source Address Selection", RFC 5014, Henderson, "Host Identity Protocol", RFC 5201, April
September 2007. 2008.
[RFC5201] Moskowitz, R., Nikander, P., Jokela, P., and T. Henderson, [RFC5205] Nikander, P. and J. Laganier, "Host Identity Protocol
"Host Identity Protocol", RFC 5201, April 2008. (HIP) Domain Name System (DNS) Extensions", RFC 5205,
April 2008.
[RFC5205] Nikander, P. and J. Laganier, "Host Identity Protocol [RFC5338] Henderson, T., Nikander, P., and M. Komu, "Using the Host
(HIP) Domain Name System (DNS) Extensions", RFC 5205, Identity Protocol with Legacy Applications", RFC 5338,
April 2008. September 2008.
[RFC5338] Henderson, T., Nikander, P., and M. Komu, "Using the Host [RFC6316] Komu, M., Bagnulo, M., Slavov, K., and S. Sugimoto, Ed.,
Identity Protocol with Legacy Applications", RFC 5338, "Sockets Application Program Interface (API) for
September 2008. Multihoming Shim", RFC 6316, July 2011.
10.2. Informative References 9.2. Informative References
[RFC5533] Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming [RFC5533] Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming
Shim Protocol for IPv6", RFC 5533, June 2009. Shim Protocol for IPv6", RFC 5533, June 2009.
Authors' Addresses Authors' Addresses
Miika Komu Miika Komu
Helsinki Institute for Information Technology Aalto University
Metsanneidonkuja 4 Espoo
Helsinki
Finland Finland
Phone: +358503841531 Phone: +358505734395
Fax: +35896949768 Fax: +358947025014
Email: miika@iki.fi EMail: miika@iki.fi
URI: http://www.iki.fi/miika/ URI: http://cse.aalto.fi/research/groups/datacommunications/people/
Thomas Henderson Thomas Henderson
The Boeing Company The Boeing Company
P.O. Box 3707 P.O. Box 3707
Seattle, WA Seattle, WA
USA USA
Email: thomas.r.henderson@boeing.com EMail: thomas.r.henderson@boeing.com
 End of changes. 100 change blocks. 
308 lines changed or deleted 297 lines changed or added

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