Host Identity Protocol                                           M. Komu
Internet-Draft                        Helsinki Institute for Information
Intended status: Informational                                Technology
Expires: January 8, May 22, 2008                                    July 7,                                  November 19, 2007

   Native Application Programming Interfaces (APIs) for SHIM APIs
                      draft-ietf-hip-native-api-02 Host Identity
                             Protocol (HIP)
                      draft-ietf-hip-native-api-03

Status of this Memo

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

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

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

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

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

   This Internet-Draft will expire on January 8, May 22, 2008.

Copyright Notice

   Copyright (C) The IETF Trust (2007).

Abstract

   This document defines extensions to the current networking APIs sockets API for
   protocols based on identifier/locator split.  Currently, the document
   focuses Host
   Identity Protocol (HIP).  The extensions focus on HIP, but the extensions can be used also by other
   protocols implementing identifier locator split. initial
   discovery of public-key based identifiers.  Using the API extensions, new SHIM aware applications the
   application can configure manually
   mappings between upper layer identifiers and verify that the corresponding
   locators.  Also, identifier is a Host Identity Tag
   (HIT) and it can require the API describes how system resolver to handle outbound connection
   establishment where an return only HITs from
   DNS.  The application is unaware of can also to explicitly allow more relaxed
   security models where the communication can be non-HIP based in the
   absence of a peer identifier
   but knows identifiers, or that the application allows peer locator.
   identity to be discovered after initial contact directly with the
   peer.

Table of Contents

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

   2.  Introduction . . . . . . . . . . . . . . . . . . . . . . . . .  3

   3.  Design Model . . . . . . . . . . . . . . . . . . . . . . . . .  4
     3.1.  Layering  Namespace Model  . . . . . . . . . . . . . . . . . . . . . .  4
     3.2.  Namespace Model  Interaction with the Resolver  . . . . . . . . . . . . . .  5

   4.  API Syntax and Semantics . . . . . . . .  4
     3.3.  Interaction with the Resolver . . . . . . . . . . .  6
     4.1.  Socket Family and Address Structure Extensions . . .  5

   4.  API Syntax and Semantics . . .  6
     4.2.  Resolver Extensions  . . . . . . . . . . . . . . . .  6
     4.1.  Socket Family and Address Structure . . .  8
     4.3.  Manual Handling of Locators  . . . . . . . .  6
     4.2.  Resolver . . . . . . . 10

   5.  Summary of New Definitions . . . . . . . . . . . . . . . . . .  8

   5. 10

   6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 10

   6. 11

   7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 10

   7. 11

   8.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 10

   8. 11

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

   Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 11 12
   Intellectual Property and Copyright Statements . . . . . . . . . . 12 14

1.  Terminology

   The terms used in this document are summarized in Table 1.

   +---------+---------------------------------------------------------+
   | Term    | Explanation                                             |
   +---------+---------------------------------------------------------+
   | ULID    | Upper Layer IDentifier equals to the identity part of   |
   |         | the identity/locator split. It is the identifier used   |
   |         | by the application to name a peer for the transport     |
   |         | layer.                                                  |
   | Locator | Non-routable IPv4 or IPv6 address used at the lower     |
   |         | layers                                                  |
   | FQDN HIP     | Fully Qualified Domain Name Host Identity Protocol                                  |
   | HIT     | Host Identity Tag, a 100-bit hash of a public key with  |
   |         | a 28 bit prefix                                         |
   | LSI     | Locally Local Scope Identifier, a local, 32-bit local presentation descriptor for  |
   |         | of a given public key key.                                     |
   +---------+---------------------------------------------------------+

                                  Table 1

2.  Introduction

   Host Identity Protocol proposes
   | Locator | Routable IPv4 or IPv6 address used at the lower layers  |
   +---------+---------------------------------------------------------+

                                  Table 1

