Host Identity Protocol                                           M. Komu
Internet-Draft                        Helsinki Institute for Information
Intended status: Informational Experimental                                 Technology
Expires: May 22, August 28, 2008                                  November 19, 2007

   Native Application Programming Interfaces (APIs)                                       Henderson
                                                      The Boeing Company
                                                       February 25, 2008

   Basic Socket Interface Extensions for Host Identity Protocol (HIP)
                      draft-ietf-hip-native-api-03
                      draft-ietf-hip-native-api-04

Status of this Memo

   By submitting this Internet-Draft, each author represents that any
   applicable patent or other IPR claims of which he or she is aware
   have been or will be disclosed, and any of which he or she becomes
   aware will be disclosed, in accordance with Section 6 of BCP 79.
   This document may not be modified, and derivative works of it may not
   be created, except to publish it as an RFC and to translate it into
   languages other than English.

   Internet-Drafts are working documents of the Internet Engineering
   Task Force (IETF), its areas, and its working groups.  Note that
   other groups may also distribute working documents as Internet-
   Drafts.

   Internet-Drafts are draft documents valid for a maximum of six months
   and may be updated, replaced, or obsoleted by other documents at any
   time.  It is inappropriate to use Internet-Drafts as reference
   material or to cite them other than as "work in progress."

   The list of current Internet-Drafts can be accessed at
   http://www.ietf.org/ietf/1id-abstracts.txt.

   The list of Internet-Draft Shadow Directories can be accessed at
   http://www.ietf.org/shadow.html.

   This Internet-Draft will expire on May 22, August 28, 2008.

Copyright Notice

   Copyright (C) The IETF Trust (2007). (2008).

Abstract

   This document defines extensions to the current sockets API for Host
   Identity Protocol (HIP).  The extensions focus on the initial
   discovery use of public-key public-
   key based identifiers.  Using identifiers discovered via DNS resolution, but define also
   interfaces for manual bindings between HITs and locators.  With the
   extensions, the application can verify that the identifier is a Host Identity Tag
   (HIT) and it can require the system resolver to return only HITs from
   DNS.  The application can also to explicitly allow support more relaxed security
   models where the communication can be non-HIP based in the
   absence of a peer identifiers, or that the application allows peer
   identity based, according to be discovered after initial contact directly
   local policies.  The extensions in document are experimental and
   provide basic tools for futher experimentation with the
   peer. policies.

Table of Contents

   1.  Terminology  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3

   2.  Introduction  Terminology  . . . . . . . . . . . . . . . . . . . . . . . . .  3  4

   3.  Design Model  API Overview . . . . . . . . . . . . . . . . . . . . . . . . .  4
     3.1.  Namespace Model  . . . . . . .  Interaction with the Resolver  . . . . . . . . . . . . . .  4  5
     3.2.  Interaction with the without a Resolver . . . . . . . . . . . . . .  5

   4.  API Syntax and Semantics . . . . . . . . . . . . . . . . . . .  6
     4.1.  Socket Family and Address Structure Extensions . . . . . .  6
     4.2.  Resolver  Extensions to Resolver Data Structures . . . . . . . . . .  8
       4.2.1.  Resolver Usage . . . . . . . . .  8 . . . . . . . . . . .  9
     4.3.  Manual Handling  The Use of Locators getsockname and getpeername Functions . . . . . 10
     4.4.  Validating HITs  . . . . . . . . . . . . . . . . . . . . . 10
     4.5.  Source HIT Selection by the System . . . . . . . . . . . . 11
     4.6.  Explicit Handling of Locators  . . . . . . . . . . . . . . 12

   5.  Summary of New Definitions . . . . . . . . . . . . . . . . . . 10 14

   6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 11 15

   7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 11 15

   8.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11 15

   9.  Normative References . . . . . . . . . . . . . . . . . . . . . 12

   Author's Address . 16

   Authors' Addresses . . . . . . . . . . . . . . . . . . . . . . . . 12 17
   Intellectual Property and Copyright Statements . . . . . . . . . . 14 18

1.  Terminology  Introduction

   This document defines C-based sockets Application Programming
   Interface (API) extensions for handling HIP-based identifiers
   explicitly in HIP-aware applications.  It is up to the applications,
   or high-level programming languages or libraries, to manage the
   identifiers.  The terms used extensions in this document are summarized mainly related to
   the use case in Table 1.

   +---------+---------------------------------------------------------+
   | Term    | Explanation                                             |
   +---------+---------------------------------------------------------+
   | HIP     | Host Identity Protocol                                  |
   | HIT     | Host Identity Tag, which a 100-bit hash DNS resolution step has occurred prior to the
   creation of a public key with  |
   |         | a 28 bit prefix                                         |
   | LSI     | Local Scope Identifier, a local, 32-bit descriptor for  |
   |         | a given public key.                                     |
   | Locator | Routable IPv4 new socket, and assumes that the system has cached or IPv6 address used at
   is otherwise able to resolve identifiers to locators (IP addresses).
   The DNS extensions for HIP are described in [I-D.ietf-hip-dns].  The
   extensions also cover the lower layers  |
   +---------+---------------------------------------------------------+

                                  Table 1

