draft-ietf-hip-native-api-05.txt   draft-ietf-hip-native-api-06.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 14, 2009 Henderson Expires: November 23, 2009 Henderson
The Boeing Company The Boeing Company
July 13, 2008 May 22, 2009
Basic Socket Interface Extensions for Host Identity Protocol (HIP) Basic Socket Interface Extensions for Host Identity Protocol (HIP)
draft-ietf-hip-native-api-05 draft-ietf-hip-native-api-06
Status of this Memo Status of this Memo
By submitting this Internet-Draft, each author represents that any This Internet-Draft is submitted to IETF in full conformance with the
applicable patent or other IPR claims of which he or she is aware provisions of BCP 78 and BCP 79. This document may not be modified,
have been or will be disclosed, and any of which he or she becomes and derivative works of it may not be created, except to format it
aware will be disclosed, in accordance with Section 6 of BCP 79. for publication as an RFC or to translate it into languages other
This document may not be modified, and derivative works of it may not than English.
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 Internet-Drafts are working documents of the Internet Engineering
Task Force (IETF), its areas, and its working groups. Note that Task Force (IETF), its areas, and its working groups. Note that
other groups may also distribute working documents as Internet- other groups may also distribute working documents as Internet-
Drafts. Drafts.
Internet-Drafts are draft documents valid for a maximum of six months Internet-Drafts are draft documents valid for a maximum of six months
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 14, 2009. This Internet-Draft will expire on November 23, 2009.
Copyright Notice
Copyright (c) 2009 IETF Trust and the persons identified as the
document authors. All rights reserved.
This document is subject to BCP 78 and the IETF Trust's Legal
Provisions Relating to IETF Documents in effect on the date of
publication of this document (http://trustee.ietf.org/license-info).
Please review these documents carefully, as they describe your rights
and restrictions with respect to this document.
Abstract Abstract
This document defines extensions to the current sockets API for Host This document defines extensions to the current sockets API for Host
Identity Protocol (HIP). The extensions focus on the use of public- Identity Protocol (HIP). The extensions focus on the use of public-
key based identifiers discovered via DNS resolution, but define also key based identifiers discovered via DNS resolution, but define also
interfaces for manual bindings between HITs and locators. With the interfaces for manual bindings between HITs and locators. With the
extensions, the application can also support more relaxed security extensions, the application can also support more relaxed security
models where the communication can be non-HIP based, according to models where the communication can be non-HIP based, according to
local policies. The extensions in document are experimental and local policies. The extensions in document are experimental and
skipping to change at page 2, line 38 skipping to change at page 3, line 4
7. Security Considerations . . . . . . . . . . . . . . . . . . . 15 7. Security Considerations . . . . . . . . . . . . . . . . . . . 15
8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 15 8. Contributors . . . . . . . . . . . . . . . . . . . . . . . . . 15
9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 9. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15
10. Normative References . . . . . . . . . . . . . . . . . . . . . 16 10. Normative References . . . . . . . . . . . . . . . . . . . . . 16
Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17 Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 17
Intellectual Property and Copyright Statements . . . . . . . . . . 18
1. Introduction 1. Introduction
This document defines C-based sockets Application Programming This document defines C-based sockets Application Programming
Interface (API) extensions for handling HIP-based identifiers Interface (API) extensions for handling HIP-based identifiers
explicitly in HIP-aware applications. It is up to the applications, explicitly in HIP-aware applications. It is up to the applications,
or high-level programming languages or libraries, to manage the or high-level programming languages or libraries, to manage the
identifiers. The extensions in this document are mainly related to identifiers. The extensions in this document are mainly related to
the use case in which a DNS resolution step has occurred prior to the the use case in which a DNS resolution step has occurred prior to the
creation of a new socket, and assumes that the system has cached or creation of a new socket, and assumes that the system has cached or
skipping to change at page 3, line 32 skipping to change at page 3, line 32
cryptographic namespace by separating the roles of end-point cryptographic namespace by separating the roles of end-point
identifiers and locators by introducing a new namespace to the TCP/IP identifiers and locators by introducing a new namespace to the TCP/IP
stack. SHIM6 [I-D.ietf-shim6-proto] is another protocol based on stack. SHIM6 [I-D.ietf-shim6-proto] is another protocol based on
identity-locator split. Note that the APIs specified in this identity-locator split. Note that the APIs specified in this
document are specific to HIP. However, the APIs here have been document are specific to HIP. However, the APIs here have been
designed as much as possible so as not to preclude its use with other designed as much as possible so as not to preclude its use with other
protocols. The use of these APIs with other protocols is, protocols. The use of these APIs with other protocols is,
nevertheless, for further study. nevertheless, for further study.
Applications can observe the HIP layer and its identifiers in the Applications can observe the HIP layer and its identifiers in the
networking stacks with varying degrees of visibility. networking stacks with varying degrees of visibility. [RFC5338]
[I-D.ietf-hip-applications] discusses the lowest levels of visibility discusses the lowest levels of visibility in which applications are
in which applications are completely unaware of the underlying HIP completely unaware of the underlying HIP layer. Such HIP-unaware
layer. Such HIP-unaware applications in some circumstances use HIP- applications in some circumstances use HIP-based identifiers, such as
based identifiers, such as LSIs or HITs, instead of IPv4 or IPv6 LSIs or HITs, instead of IPv4 or IPv6 addresses and cannot observe
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. The macro AF_HIP is used as an alias socket address family, AF_HIP. The macro AF_HIP is used as an alias
for PF_HIP in this document because the distinction between AF and PF for PF_HIP in this document because the distinction between AF and PF
has been lost in practice. The extensions also describe a new socket has been lost in practice. The extensions also describe a new socket
address structure for sockets using Host Identity Tags (HITs) address structure for sockets using Host Identity Tags (HITs)
explicitly and describe how the socket calls in [RFC3493] are adapted explicitly and describe how the socket calls in [RFC3493] are adapted
or extended as a result. or extended as a result.
Some applications may accept incoming communications from any Some applications may accept incoming communications from any
skipping to change at page 7, line 41 skipping to change at page 7, line 41
and getpeername() calls in the context of connection oriented and getpeername() calls in the context of connection oriented
sockets. The difference between the use of the HIP_HIT_* and sockets. The difference between the use of the HIP_HIT_* and
HIP_ADDR_ANY macros here is that the former allows only HIP-based HIP_ADDR_ANY macros here is that the former allows only HIP-based
communications but the latter also allows communications without HIP. communications but the latter also allows communications without HIP.
The application also uses the HIP_HIT_ANY macro in ship_hit field to The application also uses the HIP_HIT_ANY macro in ship_hit field to
establish outgoing communications in Opportunistic mode [RFC5201], establish outgoing communications in Opportunistic mode [RFC5201],
i.e., when the application knows the remote peer locator but not the i.e., when the application knows the remote peer locator but not the
HIT. Outgoing communications refers here to the use of functions HIT. Outgoing communications refers here to the use of functions
such as connect(), sendto() and sendmsg(). However, the application such as connect(), sendto() and sendmsg(). However, the application
must first associate the socket with at least one IP address of the should first associate the socket with at least one IP address of the
peer using SHIM_LOCLIST_PEER_PREF socket option. peer using SHIM_LOCLIST_PEER_PREF socket option. The use of the
HIP_HIT_ANY macro guarantees that the communications will be based on
HIP or none at all.
The use of HIP_ADDR_ANY macro in the context of outgoing The use of HIP_ADDR_ANY macro in the context of outgoing
communications is left for further experimentation. It could be used communications is left for further experimentation. It could be used
for establishing a non-HIP based connectivity when HIP-based for establishing a non-HIP based connectivity when HIP-based
connectivity was unsuccessful. connectivity was unsuccessful.
Some applications rely on system level access control, either Some applications rely on system level access control, either
implicit or explicit (such as accept_filter() function found on BSD- implicit or explicit (such as accept_filter() function found on BSD-
based systems), but such discussion is out of scope. Other based systems), but such discussion is out of scope. Other
applications implement access control themselves by using the HITs. applications implement access control themselves by using the HITs.
skipping to change at page 8, line 40 skipping to change at page 8, line 42
}; };
Figure 3 Figure 3
Application must set both the flag AI_EXTFLAGS [RFC5014] in ai_flags Application must set both the flag AI_EXTFLAGS [RFC5014] in ai_flags
and HIP_PREFER_ORCHID in the ai_eflags, or otherwise the resolver and HIP_PREFER_ORCHID in the ai_eflags, or otherwise the resolver
does not return sockaddr_hip data structures. The resolver returns does not return sockaddr_hip data structures. The resolver returns
EAI_BADFLAGS when it does not support HIP_PREFER_ORCHID or EAI_BADFLAGS when it does not support HIP_PREFER_ORCHID or
AI_EXTFLAGS flags. AI_EXTFLAGS flags.
The system may have a HIP-aware interposing DNS agent as described in
section 3.2 in [RFC5014]. In such a case, the DNS agent returns
transparently LSIs or HITs in sockaddr_in and sockaddr_in6 structures
when available. To disable this behaviour, the application sets
AI_EXTFLAGS and AI_NO_ORCHID flags.
Application denotes its preference for public and anonymous types of Application denotes its preference for public and anonymous types of
HITs using HIP_PREFER_SRC_PUBLIC and HIP_PREFER_SRC_TMP flags in the HITs using HIP_PREFER_SRC_PUBLIC and HIP_PREFER_SRC_TMP flags in the
ai_eflags field. If the application sets neither of the flags, the ai_eflags field. If the application sets neither of the flags, the
resolver returns both public and anonymous HITs. resolver returns both public and anonymous HITs.
The simultaneous use of both HIP_PREFER_ORCHID and The simultaneous use of both HIP_PREFER_ORCHID and
HIP_PREFER_PASSIVE_* flags produces a single sockaddr_hip structure HIP_PREFER_PASSIVE_* flags produces a single sockaddr_hip structure
containing a wildcard address that the application can use either for containing a wildcard address that the application can use either for
incoming (node argument is NULL in getaddrinfo) or outgoing incoming (node argument is NULL in getaddrinfo) or outgoing
communications (node argument is non-NULL). For example, communications (node argument is non-NULL). For example,
skipping to change at page 10, line 5 skipping to change at page 10, line 13
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 res argument with the free_addrinfo function. The application frees res argument with the free_addrinfo function.
The res argument contains a linked list of the resolved endpoints. The res argument contains a linked list of the resolved endpoints.
The linked list contains sockaddr_hip structures only when the input The linked list contains sockaddr_hip structures only when the input
argument has the HIP_PREFER_ORCHID flag set in ai_eflags. The argument has the HIP_PREFER_ORCHID flag set in ai_eflags. The
resolver inserts HITs before any locators. When the resolver inserts HITs before any locators. When the
HIP_PREFER_ORCHID flag is set, the resolver does not return LSIs or HIP_PREFER_ORCHID flag is set, the resolver does not return LSIs or
HITs encapsulated into sockaddr_in or sockaddr_in6 data structures as HITs encapsulated into sockaddr_in or sockaddr_in6 data structures as
described in [I-D.ietf-hip-applications]. described in [RFC5338].
Resolver can return a HIT which maps to multiple locators. The Resolver can return a HIT which maps to multiple locators. The
resolver may cache the locator mappings to the HIP module. The HIP resolver may cache the locator mappings to 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.
It should be noticed that the application can configure the HIT It should be noticed that the application can configure the HIT
explicitly without setting the locator or the resolver can fail to explicitly without setting the locator or the resolver can fail to
skipping to change at page 16, line 13 skipping to change at page 16, line 13
Jaervinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari Keraenen, Jaervinen, Anthony Joseph, Teemu Koponen, Jari Arkko, Ari Keraenen,
Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews, Jan Melen and Juha-Matti Tapio, Shinta Sugimoto, Philip Matthews, Jan Melen and
Gonzalo Camarillo have also provided valuable ideas or feedback. Gonzalo Camarillo have also provided valuable ideas or feedback.
Thanks also for the APPS area folks, including Stephane Bortzmeyer, Thanks also for the APPS area folks, including Stephane Bortzmeyer,
Chris Newman, Tony Finch, "der Mouse" and Keith Moore. Chris Newman, Tony Finch, "der 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,
"IPsec Application Programming Interfaces", "C-Bindings for IPsec Application Programming Interfaces",
draft-ietf-btns-c-api-03 (work in progress), draft-ietf-btns-c-api-04 (work in progress), March 2009.
February 2008.
[I-D.ietf-hip-applications]
Henderson, T., Nikander, P., and M. Komu, "Using the Host
Identity Protocol with Legacy Applications",
draft-ietf-hip-applications-04 (work in progress),
July 2008.
[I-D.ietf-shim6-multihome-shim-api] [I-D.ietf-shim6-multihome-shim-api]
Komu, M., Bagnulo, M., Slavov, K., and S. Sugimoto, Komu, M., Bagnulo, M., Slavov, K., and S. Sugimoto,
"Socket Application Program Interface (API) for "Socket Application Program Interface (API) for
Multihoming Shim", draft-ietf-shim6-multihome-shim-api-05 Multihoming Shim", draft-ietf-shim6-multihome-shim-api-08
(work in progress), February 2008. (work in progress), May 2009.
[I-D.ietf-shim6-proto] [I-D.ietf-shim6-proto]
Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming
Shim Protocol for IPv6", draft-ietf-shim6-proto-10 (work Shim Protocol for IPv6", draft-ietf-shim6-proto-12 (work
in progress), February 2008. in progress), February 2009.
[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.
[RFC3484] Draves, R., "Default Address Selection for Internet [RFC3484] Draves, R., "Default Address Selection for Internet
Protocol version 6 (IPv6)", RFC 3484, February 2003. Protocol version 6 (IPv6)", RFC 3484, February 2003.
[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",
skipping to change at page 17, line 16 skipping to change at page 17, line 9
Socket API for Source Address Selection", RFC 5014, Socket API for Source Address Selection", RFC 5014,
September 2007. September 2007.
[RFC5201] Moskowitz, R., Nikander, P., Jokela, P., and T. Henderson, [RFC5201] Moskowitz, R., Nikander, P., Jokela, P., and T. Henderson,
"Host Identity Protocol", RFC 5201, April 2008. "Host Identity Protocol", RFC 5201, April 2008.
[RFC5205] Nikander, P. and J. Laganier, "Host Identity Protocol [RFC5205] Nikander, P. and J. Laganier, "Host Identity Protocol
(HIP) Domain Name System (DNS) Extensions", RFC 5205, (HIP) Domain Name System (DNS) Extensions", RFC 5205,
April 2008. April 2008.
[RFC5338] Henderson, T., Nikander, P., and M. Komu, "Using the Host
Identity Protocol with Legacy Applications", RFC 5338,
September 2008.
Authors' Addresses Authors' Addresses
Miika Komu Miika Komu
Helsinki Institute for Information Technology Helsinki Institute for Information Technology
Metsaenneidonkuja 4 Metsaenneidonkuja 4
Helsinki Helsinki
Finland Finland
Phone: +358503841531 Phone: +358503841531
Fax: +35896949768 Fax: +35896949768
Email: miika@iki.fi Email: miika@iki.fi
URI: http://www.iki.fi/miika/ URI: http://www.iki.fi/miika/
Thomas Henderson Thomas Henderson
The Boeing Company The Boeing Company
P.O. Box 3707 P.O. Box 3707
Seattle, WA Seattle, WA
USA USA
Email: thomas.r.henderson@boeing.com Email: thomas.r.henderson@boeing.com
Full Copyright Statement
Copyright (C) The IETF Trust (2008).
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.
 End of changes. 15 change blocks. 
34 lines changed or deleted 47 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/