2.  Introduction

   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 layer namespace to the TCP/IP architecture.
   stack.  SHIM6 [I-D.ietf-shim6-proto] is another protocol based on
   identity-locator split.  Note that the Application Programming
   Interfaces (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 see these new
   changes observe the HIP layer and its identifiers in the
   networking stacks with varying degrees of visibility.
   [I-D.henderson-hip-applications] discusses the lowest levels of
   visibility in which applications are either completely unaware of HIP.  The HIP-
   unaware the
   underlying HIP layer.  Such HIP-unaware applications use HIP-based
   identifiers, such as LSIs or HITs HITs, instead of IPv4 or IPv6
   addresses.  Such applications may be unaware of the locator bindings.

   This document discusses about visibility of HIP to HIP-aware
   applications.  The applications are completely HIP aware addresses
   and can
   control cannot observe the HIP layer and Host Identifiers. identifier-locator bindings.

   This document defines C-based sockets API extensions for handling the bindings explicitly.
   The extensions expose the identity-locator split to SHIM-aware
   applications and it
   HIP-based identifiers explicitly in HIP-aware applications.  It is up
   to the application, applications, or a higher level high-level programming language, languages or
   libraries, to manage the identities and locators. identifiers.  The extensions in this
   document are mainly related to the initial discovery of the
   identifiers, i.e., DNS resolution step.

   The API extensions introduce a new socket address structure.  The
   structure requires family, AF_HIP, and a new
   socket address family, PF_SHIM, structure for sockets that
   use HITs and locators using Host Identity Tags (HITs)
   explicitly.  An application can also use  PF_HIP is used as an alias for AF_HIP in this document
   because the
   family to detect SHIM support distinction between PF and AF has been lost in the local host.

   Hosts
   practice.

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

   There are two related IETF documents that are define other related API extensions. 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] [I-D.ietf-btns-c-api].  The
   extensions defined in this document can be used independently of the
   two mentioned related API documents.

   To recap, the extensions in this document have two goals.  The first
   goal is to allow HIP-aware applications to resolve HITs explicitly.
   The second goal is that applications can explicitly accept
   communications with unknown peer identifiers.

3.  Design Model

   In this section, the native SHIM API design HIP APIs is described from an a design point
   of view.  We first describe the layering and namespace model.
   We model and conclude the
   discussion with a description of the resolver model.

3.1.  Layering Model

   The application layer accesses the transport layer via the socket
   interface.  The application layer uses the traditional TCP/IP IPv4 or
   IPv6 interface, or the new native SHIM API interface provided by the
   socket layer.  The layering model is illustrated in Figure 1.  For
   simplicity, the IPsec layer has been excluded from the figure.

                         +--------------------------------+
      Application Layer  |           Application          |
                         +----------+----------+----------+
           Socket Layer  | IPv4 API | IPv6 API | SHIM API |
                         +----------+----+-----+----------+
        Transport Layer  |      TCP      |      UDP       |
                         +---------------+----------------+
              SHIM Layer |       HIP and other SHIMs      |
                         +---------------+----------------+
          Network Layer  |     IPv4      |     IPv6       |
                         +---------------+----------------+
             Link Layer  |   Ethernet    |     Etc        |
                         +---------------+----------------+

                                 Figure 1

   The SHIM layer is as a shim/wedge layer between the transport and
   network layers.  The datagrams delivered between the transport and
   network layers are intercepted in the SHIM layer to see if the
   datagrams are SHIM related and require SHIM intervention.

3.2.  Namespace Model

   The namespace model is shown in Table 2 from SHIM HIP point of view.  The
   namespace identifiers are described in this section.

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

             +-------------------+---------------------------+
             | Layer             | Identifier                |
              +-------------------+-------------------------+
             +-------------------+---------------------------+
             | User Interface    | Relative hostname or FQDN |
             | Application Layer | ULID, HIT, port and protocol    |
             | Transport Layer   | ULID, HIT, port                 |
             | SHIM HIP Layer         | ULID HIT or HI                 |
             | Network Layer     | Locator                   |
              +-------------------+-------------------------+
             +-------------------+---------------------------+

                                  Table 2

   User interfaces input human-readable names and translate them to
   machine-readable names.  In SHIM API, the ULID is a HIT when native APIs for HIP, the
   underlying protocol is HIP. machine readable
   names are HITs.  The ULID is HITs are present at the application
   layer layer, and also transport layer checksum is calculated
   transport-layer pseudo checksums are based on it. HITs.  The SHIM HIP layer handles also ULIDs and translates them
   transforms the HITs to locators for the network layer.

