draft-ietf-hip-native-api-00.txt   draft-ietf-hip-native-api-01.txt 
Host Identity Protocol M. Komu Host Identity Protocol M. Komu
Internet-Draft Helsinki Institute for Information Internet-Draft Helsinki Institute for Information
Expires: May 25, 2007 Technology Intended status: Standards Track Technology
November 21, 2006 Expires: September 8, 2007 March 7, 2007
Native Application Programming Interfaces for SHIM Layer Prococols Native Application Programming Interfaces for SHIM Layer Prococols
draft-ietf-hip-native-api-00.txt draft-ietf-hip-native-api-01
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 May 25, 2007. This Internet-Draft will expire on September 8, 2007.
Copyright Notice Copyright Notice
Copyright (C) The Internet Society (2006). Copyright (C) The IETF Trust (2007).
Abstract Abstract
This document proposes extensions to the current networking APIs for This document proposes 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 similar "shim" layer protocols. Using the API extensions, protocols implementing identifier locator split. Using the API
new SHIM aware applications can gain a better control of the SHIM extensions, new SHIM aware applications can gain a better control of
layer and endpoint identifiers. For example, the applications can the SHIM layer and endpoint identifiers. For example, the
query and set SHIM related attributes, or specify their own endpoint applications can query and set SHIM related attributes, or specify
identifiers for a host. In addition, a new indirection element their own endpoint identifiers for a host. In addition, a new
called endpoint descriptor is defined for SHIM aware applications. indirection element called endpoint descriptor is defined for SHIM
aware applications that can be used for implementing opportunistic
mode in a clean way.
Table of Contents
1. Introduction . . . . . . . . . . . . . . . . . . . . . . . . . 3
2. Design Architecture . . . . . . . . . . . . . . . . . . . . . 4
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.1. Data Structures . . . . . . . . . . . . . . . . . . . . . 8
3.2. Functions . . . . . . . . . . . . . . . . . . . . . . . . 10
3.2.1. Resolver Interface . . . . . . . . . . . . . . . . . . 11
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
5. Security Considerations . . . . . . . . . . . . . . . . . . . 15
6. Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15
7. References . . . . . . . . . . . . . . . . . . . . . . . . . . 15
7.1. Normative References . . . . . . . . . . . . . . . . . . . 15
7.2. Informative References . . . . . . . . . . . . . . . . . . 16
Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 16
Intellectual Property and Copyright Statements . . . . . . . . . . 18
1. Introduction 1. Introduction
The extensions defined in this draft can be used also by other The extensions defined in this draft can be used also by other
protocols based on the identifier/locator split. For example, SHIM6 protocols based on the identifier/locator split. However, this
and BTNS are possible such candidates. Related WG API drafts are documented focuses mainly to HIP.
draft-sugimoto-multihome-shim-api and [6]. However, this draft
currently focuses on HIP.
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.
[5] discusses the lowest levels of visibility in which applications [I-D.henderson-hip-applications] discusses the lowest levels of
are either completely or partially unaware of HIP. In this document, visibility in which applications are either completely or partially
we discuss about the highest level of visibility. The applications unaware of HIP. In this document, we discuss about the highest level
are completely HIP aware and are given more control over the HIP of visibility. The applications are completely HIP aware and can
layer and identifiers. The applications are allowed to query and control the HIP layer and Host Identifiers. The applications aquery
configure security related attributes and even specify their own Host and set security related attributes and even create their own Host
Identifiers. Identifiers.
Legacy HIP applications can already use a variety of identifiers, Existing applications can be used with HIP as described in
like LSIs, HITs and IP addresses as described in [5]. The varying [I-D.henderson-hip-applications]. The reason why HIP can be used in
number of identifiers can be all be used for HIP based networking in a backwards compatible way lies in the identifiers. A HIP enabled
a easily deployable way. The proposed extensions could be as well system can support the use of LSIs, HITs and even IP addresses as
based on one of the existing formats, like HITs or public keys, but upper layer identifiers to accomodate varying application
they have their own problems. For example, the HIT format may change requirements. However, these types of identifiers are not forwards
in the future, and long, variable length public keys are not directly compatible. The length of HIT may turn out insecure in the future.
applicable the current sockets API. In addition, there may be a need There may be a need to change the HITs on the fly to an already
for another new layer in the future, such as session layer, and connected socket for dynamic session mobility. Or, the socket is
choosing any of the existing identifier formats may introduce going to be associated to multiple HITs for HIP based multicast.
additional deployment problems for a new layer. We therefore propose
a new, generalized identifier called the endpoint descriptor (ED). To support forwards compatibility, we introduce a new, generalized
The ED acts as a handle to the actual identifier that separates identifier called the endpoint descriptor (ED). The ED acts as a
application layer indentifiers from the lower layer identifiers. 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
mode in a clean way. The problem with implementing HIP opportunistic
mode is that e.g. sockets API connect() call should be bound to a HIT
in order to use HIP, but the HIT is unknown until the reception the
R1 packet. At this point it is too late to change the binding e.g.
from a IP to HIT. However, the ED has to property of late binding
and therefore provides a cleaner way to implement the opportunistic
mode.
The ED socket address structure does not reveal the transport
layerport number to the application even though it is possible to
request it explicitly. This makes it possible to change the port
number dynamically without affecting the application. Also, it seems
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
sockets that use EDs. The new family is a direct consequence of
introducing a new address type (ED) to the sockets API. It can also
be used for quick detection of SHIM support in the localhost. This
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
[I-D.henderson-hip-applications] in the sense that it is also valid
only within a host. However, it has some differences. A minor
difference is that two LSIs are the same when they refer to the same
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 2. Design Architecture
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 architectural point of view. We introduce the ED concept, which is a
central idea in the API. We describe the layering and namespace central idea in the API. We describe the layering and namespace
models along with the socket bindings. We conclude the discussion models along with the socket bindings. We conclude the discussion
with a description of the endpoint identifier resolution mechanism. with a description of the endpoint identifier resolution mechanism.
2.1. Endpoint Descriptor 2.1. Endpoint Descriptor
skipping to change at page 5, line 14 skipping to change at page 5, line 35
2.3. Namespace Model 2.3. Namespace Model
The namespace model is shown in from HIP view point. The namespace The namespace model is shown in from HIP view point. The namespace
identifiers are described in this section. identifiers are described in this section.
+-------------------+-----------------------+ +-------------------+-----------------------+
| Layer | Identifier | | Layer | Identifier |
+-------------------+-----------------------+ +-------------------+-----------------------+
| User Interface | FQDN | | User Interface | FQDN |
| | |
| Application Layer | ED, port and protocol | | Application Layer | ED, port and protocol |
| | |
| Transport Layer | HI, port | | Transport Layer | HI, port |
| | |
| SHIM Layer | HI | | SHIM Layer | HI |
| | |
| Network Layer | IP address | | Network Layer | IP address |
+-------------------+-----------------------+ +-------------------+-----------------------+
Table 1 Table 1
People prefer human-readable names when referring to network People prefer human-readable names when referring to network
entities. The most commonly used identifier in the User Interface is 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, but there are also other ways to name network entities.
The FQDN format is still the preferred UI level identifier in the The FQDN format is still the preferred UI level identifier in the
context of the native SHIM API. context of the native SHIM API.
skipping to change at page 6, line 17 skipping to change at page 6, line 34
A HIP based SHIM socket is associated with one source and one A HIP based SHIM socket is associated with one source and one
destination ED, along with their port numbers and protocol type. The destination ED, along with their port numbers and protocol type. The
relationship between a socket and ED is a many-to-one one. Multiple 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 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 associated with a set of network interfaces at the local host. The
destination HI, in turn, is associated with a set of destination destination HI, in turn, is associated with a set of destination
addresses of the peer. The socket bindings are visualized in addresses of the peer. The socket bindings are visualized in
Figure 2. Figure 2.
1 +---------+ * 1 +--------+ * * +-----------+ 1 +---------+ * * +--------+ * * +-----------+
+---+ Src EID +------+ Src HI +------+ Src Iface | +---+ Src EID +------+ Src HI +------+ Src Iface |
+--------+ * | +---------+ * 1 +--------+ +-----------+ +--------+ * | +---------+ +--------+ +-----------+
| HIP +------+ | HIP +------+
| | | |
| Socket +------+ | Socket +------+
+--------+ * | +---------+ * 1 +--------+ * * +-----------+ +--------+ * | +---------+ +--------+ +-----------+
+---+ Dst EID +------+ Dst HI +------+ Dst IP | +---+ Dst EID +------+ Dst HI +------+ Dst IP |
1 +---------+ * 1 +--------+ +-----------+ 1 +---------+ * * +--------+ * * +-----------+
Figure 2 Figure 2
The relationship between a source ED and a source HI is always a The relationship between a source ED and a source HI is usually many-
many-to-one one. However, there are two refinements to the to-one one, but it can be also many-to-many on certain cases. There
relationship. First, a listening socket is allowed to accept are two refinements to the relationship. First, a listening socket
connections from all local HIs of the host. Second, the is allowed to accept connections from all local HIs of the host.
opportunistic mode allows the base exchange to be initiated to an Second, the opportunistic mode allows the base exchange to be
unknown destination HI. In a way, the relationship between the local initiated to an unknown destination HI. In a way, the relationship
ED and local HI is a many-to-undefined relationship momentarily in between the local ED and local HI is a many-to-undefined relationship
both of the cases, but once the connection is established, the ED momentarily in both of the cases, but once the connection is
will be permanently associated with a certain HI. established, the ED will be permanently associated with a certain HI.
The DNS based endpoint discovery mechanism is illustrated in The DNS based endpoint discovery mechanism is illustrated in
Figure 3. The application calls the resolver (step a.) to resolve an Figure 3. The application calls the resolver (step a.) to resolve an
FQDN (step b.). The DNS server responds with a EID and a set of FQDN (step b.). The DNS server responds with a ED and a set of
locators (step c.). The resolver does not directly pass the EID and locators (step c.). The resolver does not directly pass the ED and
the locators to the application, but sends them to the SHIM module the locators to the application, but sends them to the SHIM module
(step d.). Finally, the resolver receives an ED from the SHIM module (step d.). Finally, the resolver receives an ED from the SHIM module
(step e.) and passes the ED to the application (step f.). (step e.) and passes the ED to the application (step f.).
+----------+ +----------+
| | | |
| DNS | | DNS |
| | | |
+----------+ +----------+
^ | ^ |
skipping to change at page 8, line 12 skipping to change at page 8, line 8
receives a set of EDs in return, each ED corresponding to a single receives a set of EDs in return, each ED corresponding to a single
HI. Finally, the EDs are sent to the application. HI. Finally, the EDs are sent to the application.
3. Interface Syntax and Description 3. Interface Syntax and Description
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 native SHIM API is
otherwise identical to the sockets API [1]. otherwise identical to the sockets API [POSIX].
3.1. Data Structures 3.1. Data Structures
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 native SHIM API
is to be used in the application. The PF_SHIM constant is given as is to be used in the application. The PF_SHIM constant is given as
the first argument (domain) to the socket function. the first argument (domain) to the socket function.
The ED abstraction is realized in the sockaddr_ed structure, which is The ED abstraction is realized in the sockaddr_ed structure, which is
shown in figure Figure 4. The family of the socket, ed_family, is shown in Figure 4. The family of the socket, ed_family, is set to
set to PF_SHIM. The port number ed_port is two octets and the ED PF_SHIM. The port number ed_port is two octets and the ED value
value ed_val is four octets. The ED value is just an opaque number ed_val is four octets. The ED value is just an opaque number to the
to the application. The application should not try to associate it application. The application should not try to associate it directly
directly to a EID or even compare it to other ED values, because to a EID or even compare it to other ED values, because there are
there are separate functions for those purposes. The ED family is separate functions for those purposes. The ED family is stored in
stored in host byte order. The port and the ED value are stored in host byte order. The ED value is stored in network byte order. It
network byte order. 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 { struct sockaddr_ed {
unsigned short int ed_family; unsigned short int ed_family;
in_port_t ed_port;
sa_ed_t ed_val; sa_ed_t ed_val;
} }
Figure 4 Figure 4
The ed_val field is usually set by special native SHIM API functions, The ed_val field is usually set by special native SHIM API functions,
which are described in the following section. However, three special which are described in the following section. However, three special
macros can be used to directly set a value into the ed_val field. macros can be used to directly set a value into the ed_val field.
The macros are SHIM_ED_ANY, SHIM_ED_ANY_PUB and SHIM_ED_ANY_ANON. The macros are SHIM_ED_ANY, SHIM_ED_ANY_PUB and SHIM_ED_ANY_ANON.
They denote an ED value associated with a wildcard HI of any, public, They denote an ED value associated with a wildcard HI of any, public,
skipping to change at page 9, line 34 skipping to change at page 9, line 32
identifier, such as HI. identifier, such as HI.
The flags in the addrinfo structure control the behavior of the The flags in the addrinfo structure control the behavior of the
resolver and describe the attributes of the endpoints and locators: resolver and describe the attributes of the endpoints and locators:
o The flag AI_ED must be set, or otherwise the resolver does not o The flag AI_ED must be set, or otherwise the resolver does not
return EDs to guarantee that legacy applications won't break. return EDs to guarantee that legacy applications won't break.
When AI_ED is set, the resolver returns a linked list which When AI_ED is set, the resolver returns a linked list which
contains first the sockaddr_ed structures for SHIM identifiers if contains first the sockaddr_ed structures for SHIM identifiers if
any was found. After that, any other type of socket addresses are any was found. After that, any other type of socket addresses are
returned. returned except that HITs in sockaddr_in6 format are excluded
because they were already included in the returned sockaddr_ed
structures.
o When querying local identifiers, the AI_ED_ANON flag forces the o When querying local identifiers, the AI_ED_ANON flag forces the
resolver to query only local anonymous identifiers. The default resolver to query only local anonymous identifiers. The default
action is first to resolve the public endpoints and then the action is first to resolve the public endpoints and then the
anonymous endpoints. anonymous endpoints.
o Some applications may prefer configuring the locators manually and o Some applications may prefer configuring the locators manually and
can set the AI_ED_NOLOCATORS flag to prohibit the resolver from can set the AI_ED_NOLOCATORS flag to prohibit the resolver from
resolving any locators. resolving any locators.
o The AI_ED_ANY, AI_ED_ANY_PUB and AI_ED_ANY_ANON flags cause the 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 resolver to output only a single socket address containing an ED
that would be received using the corresponding SHIM_ED_*ANY macro. 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 o The getaddrinfo resolver does not return IP addresses belonging to
a SHIM rendezvous server unless AI_ED is defined. AI_ED_RVS, can 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 appear both in the input and output arguments of the resolver. In
the input, it can be used for resolving only rendezvous server the input, it can be used for resolving only rendezvous server
addresses. On the output, it denotes that the address is a addresses. On the output, it denotes that the address is a
rendezvous rather than end-point address. rendezvous rather than end-point address.
Application specified endpoint identifiers are essentially private Application specified endpoint identifiers are essentially private
keys. To support application specified identifiers in the API, we keys. To support application specified identifiers in the API, we
introduce new data structures for storing the private keys. The introduce new data structures for storing the private keys. The
private keys need an uniform format so that they can be easily used 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 in the API calls. The keys are stored in the endpoint structures as
shown in figure Figure 6. shown in Figure 6.
struct endpoint { struct endpoint {
se_length_t length; se_length_t length;
se_family_t family; se_family_t family;
}; };
struct endpoint_hip { struct endpoint_hip {
se_length_t length; se_length_t length;
se_family_t family; /* EF_HI in the case of HIP */ se_family_t family; /* EF_HI in the case of HIP */
se_hip_flags_t flags; se_hip_flags_t flags;
union { union {
skipping to change at page 10, line 37 skipping to change at page 10, line 41
}; };
Figure 6 Figure 6
The endpoint structure represents a generic endpoint and the The endpoint structure represents a generic endpoint and the
endpoint_hip structure represents a HIP specific endpoint. The endpoint_hip structure represents a HIP specific endpoint. The
family field distinguishes whether the identifier is HIP or other family field distinguishes whether the identifier is HIP or other
protocol related. The HIP endpoint is public by default unless protocol related. The HIP endpoint is public by default unless
SHIM_ENDPOINT_FLAG_ANON flag is set in the structure to anonymize the 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 endpoint. The id union contains the HI in the host_id member in the
format specified in [3]. If the key is private, the material is format specified in [I-D.ietf-hip-base]. If the key is private, the
appended to the host_id with the length adjusted accordingly. The material is appended to the host_id with the length adjusted
flag SHIM_ENDPOINT_FLAG_PRIVATE is also set. The hit member of the accordingly. The flag SHIM_ENDPOINT_FLAG_PRIVATE is also set. The
union is used only when the SHIM_ENDPOINT_FLAG_HIT flag is set. hit member of the union is used only when the SHIM_ENDPOINT_FLAG_HIT
flag is set.
3.2. Functions 3.2. Functions
In this section, some existing sockets API functions are reintroduced In this section, some existing sockets API functions are reintroduced
along with their additions. Also, some new auxiliary functions are along with their additions. Also, some new auxiliary functions are
defined. defined.
3.2.1. Resolver Interface 3.2.1. Resolver Interface
The native SHIM API does not introduce changes to the interface The native SHIM API does not introduce changes to the interface
syntax of the primitive sockets API functions bind, connect, send, syntax of the primitive sockets API functions bind, connect, send,
sendto, sendmsg, recv, recvfrom, and recvmsg. However, the sendto, sendmsg, recv, recvfrom, and recvmsg. However, the
application usually calls the functions with sockaddr_ed structures application usually calls the functions with sockaddr_ed structures
instead of sockaddr_in or sockaddr_in6 structures. The source of the instead of sockaddr_in or sockaddr_in6 structures. The source of the
sockaddr_ed structures in the native SHIM API is the resolver sockaddr_ed structures in the native SHIM API is the resolver
function getaddrinfo [2] which is shown in Figure 7. function getaddrinfo [RFC3493] which is shown in Figure 7.
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 7
The getaddrinfo function takes the nodename, servname, and hints as The getaddrinfo function takes the nodename, servname, and hints as
skipping to change at page 12, line 4 skipping to change at page 12, line 7
files using the function shown in Figure 8. The function files using the function shown in Figure 8. The function
shim_endpoint_load_pem is used for retrieving a private or public key 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. from a given file filename. The file must be in PEM encoded format.
The result is allocated dynamically and stored into the endpoint The result is allocated dynamically and stored into the endpoint
argument. The return value of the function is zero on success, or a 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 non-zero error value on failure. The result is deallocated with the
free system call. free system call.
int shim_endpoint_pem_load(const char *filename, int shim_endpoint_pem_load(const char *filename,
struct endpoint **endpoint) struct endpoint **endpoint)
Figure 8 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 The endpoint structure cannot be used directly in the sockets API
function calls. The application must convert the endpoint into an ED function calls. The application must convert the endpoint into an ED
first. Local endpoints are converted with the getlocaled function first. Local endpoints are converted with the getlocaled function
and peer endpoints with getpeered function. The functions are and peer endpoints with getpeered function. The functions are
illustrated in Figure 9. illustrated in Figure 10.
struct sockaddr_ed *getlocaled(const struct endpoint *endpoint, struct sockaddr_ed *getlocaled(const struct endpoint *endpoint,
const char *servname, const char *servname,
const struct addrinfo *addrs, const struct addrinfo *addrs,
const struct if_nameindex *ifaces, const struct if_nameindex *ifaces,
int flags) int flags)
struct sockaddr_ed *getpeered(const struct endpoint *endpoint, struct sockaddr_ed *getpeered(const struct endpoint *endpoint,
const char *servname, const char *servname,
const struct addrinfo *addrs, const struct addrinfo *addrs,
int flags) int flags)
Figure 9 Figure 10
The result of the conversion, an ED socket address, is returned by The result of the conversion, an ED socket address, is returned by
both of the functions. A failure in the conversion causes a NULL 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 return value to be returned and the errno to be set accordingly. The
caller of the functions is responsible of freeing the returned socket caller of the functions is responsible of freeing the returned socket
address structure. address structure.
The application can retrieve the endpoint argument e.g. with the The application can retrieve the endpoint argument e.g. with the
shim_endpoint_load_pem function. If the endpoint is NULL, the system 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 selects an arbitrary EID and associates it with the ED value of the
return value. return value.
The servname argument is the service string. The function converts The servname argument is the service string. The function converts
it to a numeric port number and fills the port number into the it to a numeric port number and fills the port number into the
returned ED socket structure for the convenience of the application. returned ED socket structure for the convenience of the application.
The addrs argument defines the initial IP addresses of the local host 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 or peer host. The argument is a pointer to a linked list of addrinfo
structures containing the initial addresses of the peer. The list structures containing the initial addresses of the peer. The list
pointer can be obtained with a getaddrinfo [2] function call. A NULL pointer can be obtained with a getaddrinfo [RFC3493] function call.
pointer indicates that the application trusts the host to already A NULL pointer indicates that the application trusts the host to
know the locators of the peer. We recommend that a NULL pointer is already know the locators of the peer. We recommend that a NULL
not given to the getpeered function to ensure reachability with the pointer is not given to the getpeered function to ensure reachability
peer. with the peer.
The getlocaled function accepts also a list of network interface The getlocaled function accepts also a list of network interface
indexes in the ifaces argument. The list can be obtained with the indexes in the ifaces argument. The list can be obtained with the
if_nameindex [2] function call. A NULL list pointer indicates all if_nameindex [RFC3493] function call. A NULL list pointer indicates
the interfaces of the local host. Both the IP addresses and all the interfaces of the local host. Both the IP addresses and
interfaces can be combined to select a specific address from a interfaces can be combined to select a specific address from a
specific interface. specific interface.
The last argument is the flags. The following flags are valid only The last argument is the flags. The following flags are valid only
for the getlocaled function: for the getlocaled function:
o Flags SHIM_ED_REUSE_UID, SHIM_ED_REUSE_GID and SHIM_ED_REUSE_ANY 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 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 processes with the same UID, GID or any UID as the calling
process. process.
skipping to change at page 13, line 29 skipping to change at page 13, line 43
SHIM_ED_ANY_ANON macros can be implemented as calls to the getlocaled SHIM_ED_ANY_ANON macros can be implemented as calls to the getlocaled
call with a NULL endpoint, NULL interface, NULL address argument and call with a NULL endpoint, NULL interface, NULL address argument and
the flag corresponding to the macro name set. the flag corresponding to the macro name set.
3.2.3. Querying Endpoint Related Information 3.2.3. Querying Endpoint Related Information
The getlocaled and getpeered functions have also their reverse The getlocaled and getpeered functions have also their reverse
counterparts. Given an ED, the getlocaledinfo and getpeeredinfo counterparts. Given an ED, the getlocaledinfo and getpeeredinfo
functions search for the EID (e.g. a HI) and the current set of 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 locators associated with the ED. The first argument is the ED to be
searched for. The functions write the results of the search, the HIs searched for. The functions write the results of the search, the
and locators, to the rest of the function arguments. The function transport layer port number of the occupied by the correponding HIT,
interfaces are depicted in Figure 10. The caller of the functions is the HIs and locators, to the rest of the function arguments. The
responsible for freeing the memory reserved for the search results. 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, int getlocaledinfo(const struct sockaddr_ed *my_ed,
struct in_port_t **port
struct endpoint **endpoint, struct endpoint **endpoint,
struct addrinfo **addrs, struct addrinfo **addrs,
struct if_nameindex **ifaces) struct if_nameindex **ifaces)
int getpeeredinfo(const struct sockaddr_ed *peer_ed, int getpeeredinfo(const struct sockaddr_ed *peer_ed,
struct in_port_t **port
struct endpoint **endpoint, struct endpoint **endpoint,
struct addrinfo **addrs) struct addrinfo **addrs)
Figure 10 Figure 11
The getlocaledinfo and getpeeredinfo functions are especially useful The getlocaledinfo and getpeeredinfo functions are especially useful
for an advanced application that receives multiple EDs from the for an advanced application that receives multiple EDs from the
resolver. The advanced application can query the properties of the resolver. The advanced application can query the properties of the
EDs using getlocaledinfo and getpeeredinfo functions and select the EDs using getlocaledinfo and getpeeredinfo functions and select the
ED that matches the desired properties. ED that matches the desired properties.
3.2.4. Socket Options 3.2.4. HIP Related Policy Attributes
Reading and writing of SHIM socket options is done using getsockopt Multihoming related attributes are defined in
and setsockopt functions. The first argument, the level, must be [I-D.ietf-shim6-multihome-shim-api]. It also specifies an event
specified as SOL_SHIM. driven API for application, which can be used for listening for
changes in locators.
A number of SHIM socket option names are listed in Table 2. The HIP related policy attributes are accessed using the definitions in
length of the option must be natural word size of the underlying [I-D.komu-btns-api]
processor, typically 32 or 64 bits. The purpose of the option value
must be interpreted in context of the protocol specifications [3]
[4].
Some of the socket options must be set before the hosts have Some of the policy attributes must be set before the hosts have
established connection. The implementation may refuse to accept the established connection. The implementation may refuse to accept the
option when there is already an existing connection and dynamic option when there is already an existing connection and dynamic
renegotiation of the option is not possible. In addition, the SHIM renegotiation of the option is not possible. In addition, the SHIM
may return an error value if the corresponding SHIM protocol does not may return an error value if the corresponding SHIM protocol does not
support the given option. support the given option.
Multihoming related socket options are defined in Table 2shows HIP related policy attributes that are accessed with the
draft-sugimoto-multihome-shim-api. It also specifies an event driven APIs defined in [I-D.komu-btns-api].
API for application, which can be used for listening for changes in
locators.
+-----------------------------------+-------------------------------+ +---------------------+---------------------------------------------+
| Socket Options | Purpose | | Attribute | Purpose |
+-----------------------------------+-------------------------------+ +---------------------+---------------------------------------------+
| SO_SHIM_CHALLENGE_SIZE | Puzzle challenge size | | IPSEC_ESP_TRANSFORM | Preferred ESP transform |
| | | | IPSEC_SA_LIFETIME | Preferred IPsec SA lifetime in seconds |
| SO_SHIM_SHIM_TRANSFORMS | Integer array of the | | SHIM_PROTOCOL | Get or set current SHIM protocol. Currently |
| | preferred SHIM transforms | | | only PF_HIP is defined. |
| | | | SHIM_CHALLENGE_SIZE | Puzzle challenge size |
| SO_SHIM_ESP_TRANSFORMS | Integer array of the | | SHIM_SHIM_TRANSFORM | Preferred SHIM transform |
| | preferred ESP transforms | | SHIM_DH_GROUP_IDS | The preferred Diffie-Hellman Group |
| | | | SHIM_AF_FAMILY | The preferred locator family. The default |
| SO_SHIM_DH_GROUP_IDS | Integer array of the | | | family is AF_ANY. |
| | preferred Diffie-Hellman | | SHIM_FAST_FALLBACK | If set to one, use the extensions in |
| | group IDs | | | [I-D.lindqvist-hip-opportunistic] |
| | | | SHIM_FAST_HANDSHAKE | If set to one, use the extensions in |
| SO_SHIM_SA_LIFETIME | Preferred IPsec SA lifetime | | | [I-D.lindqvist-hip-tcp-piggybacking] |
| | in seconds | +---------------------+---------------------------------------------+
| | |
| SO_SHIM_CTRL_RETRANS_INIT_TIMEOUT | SHIM initial retransmission |
| | timeout for SHIM control |
| | packets |
| | |
| SO_SHIM_CTRL_RETRANS_INTERVAL | SHIM retransmission interval |
| | in seconds |
| | |
| SO_SHIM_CTRL_RETRANS_ATTEMPTS | Number of retransmission |
| | attempts |
| | |
| SO_SHIM_AF_FAMILY | The preferred IP address |
| | family. The default family is |
| | AF_ANY. |
| | |
| SO_SHIM_PIGGYPACK | If set to one, HIP |
| | piggy-packing to TCP packets |
| | is used. Zero if |
| | piggy-packing must not be |
| | used. |
| | |
| SO_SHIM_OPPORTUNISTIC | Try SHIM in opportunistic |
| | mode when only the locators |
| | of the peer are known. |
| | |
| SO_SHIM_NAT_TRAVERSAL | Enable NAT traversal mode for |
| | SHIM. |
+-----------------------------------+-------------------------------+
Table 2 Table 2
4. IANA Considerations 4. IANA Considerations
No IANA considerations. No IANA considerations.
5. Security Considerations 5. Security Considerations
To be done. To be done.
6. Acknowledgements 6. 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 native HIP API. Thomas Henderson, Kristian Slavov,
Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan Melen, Andrew Julien Laganier, Jaakko Kangasharju, Mika Kousa, Jan Melen, Andrew
McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti Jaervinen and McGregor, Sasu Tarkoma, Lars Eggert, Joe Touch, Antti Jaervinen,
Anthony Joseph have also provided valuable ideas and feedback. Anthony Joseph, Teemu Koponen and Juha-Matti Tapio have also provided
valuable ideas and feedback.
7. References 7. References
7.1. Normative References 7.1. Normative References
[1] Institute of Electrical and Electronics Engineers, "IEEE Std. [I-D.henderson-hip-applications]
1003.1-2001 Standard for Information Technology - Portable Henderson, T. and P. Nikander, "Using HIP with Legacy
Operating System Interface (POSIX)", Dec 2001. Applications", draft-henderson-hip-applications-03 (work
in progress), May 2006.
[2] Gilligan, R., Thomson, S., Bound, J., McCann, J., and W. [I-D.ietf-hip-base]
Stevens, "Basic Socket Interface Extensions for IPv6", RFC 3493, Moskowitz, R., "Host Identity Protocol",
February 2003. draft-ietf-hip-base-07 (work in progress), February 2007.
[3] Moskowitz, R., "Host Identity Protocol", draft-ietf-hip-base-06 [I-D.ietf-shim6-multihome-shim-api]
(work in progress), June 2006. Komu, M., "Socket Application Program Interface (API) for
Multihoming Shim", draft-ietf-shim6-multihome-shim-api-01
(work in progress), October 2006.
[4] Nikander, P., "End-Host Mobility and Multihoming with the Host [I-D.komu-btns-api]
Identity Protocol", draft-ietf-hip-mm-03 (work in progress), Komu, M., "IPsec Application Programming Interfaces",
March 2006. draft-komu-btns-api-00 (work in progress), October 2006.
[5] Henderson, T. and P. Nikander, "Using HIP with Legacy [POSIX] Institute of Electrical and Electronics Engineers, "IEEE
Applications", draft-henderson-hip-applications-03 (work in Std. 1003.1-2001 Standard for Information Technology -
progress), May 2006. 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.
7.2. Informative References 7.2. Informative References
[6] Richardson, M. and B. Sommerfeld, "Requirements for an IPsec [I-D.lindqvist-hip-opportunistic]
API", draft-ietf-btns-ipsec-apireq-00 (work in progress), Lindqvist, J., "Establishing Host Identity Protocol
April 2006. 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
Fax: +35896949768 Fax: +35896949768
Email: miika@iki.fi Email: miika@iki.fi
URI: http://www.iki.fi/miika/ URI: http://www.iki.fi/miika/
Full Copyright Statement Full Copyright Statement
Copyright (C) The Internet Society (2006). Copyright (C) The IETF Trust (2007).
This document is subject to the rights, licenses and restrictions This document is subject to the rights, licenses and restrictions
contained in BCP 78, and except as set forth therein, the authors contained in BCP 78, and except as set forth therein, the authors
retain all their rights. retain all their rights.
This document and the information contained herein are provided on an This document and the information contained herein are provided on an
"AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY AND THE INTERNET OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS OR IMPLIED, THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE. WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.
Intellectual Property Intellectual Property
The IETF takes no position regarding the validity or scope of any The IETF takes no position regarding the validity or scope of any
Intellectual Property Rights or other rights that might be claimed to Intellectual Property Rights or other rights that might be claimed to
pertain to the implementation or use of the technology described in pertain to the implementation or use of the technology described in
this document or the extent to which any license under such rights 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 might or might not be available; nor does it represent that it has
made any independent effort to identify any such rights. Information made any independent effort to identify any such rights. Information
skipping to change at page 21, line 47 skipping to change at page 18, line 47
http://www.ietf.org/ipr. http://www.ietf.org/ipr.
The IETF invites any interested party to bring to its attention any The IETF invites any interested party to bring to its attention any
copyrights, patents or patent applications, or other proprietary copyrights, patents or patent applications, or other proprietary
rights that may cover technology that may be required to implement rights that may cover technology that may be required to implement
this standard. Please address the information to the IETF at this standard. Please address the information to the IETF at
ietf-ipr@ietf.org. ietf-ipr@ietf.org.
Acknowledgment Acknowledgment
Funding for the RFC Editor function is currently provided by the Funding for the RFC Editor function is provided by the IETF
Internet Society. Administrative Support Activity (IASA).
 End of changes. 52 change blocks. 
168 lines changed or deleted 233 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/