draft-ietf-hip-native-api-01.txt   draft-ietf-hip-native-api-02.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: Standards Track Technology Intended status: Informational Technology
Expires: September 8, 2007 March 7, 2007 Expires: January 8, 2008 July 7, 2007
Native Application Programming Interfaces for SHIM Layer Prococols Native Application Programming Interfaces for SHIM APIs
draft-ietf-hip-native-api-01 draft-ietf-hip-native-api-02
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 37
and may be updated, replaced, or obsoleted by other documents at any and may be updated, replaced, or obsoleted by other documents at any
time. It is inappropriate to use Internet-Drafts as reference time. It is inappropriate to use Internet-Drafts as reference
material or to cite them other than as "work in progress." material or to cite them other than as "work in progress."
The list of current Internet-Drafts can be accessed at The list of current Internet-Drafts can be accessed at
http://www.ietf.org/ietf/1id-abstracts.txt. http://www.ietf.org/ietf/1id-abstracts.txt.
The list of Internet-Draft Shadow Directories can be accessed at The list of Internet-Draft Shadow Directories can be accessed at
http://www.ietf.org/shadow.html. http://www.ietf.org/shadow.html.
This Internet-Draft will expire on September 8, 2007. This Internet-Draft will expire on January 8, 2008.
Copyright Notice Copyright Notice
Copyright (C) The IETF Trust (2007). Copyright (C) The IETF Trust (2007).
Abstract Abstract
This document proposes extensions to the current networking APIs for This document defines extensions to the current networking APIs for
protocols based on identifier/locator split. Currently, the document protocols based on identifier/locator split. Currently, the document
focuses on HIP, but the extensions can be used also by other focuses on HIP, but the extensions can be used also by other
protocols implementing identifier locator split. Using the API protocols implementing identifier locator split. Using the API
extensions, new SHIM aware applications can gain a better control of extensions, new SHIM aware applications can configure manually
the SHIM layer and endpoint identifiers. For example, the mappings between upper layer identifiers and the corresponding
applications can query and set SHIM related attributes, or specify locators. Also, the API describes how to handle outbound connection
their own endpoint identifiers for a host. In addition, a new establishment where an application is unaware of the peer identifier
indirection element called endpoint descriptor is defined for SHIM but knows the peer locator.
aware applications that can be used for implementing opportunistic
mode in a clean way.
Table of Contents Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3 1. Terminology . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Design Architecture . . . . . . . . . . . . . . . . . . . . . 4 2. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2.1. Endpoint Descriptor . . . . . . . . . . . . . . . . . . . 4
2.2. Layering Model . . . . . . . . . . . . . . . . . . . . . . 4
2.3. Namespace Model . . . . . . . . . . . . . . . . . . . . . 5
2.4. Socket Bindings . . . . . . . . . . . . . . . . . . . . . 6
3. Interface Syntax and Description . . . . . . . . . . . . . . . 7 3. Design Model . . . . . . . . . . . . . . . . . . . . . . . . . 4
3.1. Data Structures . . . . . . . . . . . . . . . . . . . . . 8 3.1. Layering Model . . . . . . . . . . . . . . . . . . . . . . 4
3.2. Functions . . . . . . . . . . . . . . . . . . . . . . . . 10 3.2. Namespace Model . . . . . . . . . . . . . . . . . . . . . 4
3.2.1. Resolver Interface . . . . . . . . . . . . . . . . . . 11 3.3. Interaction with the Resolver . . . . . . . . . . . . . . 5
3.2.2. Application Specified Identities . . . . . . . . . . . 11
3.2.3. Querying Endpoint Related Information . . . . . . . . 13
3.2.4. HIP Related Policy Attributes . . . . . . . . . . . . 14
4. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 15 4. API Syntax and Semantics . . . . . . . . . . . . . . . . . . . 6
4.1. Socket Family and Address Structure . . . . . . . . . . . 6
4.2. Resolver . . . . . . . . . . . . . . . . . . . . . . . . . 8
5. Security Considerations . . . . . . . . . . . . . . . . . . . 15 5. IANA Considerations . . . . . . . . . . . . . . . . . . . . . 10
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 6. Security Considerations . . . . . . . . . . . . . . . . . . . 10
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15 7. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10
7.1. Normative References . . . . . . . . . . . . . . . . . . . 15
7.2. Informative References . . . . . . . . . . . . . . . . . . 16
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16 8. Normative References . . . . . . . . . . . . . . . . . . . . . 10
Intellectual Property and Copyright Statements . . . . . . . . . . 18
1. Introduction Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11
Intellectual Property and Copyright Statements . . . . . . . . . . 12
The extensions defined in this draft can be used also by other 1. Terminology
protocols based on the identifier/locator split. However, this
documented focuses mainly to HIP. +---------+---------------------------------------------------------+
| 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 Host Identity Protocol proposes a new cryptographic namespace and a
new layer to the TCP/IP architecture. Applications can see these new new layer to the TCP/IP architecture. Applications can see these new
changes in the networking stacks with varying degrees of visibility. changes 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 completely or partially visibility in which applications are either unaware of HIP. The HIP-
unaware of HIP. In this document, we discuss about the highest level unaware applications use LSIs or HITs instead of IPv4 or IPv6
of visibility. The applications are completely HIP aware and can addresses. Such applications may be unaware of the locator bindings.
control the HIP layer and Host Identifiers. The applications aquery
and set security related attributes and even create their own Host
Identifiers.
Existing applications can be used with HIP as described in
[I-D.henderson-hip-applications]. The reason why HIP can be used in
a backwards compatible way lies in the identifiers. A HIP enabled
system can support the use of LSIs, HITs and even IP addresses as
upper layer identifiers to accomodate varying application
requirements. However, these types of identifiers are not forwards
compatible. The length of HIT may turn out insecure in the future.
There may be a need to change the HITs on the fly to an already
connected socket for dynamic session mobility. Or, the socket is
going to be associated to multiple HITs for HIP based multicast.
To support forwards compatibility, we introduce a new, generalized
identifier called the endpoint descriptor (ED). The ED acts as a
handle to the actual identifier that separates application layer
indentifiers from the lower layer identifiers.
The ED can already now be used for implementing HIP opportunistic This document discusses about visibility of HIP to HIP-aware
mode in a clean way. The problem with implementing HIP opportunistic applications. The applications are completely HIP aware and can
mode is that e.g. sockets API connect() call should be bound to a HIT control the HIP layer and Host Identifiers. This document defines
in order to use HIP, but the HIT is unknown until the reception the C-based sockets API extensions for handling the bindings explicitly.
R1 packet. At this point it is too late to change the binding e.g. The extensions expose the identity-locator split to SHIM-aware
from a IP to HIT. However, the ED has to property of late binding applications and it is up to the application, or a higher level
and therefore provides a cleaner way to implement the opportunistic programming language, to manage the identities and locators.
mode.
The ED socket address structure does not reveal the transport The API extensions introduce a new socket address structure. The
layerport number to the application even though it is possible to structure requires a new address family, PF_SHIM, for sockets that
request it explicitly. This makes it possible to change the port use HITs and locators explicitly. An application can also use the
number dynamically without affecting the application. Also, it seems family to detect SHIM support in the local host.
that the port number is irrelevant, or even misleading, in todays
NATted networks to the application.
The document also introduces a new address family, PF_SHIM, for Hosts may accept incoming or initiate outgoing communications without
sockets that use EDs. The new family is a direct consequence of the knowledge of the identity of the peer. This document describes
introducing a new address type (ED) to the sockets API. It can also also how to address this situation using late binding based on new
be used for quick detection of SHIM support in the localhost. This wildcards.
is especially useful discover when SHIM aware applications are tried
on a host that does not support SHIM.
The ED concept is similar to Local Scope Identifier There are two related IETF documents that are define other related
[I-D.henderson-hip-applications] in the sense that it is also valid API extensions. Multihoming related APIs are defined in
only within a host. However, it has some differences. A minor [I-D.ietf-shim6-multihome-shim-api]. IPsec related policy attributes
difference is that two LSIs are the same when they refer to the same and channel bindings are defined in [I-D.ietf-btns-c-api]
endpoint, but ED does not have this constraint. LSIs have a prefix
to separate them from IP addresses, but ED do not. However, the main
reason why ED is not denoted as LSI in this document is that the LSIs
are bound to AF_INET sockets whereas EDs are bound to PF_SHIM
sockets.
2. Design Architecture 3. Design Model
In this section, the native SHIM API design is described from an In this section, the native SHIM API design is described from an
architectural point of view. We introduce the ED concept, which is a design point of view. We describe the layering and namespace model.
central idea in the API. We describe the layering and namespace We conclude the discussion with a description of the resolver model.
models along with the socket bindings. We conclude the discussion
with a description of the endpoint identifier resolution mechanism.
2.1. Endpoint Descriptor
The representation of endpoints is hidden from the applications. The
ED is a ``handle'' to a HI. A given ED serves as a pointer to the
corresponding HI entry in the HI database of the host. It should be
noticed that the ED cannot be used as a referral that is passed from
one host to another because it has only local significance.
2.2. Layering Model 3.1. Layering Model
The application layer accesses the transport layer via the socket The application layer accesses the transport layer via the socket
interface. The application layer uses the traditional TCP/IP IPv4 or interface. The application layer uses the traditional TCP/IP IPv4 or
IPv6 interface, or the new native SHIM API interface provided by the IPv6 interface, or the new native SHIM API interface provided by the
socket layer. The layering model is illustrated in Figure 1. For socket layer. The layering model is illustrated in Figure 1. For
simplicity, the IPsec layer has been excluded from the figure. simplicity, the IPsec layer has been excluded from the figure.
+--------------------------------+ +--------------------------------+
Application Layer | Application | Application Layer | Application |
+----------+----------+----------+ +----------+----------+----------+
skipping to change at page 5, line 26 skipping to change at page 4, line 45
Link Layer | Ethernet | Etc | Link Layer | Ethernet | Etc |
+---------------+----------------+ +---------------+----------------+
Figure 1 Figure 1
The SHIM layer is as a shim/wedge layer between the transport and The SHIM layer is as a shim/wedge layer between the transport and
network layers. The datagrams delivered 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 network layers are intercepted in the SHIM layer to see if the
datagrams are SHIM related and require SHIM intervention. datagrams are SHIM related and require SHIM intervention.
2.3. Namespace Model 3.2. Namespace Model
The namespace model is shown in from HIP view point. The namespace The namespace model is shown in Table 2 from SHIM point of view. The
identifiers are described in this section. namespace identifiers are described in this section.
+-------------------+-----------------------+ +-------------------+-------------------------+
| Layer | Identifier | | Layer | Identifier |
+-------------------+-----------------------+ +-------------------+-------------------------+
| User Interface | FQDN | | User Interface | FQDN |
| Application Layer | ED, port and protocol | | Application Layer | ULID, port and protocol |
| Transport Layer | HI, port | | Transport Layer | ULID, port |
| SHIM Layer | HI | | SHIM Layer | ULID |
| Network Layer | IP address | | Network Layer | Locator |
+-------------------+-----------------------+ +-------------------+-------------------------+
Table 1
People prefer human-readable names when referring to network
entities. The most commonly used identifier in the User Interface is
the FQDN, but there are also other ways to name network entities.
The FQDN format is still the preferred UI level identifier in the
context of the native SHIM API.
In the current API, connection associations in the application layer
are uniquely distinguished by the source IP address, destination IP
address, source port, destination port, and protocol. HIP changes
this model by using HIT in the place of IP addresses. The HIP model
is further expanded in the native HIP API model by using ED instead
of HITs. Now, the application layer uses source ED, destination ED,
source port, destination port, and transport protocol type, to
distinguish between the different connection associations.
Basically, the difference between the application and transport layer
identifiers is that the transport layer uses HIs instead of EDs. The
TLI is named with source HI, destination HI, source port, and
destination port at the transport layer.
Correspondingly, the HIP layer uses HIs as identifiers. The HIP
security associations are based on source HI and destination HI
pairs.
The network layer uses IP addresses, i.e., locators, for routing
purposes. The network layer interacts with the HIP layer to exchange
information about changes in the local interfaces addresses and peer
addresses.
2.4. Socket Bindings
A HIP based SHIM socket is associated with one source and one
destination ED, along with their port numbers and protocol type. The
relationship between a socket and ED is a many-to-one one. Multiple
EDs can be associated with a single HI. Further, the source HI is
associated with a set of network interfaces at the local host. The
destination HI, in turn, is associated with a set of destination
addresses of the peer. The socket bindings are visualized in
Figure 2.
1 +---------+ * * +--------+ * * +-----------+ Table 2
+---+ Src EID +------+ Src HI +------+ Src Iface |
+--------+ * | +---------+ +--------+ +-----------+
| HIP +------+
| |
| Socket +------+
+--------+ * | +---------+ +--------+ +-----------+
+---+ Dst EID +------+ Dst HI +------+ Dst IP |
1 +---------+ * * +--------+ * * +-----------+
Figure 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.
The relationship between a source ED and a source HI is usually many- 3.3. Interaction with the Resolver
to-one one, but it can be also many-to-many on certain cases. There
are two refinements to the relationship. First, a listening socket
is allowed to accept connections from all local HIs of the host.
Second, the opportunistic mode allows the base exchange to be
initiated to an unknown destination HI. In a way, the relationship
between the local ED and local HI is a many-to-undefined relationship
momentarily in both of the cases, but once the connection is
established, the ED will be permanently associated with a certain HI.
The DNS based endpoint discovery mechanism is illustrated in Before an application can establish network communications, it must
Figure 3. The application calls the resolver (step a.) to resolve an translate a hostname to the corresponding identifier(s). DNS based
FQDN (step b.). The DNS server responds with a ED and a set of hostname-to-identifier translation is illustrated in Figure 2. The
locators (step c.). The resolver does not directly pass the ED and application calls the resolver (step a.) to resolve an FQDN (step
the locators to the application, but sends them to the SHIM module b.). The DNS server responds with ULIDs and a set of locators (step
(step d.). Finally, the resolver receives an ED from the SHIM module c.). The resolver may not directly pass the ULIDs and the locators
(step e.) and passes the ED to the application (step f.). 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.).
+----------+ +----------+
| | | |
| DNS | | DNS |
| | | |
+----------+ +----------+
^ | ^ |
b. <FQDN> | | c. <EID, locator> b. <FQDN> | | c. <ULIDs + locators = U+L>
| v | v
+-------------+ a. <FQDN> +----------+ +-------------+ a. <FQDN> +----------+
| |----------->| | | |----------->| |
| Application | | Resolver | | Application | | Resolver |
| |<-----------| | | |<-----------| |
+-------------+ f. <ED> +----------+ +-------------+ f. <U+L> +----------+
^ | ^ |
e. <ED> | | d. <EID, locator> | |
e. <U+L> | | d. <U+L>
| v | v
+----------+ +----------+
| | | |
| SHIM | | SHIM |
| | | |
+----------+ +----------+
Figure 3 Figure 2
The application can also receive multiple EDs from the resolver when In practise, the resolver functionality can implemented in different
the FQDN is associated with multiple EIDs. The endpoint discovery ways. It may be implemented in existing resolver libraries or as an
mechanism is still almost the same. The difference is that the DNS DNS proxy.
returns a set of EIDs (along with the associated locators) to the
resolver. The resolver sends all of them to the SHIM module and
receives a set of EDs in return, each ED corresponding to a single
HI. Finally, the EDs are sent to the application.
3. Interface Syntax and Description 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 SHIM API using the syntax of
the C programming language and present only the ``external'' the C programming language and present only the ``external''
interfaces and data structures that are visible to the applications. interfaces and data structures that are visible to the applications.
We limit the description to those interfaces and data structures that We limit the description to those interfaces and data structures that
are either modified or completely new, because the native SHIM API is are either modified or completely new, because the SHIM API is
otherwise identical to the sockets API [POSIX]. otherwise identical to the sockets API [POSIX].
3.1. Data Structures 4.1. Socket Family and Address Structure
We introduce a new protocol family, PF_SHIM, for the sockets API. 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 The AF_SHIM constant is an alias for it. The use of the PF_SHIM
constant is mandatory with the socket function if the native SHIM API constant is mandatory with the socket() function if the SHIM API is
is to be used in the application. The PF_SHIM constant is given as to be used in the application. The PF_SHIM constant is given as the
the first argument (domain) to the socket function. first argument (domain) to the socket() function.
The ED abstraction is realized in the sockaddr_ed structure, which is The ULIDs and locators are contained in the sockaddr_shim structure,
shown in Figure 4. The family of the socket, ed_family, is set to which is shown in Figure 3. The family of the socket, shim_family,
PF_SHIM. The port number ed_port is two octets and the ED value is set to PF_SHIM. The port number sins_port is two octets and the
ed_val is four octets. The ED value is just an opaque number to the sins_ulid is four octets. The ULID value is an IPv6 address. The
application. The application should not try to associate it directly locator is an IPv6 address or IPv6-mapped address IPv4 address as
to a EID or even compare it to other ED values, because there are defined in - [RFC3493]. The family is stored in host byte order and
separate functions for those purposes. The ED family is stored in the ULID and locator are stored in network byte order.
host byte order. The ED value is stored in network byte order. It
should be noticed that the port number is not present in the socket
address structure, but it can be queried with the functions in
section Section 3.2.2.
struct sockaddr_ed { typedef struct in6_addr shim_ulid_t;
unsigned short int ed_family; typedef struct in6_addr shim_locator_t;
sa_ed_t ed_val;
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 4 Figure 3
The ed_val field is usually set by special native SHIM API functions, The application usually sets the sins_ulid field using the resolver.
which are described in the following section. However, three special However, three special macros can be used to directly set a value
macros can be used to directly set a value into the ed_val field. into the sins_ulid field. The macros are SHIM_ANY, SHIM_ANY_PUB and
The macros are SHIM_ED_ANY, SHIM_ED_ANY_PUB and SHIM_ED_ANY_ANON. SHIM_ANY_ANON. They denote an ULID value associated with a wildcard
They denote an ED value associated with a wildcard HI of any, public, ULID of any, public, or anonymous type.
or anonymous type. They are useful to a ``server'' application that
is willing to accept connections to all of the HIs of the host. The
macros correspond to the sockets API macros INADDR_ANY and
IN6ADDR_ANY_INIT, but they are applicable on the SHIM layer. It
should be noted that only one process at a time can bind with the
SHIM_ED_*ANY macro on a certain port to avoid ambiguous bindings.
The native SHIM API has a new resolver function which is used for In server applications, the SHIM_* macros accept incoming connections
querying both endpoint identifiers and locators. The resolver 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.
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 introduces a new data structure, which is used both as the input and
output argument for the resolver. We reuse the existing resolver output argument for the resolver. The data structure is illustrated
datastructure shown in Figure 5. in Figure 4.
struct addrinfo { struct addrinfo {
int ai_flags; /* e.g. AI_ED */ int ai_flags; /* e.g. AI_SHIM */
int ai_family; /* e.g. PF_SHIM */ int ai_family; /* e.g. PF_SHIM */
int ai_socktype; /* e.g. SOCK_STREAM */ int ai_socktype; /* e.g. SOCK_STREAM */
int ai_protocol; /* usually just zero */ int ai_protocol; /* 0 or IPPROTO_HIP */
size_t ai_addrlen; /* length of the endpoint */ size_t ai_addrlen; /* length of the endpoint */
struct sockaddr *ai_addr; /* endpoint socket address */ struct sockaddr *ai_addr; /* socket address */
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 5 Figure 4
In addrinfo structures, the family field is set to PF_SHIM when the In addrinfo structures, the family field is set to PF_SHIM when the
socket address structure contains an ED that refers to a SHIM socket address structure contains an ULID that refers to ULID, such
identifier, such as HI. as HIT.
The flags in the addrinfo structure control the behavior of the The flag AI_SHIM must be set, or otherwise the resolver does not
resolver and describe the attributes of the endpoints and locators: 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.
o The flag AI_ED must be set, or otherwise the resolver does not The ai_family field is PF_SHIM with SHIM-specific addrinfo data
return EDs to guarantee that legacy applications won't break.
When AI_ED is set, the resolver returns a linked list which
contains first the sockaddr_ed structures for SHIM identifiers if
any was found. After that, any other type of socket addresses are
returned except that HITs in sockaddr_in6 format are excluded
because they were already included in the returned sockaddr_ed
structures. structures.
o When querying local identifiers, the AI_ED_ANON flag forces the The protocol field is 0 when the getaddrinfo caller does not care
resolver to query only local anonymous identifiers. The default about the specific SHIM protocol to be used. The caller (or the
action is first to resolve the public endpoints and then the resolver) can set this field also to IPPROTO_HIP.
anonymous endpoints.
o Some applications may prefer configuring the locators manually and
can set the AI_ED_NOLOCATORS flag to prohibit the resolver from
resolving any locators.
o The AI_ED_ANY, AI_ED_ANY_PUB and AI_ED_ANY_ANON flags cause the
resolver to output only a single socket address containing an ED
that would be received using the corresponding SHIM_ED_*ANY macro.
When these flags are used for resolving local addresses, they
allow wildcard late binding to certain types of local idenfiers.
When the flags are used for peer resolving, they allow to contact
the peer using opportunistic mode.
o The getaddrinfo resolver does not return IP addresses belonging to
a SHIM rendezvous server unless AI_ED is defined. AI_ED_RVS, can
appear both in the input and output arguments of the resolver. In
the input, it can be used for resolving only rendezvous server
addresses. On the output, it denotes that the address is a
rendezvous rather than end-point address.
Application specified endpoint identifiers are essentially private
keys. To support application specified identifiers in the API, we
introduce new data structures for storing the private keys. The
private keys need an uniform format so that they can be easily used
in the API calls. The keys are stored in the endpoint structures as
shown in Figure 6.
struct endpoint {
se_length_t length;
se_family_t family;
};
struct endpoint_hip {
se_length_t length;
se_family_t family; /* EF_HI in the case of HIP */
se_hip_flags_t flags;
union {
struct hip_host_id host_id;
hit_t hit;
} id;
};
Figure 6
The endpoint structure represents a generic endpoint and the
endpoint_hip structure represents a HIP specific endpoint. The
family field distinguishes whether the identifier is HIP or other
protocol related. The HIP endpoint is public by default unless
SHIM_ENDPOINT_FLAG_ANON flag is set in the structure to anonymize the
endpoint. The id union contains the HI in the host_id member in the
format specified in [I-D.ietf-hip-base]. If the key is private, the
material is appended to the host_id with the length adjusted
accordingly. The flag SHIM_ENDPOINT_FLAG_PRIVATE is also set. The
hit member of the union is used only when the SHIM_ENDPOINT_FLAG_HIT
flag is set.
3.2. Functions
In this section, some existing sockets API functions are reintroduced ai_addrlen is the size of the structure pointed by ai_addr.
along with their additions. Also, some new auxiliary functions are
defined.
3.2.1. Resolver Interface 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].
The native SHIM API does not introduce changes to the interface The SHIM API does not introduce changes to the interface syntax of
syntax of the primitive sockets API functions bind, connect, send, the existing sockets API functions, such as bind(), connect(),
sendto, sendmsg, recv, recvfrom, and recvmsg. However, the send(), sendto(), sendmsg(), recv(), recvfrom(), and recvmsg().
application usually calls the functions with sockaddr_ed structures However, the SHIM-aware application usually passes the functions a
instead of sockaddr_in or sockaddr_in6 structures. The source of the sockaddr_shim structure instead of a sockaddr_in or sockaddr_in6
sockaddr_ed structures in the native SHIM API is the resolver structure. A SHIM-aware application either creates the sockaddr_shim
function getaddrinfo [RFC3493] which is shown in Figure 7. 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 7 Figure 5
The getaddrinfo function takes the nodename, servname, and hints as As described in [RFC3493], the getaddrinfo function takes the
its input arguments. It places the result of the query into the res nodename, servname, and hints as its input arguments. It places the
argument. The return value is zero on success, or a non-zero error result of the query into the res argument. The return value is zero
value on error. The nodename argument specifies the host name to be on success, or a non-zero error value on error. The nodename
resolved; a NULL argument denotes the local host. The servname argument specifies the host name to be resolved; a NULL argument
parameter sets the port number to be set in the socket addresses in denotes the local host. The servname parameter declares the port
the res output argument. Both the nodename and servname cannot be number to be set in the socket addresses in the res output argument.
NULL. 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 output argument res is dynamically allocated by the resolver.
The application must free res argument with the free_addrinfo The application must free res argument with the free_addrinfo
function. The res argument contains a linked list of the resolved function. The res argument contains a linked list of the resolved
endpoints. The input argument hints acts like a filter that defines endpoints. The linked list contains sockaddr_shim structures only
the attributes required from the resolved endpoints. For example, when the input argument has the AI_SHIM flag set. When the resolver
setting the flag SHIM_ENDPOINT_FLAG_ANON in the hints forces the finds SHIM identifiers, it inserts them to the front of the list.
resolver to return only anonymous endpoints in the output argument
res. A NULL hints argument indicates that any kind of endpoints are
acceptable.
3.2.2. Application Specified Identities
Application specified local and peer endpoints can be retrieved from
files using the function shown in Figure 8. The function
shim_endpoint_load_pem is used for retrieving a private or public key
from a given file filename. The file must be in PEM encoded format.
The result is allocated dynamically and stored into the endpoint
argument. The return value of the function is zero on success, or a
non-zero error value on failure. The result is deallocated with the
free system call.
int shim_endpoint_pem_load(const char *filename,
struct endpoint **endpoint)
Figure 8
Alternatively, the application can load the image directly from
memory as shown in Figure 9
int shim_endpoint_pem_load_str(const char *pem_str,
struct endpoint **endpoint);
Figure 9
The endpoint structure cannot be used directly in the sockets API
function calls. The application must convert the endpoint into an ED
first. Local endpoints are converted with the getlocaled function
and peer endpoints with getpeered function. The functions are
illustrated in Figure 10.
struct sockaddr_ed *getlocaled(const struct endpoint *endpoint,
const char *servname,
const struct addrinfo *addrs,
const struct if_nameindex *ifaces,
int flags)
struct sockaddr_ed *getpeered(const struct endpoint *endpoint,
const char *servname,
const struct addrinfo *addrs,
int flags)
Figure 10
The result of the conversion, an ED socket address, is returned by
both of the functions. A failure in the conversion causes a NULL
return value to be returned and the errno to be set accordingly. The
caller of the functions is responsible of freeing the returned socket
address structure.
The application can retrieve the endpoint argument e.g. with the
shim_endpoint_load_pem function. If the endpoint is NULL, the system
selects an arbitrary EID and associates it with the ED value of the
return value.
The servname argument is the service string. The function converts
it to a numeric port number and fills the port number into the
returned ED socket structure for the convenience of the application.
The addrs argument defines the initial IP addresses of the local host
or peer host. The argument is a pointer to a linked list of addrinfo
structures containing the initial addresses of the peer. The list
pointer can be obtained with a getaddrinfo [RFC3493] function call.
A NULL pointer indicates that the application trusts the host to
already know the locators of the peer. We recommend that a NULL
pointer is not given to the getpeered function to ensure reachability
with the peer.
The getlocaled function accepts also a list of network interface
indexes in the ifaces argument. The list can be obtained with the
if_nameindex [RFC3493] function call. A NULL list pointer indicates
all the interfaces of the local host. Both the IP addresses and
interfaces can be combined to select a specific address from a
specific interface.
The last argument is the flags. The following flags are valid only
for the getlocaled function:
o Flags SHIM_ED_REUSE_UID, SHIM_ED_REUSE_GID and SHIM_ED_REUSE_ANY
allow the EID (e.g. a large private key) to be reused for
processes with the same UID, GID or any UID as the calling
process.
o Flags SHIM_ED_IPV4 and SHIM_ED_IPV6 can be used for limiting the
address family scope of the local interface.
It should noticed that the SHIM_ED_ANY, SHIM_ED_ANY_PUB and
SHIM_ED_ANY_ANON macros can be implemented as calls to the getlocaled
call with a NULL endpoint, NULL interface, NULL address argument and
the flag corresponding to the macro name set.
3.2.3. Querying Endpoint Related Information
The getlocaled and getpeered functions have also their reverse
counterparts. Given an ED, the getlocaledinfo and getpeeredinfo
functions search for the EID (e.g. a HI) and the current set of
locators associated with the ED. The first argument is the ED to be
searched for. The functions write the results of the search, the
transport layer port number of the occupied by the correponding HIT,
the HIs and locators, to the rest of the function arguments. The
function interfaces are depicted in Figure 11. The caller of the
functions is responsible for freeing the memory reserved for the
search results.
int getlocaledinfo(const struct sockaddr_ed *my_ed,
struct in_port_t **port
struct endpoint **endpoint,
struct addrinfo **addrs,
struct if_nameindex **ifaces)
int getpeeredinfo(const struct sockaddr_ed *peer_ed,
struct in_port_t **port
struct endpoint **endpoint,
struct addrinfo **addrs)
Figure 11
The getlocaledinfo and getpeeredinfo functions are especially useful
for an advanced application that receives multiple EDs from the
resolver. The advanced application can query the properties of the
EDs using getlocaledinfo and getpeeredinfo functions and select the
ED that matches the desired properties.
3.2.4. HIP Related Policy Attributes
Multihoming related attributes are defined in
[I-D.ietf-shim6-multihome-shim-api]. It also specifies an event
driven API for application, which can be used for listening for
changes in locators.
HIP related policy attributes are accessed using the definitions in
[I-D.komu-btns-api]
Some of the policy attributes must be set before the hosts have
established connection. The implementation may refuse to accept the
option when there is already an existing connection and dynamic
renegotiation of the option is not possible. In addition, the SHIM
may return an error value if the corresponding SHIM protocol does not
support the given option.
Table 2shows HIP related policy attributes that are accessed with the
APIs defined in [I-D.komu-btns-api].
+---------------------+---------------------------------------------+
| Attribute | Purpose |
+---------------------+---------------------------------------------+
| IPSEC_ESP_TRANSFORM | Preferred ESP transform |
| IPSEC_SA_LIFETIME | Preferred IPsec SA lifetime in seconds |
| SHIM_PROTOCOL | Get or set current SHIM protocol. Currently |
| | only PF_HIP is defined. |
| SHIM_CHALLENGE_SIZE | Puzzle challenge size |
| SHIM_SHIM_TRANSFORM | Preferred SHIM transform |
| SHIM_DH_GROUP_IDS | The preferred Diffie-Hellman Group |
| SHIM_AF_FAMILY | The preferred locator family. The default |
| | family is AF_ANY. |
| SHIM_FAST_FALLBACK | If set to one, use the extensions in |
| | [I-D.lindqvist-hip-opportunistic] |
| SHIM_FAST_HANDSHAKE | If set to one, use the extensions in |
| | [I-D.lindqvist-hip-tcp-piggybacking] |
+---------------------+---------------------------------------------+
Table 2 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.
4. IANA Considerations 5. IANA Considerations
No IANA considerations. No IANA considerations.
5. Security Considerations 6. Security Considerations
To be done. To be done.
6. Acknowledgements 7. 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 native HIP API. Thomas Henderson, Kristian Slavov, and effort to the HIP API. Thomas Henderson, Kristian Slavov, Julien
Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan Melen, Andrew Laganier, Jaakko Kangasharju, Mika Kousa, Jan Melen, Andrew McGregor,
McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti Jaervinen, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti Jaervinen, Anthony
Anthony Joseph, Teemu Koponen and Juha-Matti Tapio have also provided Joseph, Teemu Koponen and Juha-Matti Tapio have also provided
valuable ideas and feedback. valuable ideas and feedback. Thanks for the APPS area folks,
Stephane Bortzmeyer, Chris Newman, Tony Finch, "der Mouse" and
7. References especially Keith Moore for comments.
7.1. Normative References 8. 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-hip-base] [I-D.ietf-btns-c-api]
Moskowitz, R., "Host Identity Protocol", Komu, M., "IPsec Application Programming Interfaces",
draft-ietf-hip-base-07 (work in progress), February 2007. 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] [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-01 Multihoming Shim", draft-ietf-shim6-multihome-shim-api-02
(work in progress), October 2006. (work in progress), March 2007.
[I-D.komu-btns-api]
Komu, M., "IPsec Application Programming Interfaces",
draft-komu-btns-api-00 (work in progress), October 2006.
[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.
7.2. Informative References [RFC4843] Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix
for Overlay Routable Cryptographic Hash Identifiers
[I-D.lindqvist-hip-opportunistic] (ORCHID)", RFC 4843, April 2007.
Lindqvist, J., "Establishing Host Identity Protocol
Opportunistic Mode with TCP Option",
draft-lindqvist-hip-opportunistic-01 (work in progress),
March 2006.
[I-D.lindqvist-hip-tcp-piggybacking]
Lindqvist, J., "Piggybacking TCP to Host Identity
Protocol", draft-lindqvist-hip-tcp-piggybacking-00 (work
in progress), July 2006.
Author's Address Author's Address
Miika Komu Miika Komu
Helsinki Institute for Information Technology Helsinki Institute for Information Technology
Tammasaarenkatu 3 Tammasaarenkatu 3
Helsinki Helsinki
Finland Finland
Phone: +358503841531 Phone: +358503841531
 End of changes. 71 change blocks. 
520 lines changed or deleted 249 lines changed or added

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