Host Identity Protocol M. Komu
Internet-Draft Helsinki Institute for Information
Intended status: Informational Technology
Expires: January 8, 2008 July 7, 2007
Native Application Programming Interfaces for SHIM APIs
draft-ietf-hip-native-api-02
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 January 8, 2008.
Copyright Notice
Copyright (C) The IETF Trust (2007).
Abstract
This document defines extensions to the current networking APIs for
protocols based on identifier/locator split. Currently, the document
focuses on HIP, but the extensions can be used also by other
protocols implementing identifier locator split. Using the API
extensions, new SHIM aware applications can configure manually
Komu Expires January 8, 2008 [Page 1]
Internet-Draft Native SHIM APIs July 2007 mappings between upper layer identifiers and the corresponding locators. Also, the API describes how to handle outbound connection establishment where an application is unaware of the peer identifier but knows the peer locator. Table of Contents 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 3. Design Model . . . . . . . . . . . . . . . . . . . . . . . . . 4 3.1. Layering Model . . . . . . . . . . . . . . . . . . . . . . 4 3.2. Namespace Model . . . . . . . . . . . . . . . . . . . . . 4 3.3. Interaction with the Resolver . . . . . . . . . . . . . . 5 4. API Syntax and Semantics . . . . . . . . . . . . . . . . . . . 6 4.1. Socket Family and Address Structure . . . . . . . . . . . 6 4.2. Resolver . . . . . . . . . . . . . . . . . . . . . . . . . 8 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10 8. Normative References . . . . . . . . . . . . . . . . . . . . . 10 Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 Intellectual Property and Copyright Statements . . . . . . . . . . 12 Komu Expires January 8, 2008 [Page 2]
Internet-Draft Native SHIM APIs July 2007 1. Terminology +---------+---------------------------------------------------------+ | Term | Explanation | +---------+---------------------------------------------------------+ | ULID | Upper Layer IDentifier equals to the identity part of | | | 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 | | | a 28 bit prefix | | LSI | Locally Scope Identifier, a 32-bit local presentation | | | of a public key | +---------+---------------------------------------------------------+ Table 1 2. Introduction Host Identity Protocol proposes a new cryptographic namespace and a new layer to the TCP/IP architecture. Applications can see these new changes in the networking stacks with varying degrees of visibility. [I-D.henderson-hip-applications] discusses the lowest levels of visibility in which applications are either unaware of HIP. The HIP- unaware applications use LSIs or HITs instead of IPv4 or IPv6 addresses. Such applications may be unaware of the locator bindings. This document discusses about visibility of HIP to HIP-aware applications. The applications are completely HIP aware and can control the HIP layer and Host Identifiers. This document defines C-based sockets API extensions for handling the bindings explicitly. The extensions expose the identity-locator split to SHIM-aware applications and it is up to the application, or a higher level programming language, to manage the identities and locators. The API extensions introduce a new socket address structure. The structure requires a new address family, PF_SHIM, for sockets that use HITs and locators explicitly. An application can also use the family to detect SHIM support in the local host. Hosts may accept incoming or initiate outgoing communications without the knowledge of the identity of the peer. This document describes also how to address this situation using late binding based on new wildcards. Komu Expires January 8, 2008 [Page 3]
Internet-Draft Native SHIM APIs July 2007 There are two related IETF documents that are define other related API extensions. Multihoming related APIs are defined in [I-D.ietf-shim6-multihome-shim-api]. IPsec related policy attributes and channel bindings are defined in [I-D.ietf-btns-c-api] 3. Design Model 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. +--------------------------------+ Application Layer | Application | +----------+----------+----------+ Socket Layer | IPv4 API | IPv6 API | SHIM API | +----------+----+-----+----------+ Transport Layer | TCP | UDP | +---------------+----------------+ SHIM Layer | HIP and other SHIMs | +---------------+----------------+ Network Layer | IPv4 | IPv6 | +---------------+----------------+ Link Layer | Ethernet | Etc | +---------------+----------------+ Figure 1 The SHIM layer is as a shim/wedge layer between the transport and network layers. The datagrams delivered between the transport and network layers are intercepted in the SHIM layer to see if the datagrams are SHIM related and require SHIM intervention. 3.2. Namespace Model The namespace model is shown in Table 2 from SHIM point of view. The namespace identifiers are described in this section. Komu Expires January 8, 2008 [Page 4]
Internet-Draft Native SHIM APIs July 2007 +-------------------+-------------------------+ | Layer | Identifier | +-------------------+-------------------------+ | User Interface | FQDN | | Application Layer | ULID, port and protocol | | Transport Layer | ULID, port | | SHIM Layer | ULID | | Network Layer | Locator | +-------------------+-------------------------+ Table 2 User interfaces input human-readable names and translate them to machine-readable names. In SHIM API, the ULID is a HIT when the underlying protocol is HIP. The ULID is present at the application layer and also transport layer checksum is calculated based on it. The SHIM layer handles also ULIDs and translates them locators for the network layer. 3.3. Interaction with the Resolver Before an application can establish network communications, it must translate a hostname to the corresponding identifier(s). DNS based hostname-to-identifier translation is illustrated in Figure 2. The application calls the resolver (step a.) to resolve an FQDN (step b.). The DNS server responds with ULIDs and a set of locators (step c.). The resolver may not directly pass the ULIDs and the locators to the application, but may first inform to the SHIM module (steps d. and e.). Finally, the resolver passes the ULIDs and locators to the application (step f.). Komu Expires January 8, 2008 [Page 5]
Internet-Draft Native SHIM APIs July 2007 +----------+ | | | DNS | | | +----------+ ^ | b. <FQDN> | | c. <ULIDs + locators = U+L> | v +-------------+ a. <FQDN> +----------+ | |----------->| | | Application | | Resolver | | |<-----------| | +-------------+ f. <U+L> +----------+ ^ | | | e. <U+L> | | d. <U+L> | v +----------+ | | | SHIM | | | +----------+ Figure 2 In practise, the resolver functionality can implemented in different ways. It may be implemented in existing resolver libraries or as an DNS proxy. 4. API Syntax and Semantics In this section, we describe the native SHIM API using the syntax of the C programming language and present only the ``external'' interfaces and data structures that are visible to the applications. We limit the description to those interfaces and data structures that are either modified or completely new, because the SHIM API is otherwise identical to the sockets API [POSIX]. 4.1. Socket Family and Address Structure We introduce a new protocol family, PF_SHIM, for the sockets API. The AF_SHIM constant is an alias for it. The use of the PF_SHIM constant is mandatory with the socket() function if the SHIM API is to be used in the application. The PF_SHIM constant is given as the first argument (domain) to the socket() function. The ULIDs and locators are contained in the sockaddr_shim structure, Komu Expires January 8, 2008 [Page 6]
Internet-Draft Native SHIM APIs July 2007 which is shown in Figure 3. The family of the socket, shim_family, is set to PF_SHIM. The port number sins_port is two octets and the sins_ulid is four octets. The ULID value is an IPv6 address. The locator is an IPv6 address or IPv6-mapped address IPv4 address as defined in - [RFC3493]. The family is stored in host byte order and the ULID and locator are stored in network byte order. typedef struct in6_addr shim_ulid_t; typedef struct in6_addr shim_locator_t; struct sockaddr_shim { uint8_t sins_len; uint8_t sins_family; uint16_t sins_port; shim_ulid_t sins_ulid; shim_locator_t sins_locator; uint64_t sins_flags; } Figure 3 The application usually sets the sins_ulid field using the resolver. However, three special macros can be used to directly set a value into the sins_ulid field. The macros are SHIM_ANY, SHIM_ANY_PUB and SHIM_ANY_ANON. They denote an ULID value associated with a wildcard ULID of any, public, or anonymous type. In server applications, the SHIM_* macros accept incoming connections to all of the ULID of the local host. The macros correspond to the sockets API macros INADDR_ANY and IN6ADDR_ANY_INIT, but they are applicable at the SHIM layer. It should be noticed that only one process at a time in a host can bind with the SHIM_*ANY macro to the same port to avoid ambiguous bindings. A client application can use the SHIM_ANY macro to establish a connection when only the server locator (and not the ULID) is known beforehand. In both client and server based applications, the use of the SHIM_ANY* macro accepts also non-SHIM based communications to maximize backwards compatibility. When the application wants enforces the use of SHIM-based communications with ORCHID prefix [RFC4843], it sets the flag SHIM_FLAG_ONLY_ORCHID in sins_flags. Alternatively, the application accepts both ORCHID and non-ORCHID- based communications, but informs the difference e.g. to the user. In this case, the application calls SHIM_IPV6_ADDR_IS_ORCHID macro which inputs a pointer to a in6_addr and returns 1 when the address has orchid prefix and 0 otherwise. Komu Expires January 8, 2008 [Page 7]
Internet-Draft Native SHIM APIs July 2007 Applications can also implement access control using the ULIDs. In such a case, the application can compare two ULIDs using memcmp() or similar function. 4.2. Resolver The SHIM API uses the getaddrinfo resolver function which the application uses to query both ULIDs and locators. The resolver introduces a new data structure, which is used both as the input and output argument for the resolver. The data structure is illustrated in Figure 4. struct addrinfo { int ai_flags; /* e.g. AI_SHIM */ int ai_family; /* e.g. PF_SHIM */ int ai_socktype; /* e.g. SOCK_STREAM */ int ai_protocol; /* 0 or IPPROTO_HIP */ size_t ai_addrlen; /* length of the endpoint */ struct sockaddr *ai_addr; /* socket address */ char *ai_canonname; /* canon. name of the host */ struct addrinfo *ai_next; /* next endpoint */ }; Figure 4 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 structures. The protocol field is 0 when the getaddrinfo caller does not care about the specific SHIM protocol to be used. The caller (or the resolver) can set this field also to IPPROTO_HIP. ai_addrlen is the size of the structure pointed by ai_addr. The ai_addr points to a sockaddr_shim structure when the value of ai_family is PF_SHIM. The resolver sets SHIM_RVS in sins_flags of the when the locator belongs to a rendezvous server [I-D.ietf-hip-dns]. Komu Expires January 8, 2008 [Page 8]
Internet-Draft Native SHIM APIs July 2007 The SHIM API does not introduce changes to the interface syntax of 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, const char *servname, const struct addrinfo *hints, struct addrinfo **res) void free_addrinfo(struct addrinfo *res) Figure 5 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. For example, the resolver returns only anonymous endpoints in the output argument res 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 application must free res argument with the free_addrinfo function. The res argument contains a linked list of the resolved endpoints. The linked list contains sockaddr_shim structures only when the input argument has the AI_SHIM flag set. When the resolver finds SHIM identifiers, it inserts them to the front of the list. Resolving of a hostname may result in multiple locators associated to a single ULID, but the sockaddr_shim structure contains only a single ULID-locator pair. The resolver handles this by repeating the ULD as many time as needed. For example, let us consider a case where the 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. Komu Expires January 8, 2008 [Page 9]
Internet-Draft Native SHIM APIs July 2007 5. IANA Considerations No IANA considerations. 6. Security Considerations To be done. 7. Acknowledgements Jukka Ylitalo and Pekka Nikander have contributed many ideas, time and effort to the HIP API. 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 and Juha-Matti Tapio have also provided valuable ideas and feedback. Thanks for the APPS area folks, Stephane Bortzmeyer, Chris Newman, Tony Finch, "der Mouse" and especially Keith Moore for comments. 8. 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-00 (work in progress), June 2007. [I-D.ietf-hip-dns] Nikander, P. and J. Laganier, "Host Identity Protocol (HIP) Domain Name System (DNS) Extensions", draft-ietf-hip-dns-09 (work in progress), April 2007. [I-D.ietf-shim6-multihome-shim-api] Komu, M., "Socket Application Program Interface (API) for Multihoming Shim", draft-ietf-shim6-multihome-shim-api-02 (work in progress), March 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. Komu Expires January 8, 2008 [Page 10]
Internet-Draft Native SHIM APIs July 2007 Stevens, "Basic Socket Interface Extensions for IPv6", RFC 3493, February 2003. [RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix for Overlay Routable Cryptographic Hash Identifiers (ORCHID)", RFC 4843, April 2007. Author's Address Miika Komu Helsinki Institute for Information Technology Tammasaarenkatu 3 Helsinki Finland Phone: +358503841531 Fax: +35896949768 Email: miika@iki.fi URI: http://www.iki.fi/miika/ Komu Expires January 8, 2008 [Page 11]
Internet-Draft Native SHIM APIs July 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 January 8, 2008 [Page 12]
Datatracker
draft-ietf-hip-native-api-02
This is an older version of an Internet-Draft that was ultimately published as RFC 6317.
| Document | Document type |
This is an older version of an Internet-Draft that was ultimately published as RFC 6317.
Expired & archived
|
|
|---|---|---|---|
| Select version | |||
| Compare versions | |||
| Author | |||
| RFC stream |
|
||
| Other formats | |||
| Additional resources | Mailing list discussion |