2.  Introduction case in which an application may want to
   explicitly provide suggested locators with the identifiers, including
   supporting the opportunistic case in which the system does not know
   the peer host identity.

   The Host Identity Protocol (HIP) [RFC4423] proposes a new
   cryptographic namespace by separating the roles of end-point
   identifiers and locators by introducing a new namespace to the TCP/IP
   stack.  SHIM6 [I-D.ietf-shim6-proto] is another protocol based on
   identity-locator split.  Note that the Application Programming
   Interfaces (APIs) APIs specified in this
   document are specific to HIP.  However, the APIs here have been
   designed keeping generality in mind as much as possible so as not to preclude its use with other
   protocols.  The use of these APIs with other protocols is,
   nevertheless, for further study.

   Applications can observe the HIP layer and its identifiers in the
   networking stacks with varying degrees of visibility.
   [I-D.henderson-hip-applications]
   [I-D.ietf-hip-applications] discusses the lowest levels of visibility
   in which applications are completely unaware of the underlying HIP
   layer.  Such HIP-unaware applications use HIP-based identifiers, such
   as LSIs or HITs, instead of IPv4 or IPv6 addresses and cannot observe
   the identifier-locator bindings.

   This document defines C-based sockets API specifies extensions for handling
   HIP-based identifiers explicitly in HIP-aware applications.  It is up
   to the applications, or a high-level programming languages or
   libraries, to manage the identifiers.  The extensions in this
   document are mainly related [RFC3493] to the initial discovery of the
   identifiers, i.e., DNS resolution step.

   The API extensions introduce a new address family, AF_HIP, and define a new
   socket address structure for sockets using Host Identity Tags (HITs)
   explicitly. family, AF_HIP.  The macro PF_HIP is used as an alias
   for AF_HIP in this document because the distinction between PF and AF
   has been lost in the practice.  The extensions also describe a new socket
   address structure for sockets using Host Identity Tags (HITs)
   explicitly and describe how the socket calls in [RFC3493] are adapted
   or extended as a result.

   Some applications may accept incoming communications from any
   identifier.  Other applications may initiate outgoing communications
   without the knowledge of the peer identifier in Opportunistic Mode
   [I-D.ietf-hip-base] by just relying on a peer locator.  This document
   describes how to address both situations using "wildcards" as
   described later in this document.

   There are two related API documents.  Multihoming and explicit
   locator-handling related APIs are defined in
   [I-D.ietf-shim6-multihome-shim-api].  IPsec related policy attributes
   and channel bindings APIs are defined in [I-D.ietf-btns-c-api].  The  Most
   of the extensions defined in this document can be used independently
   of the two mentioned related API documents.

   The identity-locator split introduced by HIP introduces some policy
   related challenges with datagram oriented sockets, opportunistic
   mode, and manual bindings between HITs and locators.  The extensions
   in this document are of experimental nature and provide basic tools
   for experimenting with policies.  Policy related issues are left for
   further experimentation.

   To recap, the extensions in this document have two three goals.  The
   first goal is to allow HIP-aware applications to resolve open sockets to
   other hosts based on the HITs explicitly. alone, presuming that the underlying
   system can resolve the HITs to addresses used for initial contact.
   The second goal is that applications can explicitly accept initiate
   communications with unknown peer identifiers.

3.  Design Model

   In this section, the native HIP APIs  The third goal is described from a design point
   of view.  We first describe the namespace model and conclude the
   discussion to
   define how HIP-aware applications may provide suggested initial
   contact addresses along with a description of the resolver model.

3.1.  Namespace Model HITs.

2.  Terminology

   The namespace model is shown terms used in Table 2 from HIP point of view.  The
   namespace identifiers this document are described summarized in this section.

             +-------------------+---------------------------+ Table 1.

   +---------+---------------------------------------------------------+
   | Layer Term    | Identifier Explanation                                             |
             +-------------------+---------------------------+
   +---------+---------------------------------------------------------+
   | User Interface HIP     | Relative hostname or FQDN Host Identity Protocol                                  |
   | Application Layer HIT     | HIT, port and protocol Host Identity Tag, a 100-bit hash of a public key with  |
   | Transport Layer         | HIT, port a 28 bit prefix                                         |
   | HIP Layer LSI     | Local Scope Identifier, a local, 32-bit descriptor for  |
   | HIT or HI         | a given public key.                                     | Network Layer
   | Locator |
             +-------------------+---------------------------+

                                  Table 2

   User interfaces input human-readable names and translate them to
   machine-readable names.  In native APIs for HIP, the machine readable
   names are HITs.  The HITs are present Routable IPv4 or IPv6 address used at the application layer, and
   transport-layer pseudo checksums are based on HITs.  The HIP layer
   transforms lower layers  |
   +---------+---------------------------------------------------------+

                                  Table 1

3.  API Overview

   This section provides an overview of how the HITs to locators for API can be used.  First,
   the network layer case in which a resolver is involved in name resolution is
   described, and vice versa.

3.2. then the case in which no resolver is involved is
   described.

