One document matched: draft-ietf-hip-native-api-03.txt
Differences from draft-ietf-hip-native-api-02.txt
Host Identity Protocol M. Komu
Internet-Draft Helsinki Institute for Information
Intended status: Informational Technology
Expires: May 22, 2008 November 19, 2007
Native Application Programming Interfaces (APIs) for Host Identity
Protocol (HIP)
draft-ietf-hip-native-api-03
Status of this Memo
By submitting this Internet-Draft, each author represents that any
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
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
be created, except to publish it as an RFC and to translate it into
languages other than English.
Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet-
Drafts.
Internet-Drafts are draft documents valid for a maximum of six months
and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html.
This Internet-Draft will expire on May 22, 2008.
Copyright Notice
Copyright (C) The IETF Trust (2007).
Abstract
This document defines extensions to the current sockets API for Host
Identity Protocol (HIP). The extensions focus on the initial
discovery of public-key based identifiers. Using the extensions, the
application can verify that the identifier is a Host Identity Tag
Komu Expires May 22, 2008 [Page 1]
Internet-Draft Native APIs for HIP November 2007
(HIT) and it can require the system resolver to return only HITs from
DNS. The application can also to explicitly allow more relaxed
security models where the communication can be non-HIP based in the
absence of a peer identifiers, or that the application allows peer
identity to be discovered after initial contact directly with the
peer.
Table of Contents
1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
3. Design Model . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Namespace Model . . . . . . . . . . . . . . . . . . . . . 4
3.2. Interaction with the Resolver . . . . . . . . . . . . . . 5
4. API Syntax and Semantics . . . . . . . . . . . . . . . . . . . 6
4.1. Socket Family and Address Structure Extensions . . . . . . 6
4.2. Resolver Extensions . . . . . . . . . . . . . . . . . . . 8
4.3. Manual Handling of Locators . . . . . . . . . . . . . . . 10
5. Summary of New Definitions . . . . . . . . . . . . . . . . . . 10
6. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 11
7. Security Considerations . . . . . . . . . . . . . . . . . . . 11
8. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11
9. Normative References . . . . . . . . . . . . . . . . . . . . . 12
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12
Intellectual Property and Copyright Statements . . . . . . . . . . 14
Komu Expires May 22, 2008 [Page 2]
Internet-Draft Native APIs for HIP November 2007
1. Terminology
The terms used in this document are summarized in Table 1.
+---------+---------------------------------------------------------+
| Term | Explanation |
+---------+---------------------------------------------------------+
| HIP | Host Identity Protocol |
| HIT | Host Identity Tag, a 100-bit hash of a public key with |
| | a 28 bit prefix |
| LSI | Local Scope Identifier, a local, 32-bit descriptor for |
| | a given public key. |
| Locator | Routable IPv4 or IPv6 address used at the lower layers |
+---------+---------------------------------------------------------+
Table 1
2. Introduction
The Host Identity Protocol (HIP) [RFC4423] proposes a new
cryptographic namespace by separating the roles of end-point
identifiers and locators by introducing a new namespace to the TCP/IP
stack. SHIM6 [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
visibility in which applications are completely unaware of the
underlying HIP layer. Such HIP-unaware applications use HIP-based
identifiers, such as LSIs or HITs, instead of IPv4 or IPv6 addresses
and cannot observe the identifier-locator bindings.
This document defines C-based sockets API extensions for handling
HIP-based identifiers explicitly in HIP-aware applications. It is up
to the applications, or a high-level programming languages or
libraries, to manage the identifiers. The extensions in this
document are mainly related to the initial discovery of the
identifiers, i.e., DNS resolution step.
The API extensions introduce a new address family, AF_HIP, and a new
socket address structure for sockets using Host Identity Tags (HITs)
Komu Expires May 22, 2008 [Page 3]
Internet-Draft Native APIs for HIP November 2007
explicitly. PF_HIP is used as an alias for AF_HIP in this document
because the distinction between PF and AF has been lost in the
practice.
Some applications may accept incoming communications from any
identifier. Other applications may initiate outgoing communications
without knowledge of the peer identifier in Opportunistic Mode
[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 API documents. Multihoming and explicit
locator-handling related APIs are defined in
[I-D.ietf-shim6-multihome-shim-api]. IPsec related policy attributes
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
two mentioned related API documents.
To recap, the extensions in this document have two goals. The first
goal is to allow HIP-aware applications to resolve HITs explicitly.
The second goal is that applications can explicitly accept
communications with unknown peer identifiers.
3. Design Model
In this section, the native HIP APIs is described from a design point
of view. We first describe the namespace model and conclude the
discussion with a description of the resolver model.
3.1. Namespace Model
The namespace model is shown in Table 2 from HIP point of view. The
namespace identifiers are described in this section.
+-------------------+---------------------------+
| Layer | Identifier |
+-------------------+---------------------------+
| User Interface | Relative hostname or FQDN |
| Application Layer | HIT, port and protocol |
| Transport Layer | HIT, port |
| HIP Layer | HIT or HI |
| Network Layer | Locator |
+-------------------+---------------------------+
Table 2
User interfaces input human-readable names and translate them to
Komu Expires May 22, 2008 [Page 4]
Internet-Draft Native APIs for HIP November 2007
machine-readable names. In native APIs for HIP, the machine readable
names are HITs. The HITs are present at the application layer, and
transport-layer pseudo checksums are based on HITs. The HIP layer
transforms the HITs to locators for the network layer and vice versa.
3.2. Interaction with the Resolver
Before an application can establish network communications with the
entity named by a given FQDN or relative host name, the application
must translate the name into the corresponding identifier(s). DNS
based hostname-to-identifier translation is illustrated in Figure 1.
The application calls the resolver (step a.) to resolve an FQDN (step
b.). The DNS server responds with a list of HITs and a set of
locators (step c.). Optionally (in step d.), the resolver caches the
HIT to locator mapping to the HIP module. The resolver returns the
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 |
| |
+----------+
^ |
b. <FQDN> | | c. <HITs + locators
| v = HITs+locs>
+-------------+ a. getaddrinfo(<FQDN>) +----------+
| |------------------------>| |
| Application | | Resolver |
| |<------------------------| |
+-------------+ e. <HITs> +----------+
| |
| |
| f. connect(<HIT>) | d. <HITs+locs>
v v
+----------+ +----------+
| | | |
| TCP/IP | | HIP |
| Stack | | |
+----------+ +----------+
Figure 1
In practice, the resolver functionality can be implemented in
different ways. For example, it may be implemented in existing
resolver libraries or as a DNS proxy.
The extensions in this document focus on the use of the resolver to
Komu Expires May 22, 2008 [Page 5]
Internet-Draft Native APIs for HIP November 2007
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
In this section, we describe the native HIP APIs using the syntax of
the C programming language. We limit the description to the
interfaces and data structures that are either modified or completely
new, because the native HIP APIs are otherwise identical to the
sockets API [POSIX].
4.1. Socket Family and Address Structure Extensions
The sockets API extensions define a new protocol family, PF_HIP, and
a new address family, AF_HIP. The AF_HIP and PF_HIP are aliases to
each other. The use of the PF_HIP constant is mandatory with the
socket() function when application uses the native HIP APIs. The
application gives the PF_HIP constant as the first argument (domain)
to the socket() function. The system returns EPFNOSUPPORT in the
socket call when it does not support HIP.
The application can also use the new PF_HIP family to detect HIP
support in the local host. Namely, the application creates a socket
by calling socket() function with the first argument (domain) as
PF_HIP. The system returns a positive integer representing a socket
descriptor when the system supports HIP. Otherwise, the system
returns -1 and sets errno to EAFNOSUPPORT.
A HIT is contained in a sockaddr_hip structure, which is shown in
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.
Komu Expires May 22, 2008 [Page 6]
Internet-Draft Native APIs for HIP November 2007
#include <netinet/in.h>
typedef struct in6_addr hip_hit_t;
struct sockaddr_hip {
uint8_t ship_len;
uint8_t ship_family;
uint16_t ship_port;
uint64_t ship_flags;
hip_hit_t ship_hit;
uint8_t reserved[16];
}
Figure 2
The application usually sets the ship_hit field using the resolver.
However, the application can use three special wildcard macros to set
a value directly into the ship_hit field. The macros are
HIP_HIT_ANY, HIP_HIT_ANY_PUB and HIP_HIT_ANY_ANON. They denote a HIT
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.
The application can use the macro HIP_IS_IPV6_ADDR_ANON_HIT to verify
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
applicable at the HIP layer. After initial contact with the peer,
the local and peer HITs can be discovered using getsockname() and
getpeername() calls for connection oriented sockets.
The application also uses the the HIP_HIT_ANY macro in ship_hit field
to establish outgoing communications in Opportunistic mode
[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
Komu Expires May 22, 2008 [Page 7]
Internet-Draft Native APIs for HIP November 2007
peer HITs using getsockname() and getpeername() calls when it is
using connection-oriented sockets.
The HIP_HIT_ANY_ macros also allow non-ORCHID based communications.
To distinguish between ORCHID [RFC4843] and non-ORCHID-based
communications in the case of the HIP_HIT_ANY_ macros, the
application calls getsockname() and getpeername() to discover the
actual identifiers used for the communications and verifies orchid
prefix with HIP_IS_IPV6_ADDR_ORCHID macro. The macro inputs a
pointer to an in6_addr structure and returns 1 when the address has
orchid prefix and 0 otherwise. Alternatively, the application can
set the flag HIP_FLAG_ONLY_ORCHID in ship_flags to allow only ORCHID-
based communications.
Applications can also implement access control using the HITs. In
such a case, the application can compare two HITs using memcmp() or
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 Extensions
The HIP APIs introduces a new addrinfo flag, AI_HIP, to be used by
application to query for both HIT and locator information via the
getaddrinfo() resolver function [RFC3493]. The getaddrinfo()
function uses a data structure used for both input to and output from
the resolver. The data structure is illustrated in Figure 3.
#include <netdb.h>
struct addrinfo {
int ai_flags; /* e.g. AI_HIP */
int ai_family; /* e.g. PF_HIP */
int ai_socktype; /* e.g. SOCK_STREAM */
int ai_protocol; /* 0 or IPPROTO_HIP */
size_t ai_addrlen; /* size of *ai_addr */
struct sockaddr *ai_addr; /* sockaddr_hip */
char *ai_canonname; /* canon. name of the host */
struct addrinfo *ai_next; /* next endpoint */
};
Figure 3
The flag AI_HIP must be set in the ai_flags, or otherwise the
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
Komu Expires May 22, 2008 [Page 8]
Internet-Draft Native APIs for HIP November 2007
AI_PASSIVE_PUB and AI_PASSIVE_ANON flag equals to the use of
HIP_HIT_ANY_PUB and HIP_HIT_ANY_ANON.
The ai_family field is set to PF_HIP in the addrinfo structure when
ai_addr points to a sockaddr_hip structure.
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.
A HIP-aware application creates the sockaddr_hip structures manually
or obtains them from the resolver. The manual configuration is
described in [I-D.ietf-shim6-multihome-shim-api]. This document
defines resolver extensions for getaddrinfo resolver [RFC3493].
#include <netdb.h>
int getaddrinfo(const char *nodename,
const char *servname,
const struct addrinfo *hints,
struct addrinfo **res)
void free_addrinfo(struct addrinfo *res)
Figure 4
As described in [RFC3493], the getaddrinfo function takes 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
on success, or a non-zero error value on error. The nodename
argument specifies the host name to be resolved; a NULL argument
denotes the local host. The servname parameter declares the port
number to be set in the socket addresses in the res output argument.
Both the nodename and servname cannot be NULL.
The input argument "hints" acts like a filter that defines the
attributes required from the resolved endpoints. A NULL hints
argument indicates that any kind of endpoints are acceptable.
The output argument "res" is dynamically allocated by the resolver.
The application frees res argument with the free_addrinfo function.
The res argument contains a linked list of the resolved endpoints.
The linked list contains sockaddr_hip structures only when the input
argument has the AI_HIP flag set. The resolver inserts HITs before
any locators.
Resolver can return a HIT which maps to multiple locators. The
Komu Expires May 22, 2008 [Page 9]
Internet-Draft Native APIs for HIP November 2007
resolver may cache the locator mappings to the HIP module. The HIP
module manages the multiple locators according to local policies of
the host.
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.
Komu Expires May 22, 2008 [Page 10]
Internet-Draft Native APIs for HIP November 2007
+-----------------+---------------------------+
| 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.
7. Security Considerations
No security considerations currently.
8. Acknowledgements
Jukka Ylitalo and Pekka Nikander have contributed many ideas, time
and effort to the native HIP APIs. Thomas Henderson, Kristian
Slavov, Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan Melen,
Andrew McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti
Jaervinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari Keraenen,
Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews, Jan Melen and
Gonzalo Camarillo have also provided valuable ideas or feedback.
Thanks for the APPS area folks, Stephane Bortzmeyer, Chris Newman,
Tony Finch, "der Mouse" and Keith Moore for comments.
Komu Expires May 22, 2008 [Page 11]
Internet-Draft Native APIs for HIP November 2007
9. Normative References
[I-D.henderson-hip-applications]
Henderson, T. and P. Nikander, "Using HIP with Legacy
Applications", draft-henderson-hip-applications-03 (work
in progress), May 2006.
[I-D.ietf-btns-c-api]
Komu, M., "IPsec Application Programming Interfaces",
draft-ietf-btns-c-api-01 (work in progress), July 2007.
[I-D.ietf-hip-base]
Moskowitz, R., Nikander, P., Jokela, P., and T. Henderson,
"Host Identity Protocol", draft-ietf-hip-base-10 (work in
progress), October 2007.
[I-D.ietf-shim6-multihome-shim-api]
Komu, M., "Socket Application Program Interface (API) for
Multihoming Shim", draft-ietf-shim6-multihome-shim-api-03
(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
Std. 1003.1-2001 Standard for Information Technology -
Portable Operating System Interface (POSIX)", Dec 2001.
[RFC3493] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W.
Stevens, "Basic Socket Interface Extensions for IPv6",
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
for Overlay Routable Cryptographic Hash Identifiers
(ORCHID)", RFC 4843, April 2007.
Komu Expires May 22, 2008 [Page 12]
Internet-Draft Native APIs for HIP November 2007
Author's Address
Miika Komu
Helsinki Institute for Information Technology
Metsaenneidonkuja 4
Helsinki
Finland
Phone: +358503841531
Fax: +35896949768
Email: miika@iki.fi
URI: http://www.iki.fi/miika/
Komu Expires May 22, 2008 [Page 13]
Internet-Draft Native APIs for HIP November 2007
Full Copyright Statement
Copyright (C) The IETF Trust (2007).
This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors
retain all their rights.
This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property
The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights
might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information
on the procedures with respect to rights in RFC documents can be
found in BCP 78 and BCP 79.
Copies of IPR disclosures made to the IETF Secretariat and any
assurances of licenses to be made available, or the result of an
attempt made to obtain a general license or permission for the use of
such proprietary rights by implementers or users of this
specification can be obtained from the IETF on-line IPR repository at
http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at
ietf-ipr@ietf.org.
Acknowledgment
Funding for the RFC Editor function is provided by the IETF
Administrative Support Activity (IASA).
Komu Expires May 22, 2008 [Page 14]
| PAFTECH AB 2003-2026 | 2026-04-23 20:38:26 |