draft-ietf-hip-native-api-02.txt   draft-ietf-hip-native-api-03.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: Informational Technology Intended status: Informational Technology
Expires: January 8, 2008 July 7, 2007 Expires: May 22, 2008 November 19, 2007
Native Application Programming Interfaces for SHIM APIs Native Application Programming Interfaces (APIs) for Host Identity
draft-ietf-hip-native-api-02 Protocol (HIP)
draft-ietf-hip-native-api-03
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any By submitting this Internet-Draft, each author represents that any
applicable patent or other IPR claims of which he or she is aware applicable patent or other IPR claims of which he or she is aware
have been or will be disclosed, and any of which he or she becomes have been or will be disclosed, and any of which he or she becomes
aware will be disclosed, in accordance with Section 6 of BCP 79. aware will be disclosed, in accordance with Section 6 of BCP 79.
This document may not be modified, and derivative works of it may not This document may not be modified, and derivative works of it may not
be created, except to publish it as an RFC and to translate it into be created, except to publish it as an RFC and to translate it into
languages other than English. languages other than English.
skipping to change at page 1, line 37 skipping to change at page 1, line 38
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 8, 2008. This Internet-Draft will expire on May 22, 2008.
Copyright Notice Copyright Notice
Copyright (C) The IETF Trust (2007). Copyright (C) The IETF Trust (2007).
Abstract Abstract
This document defines extensions to the current networking APIs for This document defines extensions to the current sockets API for Host
protocols based on identifier/locator split. Currently, the document Identity Protocol (HIP). The extensions focus on the initial
focuses on HIP, but the extensions can be used also by other discovery of public-key based identifiers. Using the extensions, the
protocols implementing identifier locator split. Using the API application can verify that the identifier is a Host Identity Tag
extensions, new SHIM aware applications can configure manually (HIT) and it can require the system resolver to return only HITs from
mappings between upper layer identifiers and the corresponding DNS. The application can also to explicitly allow more relaxed
locators. Also, the API describes how to handle outbound connection security models where the communication can be non-HIP based in the
establishment where an application is unaware of the peer identifier absence of a peer identifiers, or that the application allows peer
but knows the peer locator. identity to be discovered after initial contact directly with the
peer.
Table of Contents Table of Contents
1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Design Model . . . . . . . . . . . . . . . . . . . . . . . . . 4 3. Design Model . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Layering Model . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Namespace Model . . . . . . . . . . . . . . . . . . . . . 4
3.2. Namespace Model . . . . . . . . . . . . . . . . . . . . . 4 3.2. Interaction with the Resolver . . . . . . . . . . . . . . 5
3.3. Interaction with the Resolver . . . . . . . . . . . . . . 5
4. API Syntax and Semantics . . . . . . . . . . . . . . . . . . . 6 4. API Syntax and Semantics . . . . . . . . . . . . . . . . . . . 6
4.1. Socket Family and Address Structure . . . . . . . . . . . 6 4.1. Socket Family and Address Structure Extensions . . . . . . 6
4.2. Resolver . . . . . . . . . . . . . . . . . . . . . . . . . 8 4.2. Resolver Extensions . . . . . . . . . . . . . . . . . . . 8
4.3. Manual Handling of Locators . . . . . . . . . . . . . . . 10
5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 5. Summary of New Definitions . . . . . . . . . . . . . . . . . . 10
6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10 7. Security Considerations . . . . . . . . . . . . . . . . . . . 11
8. Normative References . . . . . . . . . . . . . . . . . . . . . 10 8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 9. Normative References . . . . . . . . . . . . . . . . . . . . . 12
Intellectual Property and Copyright Statements . . . . . . . . . . 12
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12
Intellectual Property and Copyright Statements . . . . . . . . . . 14
1. Terminology 1. Terminology
The terms used in this document are summarized in Table 1.
+---------+---------------------------------------------------------+ +---------+---------------------------------------------------------+
| Term | Explanation | | Term | Explanation |
+---------+---------------------------------------------------------+ +---------+---------------------------------------------------------+
| ULID | Upper Layer IDentifier equals to the identity part of | | HIP | Host Identity Protocol |
| | the identity/locator split. It is the identifier used |
| | by the application to name a peer for the transport |
| | layer. |
| Locator | Non-routable IPv4 or IPv6 address used at the lower |
| | layers |
| FQDN | Fully Qualified Domain Name |
| 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 | Locally Scope Identifier, a 32-bit local presentation | | LSI | Local Scope Identifier, a local, 32-bit descriptor for |
| | of a public key | | | a given public key. |
| Locator | Routable IPv4 or IPv6 address used at the lower layers |
+---------+---------------------------------------------------------+ +---------+---------------------------------------------------------+
Table 1 Table 1
2. Introduction 2. Introduction
Host Identity Protocol proposes a new cryptographic namespace and a The Host Identity Protocol (HIP) [RFC4423] proposes a new
new layer to the TCP/IP architecture. Applications can see these new cryptographic namespace by separating the roles of end-point
changes in the networking stacks with varying degrees of visibility. identifiers and locators by introducing a new namespace to the TCP/IP
stack. SHIM6 [I-D.ietf-shim6-proto] is another protocol based on
identity-locator split. Note that the Application Programming
Interfaces (APIs) specified in this document are specific to HIP.
However, the APIs here have been designed keeping generality in mind
as much as possible so as not to preclude its use with other
protocols. The use of these APIs with other protocols is,
nevertheless, for further study.
Applications can observe the HIP layer and its identifiers in the
networking stacks with varying degrees of visibility.
[I-D.henderson-hip-applications] discusses the lowest levels of [I-D.henderson-hip-applications] discusses the lowest levels of
visibility in which applications are either unaware of HIP. The HIP- visibility in which applications are completely unaware of the
unaware applications use LSIs or HITs instead of IPv4 or IPv6 underlying HIP layer. Such HIP-unaware applications use HIP-based
addresses. Such applications may be unaware of the locator bindings. identifiers, such as LSIs or HITs, instead of IPv4 or IPv6 addresses
and cannot observe the identifier-locator bindings.
This document discusses about visibility of HIP to HIP-aware This document defines C-based sockets API extensions for handling
applications. The applications are completely HIP aware and can HIP-based identifiers explicitly in HIP-aware applications. It is up
control the HIP layer and Host Identifiers. This document defines to the applications, or a high-level programming languages or
C-based sockets API extensions for handling the bindings explicitly. libraries, to manage the identifiers. The extensions in this
The extensions expose the identity-locator split to SHIM-aware document are mainly related to the initial discovery of the
applications and it is up to the application, or a higher level identifiers, i.e., DNS resolution step.
programming language, to manage the identities and locators.
The API extensions introduce a new socket address structure. The The API extensions introduce a new address family, AF_HIP, and a new
structure requires a new address family, PF_SHIM, for sockets that socket address structure for sockets using Host Identity Tags (HITs)
use HITs and locators explicitly. An application can also use the explicitly. PF_HIP is used as an alias for AF_HIP in this document
family to detect SHIM support in the local host. because the distinction between PF and AF has been lost in the
practice.
Hosts may accept incoming or initiate outgoing communications without Some applications may accept incoming communications from any
the knowledge of the identity of the peer. This document describes identifier. Other applications may initiate outgoing communications
also how to address this situation using late binding based on new without knowledge of the peer identifier in Opportunistic Mode
wildcards. [I-D.ietf-hip-base] by just relying on a peer locator. This document
describes how to address both situations using "wildcards" as
described later in this document.
There are two related IETF documents that are define other related There are two related API documents. Multihoming and explicit
API extensions. Multihoming 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 are defined in [I-D.ietf-btns-c-api] and channel bindings APIs are defined in [I-D.ietf-btns-c-api]. The
extensions defined in this document can be used independently of the
3. Design Model two mentioned related API documents.
In this section, the native SHIM API design is described from an
design point of view. We describe the layering and namespace model.
We conclude the discussion with a description of the resolver model.
3.1. Layering Model
The application layer accesses the transport layer via the socket
interface. The application layer uses the traditional TCP/IP IPv4 or
IPv6 interface, or the new native SHIM API interface provided by the
socket layer. The layering model is illustrated in Figure 1. For
simplicity, the IPsec layer has been excluded from the figure.
+--------------------------------+ To recap, the extensions in this document have two goals. The first
Application Layer | Application | goal is to allow HIP-aware applications to resolve HITs explicitly.
+----------+----------+----------+ The second goal is that applications can explicitly accept
Socket Layer | IPv4 API | IPv6 API | SHIM API | communications with unknown peer identifiers.
+----------+----+-----+----------+
Transport Layer | TCP | UDP |
+---------------+----------------+
SHIM Layer | HIP and other SHIMs |
+---------------+----------------+
Network Layer | IPv4 | IPv6 |
+---------------+----------------+
Link Layer | Ethernet | Etc |
+---------------+----------------+
Figure 1 3. Design Model
The SHIM layer is as a shim/wedge layer between the transport and In this section, the native HIP APIs is described from a design point
network layers. The datagrams delivered between the transport and of view. We first describe the namespace model and conclude the
network layers are intercepted in the SHIM layer to see if the discussion with a description of the resolver model.
datagrams are SHIM related and require SHIM intervention.
3.2. Namespace Model 3.1. Namespace Model
The namespace model is shown in Table 2 from SHIM point of view. The The namespace model is shown in Table 2 from HIP point of view. The
namespace identifiers are described in this section. namespace identifiers are described in this section.
+-------------------+-------------------------+ +-------------------+---------------------------+
| Layer | Identifier | | Layer | Identifier |
+-------------------+-------------------------+ +-------------------+---------------------------+
| User Interface | FQDN | | User Interface | Relative hostname or FQDN |
| Application Layer | ULID, port and protocol | | Application Layer | HIT, port and protocol |
| Transport Layer | ULID, port | | Transport Layer | HIT, port |
| SHIM Layer | ULID | | HIP Layer | HIT or HI |
| Network Layer | Locator | | Network Layer | Locator |
+-------------------+-------------------------+ +-------------------+---------------------------+
Table 2 Table 2
User interfaces input human-readable names and translate them to User interfaces input human-readable names and translate them to
machine-readable names. In SHIM API, the ULID is a HIT when the machine-readable names. In native APIs for HIP, the machine readable
underlying protocol is HIP. The ULID is present at the application names are HITs. The HITs are present at the application layer, and
layer and also transport layer checksum is calculated based on it. transport-layer pseudo checksums are based on HITs. The HIP layer
The SHIM layer handles also ULIDs and translates them locators for transforms the HITs to locators for the network layer and vice versa.
the network layer.
3.3. Interaction with the Resolver 3.2. Interaction with the Resolver
Before an application can establish network communications, it must Before an application can establish network communications with the
translate a hostname to the corresponding identifier(s). DNS based entity named by a given FQDN or relative host name, the application
hostname-to-identifier translation is illustrated in Figure 2. The must translate the name into the corresponding identifier(s). DNS
application calls the resolver (step a.) to resolve an FQDN (step based hostname-to-identifier translation is illustrated in Figure 1.
b.). The DNS server responds with ULIDs and a set of locators (step The application calls the resolver (step a.) to resolve an FQDN (step
c.). The resolver may not directly pass the ULIDs and the locators b.). The DNS server responds with a list of HITs and a set of
to the application, but may first inform to the SHIM module (steps d. locators (step c.). Optionally (in step d.), the resolver caches the
and e.). Finally, the resolver passes the ULIDs and locators to the HIT to locator mapping to the HIP module. The resolver returns the
application (step f.). HITs to the application in step e. Finally, the application selects
one HIT and uses it in a socket call such as connect() in step e.
+----------+ +----------+
| | | |
| DNS | | DNS |
| | | |
+----------+ +----------+
^ | ^ |
b. <FQDN> | | c. <ULIDs + locators = U+L> b. <FQDN> | | c. <HITs + locators
| v | v = HITs+locs>
+-------------+ a. <FQDN> +----------+ +-------------+ a. getaddrinfo(<FQDN>) +----------+
| |----------->| | | |------------------------>| |
| Application | | Resolver | | Application | | Resolver |
| |<-----------| | | |<------------------------| |
+-------------+ f. <U+L> +----------+ +-------------+ e. <HITs> +----------+
^ |
| |
e. <U+L> | | d. <U+L>
| v
+----------+
| | | |
| SHIM |
| | | |
+----------+ | f. connect(<HIT>) | d. <HITs+locs>
v v
+----------+ +----------+
| | | |
| TCP/IP | | HIP |
| Stack | | |
+----------+ +----------+
Figure 2 Figure 1
In practise, the resolver functionality can implemented in different In practice, the resolver functionality can be implemented in
ways. It may be implemented in existing resolver libraries or as an different ways. For example, it may be implemented in existing
DNS proxy. resolver libraries or as a DNS proxy.
The extensions in this document focus on the use of the resolver to
map host names to HITs and locators in HIP-aware applications. The
resolver associates implicitly the the HIT with the locator(s).
However, it is possible that an application operates directly with a
peer HIT without interacting with the resolver. In such a case, the
application may resort to the system to map the peer HIT to an IP
address. Alternatively, the application can explicitly map the HIT
to an IP address as specified in [I-D.ietf-shim6-multihome-shim-api].
Both of these two approaches may be more prone to errors than the use
resolver with host names. Hence, HIP-aware applications should
prefer to use the resolver with host names.
4. API Syntax and Semantics 4. API Syntax and Semantics
In this section, we describe the native SHIM API using the syntax of In this section, we describe the native HIP APIs using the syntax of
the C programming language and present only the ``external'' the C programming language. We limit the description to the
interfaces and data structures that are visible to the applications. interfaces and data structures that are either modified or completely
We limit the description to those interfaces and data structures that new, because the native HIP APIs are otherwise identical to the
are either modified or completely new, because the SHIM API is sockets API [POSIX].
otherwise identical to the sockets API [POSIX].
4.1. Socket Family and Address Structure 4.1. Socket Family and Address Structure Extensions
We introduce a new protocol family, PF_SHIM, for the sockets API. The sockets API extensions define a new protocol family, PF_HIP, and
The AF_SHIM constant is an alias for it. The use of the PF_SHIM a new address family, AF_HIP. The AF_HIP and PF_HIP are aliases to
constant is mandatory with the socket() function if the SHIM API is each other. The use of the PF_HIP constant is mandatory with the
to be used in the application. The PF_SHIM constant is given as the socket() function when application uses the native HIP APIs. The
first argument (domain) to the socket() function. application gives the PF_HIP constant as the first argument (domain)
to the socket() function. The system returns EPFNOSUPPORT in the
socket call when it does not support HIP.
The ULIDs and locators are contained in the sockaddr_shim structure, The application can also use the new PF_HIP family to detect HIP
which is shown in Figure 3. The family of the socket, shim_family, support in the local host. Namely, the application creates a socket
is set to PF_SHIM. The port number sins_port is two octets and the by calling socket() function with the first argument (domain) as
sins_ulid is four octets. The ULID value is an IPv6 address. The PF_HIP. The system returns a positive integer representing a socket
locator is an IPv6 address or IPv6-mapped address IPv4 address as descriptor when the system supports HIP. Otherwise, the system
defined in - [RFC3493]. The family is stored in host byte order and returns -1 and sets errno to EAFNOSUPPORT.
the ULID and locator are stored in network byte order.
typedef struct in6_addr shim_ulid_t; A HIT is contained in a sockaddr_hip structure, which is shown in
typedef struct in6_addr shim_locator_t; Figure 2. The family of the socket, ship_family, is set to PF_HIP.
The port number ship_port is two octets and the sins_hit is four
octets. The HIT value is an IPv6 address and it is stored in network
byte order.
struct sockaddr_shim { #include <netinet/in.h>
uint8_t sins_len;
uint8_t sins_family; typedef struct in6_addr hip_hit_t;
uint16_t sins_port;
shim_ulid_t sins_ulid; struct sockaddr_hip {
shim_locator_t sins_locator; uint8_t ship_len;
uint64_t sins_flags; uint8_t ship_family;
uint16_t ship_port;
uint64_t ship_flags;
hip_hit_t ship_hit;
uint8_t reserved[16];
} }
Figure 3 Figure 2
The application usually sets the sins_ulid field using the resolver. The application usually sets the ship_hit field using the resolver.
However, three special macros can be used to directly set a value However, the application can use three special wildcard macros to set
into the sins_ulid field. The macros are SHIM_ANY, SHIM_ANY_PUB and a value directly into the ship_hit field. The macros are
SHIM_ANY_ANON. They denote an ULID value associated with a wildcard HIP_HIT_ANY, HIP_HIT_ANY_PUB and HIP_HIT_ANY_ANON. They denote a HIT
ULID of any, public, or anonymous type. value associated with a wildcard HIT of any, public, or anonymous
type. The HIP_HIT_ANY means HIP_HIT_ANY_PUB or HIP_HIT_ANY_ANON.
The anonymous identifiers refer to the use anonymous identifiers as
specified in [RFC4423]. The system may designate anonymous
identifiers as meta data associated with a HIT regarding whether it
has been published or not, but that from the HIP protocol
perspective, there is no difference in the classes of HITs.
In server applications, the SHIM_* macros accept incoming connections The application can use the macro HIP_IS_IPV6_ADDR_ANON_HIT to verify
to all of the ULID of the local host. The macros correspond to the whether a HIT is anonymous or public. The macro inputs a pointer to
a hip_hit_t structure and returns an integer (int) set to one when
the corresponding HIT is anonymous and zero when it is public. The
macro returns -1 when the anonymity status is not available.
The application can use the HIP_HIT_ macros to accept incoming
communications to all of the HITs of the local host. Incoming
communications refers here to the functions such as bind(),
recvfrom() and recvmsg(). The HIP_HIT_ macros correspond to the
sockets API macros INADDR_ANY and IN6ADDR_ANY_INIT, but they are sockets API macros INADDR_ANY and IN6ADDR_ANY_INIT, but they are
applicable at the SHIM layer. It should be noticed that only one applicable at the HIP layer. After initial contact with the peer,
process at a time in a host can bind with the SHIM_*ANY macro to the the local and peer HITs can be discovered using getsockname() and
same port to avoid ambiguous bindings. getpeername() calls for connection oriented sockets.
A client application can use the SHIM_ANY macro to establish a The application also uses the the HIP_HIT_ANY macro in ship_hit field
connection when only the server locator (and not the ULID) is known to establish outgoing communications in Opportunistic mode
beforehand. [I-D.ietf-hip-base], when the application knows the remote peer
locator but not the HIT. Outgoing communications refers here to the
use of functions such as connect(), sendto() and sendmsg(). After
initial contact with the peer, the application discovers local and
peer HITs using getsockname() and getpeername() calls when it is
using connection-oriented sockets.
In both client and server based applications, the use of the The HIP_HIT_ANY_ macros also allow non-ORCHID based communications.
SHIM_ANY* macro accepts also non-SHIM based communications to To distinguish between ORCHID [RFC4843] and non-ORCHID-based
maximize backwards compatibility. When the application wants communications in the case of the HIP_HIT_ANY_ macros, the
enforces the use of SHIM-based communications with ORCHID prefix application calls getsockname() and getpeername() to discover the
[RFC4843], it sets the flag SHIM_FLAG_ONLY_ORCHID in sins_flags. actual identifiers used for the communications and verifies orchid
Alternatively, the application accepts both ORCHID and non-ORCHID- prefix with HIP_IS_IPV6_ADDR_ORCHID macro. The macro inputs a
based communications, but informs the difference e.g. to the user. pointer to an in6_addr structure and returns 1 when the address has
In this case, the application calls SHIM_IPV6_ADDR_IS_ORCHID macro orchid prefix and 0 otherwise. Alternatively, the application can
which inputs a pointer to a in6_addr and returns 1 when the address set the flag HIP_FLAG_ONLY_ORCHID in ship_flags to allow only ORCHID-
has orchid prefix and 0 otherwise. based communications.
Applications can also implement access control using the ULIDs. In Applications can also implement access control using the HITs. In
such a case, the application can compare two ULIDs using memcmp() or such a case, the application can compare two HITs using memcmp() or
similar function. similar function. It should be noticed that different connection
attempts between the same two hosts can result in different HITs
because a host is allowed to have multiple HITs.
4.2. Resolver 4.2. Resolver Extensions
The SHIM API uses the getaddrinfo resolver function which the The HIP APIs introduces a new addrinfo flag, AI_HIP, to be used by
application uses to query both ULIDs and locators. The resolver application to query for both HIT and locator information via the
introduces a new data structure, which is used both as the input and getaddrinfo() resolver function [RFC3493]. The getaddrinfo()
output argument for the resolver. The data structure is illustrated function uses a data structure used for both input to and output from
in Figure 4. the resolver. The data structure is illustrated in Figure 3.
#include <netdb.h>
struct addrinfo { struct addrinfo {
int ai_flags; /* e.g. AI_SHIM */ int ai_flags; /* e.g. AI_HIP */
int ai_family; /* e.g. PF_SHIM */ int ai_family; /* e.g. PF_HIP */
int ai_socktype; /* e.g. SOCK_STREAM */ int ai_socktype; /* e.g. SOCK_STREAM */
int ai_protocol; /* 0 or IPPROTO_HIP */ int ai_protocol; /* 0 or IPPROTO_HIP */
size_t ai_addrlen; /* length of the endpoint */ size_t ai_addrlen; /* size of *ai_addr */
struct sockaddr *ai_addr; /* socket address */ struct sockaddr *ai_addr; /* sockaddr_hip */
char *ai_canonname; /* canon. name of the host */ char *ai_canonname; /* canon. name of the host */
struct addrinfo *ai_next; /* next endpoint */ struct addrinfo *ai_next; /* next endpoint */
}; };
Figure 4 Figure 3
In addrinfo structures, the family field is set to PF_SHIM when the
socket address structure contains an ULID that refers to ULID, such
as HIT.
The flag AI_SHIM must be set, or otherwise the resolver does not
return sockaddr_shim data structures to guarantee that legacy
applications do not break. Some applications may prefer configuring
the locators manually and can set the AI_SHIM_NOLOCATORS flag to
prohibit the getaddrinfo from resolving any locators.
The ai_family field is PF_SHIM with SHIM-specific addrinfo data The flag AI_HIP must be set in the ai_flags, or otherwise the
structures. resolver does not return sockaddr_hip data structures. The resolver
returns EAI_BADFLAGS when AI_HIP is not supported. The simultaneous
use of both AI_HIP and AI_PASSIVE flags equals to the use HIP_HIT_ANY
macro as described in section Section 4.1. Similarly, the use of
AI_PASSIVE_PUB and AI_PASSIVE_ANON flag equals to the use of
HIP_HIT_ANY_PUB and HIP_HIT_ANY_ANON.
The protocol field is 0 when the getaddrinfo caller does not care The ai_family field is set to PF_HIP in the addrinfo structure when
about the specific SHIM protocol to be used. The caller (or the ai_addr points to a sockaddr_hip structure.
resolver) can set this field also to IPPROTO_HIP.
ai_addrlen is the size of the structure pointed by ai_addr. When ai_protocol field is set to zero, the resolver also returns
locators in sockaddr_in and sockaddr_in6 structures in addition to
sockaddr_hip structures. The resolver only returns sockaddr_hip
structures when ai_protocol field is set to IPPROTO_HIP or a
sockaddr_hip structure is given as the hint argument to the resolver.
The ai_addr points to a sockaddr_shim structure when the value of A HIP-aware application creates the sockaddr_hip structures manually
ai_family is PF_SHIM. The resolver sets SHIM_RVS in sins_flags of or obtains them from the resolver. The manual configuration is
the when the locator belongs to a rendezvous server described in [I-D.ietf-shim6-multihome-shim-api]. This document
[I-D.ietf-hip-dns]. defines resolver extensions for getaddrinfo resolver [RFC3493].
The SHIM API does not introduce changes to the interface syntax of #include <netdb.h>
the existing sockets API functions, such as bind(), connect(),
send(), sendto(), sendmsg(), recv(), recvfrom(), and recvmsg().
However, the SHIM-aware application usually passes the functions a
sockaddr_shim structure instead of a sockaddr_in or sockaddr_in6
structure. A SHIM-aware application either creates the sockaddr_shim
structures manually or obtains them from the resolver. The
getaddrinfo resolver [RFC3493] is shown in Figure 5.
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 5 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 argument. The return value is zero result of the query into the res argument. The return value is zero
on success, or a non-zero error value on error. The nodename 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 local host. The servname parameter declares the port denotes the local host. The servname parameter declares the port
number to be set in the socket addresses in the res output argument. number to be set in the socket addresses in the res output argument.
Both the nodename and servname cannot be NULL. Both the nodename and servname cannot be NULL.
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. For example, the attributes required from the resolved endpoints. A NULL hints
resolver returns only anonymous endpoints in the output argument res argument indicates that any kind of endpoints are acceptable.
when the application sets the ai_addr pointer of hints to point to a
sockaddr_shim structure with sins_ulid filled with SHIM_ANY_ANON. A
NULL hints 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 must free res argument with the free_addrinfo The application frees res argument with the free_addrinfo function.
function. The res argument contains a linked list of the resolved The res argument contains a linked list of the resolved endpoints.
endpoints. The linked list contains sockaddr_shim structures only The linked list contains sockaddr_hip structures only when the input
when the input argument has the AI_SHIM flag set. When the resolver argument has the AI_HIP flag set. The resolver inserts HITs before
finds SHIM identifiers, it inserts them to the front of the list. any locators.
Resolving of a hostname may result in multiple locators associated to Resolver can return a HIT which maps to multiple locators. The
a single ULID, but the sockaddr_shim structure contains only a single resolver may cache the locator mappings to the HIP module. The HIP
ULID-locator pair. The resolver handles this by repeating the ULD as module manages the multiple locators according to local policies of
many time as needed. For example, let us consider a case where the the host.
resolver finds an ULID that is associated to two locators. In such a
case, the resolver outputs two sockaddr_shim structures with the same
ULID but different locators.
5. IANA Considerations 4.3. Manual Handling of Locators
The system resolver, or the HIP module, maps HITs to locators
implicitly. However, some applications may want to specify initial
locator mappings explicitly. In such a case, the application first
creates a socket with PF_HIP as the domain argument. Second, the
application binds the socket to a local or peer locator with the
setsockopt function with either SHIM_LOC_LOCAL_PREF or
SHIM_LOC_PEER_PREF as the socket option name as defined in
[I-D.ietf-shim6-multihome-shim-api]. Third, the application creates
a valid sockaddr_hip structure. Finally, the application associates
the socket also with the sockaddr_hip structure by calling some
socket-related function, such as connect or bind. The function
returns EINVALIDLOCATOR when the HIT is not reachable at the
specified locator.
It should be noticed that the application may just configure the HIT
manually without setting the locator. In this scenario, the
application relies on the system to map the HIT to an IP address.
When the system fails to provide the mapping, it returns
EADDRNOTAVAIL in the called sockets API function to the application
and sets errno to indicate the error.
5. Summary of New Definitions
Table 3 summarizes the new macro and structures defined in this
document.
+-----------------+---------------------------+
| Header | Definition |
+-----------------+---------------------------+
| <sys/socket.h> | PF_HIP |
| <sys/socket.h> | AF_HIP |
| <netinet/in.h> | IPPROTO_HIP |
| <netinet/hip.h> | HIP_HIT_ANY |
| <netinet/hip.h> | HIP_HIT_ANY_PUB |
| <netinet/hip.h> | HIP_HIT_ANY_ANON |
| <netinet/hip.h> | HIP_IS_IPV6_ADDR_ORCHID |
| <netinet/hip.h> | HIP_IS_IPV6_ADDR_ANON_HIT |
| <netinet/hip.h> | HIP_FLAG_ONLY_ORCHID |
| <netdb.h> | AI_HIP |
| <netdb.h> | AI_PASSIVE_ANON |
| <netdb.h> | AI_PASSIVE_PUB |
| <netdb.h> | AI_HIP_NOLOCATORS |
| <netinet/hip.h> | hip_hit_t |
| <netinet/in.h> | sockaddr_hip |
+-----------------+---------------------------+
Table 3
6. IANA Considerations
No IANA considerations. No IANA considerations.
6. Security Considerations 7. Security Considerations
To be done. No security considerations currently.
7. Acknowledgements 8. Acknowledgements
Jukka Ylitalo and Pekka Nikander have contributed many ideas, time Jukka Ylitalo and Pekka Nikander have contributed many ideas, time
and effort to the HIP API. Thomas Henderson, Kristian Slavov, Julien and effort to the native HIP APIs. Thomas Henderson, Kristian
Laganier, Jaakko Kangasharju, Mika Kousa, Jan Melen, Andrew McGregor, Slavov, Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan Melen,
Sasu Tarkoma, Lars Eggert, Joe Touch, Antti Jaervinen, Anthony Andrew McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti
Joseph, Teemu Koponen and Juha-Matti Tapio have also provided Jaervinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari Keraenen,
valuable ideas and feedback. Thanks for the APPS area folks, Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews, Jan Melen and
Stephane Bortzmeyer, Chris Newman, Tony Finch, "der Mouse" and Gonzalo Camarillo have also provided valuable ideas or feedback.
especially Keith Moore for comments. Thanks for the APPS area folks, Stephane Bortzmeyer, Chris Newman,
Tony Finch, "der Mouse" and Keith Moore for comments.
8. Normative References 9. Normative References
[I-D.henderson-hip-applications] [I-D.henderson-hip-applications]
Henderson, T. and P. Nikander, "Using HIP with Legacy Henderson, T. and P. Nikander, "Using HIP with Legacy
Applications", draft-henderson-hip-applications-03 (work Applications", draft-henderson-hip-applications-03 (work
in progress), May 2006. in progress), May 2006.
[I-D.ietf-btns-c-api] [I-D.ietf-btns-c-api]
Komu, M., "IPsec Application Programming Interfaces", Komu, M., "IPsec Application Programming Interfaces",
draft-ietf-btns-c-api-00 (work in progress), June 2007. draft-ietf-btns-c-api-01 (work in progress), July 2007.
[I-D.ietf-hip-dns] [I-D.ietf-hip-base]
Nikander, P. and J. Laganier, "Host Identity Protocol Moskowitz, R., Nikander, P., Jokela, P., and T. Henderson,
(HIP) Domain Name System (DNS) Extensions", "Host Identity Protocol", draft-ietf-hip-base-10 (work in
draft-ietf-hip-dns-09 (work in progress), April 2007. progress), October 2007.
[I-D.ietf-shim6-multihome-shim-api] [I-D.ietf-shim6-multihome-shim-api]
Komu, M., "Socket Application Program Interface (API) for Komu, M., "Socket Application Program Interface (API) for
Multihoming Shim", draft-ietf-shim6-multihome-shim-api-02 Multihoming Shim", draft-ietf-shim6-multihome-shim-api-03
(work in progress), March 2007. (work in progress), July 2007.
[I-D.ietf-shim6-proto]
Bagnulo, M. and E. Nordmark, "Shim6: Level 3 Multihoming
Shim Protocol for IPv6", draft-ietf-shim6-proto-09 (work
in progress), November 2007.
[POSIX] Institute of Electrical and Electronics Engineers, "IEEE [POSIX] Institute of Electrical and Electronics Engineers, "IEEE
Std. 1003.1-2001 Standard for Information Technology - Std. 1003.1-2001 Standard for Information Technology -
Portable Operating System Interface (POSIX)", Dec 2001. Portable Operating System Interface (POSIX)", Dec 2001.
[RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. [RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W.
Stevens, "Basic Socket Interface Extensions for IPv6", Stevens, "Basic Socket Interface Extensions for IPv6",
RFC 3493, February 2003. RFC 3493, February 2003.
[RFC4423] Moskowitz, R. and P. Nikander, "Host Identity Protocol
(HIP) Architecture", RFC 4423, May 2006.
[RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix [RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix
for Overlay Routable Cryptographic Hash Identifiers for Overlay Routable Cryptographic Hash Identifiers
(ORCHID)", RFC 4843, April 2007. (ORCHID)", RFC 4843, April 2007.
Author's Address Author's Address
Miika Komu Miika Komu
Helsinki Institute for Information Technology Helsinki Institute for Information Technology
Tammasaarenkatu 3 Metsaenneidonkuja 4
Helsinki Helsinki
Finland Finland
Phone: +358503841531 Phone: +358503841531
Fax: +35896949768 Fax: +35896949768
Email: miika@iki.fi Email: miika@iki.fi
URI: http://www.iki.fi/miika/ URI: http://www.iki.fi/miika/
Full Copyright Statement Full Copyright Statement
 End of changes. 77 change blocks. 
266 lines changed or deleted 342 lines changed or added

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