3.1.  Interaction with the Resolver

   Before an application can establish network communications with the
   entity named by a given FQDN or relative host name, the application
   must translate the name into the corresponding identifier(s).  DNS  DNS-
   based hostname-to-identifier translation is illustrated in Figure 1.
   The application calls the resolver (step a.) in step a to resolve an FQDN (step
   b.). step
   b.  The DNS server responds with a list of HITs and a set of locators (step c.).
   step c.  Optionally (in in step d.), d, the resolver caches the HIT to locator
   mapping to the HIP module.  The resolver returns the HITs to the
   application in step e.  Finally, the application selects one HIT and
   uses it in a socket call such as connect() in step e. f.

                                              +----------+
                                              |          |
                                              |   DNS    |
                                              |          |
                                              +----------+
                                                  ^  |
                                        b. <FQDN> |  | c. <HITs + locators <HITs+locators
                                                  |  v      = HITs+locs>
       +-------------+ a. getaddrinfo(<FQDN>)  +----------+
       |             |------------------------>|          |
       | Application |                         | Resolver |
       |             |<------------------------|          |
       +-------------+        e. <HITs>        +----------+
               |                                    |
               |                                    |
               | f. connect(<HIT>)                  | d. <HITs+locs>
               v                                    v
        +----------+                           +----------+
        |          |                           |          |
        |  TCP/IP  |                           |   HIP    |
        |  Stack   |                           |          |
        +----------+                           +----------+

                                 Figure 1

   In practice, the resolver functionality can be implemented in
   different ways.  For example, it may be implemented in existing
   resolver libraries or as a DNS proxy.

3.2.  Interaction without a Resolver

   The extensions in this document focus on the use of the resolver to
   map host names to HITs and locators in HIP-aware applications.  The
   resolver associates implicitly the the HIT with the locator(s). locator(s) by e.g.
   communicating the HIT-to-IP mapping to the HIP daemon.  However, it
   is possible that an application operates directly with on a peer HIT
   without interacting with the resolver.  In such a case, the
   application may resort to the system to map the peer HIT to an IP
   address.  Alternatively, the application can explicitly map the HIT
   to an IP address using socket options as specified in
   [I-D.ietf-shim6-multihome-shim-api].
   Both  Full support for all of these two approaches may be more prone the
   extensions defined in this draft requires shim socket options to errors than be
   implemented by the use
   resolver with host names.  Hence, HIP-aware applications should
   prefer to use the resolver with host names. system.

4.  API Syntax and Semantics

   In this section, we describe the native HIP APIs using the syntax of
   the C programming language.  We limit the description to the
   interfaces and data structures that are either modified or completely
   new, because the native HIP APIs are otherwise identical to the
   sockets API [POSIX].