3.3. layer and vice versa.

3.2.  Interaction with the Resolver

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

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

                                 Figure 2 1

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

   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).
   However, it is possible that an application operates directly with 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 as specified in [I-D.ietf-shim6-multihome-shim-api].
   Both of these two approaches may be more prone to errors than the use
   resolver with host names.  Hence, HIP-aware applications should
   prefer to use the resolver with host names.

4.  API Syntax and Semantics

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

4.1.  Socket Family and Address Structure

   We introduce Extensions

   The sockets API extensions define a new protocol family, PF_HIP, and
   a new protocol address family, PF_SHIM, for the sockets API. AF_HIP.  The AF_SHIM constant is an alias for it. AF_HIP and PF_HIP are aliases to
   each other.  The use of the PF_SHIM PF_HIP constant is mandatory with the
   socket() function if the SHIM API is
   to be used in when application uses the application. native HIP APIs.  The PF_SHIM
   application gives the PF_HIP constant is given as the first argument (domain)
   to the socket() function.  The ULIDs 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 locators are sets errno to EAFNOSUPPORT.

   A HIT is contained in the sockaddr_shim a sockaddr_hip structure, which is shown in
   Figure 3. 2.  The family of the socket, shim_family, ship_family, is set to PF_SHIM. PF_HIP.
   The port number sins_port ship_port is two octets and the
   sins_ulid sins_hit is four
   octets.  The ULID HIT value is an IPv6 address.  The
   locator is an IPv6 address or IPv6-mapped address IPv4 address as
   defined in - [RFC3493].  The family is stored in host byte order and
   the ULID and locator are it is stored in network
   byte order.

         #include <netinet/in.h>

         typedef struct in6_addr shim_ulid_t;
         typedef struct in6_addr shim_locator_t; hip_hit_t;

         struct sockaddr_shim sockaddr_hip {
                 uint8_t        sins_len;        ship_len;
                 uint8_t        sins_family;        ship_family;
                 uint16_t       sins_port;
                 shim_ulid_t    sins_ulid;
                 shim_locator_t sins_locator;       ship_port;
                 uint64_t       sins_flags;       ship_flags;
                 hip_hit_t      ship_hit;
                 uint8_t        reserved[16];
         }

                                 Figure 3 2

   The application usually sets the sins_ulid ship_hit field using the resolver.
   However, the application can use three special wildcard macros can be used to directly set
   a value directly into the sins_ulid ship_hit field.  The macros are SHIM_ANY, SHIM_ANY_PUB
   HIP_HIT_ANY, HIP_HIT_ANY_PUB and
   SHIM_ANY_ANON. HIP_HIT_ANY_ANON.  They denote an ULID a HIT
   value associated with a wildcard
   ULID HIT of any, public, or anonymous
   type.

   In server applications,  The HIP_HIT_ANY means HIP_HIT_ANY_PUB or HIP_HIT_ANY_ANON.
   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 whether it
   has been published or not, but that from the HIP protocol
   perspective, 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 the SHIM_* anonymity status is not available.

   The application can use the HIP_HIT_ macros to accept incoming connections
   communications to all of the ULID HITs of the local host.  Incoming
   communications refers here to the functions such as bind(),
   recvfrom() and recvmsg().  The HIP_HIT_ macros correspond to the
   sockets API macros INADDR_ANY and IN6ADDR_ANY_INIT, but they are
   applicable at the SHIM layer.  It should be noticed that only one
   process are
   applicable at a time in a host can bind the HIP layer.  After initial contact with the SHIM_*ANY macro to peer,
   the
   same port to avoid ambiguous bindings.

   A client application local and peer HITs can use be discovered using getsockname() and
   getpeername() calls for connection oriented sockets.

   The application also uses the SHIM_ANY the HIP_HIT_ANY macro in ship_hit field
   to establish a
   connection outgoing communications in Opportunistic mode
   [I-D.ietf-hip-base], when only the server application knows the remote peer
   locator (and but not the ULID) is known
   beforehand.

   In both client and server based applications, the use of the
   SHIM_ANY* macro accepts also non-SHIM based HIT.  Outgoing communications refers here to
   maximize backwards compatibility.  When the application wants
   enforces the
   use of SHIM-based communications functions such as connect(), sendto() and sendmsg().  After
   initial contact with ORCHID prefix
   [RFC4843], it sets the flag SHIM_FLAG_ONLY_ORCHID in sins_flags.
   Alternatively, peer, the application accepts both ORCHID discovers local and
   peer HITs using getsockname() and non-ORCHID- getpeername() calls when it is
   using connection-oriented sockets.

   The HIP_HIT_ANY_ macros also allow non-ORCHID based communications, but informs communications.
   To distinguish between ORCHID [RFC4843] and non-ORCHID-based
   communications in the difference e.g. to case of the user.
   In this case, HIP_HIT_ANY_ macros, the
   application calls SHIM_IPV6_ADDR_IS_ORCHID getsockname() and getpeername() to discover the
   actual identifiers used for the communications and verifies orchid
   prefix with HIP_IS_IPV6_ADDR_ORCHID macro.  The macro
   which inputs a
   pointer to a an in6_addr structure and returns 1 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-
   based communications.

   Applications can also implement access control using the ULIDs. HITs.  In
   such a case, the application can compare two ULIDs 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

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

          #include <netdb.h>

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

                                 Figure 4

   In addrinfo structures, the family field is set to PF_SHIM when the
   socket address structure contains an ULID that refers to ULID, such
   as HIT. 3

   The flag AI_SHIM AI_HIP must be set, set in the ai_flags, or otherwise the
   resolver does not return sockaddr_shim sockaddr_hip data structures structures.  The resolver
   returns EAI_BADFLAGS when AI_HIP is not supported.  The simultaneous
   use of both AI_HIP and AI_PASSIVE flags equals to guarantee that legacy
   applications do not break.  Some applications may prefer configuring the locators manually and can set use HIP_HIT_ANY
   macro as described in section Section 4.1.  Similarly, the AI_SHIM_NOLOCATORS use of
   AI_PASSIVE_PUB and AI_PASSIVE_ANON flag equals to
   prohibit the getaddrinfo from resolving any locators. use of
   HIP_HIT_ANY_PUB and HIP_HIT_ANY_ANON.

   The ai_family field is PF_SHIM with SHIM-specific addrinfo data
   structures.

   The protocol field is 0 when the getaddrinfo caller does not care
   about the specific SHIM protocol to be used.  The caller (or the
   resolver) can set this field also to IPPROTO_HIP.

   ai_addrlen is the size of PF_HIP in the addrinfo structure pointed by ai_addr.

   The when
   ai_addr points to a sockaddr_shim structure when the value of
   ai_family sockaddr_hip structure.

   When ai_protocol field is PF_SHIM.  The set to zero, the resolver sets SHIM_RVS also returns
   locators in sins_flags of
   the when the locator belongs sockaddr_in and sockaddr_in6 structures in addition to a rendezvous server
   [I-D.ietf-hip-dns].
   sockaddr_hip structures.  The SHIM API does not introduce changes resolver only returns sockaddr_hip
   structures when ai_protocol field is set to the interface syntax of
   the existing sockets API functions, such IPPROTO_HIP or a
   sockaddr_hip structure is given as bind(), connect(),
   send(), sendto(), sendmsg(), recv(), recvfrom(), and recvmsg().
   However, the SHIM-aware application usually passes hint argument to the functions a
   sockaddr_shim structure instead of a sockaddr_in or sockaddr_in6
   structure. resolver.

   A SHIM-aware HIP-aware application either creates the sockaddr_shim sockaddr_hip structures manually
   or obtains them from the resolver.  The
   getaddrinfo resolver [RFC3493] manual configuration is shown
   described in Figure 5. [I-D.ietf-shim6-multihome-shim-api].  This document
   defines resolver extensions for 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 5 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 "hints" acts like a filter that defines the
   attributes required from the resolved endpoints.  For example, the
   resolver returns only anonymous endpoints in the output argument res
   when the application sets the ai_addr pointer of hints to point to a
   sockaddr_shim structure with sins_ulid filled with SHIM_ANY_ANON.  A NULL hints
   argument indicates that any kind of endpoints are acceptable.

   The output argument res "res" is dynamically allocated by the resolver.
   The application must free frees res argument with the free_addrinfo function.
   The res argument contains a linked list of the resolved endpoints.
   The linked list contains sockaddr_shim sockaddr_hip structures only when the input argument has input
   argument has the AI_HIP flag set.  The resolver inserts HITs before
   any locators.

   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 policies of
   the host.

