draft-ietf-hip-native-api-08.txt   draft-ietf-hip-native-api-09.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: January 31, 2010 Henderson Expires: March 14, 2010 Henderson
The Boeing Company The Boeing Company
July 30, 2009 September 10, 2009
Basic Socket Interface Extensions for Host Identity Protocol (HIP) Basic Socket Interface Extensions for Host Identity Protocol (HIP)
draft-ietf-hip-native-api-08 draft-ietf-hip-native-api-09
Status of this Memo Status of this Memo
This Internet-Draft is submitted to IETF in full conformance with the This Internet-Draft is submitted to IETF in full conformance with the
provisions of BCP 78 and BCP 79. This document may not be modified, provisions of BCP 78 and BCP 79. This document may not be modified,
and derivative works of it may not be created, except to format it and derivative works of it may not be created, except to format it
for publication as an RFC or to translate it into languages other for publication as an RFC or to translate it into languages other
than English. than English.
Internet-Drafts are working documents of the Internet Engineering Internet-Drafts are working documents of the Internet Engineering
skipping to change at page 1, line 37 skipping to change at page 1, line 37
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 January 31, 2010. This Internet-Draft will expire on March 14, 2010.
Copyright Notice Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the Copyright (c) 2009 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 in effect on the date of Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info). publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights Please review these documents carefully, as they describe your rights
and restrictions with respect to this document. and restrictions with respect to this document.
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
define also interfaces for manual bindings between HITs and locators. define also interfaces for manual bindings between HITs and locators.
With the extensions, the application can also support more relaxed With the extensions, the application can also support more relaxed
security models where the communication can be non-HIP based, security models where the communication can be non-HIP based,
according to local policies. The extensions in document are according to local policies. The extensions in this document are
experimental and provide basic tools for further experimentation with experimental and provide basic tools for further experimentation with
policies. policies.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4 2. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 4
3. Name Resolution Process . . . . . . . . . . . . . . . . . . . 5 3. Name Resolution Process . . . . . . . . . . . . . . . . . . . 5
3.1. Interaction with the Resolver . . . . . . . . . . . . . . 5 3.1. Interaction with the Resolver . . . . . . . . . . . . . . 5
3.2. Interaction without a Resolver . . . . . . . . . . . . . . 6 3.2. Interaction without a Resolver . . . . . . . . . . . . . . 6
4. API Syntax and Semantics . . . . . . . . . . . . . . . . . . . 7 4. API Syntax and Semantics . . . . . . . . . . . . . . . . . . . 7
4.1. Socket Family and Address Structure Extensions . . . . . . 7 4.1. Socket Family and Address Structure Extensions . . . . . . 7
4.2. Extensions to Resolver Data Structures . . . . . . . . . . 9 4.2. Extensions to Resolver Data Structures . . . . . . . . . . 9
4.3. The Use of getsockname and getpeername Functions . . . . . 11 4.3. The Use of getsockname and getpeername Functions . . . . . 12
4.4. Selection of Source HIT Type . . . . . . . . . . . . . . . 11 4.4. Selection of Source HIT Type . . . . . . . . . . . . . . . 12
4.5. Verification of Source HIT Type . . . . . . . . . . . . . 12 4.5. Verification of HIT Type . . . . . . . . . . . . . . . . . 13
4.6. Explicit Handling of Locators . . . . . . . . . . . . . . 13 4.6. Explicit Handling of Locators . . . . . . . . . . . . . . 14
5. Summary of New Definitions . . . . . . . . . . . . . . . . . . 14 5. Summary of New Definitions . . . . . . . . . . . . . . . . . . 15
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 16
7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 7. Security Considerations . . . . . . . . . . . . . . . . . . . 16
8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 15 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 17
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 17
10. Normative References . . . . . . . . . . . . . . . . . . . . . 16 10. Normative References . . . . . . . . . . . . . . . . . . . . . 17
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 18
1. Introduction 1. Introduction
This document defines C-based sockets Application Programming This document defines the 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 [RFC5205]. 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 an
identity-locator split. The APIs specified in this document are identity-locator split. The APIs specified in this document are
specific to HIP, but have been designed as much as possible so as not specific to HIP, but have been designed as much as possible so as not
to preclude its use with other protocols. The use of these APIs with to preclude its use with other protocols. The use of these APIs with
other protocols is, nevertheless, for further study. other protocols is, nevertheless, for further study.
The APIs in this document are based on IPv6 addresses with the ORCHID The APIs in this document are based on IPv6 addresses with the ORCHID
prefix [RFC4843]. ORCHIDs are derived from Host Identifiers using a prefix [RFC4843]. ORCHIDs are derived from Host Identifiers using a
hash and fitting the result into an IPv6 address. Such addresses are hash and fitting the result into an IPv6 address. Such addresses are
called Host Identity Tags (HITs) and they can be distinguished from called Host Identity Tags (HITs) and they can be distinguished from
other IPv6 addresses with the ORCHID prefix. other IPv6 addresses via the ORCHID prefix.
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. [RFC5338] networking stacks with varying degrees of visibility. [RFC5338]
discusses the lowest levels of visibility in which applications are discusses the lowest levels of visibility in which applications are
completely unaware of the underlying HIP layer. Such HIP-unaware completely unaware of the underlying HIP layer. Such HIP-unaware
applications in some circumstances use HIP-based identifiers, such as applications in some circumstances use HIP-based identifiers, such as
LSIs or HITs, instead of IPv4 or IPv6 addresses and cannot observe LSIs or HITs, instead of IPv4 or IPv6 addresses and cannot observe
the identifier-locator bindings. 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. Similarly to other address families, socket address family, AF_HIP. Similarly to other address families,
AF_HIP can used as an alias for PF_HIP. The extensions also describe AF_HIP can be used as an alias for PF_HIP. The extensions also
a new socket address structure for sockets using HITs explicitly and describe a new socket address structure for sockets using HITs
describe how the socket calls in [RFC3493] are adapted or extended as explicitly and describe how the socket calls in [RFC3493] are adapted
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 in [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 later in this document. as described in Section 4.1.1.
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 binding 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 API documents. of the two mentioned 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
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.
skipping to change at page 5, line 19 skipping to change at page 5, line 19
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 host name, 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
HIT(s). The resolver queries the DNS in step (b) to map the FQDN to one or more socket addresses within the PF_HIP family. The resolver,
a host identifier and locator (A and AAAA records). It should be in turn, queries the DNS in step (b) to map the FQDN to one or more
noticed that the FQDN may map to multiple host identifiers and HIP RRs with the HIT and HI and possibly rendezvous server of the
locators, and this step may involve multiple DNS transactions, Responder, and also (in parallel or sequentially) to resolve the FQDN
including queries for A, AAAA, HI and possibly other resource into possibly one or more A and AAAA records. It should be noted
records. The DNS server responds with a list of HIP resource records that the FQDN may map to multiple host identifiers and locators, and
in step (c). Optionally in step (d), the resolver caches the HIT to this step may involve multiple DNS transactions, including queries
locator mapping with the HIP module. The resolver converts the HIP for A, AAAA, HI and possibly other resource records. The DNS server
records to HITs and returns the HITs to the application contained in responds with a list of HIP resource records in step (c). Optionally
HIP socket address structures in step (e). Depending on the in step (d), the resolver caches the HIT-to-locator mapping with the
parameters for the resolver call, the resolver may return also other HIP module. The resolver converts the HIP records to HITs and
socket address structures to the application. Finally, the returns the HITs to the application contained in HIP socket address
application receives the socket address structure(s) from the structures in step (e). Depending on the parameters for the resolver
resolver and uses them in socket calls such as connect() in step (f). call, the resolver may return also other socket address structures to
the application. Finally, the application receives the socket
address structure(s) from the resolver and uses them in socket calls
such as connect() in step (f).
+----------+ +----------+
| | | |
| 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 10 skipping to change at page 7, line 10
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 draft requires
a number of shim socket options [I-D.ietf-shim6-multihome-shim-api] a number of shim socket options [I-D.ietf-shim6-multihome-shim-api]
to be implemented by the system. to be implemented 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 are aliases to a new address family, AF_HIP. The AF_HIP and PF_HIP constants are
each other. These definition shall be defined as a result of aliases to each other. These definitions shall be defined as a
including <sys/socket.h>. result of including <sys/socket.h>.
The use of the PF_HIP constant is mandatory with the socket() When the socket() function is called with PF_HIP as the first
function when an application uses the native HIP APIs. The argument (domain), it attempts to create a socket for HIP
application gives the PF_HIP constant as the first argument (domain) communication. If HIP is not supported, socket() follows its default
to the socket() function. The system returns a positive integer behaviour and returns -1 and sets errno to EAFNOSUPPORT.
representing a socket descriptor when the system supports HIP.
Otherwise, the system returns -1 and sets errno to EAFNOSUPPORT.
This is the default behavior for unsupported address families and
does not require any changes to legacy systems.
Figure 2 shows socket address structure for HIP. Figure 2 shows the recommended implementation of the socket address
structure for HIP in POSIX.1.g format.
#include <netinet/in.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;
sa_family_t ship_family; sa_family_t ship_family;
in_port_t ship_port; in_port_t ship_port;
uint32_t ship_pad; uint32_t ship_flags;
uint64_t ship_flags; ' hip_hit_t ship_hit;
hip_hit_t ship_hit;
uint8_t ship_reserved[16];
}; };
Figure 2 Figure 2
Figure 2 is in 4.3BSD format. The family of the socket, ship_family, uint8_t ship_len: This field is optional in POSIX.1.g (and 4.3BSD-
is set to AF_HIP. The port number ship_port is two octets in network RENO). The field defines the length of the structure.
byte order and the ship_hit is 16 octets in network byte order. An Implementations that do not define this field typically embed the
implementation may have extra member(s) in this structure. information in the following ship_family field.
The application usually sets the ship_hit field using the resolver.
However, the application can use three special constants to set a
wildcard value manually into the ship_hit field. The constants are
HIP_HIT_ANY, HIP_HIT_ANY_PUB, HIP_HIT_ANY_TMP and HIP_ENDPOINT_ANY.
The first three equal to a HIT value associated with a wildcard HIT
of any type, public type, or anonymous type. The fourth constant,
HIP_ENDPOINT_ANY, denotes that the application accepts HIT, IPv4 and
IPv6-based addresses. The HIP_HIT_ANY denotes that the application
accepts any type of HIT. The anonymous identifiers refer to the use
of anonymous identifiers as specified in [RFC4423]. The system may
designate anonymous identifiers as meta data associated with a HIT
depending on whether it has been published or not. However, there is
no difference in the classes of HITs from the protocol perspective.
The application can use the HIP_HIT_ANY_* and HIP_ENDPOINT_ANY sa_family_t ship_family: This mandatory field identifies this as a
constants to accept incoming communications to all of the HITs of the sockaddr_hip structure. It overlays the sa_family field of the
local host. Incoming communications refers here to functions such as sockaddr structure. Its value must be AF_HIP.
bind(), recvfrom() and recvmsg(). The HIP_HIT_* constants are
similar to the sockets API constants INADDR_ANY and IN6ADDR_ANY_INIT,
but they are applicable to HITs only. After initial contact with the
peer, the application can discover the local and peer HITs using
getsockname() and getpeername() calls as described in Section 4.3.
The difference between the use of the HIP_HIT_* and HIP_ENDPOINT_ANY
constants here is that the former allows only HIP-based
communications but the latter also allows communications without HIP.
When a connection-oriented server application binds to in_port_t ship_port: This mandatory field contains the transport
HIP_ENDPOINT_ANY and calls accept(), the call outputs always a protocol port number. It is handled in the same way as the sin_port
sockaddr_hip structure containing information on the connected client field of the sockaddr_in structure. The port number is stored in
with the address family set to AF_HIP. The same applies also to network byte order.
datagram-oriented recvfrom() and recvmsg() calls. If the data flow
was based on HIP, the ship_hit field contains a HIT. In the case of
an IPv6 data flow without HIP, the field contains the corresponding
IPv6 address of the client. In the case of an IPv4 flow without HIP,
the fields contains the client's IPv4 address in IPv4-mapped IPv6
address format as described in section 3.7 of [RFC3493]. Section 4.5
describes how the application can verify the type of the address
returned by the socket API calls.
The application also uses the HIP_HIT_ANY constant in ship_hit field uint32_t ship_flags: This mandatory bit field contains auxiliary
to establish outgoing communications in Opportunistic mode [RFC5201], flags. This document does not define any flags. This field is
i.e., when the application knows the remote peer locator but not the included for future extensions.
HIT. Outgoing communications refers here to the use of functions
such as connect(), sendto() and sendmsg(). However, the application
should first associate the socket with at least one IP address of the
peer using SHIM_LOCLIST_PEER_PREF socket option. The use of the
HIP_HIT_ANY constant guarantees that the communications will be based
on HIP or none at all.
The use of HIP_ENDPOINT_ANY constant in the context of outgoing hip_hit_t ship_hit: This mandatory field contains the end-point
communications is left for further experimentation in the context of identifier. When the system passes a sockaddr_hip structure to the
opportunistic mode. It can result in a data flow with or without application, the value of this field is set to a valid HIT, IPv4, or
HIP. IPv6 address, as discussed in Section 4.5. When the application
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.
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 the accept_filter() function found on
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.
In such a case, the application can compare two HITs contained in the Applications operating on sockaddr_hip structures can use memcmp() or
ship_hit field using memcmp() or similar function. It should be similar function to compare the ship_hit fields. It should be also
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
HIP wildcard addresses are similar to IPv4 and IPv6 wildcard
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
bind(), connect(), sendto(), sendmsg().
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
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.
The value HIP_HIT_ANY_TMP binds a socket to all local anonymous
identifiers only as specified in [RFC4423]. The system may label
anonymous identifiers as such depending on whether they have been
published or not. After binding a socket via one of the
HIP_HIT_ANY_* wildcard addresses, the application is guaranteed to
receive only HIP-based data flows. With the HIP_ENDPOINT_ANY
wildcard address, the socket accepts HIP, IPv6, and IPv4-based data
flows.
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
the AF_HIP family, i.e. sockaddr_hip structures, for this socket.
This applies to all functions which provide addresses to the
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-
HIP IPv6 data flow, the field contains the peer's IPv6 address. For
a non-HIP IPv4 data flow, the field contains the peer's IPv4 address
in IPv4-mapped IPv6 address format as described in section 3.7 of
[RFC3493]. Section 4.5 describes how the application can verify the
type of the address returned by the socket API calls.
An application uses the socket API as follows to set up a connection
or to send messages in HIP Opportunistic Mode (cf. [RFC5201]).
First, the application associates a socket with at least one IP
address of the destination peer via setting the
SHIM_LOCLIST_PEER_PREF socket option. It then uses outgoing socket
functions such as connect(), sendto(), or sendmsg() with the
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,
the underlying system allows only HIP-based data flows with the
corresponding socket. For incoming packets, the system discards all
non-HIP-related traffic arriving at the socket. For outgoing
packets, the system returns -1 in the socket call and sets errno to
an appropriate error type when the system failed to deliver the
packet over a HIP-based data channel. The semantics of using the
HIP_ENDPOINT_ANY are the subject of further experimentation in the
context of opportunistic mode. Such use may result in a data flow
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 applications can use to control the address type returned from the
getaddrinfo() function [RFC3493]. The getaddrinfo() function uses a getaddrinfo() function [RFC3493]. The getaddrinfo() function uses a
data structure called addrinfo in its "hints" and "res" argument data structure called addrinfo in its "hints" and "res" argument
which are described in more detail in the next section. The addrinfo which is described in more detail in the next section. The addrinfo
data structure is illustrated in Figure 3. data structure is illustrated in Figure 3.
#include <netdb.h> #include <netdb.h>
struct addrinfo { struct addrinfo {
int ai_flags; /* e.g. AI_CANONNAME */ int ai_flags; /* e.g. AI_CANONNAME */
int ai_family; /* e.g. AF_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 */
socklen_t ai_addrlen; /* size of *ai_addr */ socklen_t ai_addrlen; /* size of *ai_addr */
skipping to change at page 10, line 16 skipping to change at page 10, line 42
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 in [RFC5338]. In such a case, the DNS agent may,
according to local policy, return transparently LSIs or HITs in according to local policy, return transparently 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 AI_NO_HIT flag to prevent the resolver from
returning HITs in any kind of data structures. returning HITs in any kind of data structures.
When getaddrinfo() returns resolved outputs the results to 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 [I-D.ietf-shim6-multihome-shim-api]. This
document defines "automated" resolver extensions for getaddrinfo() document defines "automated" resolver extensions for getaddrinfo()
resolver [RFC3493]. resolver [RFC3493]. Other resolver calls, such as gethostbyname()
and getservbyname() are not defined in this document. The
getaddrinfo 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 the
nodename, servname, and hints as its input arguments. It places the nodename, servname, and hints as its input arguments. It places the
result of the query into the res output argument. The return value result of the query into the res output argument. The return value
is zero on success, or a non-zero error value on error. The nodename is zero on success, or a non-zero error value on error. The nodename
argument specifies the host name to be resolved; a NULL argument argument specifies the host name to be resolved; a NULL argument
denotes the HITs of the local host. The servname parameter declares denotes the HITs of the local host. The servname parameter declares
the port number to be set in the socket addresses in the res output the port number to be set in the socket addresses in the res output
argument. Both the nodename and servname cannot be NULL at the same argument. Both the nodename and servname cannot 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 endpoints are 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 sockaddr_hip structures only 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 which 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
[I-D.ietf-shim6-multihome-shim-api] describes how an application can [I-D.ietf-shim6-multihome-shim-api] describes how an application can
override system default policies. override system default policies.
skipping to change at page 12, line 5 skipping to change at page 12, line 32
for a client-side application to affect the selection of the source for a client-side application to affect the selection of the source
HIT type where the application does not call bind() explicitly. HIT type where the application does not call bind() explicitly.
Instead, the application just specifies the preferred requirements Instead, the application just specifies the preferred requirements
for the source HIT type. for the source HIT type.
The Socket API for Source Address Selection [RFC5014] defines socket The Socket 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 RFC 5014, the following socket IPV6_ADDR_PREFERENCES defined in [RFC5014], the socket option
option HIT_PREFERENCES is defined for HIP-based sockets. This socket HIT_PREFERENCES is defined for HIP-based sockets. This socket option
option can be used with setsockopt() and getsockopt() calls to set can be used with setsockopt() and getsockopt() calls to set and get
and get the HIT selection preferences affecting a HIP-enabled socket. the HIT selection preferences affecting a HIP-enabled socket. The
The socket option value (optval) is a 32-bit unsigned integer socket option value (optval) is a 32-bit unsigned integer argument.
argument. The argument consists of a number of flags where each flag The argument consists of a number of flags where each flag indicates
indicates an address selection preference that modifies one of the an address selection preference that modifies one of the rules in the
rules in the default HIT selection; these flags are shown in Table 2. default HIT selection; these flags are shown in Table 2.
+---------------------------+-------------------------+ +---------------------------+-------------------------+
| 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 Source 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 communications was based on HIP or not.
Also, the application may want to verify whether a local HIT is Also, the application may want to verify whether a HIT belonging to
public or anonymous. The application accomplishes these using a new the local host is public or anonymous. The application accomplishes
function called sockaddr_is_srcaddr() which is illustrated in this using a new function called sockaddr_is_srcaddr() which is
Figure 5. illustrated in Figure 5.
#include <netinet/in.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 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 the
type of an address belonging to the local host. The difference is type of an address belonging to the local host. The difference is
that the sockaddr_is_srcaddr() function handles sockaddr_hip that the sockaddr_is_srcaddr() function handles sockaddr_hip
structures in addition to sockaddr_in6, and possibly some other structures in addition to sockaddr_in6, and possibly other socket
socket structures in further extensions. The flags argument is also structures in further extensions. Also, the length of the flags
64 bit instead of 32 bits because new function handles the same flags argument is 64-bits instead of 32 bits because the new function
as defined in [RFC5014] in addition to two HIP-specific flags, handles the same flags as defined in [RFC5014] in addition to two
HIP_PREFER_SRC_HIT_TMP and HIP_PREFER_SRC_HIT_PUBLIC. With these two HIP-specific flags, HIP_PREFER_SRC_HIT_TMP and
flags, the application can distinguish anonymous HITs from public HIP_PREFER_SRC_HIT_PUBLIC. With these two flags, the application can
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 as
inet6_is_srcaddr() function as described in [RFC5014]. With AF_HIP inet6_is_srcaddr() function as described in [RFC5014]. With an
socket, the function returns 1 when the HIT contained in the socket AF_HIP socket, the function returns 1 when the HIT contained in the
address structure corresponds to a valid HIT of the local host and socket address structure corresponds to a valid HIT of the local host
the HIT satisfies the given flags. The function returns -1 when the and the HIT satisfies the given flags. The function returns -1 when
HIT does not belong to the local host or the flags are not valid. the HIT does not belong to the local host or the flags are not valid.
The function returns 0 when the preference flags are valid but the The function returns 0 when the preference flags are valid but the
HIT does not match the given flags. HIT does not match the given flags. The function also returns 0 on a
sockaddr_hip structure containing a HIP_ENDPOINT_ANY or HIP_HIT_ANY_*
wildcard.
The sockaddr_is_srcaddr() interface applies only to local HITs.
Applications can call the function hip_is_hit() to verify that the
given hit_hit_t pointer has the HIT prefix. The function is
illustrated in Figure 6.
#include <netinet/hip.h>
short hip_is_hit(hip_hit_t *hit);
Figure 6
The hip_is_hit() function returns 1 when the given argument contains
the HIT prefix. The function returns -1 on error and sets errno
appropriately. The function returns 0 when the argument does not
have the HIT prefix. The function also returns 0 when the argument
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 [I-D.ietf-shim6-multihome-shim-api]. The related
skipping to change at page 14, line 4 skipping to change at page 14, line 51
| 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 to 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 are provided. If the application
provides one or more addresses in the SHIM_LOCLIST_PEER setsockopt provides one or more addresses in the SHIM_LOCLIST_PEER setsockopt
call, the system should not connect to the host via another call, the system should not connect to the host via another
destination address, in case the application intends to restrict the destination address, in case the application intends to restrict the
range of addresses permissible as a policy choice. The application range of addresses permissible as a policy choice. The application
can override the default peer locator by setting the 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 socket
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
[I-D.ietf-shim6-multihome-shim-api] are followed in this case. [I-D.ietf-shim6-multihome-shim-api] are followed in this 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 above and then calls connect() with the wildcard option as described earlier in this section and then calls connect()
HIT. The connect() call returns -1 and sets errno to EADDRNOTAVAIL with the wildcard HIT. The connect() call returns -1 and sets errno
when the application connects to a wildcard without specifying any to EADDRNOTAVAIL when the application connects to a wildcard without
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. This described in detail in to control the locators, as described in detail in
[I-D.ietf-shim6-multihome-shim-api]. [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 |
| <sys/socket.h> | PF_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_ENDPOINT_ANY | | <netinet/hip.h> | HIP_ENDPOINT_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> | 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() |
+-----------------+-----------------------+
Table 4 Table 4
6. IANA Considerations 6. IANA Considerations
No IANA considerations. No IANA considerations.
7. Security Considerations 7. Security Considerations
The use of HIP_ENDPOINT_ANY can be used to accept incoming or create The HIP_ENDPOINT_ANY constant can be used to accept incoming or
outgoing data flows without HIP. The application should use the create outgoing data flows without HIP. The application should use
sockaddr_is_srcaddr() function to validate the type of the connection the sockaddr_is_srcaddr() function to validate the type of the
in order to e.g. inform the user of the lack of HIP-based security. connection in order to e.g. inform the user of the lack of HIP-based
The use of the HIP_HIT_ANY_* constants is recommended in security- security. The use of the HIP_HIT_ANY_* constants is recommended in
critical applications and systems. security-critical applications and systems.
It should be noted that the wildcards described in this document are
not suitable for identifying end-hosts. Instead, applications should
use getsockname() and getpeername() as described in Section 4.3 to
identify an end-host.
Future proofing of HITs was discussed during the design of this API.
If HITs longer than 128-bits are required at the application layer,
this will require explicit support from the applications because they
can store or cache HITs with their explicit sizes. To support longer
HITs, further extensions of this API may define an additional flag
for getaddrinfo() to generate different kind of socket address
structures for HIP.
8. Contributors 8. Contributors
Thanks for Jukka Ylitalo and Pekka Nikander for their original Thanks for Jukka Ylitalo and Pekka Nikander for their original
contribution, time and effort to the native HIP APIs. Thanks for contribution, time and effort to the native HIP APIs. Thanks for
Yoshifuji Hideaki for his contributions to this document. Yoshifuji Hideaki and Stefan Goetz for their contributions to this
document.
9. Acknowledgements 9. Acknowledgements
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, Stefan Gotz and Gonzalo Camarillo have
valuable ideas and feedback. Thanks also for the APPS area folks, provided valuable ideas and feedback. Thanks also for the APPS area
including Stephane Bortzmeyer, Chris Newman, Tony Finch, "der Mouse" folks, including Stephane Bortzmeyer, Chris Newman, Tony Finch, "der
and Keith Moore. Mouse" and Keith Moore.
10. Normative References 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,
"C-Bindings for IPsec Application Programming Interfaces", "C-Bindings for IPsec Application Programming Interfaces",
draft-ietf-btns-c-api-04 (work in progress), March 2009. draft-ietf-btns-c-api-04 (work in progress), March 2009.
[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,
 End of changes. 51 change blocks. 
172 lines changed or deleted 223 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/