4.1.  Socket Family and Address Structure Extensions

   The sockets API extensions define a new protocol family, PF_HIP, and
   a new address family, AF_HIP.  The AF_HIP and PF_HIP are aliases to
   each other.  The use of the PF_HIP constant is mandatory with the
   socket() function when application uses the native HIP APIs.  The
   application gives the PF_HIP constant as the first argument (domain)
   to the socket() function.  The system returns EPFNOSUPPORT in the
   socket call when it does not support HIP.

   The application can also use the new PF_HIP family to detect HIP
   support in the local host.  Namely, the application creates a socket
   by calling socket() function with the first argument (domain) as
   PF_HIP.  The system returns a positive integer
   representing a socket descriptor when the system supports HIP.
   Otherwise, the system returns -1 and sets errno to EAFNOSUPPORT.

   A HIT is contained in a sockaddr_hip structure, which is shown in
   Figure 2. 2 in 4.4BSD format.  The family of the socket, ship_family, is
   set to PF_HIP.  The port number ship_port is two octets and the sins_hit
   ship_hit is four 16 octets.  The HIT value is an IPv6 address and it is stored in network
   byte order.

         #include <netinet/in.h>

         typedef struct in6_addr hip_hit_t;

         struct sockaddr_hip {
                 uint8_t        ship_len;
                 uint8_t        ship_family;
                 uint16_t       ship_port;
                 uint64_t       ship_flags;
                 hip_hit_t      ship_hit;
                 uint8_t        reserved[16];
         }

                                 Figure 2
   The application usually sets the ship_hit field using the resolver.
   However, the application can use three special wildcard macros to set
   a value directly into the ship_hit field.  The macros are
   HIP_HIT_ANY, HIP_HIT_ANY_PUB HIP_HIT_ANY_PUB, HIP_HIT_ANY_TMP and HIP_HIT_ANY_ANON.  They denote HIP_ADDR_ANY.  The
   first three equal to a HIT value associated with a wildcard HIT of
   any, public, or anonymous type.  The fourth macro, HIP_ADDR_ANY,
   denotes both HIP_HIT_ANY or any IPv4 or IPv6 address.  The
   HIP_HIT_ANY means equals to HIP_HIT_ANY_PUB or HIP_HIT_ANY_ANON. HIP_HIT_ANY_TMP.  The
   anonymous identifiers refer to the use anonymous identifiers as
   specified in [RFC4423].  The system may designate anonymous
   identifiers as meta data associated with a HIT regarding depending on whether
   it has been published or not, but that from the HIP protocol
   perspective, not.  However, there is no difference in the
   classes of HITs.

   The application can use the macro HIP_IS_IPV6_ADDR_ANON_HIT to verify
   whether a HIT is anonymous or public.  The macro inputs a pointer to
   a hip_hit_t structure and returns an integer (int) set to one when
   the corresponding HIT is anonymous and zero when it is public.  The
   macro returns -1 when HITs from the anonymity status is not available. HIP protocol perspective,

   The application can use the HIP_HIT_ HIP_HIT_ANY_* and HIP_ADDR_ANY macros to
   accept incoming communications to all of the HITs of the local host.
   Incoming communications refers here to the functions such as bind(),
   recvfrom() and recvmsg().  The HIP_HIT_ HIP_HIT_* macros correspond are similar to the
   sockets API macros INADDR_ANY and IN6ADDR_ANY_INIT, but they are
   applicable at the HIP layer. to HITs only.  After initial contact with the peer, the
   application can discover the local and peer HITs can be discovered using getsockname()
   and getpeername() calls for in the context of connection oriented
   sockets.  The difference between the use of the HIP_HIT_* and
   HIP_ADDR_ANY macros here is that the former allows only HIP-based
   communications but the latter also allows communications without HIP.

   The application also uses the the HIP_HIT_ANY macro in ship_hit field to
   establish outgoing communications in Opportunistic mode
   [I-D.ietf-hip-base], i.e., when the application knows the remote peer
   locator but not the HIT.  Outgoing communications refers here to the
   use of functions such as connect(), sendto() and sendmsg().  After
   initial contact with the peer,  However,
   the application discovers local and must first associate the socket with at least one IP
   address of the peer HITs using getsockname() and getpeername() calls when it is using connection-oriented sockets. SHIM_LOCLIST_PEER_PREF socket option.

   The HIP_HIT_ANY_ macros also allow non-ORCHID based communications.
   To distinguish between ORCHID [RFC4843] and non-ORCHID-based
   communications use of HIP_ADDR_ANY macro in the case context of the HIP_HIT_ANY_ macros, the
   application calls getsockname() and getpeername() to discover the
   actual identifiers outgoing
   communications is left for further experimentation.  It could be used
   for the communications and verifies orchid
   prefix with HIP_IS_IPV6_ADDR_ORCHID macro.  The macro inputs establishing a
   pointer to an in6_addr structure and returns 1 non-HIP based connectivity when the address has
   orchid prefix and 0 otherwise.  Alternatively, the application can
   set the flag HIP_FLAG_ONLY_ORCHID in ship_flags to allow only ORCHID- HIP-based
   connectivity was unsuccessful.

   Some applications rely on system level access control, either
   implicit or explicit (such as accept_filter() function found on BSD-
   based communications.

   Applications can also systems), but such discussion is out of scope.  Other
   applications implement access control themselves by using the HITs.
   In such a case, the application can compare two HITs using memcmp()
   or similar function.  It should be noticed that different connection
   attempts between the same two hosts can result in different HITs
   because a host is allowed to have multiple HITs.

4.2.  Resolver  Extensions to Resolver Data Structures

   The HIP APIs introduces introduce a new addrinfo flag, AI_HIP, HIP_PREFER_ORCHID, to be
   used by application to query for both HIT and locator information via
   the getaddrinfo() resolver function [RFC3493].  The getaddrinfo()
   function uses a data structure used for both input to and output from
   the resolver.  The data structure is illustrated in Figure 3.

          #include <netdb.h>

          struct addrinfo {
              int    ai_flags;          /* e.g. AI_HIP AI_EXTFLAGS */
              int    ai_family;         /* e.g. PF_HIP */
              int    ai_socktype;       /* e.g. SOCK_STREAM */
              int    ai_protocol;       /* 0 or IPPROTO_HIP */
              size_t ai_addrlen;        /* size of *ai_addr  */
              struct sockaddr *ai_addr; /* sockaddr_hip */
              char   *ai_canonname;     /* canon. name of the host */
              struct addrinfo *ai_next; /* next endpoint */
              int    ai_eflags;         /* RFC5014 extension */
          };

                                 Figure 3

   The flag AI_HIP

   Application must be set both the flag AI_EXTFLAGS [RFC5014] in ai_flags
   and HIP_PREFER_ORCHID in the ai_flags, ai_eflags, or otherwise the resolver
   does not return sockaddr_hip data structures.  The resolver returns
   EAI_BADFLAGS when AI_HIP is it does not supported. support HIP_PREFER_ORCHID or
   AI_EXTFLAGS flags.

   Application denotes its preference for public and anonymous types of
   HITs using HIP_PREFER_SRC_PUBLIC and HIP_PREFER_SRC_TMP flags in the
   ai_eflags field.  If the application sets neither of the flags, the
   resolver returns both public and anonymous HITs.

   The simultaneous use of both AI_HIP HIP_PREFER_ORCHID and AI_PASSIVE
   HIP_PREFER_PASSIVE_* flags equals to produces a single sockaddr_hip structure
   containing a wildcard address that the application can use HIP_HIT_ANY
   macro as described either for
   incoming (node argument is NULL in section Section 4.1.  Similarly, the use of
   AI_PASSIVE_PUB and AI_PASSIVE_ANON getaddrinfo) or outgoing
   communications (node argument is non-NULL).  For example,
   HIP_PREFER_PASSIVE_HIT_TMP flag equals to produces one sockaddr_hip structure
   that contains a HIP_HIT_ANY_TMP in the use of
   HIP_HIT_ANY_PUB and HIP_HIT_ANY_ANON. ship_hit field.

   The resolver sets the ai_family field is set to PF_HIP in the addrinfo
   structure when ai_addr points to a sockaddr_hip structure.

   When ai_protocol field is set to zero, the resolver also returns
   locators in sockaddr_in and sockaddr_in6 structures in addition to
   sockaddr_hip structures.  The resolver only returns only sockaddr_hip
   structures when the application has set the ai_protocol field is set to
   IPPROTO_HIP or a sockaddr_hip structure is given as the hint argument
   to the resolver.