4.3.  Manual 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 AI_SHIM flag set.  When
   application binds the resolver
   finds SHIM identifiers, it inserts them socket to a local or peer locator with the front of
   setsockopt function with either SHIM_LOC_LOCAL_PREF or
   SHIM_LOC_PEER_PREF as the list.

   Resolving of a hostname may result socket option name as defined in multiple locators associated to
   [I-D.ietf-shim6-multihome-shim-api].  Third, the application creates
   a single ULID, but valid sockaddr_hip structure.  Finally, the application associates
   the sockaddr_shim socket also with the sockaddr_hip structure contains only a single
   ULID-locator pair. by calling some
   socket-related function, such as connect or bind.  The resolver handles function
   returns EINVALIDLOCATOR when the HIT is not reachable at the
   specified locator.

   It should be noticed that the application may just configure the HIT
   manually without setting the locator.  In this by repeating scenario, the ULD as
   many time as needed.  For example, let us consider a case where
   application relies on the
   resolver finds system to map the HIT to an ULID that is associated IP address.
   When the system fails to two locators.  In such a
   case, provide the resolver outputs two sockaddr_shim structures with mapping, it returns
   EADDRNOTAVAIL in the same
   ULID but different locators. called sockets API function to the application
   and sets errno to indicate the error.

5.  Summary of New Definitions

   Table 3 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          |
              | <netinet/hip.h> | HIP_IS_IPV6_ADDR_ORCHID   |
              | <netinet/hip.h> | HIP_IS_IPV6_ADDR_ANON_HIT |
              | <netinet/hip.h> | HIP_FLAG_ONLY_ORCHID      |
              | <netdb.h>       | AI_HIP                    |
              | <netdb.h>       | AI_PASSIVE_ANON           |
              | <netdb.h>       | AI_PASSIVE_PUB            |
              | <netdb.h>       | AI_HIP_NOLOCATORS         |
              | <netinet/hip.h> | hip_hit_t                 |
              | <netinet/in.h>  | sockaddr_hip              |
              +-----------------+---------------------------+

                                  Table 3