4.2.1.  Resolver Usage

   A HIP-aware application creates the sockaddr_hip structures manually
   explicitly or obtains them from the resolver.  The manual explicit
   configuration of locators is described in
   [I-D.ietf-shim6-multihome-shim-api].  This document defines
   "automated" resolver extensions for getaddrinfo getaddrinfo() resolver [RFC3493].

           #include <netdb.h>

           int getaddrinfo(const char *nodename,
                           const char *servname,
                           const struct addrinfo *hints,
                           struct addrinfo **res)
           void free_addrinfo(struct addrinfo *res)

                                 Figure 4

   As described in [RFC3493], the getaddrinfo function takes the
   nodename, servname, and hints as its input arguments.  It places the
   result of the query into the res argument.  The return value is zero
   on success, or a non-zero error value on error.  The nodename
   argument specifies the host name to be resolved; a NULL argument
   denotes the local host.  The servname parameter declares the port
   number to be set in the socket addresses in the res output argument.
   Both the nodename and servname cannot be NULL.

   The input argument "hints" acts like a filter that defines the
   attributes required from the resolved endpoints.  A NULL hints
   argument indicates that any kind of endpoints are acceptable.

   The output argument "res" is dynamically allocated by the resolver.
   The application frees res argument with the free_addrinfo function.
   The res argument contains a linked list of the resolved endpoints.
   The linked list contains sockaddr_hip structures only when the input
   argument has the AI_HIP HIP_PREFER_ORCHID flag set. set in ai_eflags.  The
   resolver inserts HITs before any locators.  When the
   HIP_PREFER_ORCHID flag is set, the resolver does not return LSIs or
   HITs encapsulated into sockaddr_in or sockaddr_in6 data structures as
   described in [I-D.ietf-hip-applications].

   Resolver can return a HIT which maps to multiple locators.  The
   resolver may cache the locator mappings to the HIP module.  The HIP
   module manages the multiple locators according to local system policies of
   the host.

4.3.  Manual Handling of Locators  The multihoming document
   [I-D.ietf-shim6-multihome-shim-api] describes how an application can
   override system resolver, default policies.

   It should be noticed that the application can configure the HIT
   explicitly without setting the locator or the HIP module, maps HITs to locators
   implicitly.  However, some applications may want resolver can fail to specify initial
   locator
   resolve any locator.  In this scenario, the application relies on the
   system to map the HIT to an IP address.  When the system fails to
   provide the mapping, it returns -1 in the called sockets API function
   to the application and sets errno to EADDRNOTAVAIL.

4.3.  The Use of getsockname and getpeername Functions

   The application usually discovers the local or peer HITs from the
   sockaddr_hip structures returned by getaddrinfo().  However, the
   sockaddr_hip structure does not contain a HIT when the application
   uses the HIP_HIT_ANY_* macros.  In such a case, the application
   discovers the local and peer HITs using the getsockname() and
   getpeername() functions.  The functions return sockadd_hip structures
   when the family of the socket is PF_HIP.

4.4.  Validating HITs

   An application that uses the HIP_ADDR_ANY macro may want to check if
   the local or peer address is an orchid-based HIT [RFC4843].  Also,
   the application may want to verify whether a HIT is public or
   anonymous.  The application accomplishes these using a new function
   called sockaddr_is_srcaddr() which is illustrated in Figure 5.

         #include <netinet/in.h>

         short sockaddr_is_srcaddr(struct sockaddr *srcaddr
                                   uint64_t flags);

                                 Figure 5

   The sockaddr_is_srcaddr() function operates in the same way as
   inet6_is_srcaddr() function [RFC5014] which can be used to verify the
   type of an address belonging to the localhost.  The difference is
   that sockaddr_is_srcaddr() function handles sockaddr_hip structures
   in addition to sockaddr_in6, and possibly some other socket
   structures in further extensions.  The function has also 64 bit flags
   instead of 32 bits.  This new function handles the same flags as
   defined in [RFC5014] in addition to some HIP-specific flags listed in
   Table 2.

            +-----------------------+-------------------------+
            | Flag                  | Purpose                 |
            +-----------------------+-------------------------+
            | HIP_PREFER_ORCHID     | The identifier is a HIT |
            | HIP_PREFER_SRC_TMP    | Anonymous HIT           |
            | HIP_PREFER_SRC_PUBLIC | Public HIT              |
            +-----------------------+-------------------------+

                                  Table 2