6.  IANA Considerations

   No IANA considerations.

6.

7.  Security Considerations

   To be done.

7.

   No security considerations currently.

8.  Acknowledgements

   Jukka Ylitalo and Pekka Nikander have contributed many ideas, time
   and effort to the native HIP API. 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 and Koponen, Jari Arkko, Ari Keraenen,
   Juha-Matti Tapio Tapio, Shinta Sugimoto, Philip Matthews, Jan Melen and
   Gonzalo Camarillo have also provided valuable ideas and or feedback.
   Thanks for the APPS area folks, Stephane Bortzmeyer, Chris Newman,
   Tony Finch, "der Mouse" and
   especially Keith Moore for comments.

8.

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]
              Komu, M., "IPsec Application Programming Interfaces",
              draft-ietf-btns-c-api-00
              draft-ietf-btns-c-api-01 (work in progress), June July 2007.

   [I-D.ietf-hip-dns]

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

   [I-D.ietf-shim6-multihome-shim-api]
              Komu, M., "Socket Application Program Interface (API) for
              Multihoming Shim", draft-ietf-shim6-multihome-shim-api-02 draft-ietf-shim6-multihome-shim-api-03
              (work in progress), July 2007.

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

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

   [RFC3493]  Gilligan, R., Thomson, S., Bound, J., McCann, J., and W.
              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 Address

   Miika Komu
   Helsinki Institute for Information Technology
   Tammasaarenkatu 3
   Metsaenneidonkuja 4
   Helsinki
   Finland

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

Full Copyright Statement

   Copyright (C) The IETF Trust (2007).

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

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

Intellectual Property

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

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

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

Acknowledgment

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