4.5.  Source HIT Selection by the System

   Some applications initiate communications by specifying only the
   destination identifier and let the underlying system specify the
   source.  When the system selects the source HIT, the system should
   apply the rules specified in [RFC3484] according to the default
   policy table for HITs shown in Table 3.

                 +-----------------+------------+-------+
                 | HIT Type        | Precedence | Label |
                 +-----------------+------------+-------+
                 | Anonymous DSA   | 110        | 5     |
                 | Anonymous RSA   | 120        | 6     |
                 | Public DSA      | 130        | 7     |
                 | Public RSA      | 140        | 8     |
                 | [RFC3484] rules | 50-100     | 7     |
                 +-----------------+------------+-------+

                                  Table 3

   When application using a PF_HIP-based socket does not specify the
   source identifier, the system selects the source identifier on the
   behalf of the application according to the precedence in the above
   table.  For example, the system prefers public (published) keys
   before anonymous keys because they work better for referral purposes.
   RSA-based keys are preferred over DSA based because RSA is the
   default algorithm in HIP.

   When system provides multiple keys of same type, but with different
   key lengths, the longer keys should have a higher preference.  As
   example, system providing two public RSA keys of different size would
   give the smaller key preference value 140 and 145 for the larger.
   The preference value should not exceed 150.  Systems supporting more
   than 10 keys of same key size may use digits to further fragment the
   precedence namespace.  IPv6 addresses have the lowest presedence
   value to denote that HITs have a higher precedence when operating on
   PF_HIP-based sockets.

   [RFC5014] specifies flags for the getaddrinfo resolver and socket
   options for MobileIPv6.  The resolver, operating under
   HIP_PREFER_ORCHID flag, or the socket handler, operating on a PF_HIP-
   based socket, may encounter such flags or options.  In such a case
   the resolver or socket handler should silenty ignore the flags or
   options without returning an error.  However, a HIP-aware application
   may use the HIP-specific flags HIP_PREFER_ORCHID, HIP_PREFER_SRC_TMP
   or HIP_PREFER_SRC_PUBLIC in getsockopt(), setsockopt(), getaddrinfo()
   calls and in the anchillary data of datagram packets as specified in
   [RFC5014].  The level of the socket options should be set to SOL_SHIM
   [I-D.ietf-shim6-multihome-shim-api] and the option name should be
   HIP_HIT_PREFERENCES.

4.6.  Explicit Handling of Locators

   The system resolver, or the HIP module, maps HITs to locators
   implicitly.  However, some applications may want to specify initial
   locator mappings explicitly.  In such a case, the application first
   creates a socket with PF_HIP as the domain argument.  Second, the
   application binds PF_HIP as the domain argument.  Second, the
   application may set locator information with one of the following
   shim socket options as defined in the multihoming extensions in
   [I-D.ietf-shim6-multihome-shim-api]:

   +-----------------------------+-----+-----+-----------------+-------+
   | optname                     | get | set | description     | dtype |
   +-----------------------------+-----+-----+-----------------+-------+
   | SHIM_LOC_LOCAL_PREF         | o   | o   | Get or set the  | *1    |
   |                             |     |     | preferred       |       |
   |                             |     |     | locator on the  |       |
   |                             |     |     | local side for  |       |
   |                             |     |     | the context     |       |
   |                             |     |     | associated with |       |
   |                             |     |     | the socket.     |       |
   | SHIM_LOC_PEER_PREF          | o   | o   | Get or set the  | *1    |
   |                             |     |     | preferred       |       |
   |                             |     |     | locator on the  |       |
   |                             |     |     | remote side for |       |
   |                             |     |     | the context     |       |
   |                             |     |     | associated with |       |
   |                             |     |     | the socket.     |       |
   | SHIM_LOCLIST_LOCAL          | o   | o   | Get or set a    | *2    |
   |                             |     |     | list of         |       |
   |                             |     |     | locators        |       |
   |                             |     |     | associated with |       |
   |                             |     |     | the socket to a local EID.  |       |
   | SHIM_LOCLIST_PEER           | o   | o   | Get or peer locator set a    | *2    |
   |                             |     |     | list of         |       |
   |                             |     |     | locators        |       |
   |                             |     |     | associated with |       |
   |                             |     |     | the
   setsockopt function with either SHIM_LOC_LOCAL_PREF or
   SHIM_LOC_PEER_PREF peer's EID. |       |
   | SHIM_LOC_LOCAL_SEND         | o   | o   | Request use of  | *2    |
   |                             |     |     | specific        |       |
   |                             |     |     | locator as the socket option name      |       |
   |                             |     |     | source locator  |       |
   |                             |     |     | of outgoing IP  |       |
   |                             |     |     | packets.        |       |
   | SHIM_LOC_PEER_SEND          | o   | o   | Request use of  | *2    |
   |                             |     |     | specific        |       |
   |                             |     |     | locator as      |       |
   |                             |     |     | destination     |       |
   |                             |     |     | locator of      |       |
   |                             |     |     | outgoing IP     |       |
   |                             |     |     | packets.        |       |
   +-----------------------------+-----+-----+-----------------+-------+
   *1: Pointer to a shim_locator which is defined in
   [I-D.ietf-shim6-multihome-shim-api].  Third, Section 7 of
   draft-ietf-shim6-multihome-shim-api.
   *2: Pointer to an array of shim_locator.

                                 Figure 6

   Finally, the application creates a valid sockaddr_hip structure.  Finally, the application structure and
   associates the socket also with the sockaddr_hip structure by calling
   some socket-related function, such as connect connect() or bind. bind().

   The function
   returns EINVALIDLOCATOR when the HIT is not reachable usage and semantics for typical use cases are as follows:

   An application that initiates a connection using a connection
   oriented socket to a particular host at a known address or set of
   addresses can call SHIM_LOCLIST_PEER socket option.  The HIP module
   uses the
   specified locator.

   It should be noticed that the first address (if multiple are provided, or else the
   application may just configure can override this by setting SHIM_LOC_PEER_PREF to one of
   the addresses in SHIM_LOCLIST_PEER.  The application later provides a
   specific HIT
   manually without setting in the locator.  In this scenario, ship_hit field of the sockaddr_hip in the
   connect() system call.  If the application relies on provides one or more
   addresses in SHIM_LOCLIST_PEER setsockopt call, the system should not
   connect to map the HIT host via another destination address, in case the
   application intends to an IP address.
   When restrict the range of addresses permissable as
   a policy choice.  If the system fails to provide cannot reach the mapping, it returns
   EADDRNOTAVAIL in provided HIT at one
   of the called sockets addresses provided, the outbound socket API function functions
   (connect, sendmsg, etc.) return -1 and set errno to EINVALIDLOCATOR.

   Another common use case is to set up an association in opportunistic
   mode, when the application destination HIT is specified as a wildcard.  This can
   be accomplished by setting one or more destination addresses using
   the SHIM_LOCLIST_PEER socket option as described above and then
   calling connect() with the wildcard HIT.  The connect() call returns
   -1 and sets errno to indicate EADDRNOTAVAIL when the error. application connected to
   a wildcard without specifying any destination address.

   Applications may also choose to associate local addresses with
   sockets.  The procedures specified in
   [I-D.ietf-shim6-multihome-shim-api] are followed in this case.

5.  Summary of New Definitions

   Table 3 4 summarizes the new macro and structures defined in this
   document.

              +-----------------+---------------------------+

             +-----------------+-----------------------------+
             | Header          | Definition                  |
              +-----------------+---------------------------+
             +-----------------+-----------------------------+
             | <sys/socket.h>  | PF_HIP                      |
             | <sys/socket.h>  | AF_HIP                      |
             | <netinet/in.h>  | IPPROTO_HIP                 |
             | <netinet/hip.h> | HIP_HIT_ANY                 |
             | <netinet/hip.h> | HIP_HIT_ANY_PUB             |
             | <netinet/hip.h> | HIP_HIT_ANY_ANON HIP_HIT_ANY_TMP             |
             | <netinet/hip.h> | HIP_IS_IPV6_ADDR_ORCHID HIP_ADDR_ANY                |
             | <netinet/hip.h> | HIP_IS_IPV6_ADDR_ANON_HIT HIP_HIT_PREFERENCES         |
             | <netinet/hip.h> | HIP_FLAG_ONLY_ORCHID hip_hit_t                   |
             | <netdb.h>       | HIP_PREFER_ORCHID           |
             | <netdb.h>       | AI_HIP HIP_PREFER_SRC_TMP          |
             | <netdb.h>       | AI_PASSIVE_ANON HIP_PREFER_SRC_PUBLIC       |
             | <netdb.h>       | AI_PASSIVE_PUB HIP_PREFER_PASSIVE_HIT_TMP  |
             | <netdb.h>       | AI_HIP_NOLOCATORS HIP_PREFER_PASSIVE_HIT_PUB  |
             | <netinet/hip.h> <netdb.h>       | HIP_PREFER_PASSIVE_HIT_ANY  | hip_hit_t
             | <netdb.h>       | HIP_PREFER_PASSIVE_ADDR_ANY |
             | <netinet/in.h>  | sockaddr_hip                |
              +-----------------+---------------------------+
             | <netinet/in.h>  | sockaddr_is_srcaddr         |
             +-----------------+-----------------------------+

                                  Table 3 4

6.  IANA Considerations

   No IANA considerations.

7.  Security Considerations

   No security considerations currently.

8.  Acknowledgements

   Jukka Ylitalo and Pekka Nikander have contributed many ideas, time
   and effort to the native HIP APIs.  Thomas Henderson,  Kristian Slavov, Julien Laganier,
   Jaakko Kangasharju, Mika Kousa, Jan Melen, Andrew McGregor, Sasu
   Tarkoma, Lars Eggert, Joe Touch, Antti Jaervinen, Anthony Joseph,
   Teemu Koponen, Jari Arkko, Ari Keraenen, Juha-Matti Tapio, Shinta
   Sugimoto, Philip Matthews, Jan Melen and Gonzalo Camarillo have also
   provided valuable ideas or feedback.  Thanks for the APPS area folks,
   Stephane Bortzmeyer, Chris Newman, Tony Finch, "der Mouse" and Keith
   Moore for comments.

9.  Normative References

   [I-D.henderson-hip-applications]
              Henderson, T. and P. Nikander, "Using HIP with Legacy
              Applications", draft-henderson-hip-applications-03 (work
              in progress), May 2006.

   [I-D.ietf-btns-c-api]
              Richardson, M., Williams, N., Komu, M., and S. Tarkoma,
              "IPsec Application Programming Interfaces",
              draft-ietf-btns-c-api-01
              draft-ietf-btns-c-api-03 (work in progress),
              February 2008.

   [I-D.ietf-hip-applications]
              Henderson, T., Nikander, P., and M. Komu, "Using the Host
              Identity Protocol with Legacy Applications",
              draft-ietf-hip-applications-02 (work in progress), July
              November 2007.

   [I-D.ietf-hip-base]
              Moskowitz, R., Nikander, P., Jokela, P., and T. Henderson,
              "Host Identity Protocol", draft-ietf-hip-base-10 (work in
              progress), October 2007.

   [I-D.ietf-hip-dns]
              Nikander, P. and J. Laganier, "Host Identity Protocol
              (HIP) Domain Name System (DNS) Extensions",
              draft-ietf-hip-dns-09 (work in progress), April 2007.

   [I-D.ietf-shim6-multihome-shim-api]
              Komu, M., Bagnulo, M., Slavov, K., and S. Sugimoto,
              "Socket Application Program Interface (API) for
              Multihoming Shim", draft-ietf-shim6-multihome-shim-api-03 draft-ietf-shim6-multihome-shim-api-05
              (work in progress), July 2007. February 2008.

   [I-D.ietf-shim6-proto]
              Bagnulo, M. and E.
              Nordmark, E. and M. Bagnulo, "Shim6: Level 3 Multihoming
              Shim Protocol for IPv6", draft-ietf-shim6-proto-09 draft-ietf-shim6-proto-10 (work
              in progress), November 2007. February 2008.

   [POSIX]    Institute of Electrical and Electronics Engineers, "IEEE
              Std. 1003.1-2001 Standard for Information Technology -
              Portable Operating System Interface (POSIX)", Dec 2001.

   [RFC3484]  Draves, R., "Default Address Selection for Internet
              Protocol version 6 (IPv6)", RFC 3484, February 2003.

   [RFC3493]  Gilligan, R., Thomson, S., Bound, J., McCann, J., and W.
              Stevens, "Basic Socket Interface Extensions for IPv6",
              RFC 3493, February 2003.

   [RFC4423]  Moskowitz, R. and P. Nikander, "Host Identity Protocol
              (HIP) Architecture", RFC 4423, May 2006.

   [RFC4843]  Nikander, P., Laganier, J., and F. Dupont, "An IPv6 Prefix
              for Overlay Routable Cryptographic Hash Identifiers
              (ORCHID)", RFC 4843, April 2007.

Author's

   [RFC5014]  Nordmark, E., Chakrabarti, S., and J. Laganier, "IPv6
              Socket API for Source Address Selection", RFC 5014,
              September 2007.

Authors' Addresses

   Miika Komu
   Helsinki Institute for Information Technology
   Metsaenneidonkuja 4
   Helsinki
   Finland

   Phone: +358503841531
   Fax:   +35896949768
   Email: miika@iki.fi
   URI:   http://www.iki.fi/miika/

   Thomas Henderson
   The Boeing Company
   P.O. Box 3707
   Seattle, WA
   USA

   Email: thomas.r.henderson@boeing.com

Full Copyright Statement

   Copyright (C) The IETF Trust (2007). (2008).

   This document is subject to the rights, licenses and restrictions
   contained in BCP 78, and except as set forth therein, the authors
   retain all their rights.

   This document and the information contained herein are provided on an
   "AS IS" basis and THE CONTRIBUTOR, THE ORGANIZATION HE/SHE REPRESENTS
   OR IS SPONSORED BY (IF ANY), THE INTERNET SOCIETY, THE IETF TRUST AND
   THE INTERNET ENGINEERING TASK FORCE DISCLAIM ALL WARRANTIES, EXPRESS
   OR IMPLIED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF
   THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED
   WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Intellectual Property

   The IETF takes no position regarding the validity or scope of any
   Intellectual Property Rights or other rights that might be claimed to
   pertain to the implementation or use of the technology described in
   this document or the extent to which any license under such rights
   might or might not be available; nor does it represent that it has
   made any independent effort to identify any such rights.  Information
   on the procedures with respect to rights in RFC documents can be
   found in BCP 78 and BCP 79.

   Copies of IPR disclosures made to the IETF Secretariat and any
   assurances of licenses to be made available, or the result of an
   attempt made to obtain a general license or permission for the use of
   such proprietary rights by implementers or users of this
   specification can be obtained from the IETF on-line IPR repository at
   http://www.ietf.org/ipr.

   The IETF invites any interested party to bring to its attention any
   copyrights, patents or patent applications, or other proprietary
   rights that may cover technology that may be required to implement
   this standard.  Please address the information to the IETF at
   ietf-ipr@ietf.org.

Acknowledgment

   Funding for the RFC Editor function is provided by the IETF
   Administrative Support Activity (IASA).