Host Identity Protocol                                           M. Komu
Internet-Draft                        Helsinki Institute for Information
Intended status: Standards Track Informational                                Technology
Expires: September January 8, 2007                                 March 2008                                    July 7, 2007

        Native Application Programming Interfaces for SHIM Layer Prococols
                      draft-ietf-hip-native-api-01 APIs
                      draft-ietf-hip-native-api-02

Status of this Memo

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

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

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

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

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

   This Internet-Draft will expire on September January 8, 2007. 2008.

Copyright Notice

   Copyright (C) The IETF Trust (2007).

Abstract

   This document proposes defines extensions to the current networking APIs for
   protocols based on identifier/locator split.  Currently, the document
   focuses on HIP, but the extensions can be used also by other
   protocols implementing identifier locator split.  Using the API
   extensions, new SHIM aware applications can gain a better control of
   the SHIM configure manually
   mappings between upper layer identifiers and endpoint identifiers.  For example, the
   applications can query and set SHIM related attributes, or specify
   their own endpoint identifiers for a host.  In addition, a new
   indirection element called endpoint descriptor corresponding
   locators.  Also, the API describes how to handle outbound connection
   establishment where an application is defined for SHIM
   aware applications that can be used for implementing opportunistic
   mode in a clean way. unaware of the peer identifier
   but knows the peer locator.

Table of Contents

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

   2.  Design Architecture  . . . . . . . . . . . .  Introduction . . . . . . . . .  4
     2.1.  Endpoint Descriptor . . . . . . . . . . . . . . . .  3

   3.  Design Model . . .  4
     2.2.  Layering Model . . . . . . . . . . . . . . . . . . . . . .  4
     2.3.  Namespace
     3.1.  Layering Model . . . . . . . . . . . . . . . . . . . . .  5
     2.4.  Socket Bindings  . . . . . . . . . . . . . . . .  4
     3.2.  Namespace Model  . . . . .  6

   3.  Interface Syntax and Description . . . . . . . . . . . . . . .  7
     3.1.  Data Structures .  4
     3.3.  Interaction with the Resolver  . . . . . . . . . . . . . .  5

   4.  API Syntax and Semantics . . . . . .  8
     3.2.  Functions . . . . . . . . . . . . .  6
     4.1.  Socket Family and Address Structure  . . . . . . . . . . . 10
       3.2.1.  6
     4.2.  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.  8

   5.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 15

   5. 10

   6.  Security Considerations  . . . . . . . . . . . . . . . . . . . 15

   6.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15 10

   7.  References . . .  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 15
     7.1. 10

   8.  Normative References . . . . . . . . . . . . . . . . . . . 15
     7.2.  Informative References . . . . . . . . . . . . . . . . . . 16 10

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

1.  Introduction

   The extensions defined in this draft can be used also by other
   protocols based on  Terminology

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

                                  Table 1

2.  Introduction

   Host Identity Protocol proposes a new cryptographic namespace and a
   new layer to the TCP/IP architecture.  Applications can see these new
   changes in the networking stacks with varying degrees of visibility.
   [I-D.henderson-hip-applications] discusses the lowest levels of
   visibility in which applications are either completely or partially unaware of HIP.  In this document, we discuss about  The HIP-
   unaware applications use LSIs or HITs instead of IPv4 or IPv6
   addresses.  Such applications may be unaware of the highest level locator bindings.

   This document discusses about visibility of visibility. HIP to HIP-aware
   applications.  The applications are completely HIP aware and can
   control the HIP layer and Host Identifiers.  This document defines
   C-based sockets API extensions for handling the bindings explicitly.
   The extensions expose the identity-locator split to SHIM-aware
   applications aquery and set security related attributes it is up to the application, or a higher level
   programming language, to manage the identities and even create their own Host
   Identifiers.

   Existing applications can be used with HIP as described in
   [I-D.henderson-hip-applications]. locators.

   The reason why HIP can be used in API extensions introduce a backwards compatible way lies in the identifiers.  A HIP enabled
   system can support the new socket address structure.  The
   structure requires a new address family, PF_SHIM, for sockets that
   use of LSIs, HITs and even IP addresses as
   upper layer identifiers to accomodate varying locators explicitly.  An application
   requirements.  However, these types of identifiers are not forwards
   compatible.  The length of HIT may turn out insecure can also use the
   family to detect SHIM support in the future.
   There local host.

   Hosts may be a need to change accept incoming or initiate outgoing communications without
   the HITs on knowledge of the fly to an already
   connected socket for dynamic session mobility.  Or, identity of the socket is
   going to be associated peer.  This document describes
   also how to multiple HITs for HIP address this situation using late binding based multicast.

   To support forwards compatibility, we introduce a new, generalized
   identifier called the endpoint descriptor (ED).  The ED acts as a
   handle to the actual identifier that separates application layer
   indentifiers from the lower layer identifiers.

   The ED can already now be used for implementing HIP opportunistic
   mode in a clean way.  The problem with implementing HIP opportunistic
   mode is on new
   wildcards.

   There are two related IETF documents that e.g. sockets are define other related
   API connect() call should be bound to a HIT extensions.  Multihoming related APIs are defined in order to use HIP, but the HIT is unknown until the reception the
   R1 packet.  At
   [I-D.ietf-shim6-multihome-shim-api].  IPsec related policy attributes
   and channel bindings are defined in [I-D.ietf-btns-c-api]

3.  Design Model

   In this point it is too late to change section, the binding e.g. native SHIM API design is described from a IP to HIT.  However, the ED has to property an
   design point of late binding view.  We describe the layering and therefore provides namespace model.
   We conclude the discussion with a cleaner way to implement description of the opportunistic
   mode. resolver model.

3.1.  Layering Model

   The ED socket address structure does not reveal application layer accesses the transport
   layerport number to layer via the socket
   interface.  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 layer uses the port number is irrelevant, traditional TCP/IP IPv4 or
   IPv6 interface, 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 native SHIM support in API interface provided by the localhost.  This
   is especially useful discover when SHIM aware applications are tried
   on a host that does not support SHIM.
   socket layer.  The ED concept layering model is similar to Local Scope Identifier
   [I-D.henderson-hip-applications] illustrated in Figure 1.  For
   simplicity, 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

   In this section, the native SHIM API design is described from an
   architectural point of view.  We introduce the ED concept, which is a
   central idea in the API.  We describe the layering and namespace
   models along with the socket bindings.  We conclude the discussion
   with a description of the endpoint identifier resolution mechanism.

2.1.  Endpoint Descriptor

   The representation of endpoints is hidden from the applications.  The
   ED is a ``handle'' to a HI.  A given ED serves as a pointer to the
   corresponding HI entry in the HI database of the host.  It should be
   noticed that the ED cannot be used as a referral that is passed from
   one host to another because it has only local significance.

2.2.  Layering Model

   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 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.

2.3.

3.2.  Namespace Model

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

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

              +-------------------+-------------------------+
              | Layer             | Identifier              |
               +-------------------+-----------------------+
              +-------------------+-------------------------+
              | User Interface    | FQDN                    |
              | Application Layer | ED, ULID, port and protocol |
              | Transport Layer   | HI, ULID, port              |
              | SHIM Layer        | HI ULID                    |
              | Network Layer     | IP address Locator                 |
               +-------------------+-----------------------+
              +-------------------+-------------------------+

                                  Table 1

   People prefer 2

   User interfaces input human-readable names when referring and translate them to network
   entities.  The most commonly used identifier in
   machine-readable names.  In SHIM API, the User Interface ULID is a HIT when the FQDN, but there are also other ways to name network entities.
   underlying protocol is HIP.  The FQDN format ULID is still the preferred UI level identifier in the
   context of the native SHIM API.

   In the current API, connection associations in present at the application
   layer
   are uniquely distinguished by the source IP address, destination IP
   address, source port, destination port, and protocol.  HIP changes
   this model by using HIT in the place of IP addresses.  The HIP model
   is further expanded in the native HIP API model by using ED instead
   of HITs.  Now, the application layer uses source ED, destination ED,
   source port, destination port, and transport protocol type, to
   distinguish between the different connection associations.

   Basically, the difference between the application and transport layer
   identifiers is that the also transport layer uses HIs instead of EDs.  The
   TLI checksum is named with source HI, destination HI, source port, and
   destination port at the transport layer.

   Correspondingly, the HIP layer uses HIs as identifiers.  The HIP
   security associations are calculated based on source HI and destination HI
   pairs.

   The network layer uses IP addresses, i.e., locators, for routing
   purposes. it.
   The network layer interacts with the HIP layer to exchange
   information about changes in the local interfaces addresses and peer
   addresses.

2.4.  Socket Bindings

   A HIP based SHIM socket is associated with one source and one
   destination ED, along with their port numbers and protocol type.  The
   relationship between a socket layer handles also ULIDs and ED is a many-to-one one.  Multiple
   EDs can be associated with a single HI.  Further, translates them locators for
   the source HI is
   associated with a set of network interfaces at the local host.  The
   destination HI, in turn, is associated layer.

3.3.  Interaction with a set of destination
   addresses of the peer.  The socket bindings are visualized in
   Figure 2.

                        1 +---------+ *  * +--------+ *  * +-----------+
                      +---+ Src EID +------+ Src HI +------+ Src Iface |
      +--------+ *    |   +---------+      +--------+      +-----------+
      |  HIP   +------+
      |        |
      | Socket +------+
      +--------+ *    |   +---------+      +--------+      +-----------+
                      +---+ Dst EID +------+ Dst HI +------+  Dst IP   |
                        1 +---------+ *  * +--------+ *  * +-----------+

                                 Figure 2

   The relationship between a source ED and a source HI is usually many-
   to-one one, but it can be also many-to-many on certain cases.  There
   are two refinements to the relationship.  First, a listening socket
   is allowed to accept connections from all local HIs of the host.
   Second, the opportunistic mode allows the base exchange to be
   initiated to Resolver

   Before an unknown destination HI.  In a way, the relationship
   between the local ED and local HI is a many-to-undefined relationship
   momentarily in both of the cases, but once the connection is
   established, the ED will be permanently associated with a certain HI.

   The DNS based endpoint discovery mechanism is illustrated in
   Figure 3.  The application calls the resolver (step a.) to resolve an
   FQDN (step b.).  The DNS server responds with a ED and a set of
   locators (step c.).  The resolver does not directly pass the ED and
   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 e.) and passes the ED to the application (step f.).

                                  +----------+
                                  |          |
                                  |   DNS    |
                                  |          |
                                  +----------+
                                      ^  |
                            b. <FQDN> |  | c. <EID, locator>
                                      |  v
       +-------------+ a. <FQDN>  +----------+
       |             |----------->|          |
       | Application |            | Resolver |
       |             |<-----------|          |
       +-------------+  f. <ED>   +----------+
                                      ^  |
                             e. <ED>  |  | d. <EID, locator>
                                      |  v
                                  +----------+
                                  |          |
                                  |   SHIM   |
                                  |          |
                                  +----------+

                                 Figure 3

   The application can also receive multiple EDs from the resolver when
   the FQDN is associated with multiple EIDs.  The endpoint discovery
   mechanism is still almost the same.  The difference is that the DNS
   returns a set of EIDs (along with the associated locators) to the
   resolver.  The resolver sends all of them to the SHIM module and
   receives a set of EDs in return, each ED corresponding to a single
   HI.  Finally, the EDs are sent to the application.

3.  Interface Syntax and Description

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

3.1.  Data Structures

   We introduce a new protocol family, PF_SHIM, for the sockets API.
   The AF_SHIM constant is an alias for it.  The use of the PF_SHIM
   constant is mandatory with the socket function if the native SHIM API
   is to be used in the application.  The PF_SHIM constant is given as
   the first argument (domain) to the socket function.

   The ED abstraction is realized in the sockaddr_ed structure, which is
   shown in Figure 4.  The family of the socket, ed_family, is set to
   PF_SHIM.  The port number ed_port is two octets and the ED value
   ed_val is four octets.  The ED value is just an opaque number to the
   application.  The application should not try to associate it directly
   to a EID or even compare it to other ED values, because there are
   separate functions for those purposes.  The ED family is stored in
   host byte order.  The ED value is stored in network byte order.  It
   should be noticed that the port number is not present in the socket
   address structure, but it can be queried with the functions in
   section Section 3.2.2.

         struct sockaddr_ed {
                 unsigned short int ed_family;
                 sa_ed_t ed_val;
         }

                                 Figure 4

   The ed_val field is usually set by special native SHIM API functions,
   which are described in the following section.  However, three special
   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.
   They denote an ED value associated with a wildcard HI of any, public,
   or anonymous type.  They are useful to a ``server'' application that
   is willing to accept connections to all of the HIs of the host.  The
   macros correspond to the sockets API macros INADDR_ANY and
   IN6ADDR_ANY_INIT, but they are applicable on the SHIM layer.  It
   should be noted that only one process at a time can bind with the
   SHIM_ED_*ANY macro on a certain port to avoid ambiguous bindings.

   The native SHIM API has a new resolver function which is used for
   querying both endpoint identifiers and locators.  The resolver
   introduces a new data structure, which is used both as the input and
   output argument for the resolver.  We reuse the existing resolver
   datastructure shown in Figure 5.

          struct addrinfo {
              int    ai_flags;          /* e.g. AI_ED */
              int    ai_family;         /* e.g. PF_SHIM */
              int    ai_socktype;       /* e.g. SOCK_STREAM */
              int    ai_protocol;       /* usually just zero */
              size_t ai_addrlen;        /* length of the endpoint */
              struct sockaddr *ai_addr; /* endpoint socket address */
              char   *ai_canonname;     /* canon. name of the host */
              struct addrinfo *ai_next; /* next endpoint */
          };

                                 Figure 5

   In addrinfo structures, the family field is set to PF_SHIM when the
   socket address structure contains an ED that refers to a SHIM
   identifier, such as HI.

   The flags in the addrinfo structure control the behavior of the
   resolver and describe the attributes of the endpoints and locators:

   o  The flag AI_ED must be set, or otherwise the resolver does not
      return EDs to guarantee that legacy applications won't break.
      When AI_ED is set, the resolver returns a linked list which
      contains first the sockaddr_ed structures for SHIM identifiers if
      any was found.  After that, any other type of socket addresses are
      returned except that HITs in sockaddr_in6 format are excluded
      because they were already included in the returned sockaddr_ed
      structures.

   o  When querying local identifiers, the AI_ED_ANON flag forces the
      resolver to query only local anonymous identifiers.  The default
      action is first to resolve the public endpoints and then the
      anonymous endpoints.

   o  Some applications may prefer configuring the locators manually and
      can set the AI_ED_NOLOCATORS flag to prohibit the resolver from
      resolving any locators.

   o  The AI_ED_ANY, AI_ED_ANY_PUB and AI_ED_ANY_ANON flags cause the
      resolver to output only a single socket address containing an ED
      that would be received using the corresponding SHIM_ED_*ANY macro.
      When these flags are used for resolving local addresses, they
      allow wildcard late binding to certain types of local idenfiers.
      When the flags are used for peer resolving, they allow to contact
      the peer using opportunistic mode.

   o  The getaddrinfo resolver does not return IP addresses belonging to
      a SHIM rendezvous server unless AI_ED is defined.  AI_ED_RVS, can
      appear both in the input and output arguments of the resolver.  In
      the input, it can be used for resolving only rendezvous server
      addresses.  On the output, it denotes that the address is a
      rendezvous rather than end-point address.

   Application specified endpoint identifiers are essentially private
   keys.  To support application specified identifiers in the API, we
   introduce new data structures for storing the private keys.  The
   private keys need an uniform format so that they can be easily used
   in the API calls.  The keys are stored in the endpoint structures as
   shown in Figure 6.

         struct endpoint {
                 se_length_t   length;
                 se_family_t   family;
         };
         struct endpoint_hip {
                 se_length_t length;
                 se_family_t family; /* EF_HI in the case of HIP */
                 se_hip_flags_t flags;
                 union {
                         struct hip_host_id host_id;
                         hit_t hit;
                 } id;
         };

                                 Figure 6

   The endpoint structure represents a generic endpoint and the
   endpoint_hip structure represents establish network communications, it must
   translate a HIP specific endpoint.  The
   family field distinguishes whether hostname to the identifier is HIP or other
   protocol related.  The HIP endpoint is public by default unless
   SHIM_ENDPOINT_FLAG_ANON flag corresponding identifier(s).  DNS based
   hostname-to-identifier translation is set illustrated in Figure 2.  The
   application calls the structure resolver (step a.) to anonymize the
   endpoint. resolve an FQDN (step
   b.).  The id union contains the HI in the host_id member in DNS server responds with ULIDs and a set of locators (step
   c.).  The resolver may not directly pass the
   format specified in [I-D.ietf-hip-base].  If ULIDs and the key is private, locators
   to the
   material is appended application, but may first inform to the host_id with SHIM module (steps d.
   and e.).  Finally, the length adjusted
   accordingly.  The flag SHIM_ENDPOINT_FLAG_PRIVATE is also set.  The
   hit member of resolver passes the union is used only when ULIDs and locators to the SHIM_ENDPOINT_FLAG_HIT
   flag is set.

3.2.  Functions
   application (step f.).

                                  +----------+
                                  |          |
                                  |   DNS    |
                                  |          |
                                  +----------+
                                      ^  |
                            b. <FQDN> |  | c. <ULIDs + locators = U+L>
                                      |  v
       +-------------+ a. <FQDN>  +----------+
       |             |----------->|          |
       | Application |            | Resolver |
       |             |<-----------|          |
       +-------------+  f. <U+L>  +----------+
                                      ^  |
                                      |  |
                             e. <U+L> |  | d. <U+L>
                                      |  v
                                  +----------+
                                  |          |
                                  |   SHIM   |
                                  |          |
                                  +----------+

                                 Figure 2

   In this section, some practise, the resolver functionality can implemented in different
   ways.  It may be implemented in existing sockets resolver libraries or as an
   DNS proxy.

4.  API functions are reintroduced
   along with their additions.  Also, some new auxiliary functions are
   defined.

3.2.1.  Resolver Interface

   The Syntax and Semantics

   In this section, we describe the native SHIM API does not introduce changes to using the interface syntax of
   the primitive sockets API functions bind, connect, send,
   sendto, sendmsg, recv, recvfrom, C programming language and recvmsg.  However, the
   application usually calls present only the functions with sockaddr_ed ``external''
   interfaces and data structures
   instead of sockaddr_in or sockaddr_in6 structures.  The source of that are visible to the applications.
   We limit the
   sockaddr_ed description to those interfaces and data structures in that
   are either modified or completely new, because the native SHIM API is
   otherwise identical to the resolver
   function getaddrinfo [RFC3493] which is shown in Figure 7.

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

                                 Figure 7

   The getaddrinfo function takes the nodename, servname, sockets API [POSIX].

4.1.  Socket Family and hints as
   its input arguments.  It places the result of the query into Address Structure

   We introduce a new protocol family, PF_SHIM, for the res
   argument. sockets API.
   The return value AF_SHIM constant is zero on success, or a non-zero error
   value on error. an alias for it.  The nodename argument specifies use of the host name to be
   resolved; a NULL argument denotes PF_SHIM
   constant is mandatory with the local host.  The servname
   parameter sets socket() function if the port number SHIM API is
   to be set in the socket addresses used in the res output argument.  Both the nodename and servname cannot be
   NULL. application.  The output argument res PF_SHIM constant is dynamically allocated by given as the resolver.
   The application must free res
   first argument with (domain) to the free_addrinfo socket() function.

   The res argument contains a linked list of the resolved
   endpoints.  The input argument hints acts like a filter that defines
   the attributes required from the resolved endpoints.  For example,
   setting the flag SHIM_ENDPOINT_FLAG_ANON in the hints forces the
   resolver to return only anonymous endpoints in the output argument
   res.  A NULL hints argument indicates that any kind of endpoints are
   acceptable.

3.2.2.  Application Specified Identities

   Application specified local ULIDs and peer endpoints can be retrieved from
   files using locators are contained in the function sockaddr_shim structure,
   which is shown in Figure 8.  The function
   shim_endpoint_load_pem is used for retrieving a private or public key
   from a given file filename.  The file must be in PEM encoded format. 3.  The result family of the socket, shim_family,
   is allocated dynamically set to PF_SHIM.  The port number sins_port is two octets and stored into the endpoint
   argument.
   sins_ulid is four octets.  The return ULID value of the function is zero on success, an IPv6 address.  The
   locator is an IPv6 address or a
   non-zero error value on failure. IPv6-mapped address IPv4 address as
   defined in - [RFC3493].  The result family is deallocated with the
   free system call.

           int shim_endpoint_pem_load(const char *filename,
                                      struct endpoint **endpoint)

                                 Figure 8

   Alternatively, the application can load stored in host byte order and
   the image directly from
   memory as shown ULID and locator are stored in Figure 9

           int shim_endpoint_pem_load_str(const char *pem_str, network byte order.

         typedef struct endpoint **endpoint); in6_addr shim_ulid_t;
         typedef struct in6_addr shim_locator_t;

         struct sockaddr_shim {
                 uint8_t        sins_len;
                 uint8_t        sins_family;
                 uint16_t       sins_port;
                 shim_ulid_t    sins_ulid;
                 shim_locator_t sins_locator;
                 uint64_t       sins_flags;
         }

                                 Figure 9 3

   The endpoint structure cannot application usually sets the sins_ulid field using the resolver.
   However, three special macros can be used to directly in set a value
   into the sockets API
   function calls. sins_ulid field.  The application must convert the endpoint into an ED
   first.  Local endpoints macros are converted with the getlocaled function SHIM_ANY, SHIM_ANY_PUB and peer endpoints
   SHIM_ANY_ANON.  They denote an ULID value associated with getpeered function. a wildcard
   ULID of any, public, or anonymous type.

   In server applications, the SHIM_* macros accept incoming connections
   to all of the ULID of the local host.  The functions macros correspond to the
   sockets API macros INADDR_ANY and IN6ADDR_ANY_INIT, but they are
   illustrated
   applicable at the SHIM layer.  It should be noticed that only one
   process at a time in Figure 10.

        struct sockaddr_ed *getlocaled(const struct endpoint *endpoint,
                                      const char *servname,
                                      const struct addrinfo *addrs,
                                      const struct if_nameindex *ifaces,
                                      int flags)
        struct sockaddr_ed *getpeered(const struct endpoint *endpoint,
                                      const char *servname,
                                      const struct addrinfo *addrs,
                                      int flags)

                                 Figure 10

   The result a host can bind with the SHIM_*ANY macro to the
   same port to avoid ambiguous bindings.

   A client application can use the SHIM_ANY macro to establish a
   connection when only the server locator (and not the ULID) is known
   beforehand.

   In both client and server based applications, the use of the conversion, an ED socket address, is returned by
   both
   SHIM_ANY* macro accepts also non-SHIM based communications to
   maximize backwards compatibility.  When the application wants
   enforces the use of SHIM-based communications with ORCHID prefix
   [RFC4843], it sets the functions.  A failure flag SHIM_FLAG_ONLY_ORCHID in sins_flags.
   Alternatively, the conversion causes a NULL
   return value to be returned application accepts both ORCHID and non-ORCHID-
   based communications, but informs the errno difference e.g. to be set accordingly.  The
   caller of the functions is responsible of freeing user.
   In this case, the returned socket
   address structure.

   The application calls SHIM_IPV6_ADDR_IS_ORCHID macro
   which inputs a pointer to a in6_addr and returns 1 when the address
   has orchid prefix and 0 otherwise.

   Applications can retrieve also implement access control using the endpoint argument e.g. with ULIDs.  In
   such a case, the
   shim_endpoint_load_pem application can compare two ULIDs using memcmp() or
   similar function.  If

4.2.  Resolver

   The SHIM API uses the endpoint is NULL, getaddrinfo resolver function which the system
   selects an arbitrary EID
   application uses to query both ULIDs and associates it with locators.  The resolver
   introduces a new data structure, which is used both as the ED value of input and
   output argument for the
   return value. resolver.  The servname argument data structure is illustrated
   in Figure 4.

          struct addrinfo {
              int    ai_flags;          /* e.g. AI_SHIM */
              int    ai_family;         /* e.g. PF_SHIM */
              int    ai_socktype;       /* e.g. SOCK_STREAM */
              int    ai_protocol;       /* 0 or IPPROTO_HIP */
              size_t ai_addrlen;        /* length of the service string.  The function converts
   it to a numeric port number and fills endpoint */
              struct sockaddr *ai_addr; /* socket address */
              char   *ai_canonname;     /* canon. name of the port number into host */
              struct addrinfo *ai_next; /* next endpoint */
          };

                                 Figure 4

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

   The flag AI_SHIM must be set, or otherwise the convenience of resolver does not
   return sockaddr_shim data structures to guarantee that legacy
   applications do not break.  Some applications may prefer configuring
   the application.

   The addrs argument defines locators manually and can set the initial IP addresses of AI_SHIM_NOLOCATORS flag to
   prohibit the local host
   or peer host. getaddrinfo from resolving any locators.

   The argument ai_family field is a pointer to a linked list of PF_SHIM with SHIM-specific addrinfo
   structures containing the initial addresses of the peer. data
   structures.

   The list
   pointer can be obtained with a getaddrinfo [RFC3493] function call.
   A NULL pointer indicates that protocol field is 0 when the application trusts getaddrinfo caller does not care
   about the host specific SHIM protocol to
   already know the locators of be used.  The caller (or the peer.  We recommend that a NULL
   pointer is not given
   resolver) can set this field also to IPPROTO_HIP.

   ai_addrlen is the getpeered function to ensure reachability
   with size of the peer. structure pointed by ai_addr.

   The getlocaled function accepts also ai_addr points to a list of network interface
   indexes in sockaddr_shim structure when the ifaces argument. value of
   ai_family is PF_SHIM.  The list can be obtained with the
   if_nameindex [RFC3493] function call.  A NULL list pointer indicates
   all the interfaces resolver sets SHIM_RVS in sins_flags of
   the local host.  Both when the IP addresses and
   interfaces can be combined locator belongs to select a specific address from a
   specific interface.

   The last argument is the flags. rendezvous server
   [I-D.ietf-hip-dns].

   The following flags are valid only
   for the getlocaled function:

   o  Flags SHIM_ED_REUSE_UID, SHIM_ED_REUSE_GID and SHIM_ED_REUSE_ANY
      allow the EID (e.g. a large private key) SHIM API does not introduce changes to be reused for
      processes with the same UID, GID or any UID as the calling
      process.

   o  Flags SHIM_ED_IPV4 and SHIM_ED_IPV6 can be used for limiting the
      address family scope interface syntax of
   the local interface.

   It should noticed that the SHIM_ED_ANY, SHIM_ED_ANY_PUB and
   SHIM_ED_ANY_ANON macros can be implemented existing sockets API functions, such as calls to bind(), connect(),
   send(), sendto(), sendmsg(), recv(), recvfrom(), and recvmsg().
   However, the getlocaled
   call with SHIM-aware application usually passes the functions a NULL endpoint, NULL interface, NULL address argument and
   sockaddr_shim structure instead of a sockaddr_in or sockaddr_in6
   structure.  A SHIM-aware application either creates the flag corresponding to sockaddr_shim
   structures manually or obtains them from the macro name set.

3.2.3.  Querying Endpoint Related Information resolver.  The getlocaled and getpeered functions have also their reverse
   counterparts.  Given an ED,
   getaddrinfo resolver [RFC3493] is shown in Figure 5.

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

                                 Figure 5

   As described in [RFC3493], the getlocaledinfo and getpeeredinfo
   functions search for getaddrinfo function takes the EID (e.g. a HI)
   nodename, servname, and hints as its input arguments.  It places the current set
   result of
   locators associated with the ED. query into the res argument.  The first argument return value is zero
   on success, or a non-zero error value on error.  The nodename
   argument specifies the ED host name to be
   searched for.  The functions write the results of resolved; a NULL argument
   denotes the search, local host.  The servname parameter declares the
   transport layer port
   number of the occupied by the correponding HIT,
   the HIs and locators, to the rest of the function arguments.  The
   function interfaces are depicted be set in Figure 11.  The caller of the
   functions is responsible for freeing socket addresses in the memory reserved for res output argument.
   Both the
   search results.

           int getlocaledinfo(const struct sockaddr_ed *my_ed,
                              struct in_port_t **port
                              struct endpoint **endpoint,
                              struct addrinfo **addrs,
                              struct if_nameindex **ifaces)
           int getpeeredinfo(const struct sockaddr_ed *peer_ed,
                             struct in_port_t **port
                             struct endpoint **endpoint,
                             struct addrinfo **addrs)

                                 Figure 11

   The getlocaledinfo nodename and getpeeredinfo functions are especially useful
   for an advanced application servname cannot be NULL.

   The input argument hints acts like a filter that receives multiple EDs from defines the
   resolver.  The advanced application can query
   attributes required from the properties of resolved endpoints.  For example, the
   EDs using getlocaledinfo and getpeeredinfo functions and select
   resolver returns only anonymous endpoints in the
   ED that matches output argument res
   when the desired properties.

3.2.4.  HIP Related Policy Attributes

   Multihoming related attributes are defined in
   [I-D.ietf-shim6-multihome-shim-api].  It also specifies an event
   driven API for application, which can be used for listening for
   changes in locators.

   HIP related policy attributes are accessed using application sets the definitions in
   [I-D.komu-btns-api]

   Some ai_addr pointer of hints to point to a
   sockaddr_shim structure with sins_ulid filled with SHIM_ANY_ANON.  A
   NULL hints argument indicates that any kind of endpoints are
   acceptable.

   The output argument res is dynamically allocated by the policy attributes resolver.
   The application must be set before free res argument with the hosts have
   established connection. free_addrinfo
   function.  The implementation may refuse to accept res argument contains a linked list of the
   option resolved
   endpoints.  The linked list contains sockaddr_shim structures only
   when there is already an existing connection and dynamic
   renegotiation of the option is not possible.  In addition, input argument has the SHIM
   may return an error value if AI_SHIM flag set.  When the corresponding resolver
   finds SHIM protocol does not
   support identifiers, it inserts them to the given option.

   Table 2shows HIP related policy attributes that are accessed with front of the
   APIs defined in [I-D.komu-btns-api].

   +---------------------+---------------------------------------------+
   | Attribute           | Purpose                                     |
   +---------------------+---------------------------------------------+
   | IPSEC_ESP_TRANSFORM | Preferred ESP transform                     |
   | IPSEC_SA_LIFETIME   | Preferred IPsec SA lifetime list.

   Resolving of a hostname may result in seconds      |
   | SHIM_PROTOCOL       | Get or set current SHIM protocol. Currently |
   |                     | multiple locators associated to
   a single ULID, but the sockaddr_shim structure contains only PF_HIP is defined.                     |
   | SHIM_CHALLENGE_SIZE | Puzzle challenge size                       |
   | SHIM_SHIM_TRANSFORM | Preferred SHIM transform                    |
   | SHIM_DH_GROUP_IDS   | The preferred Diffie-Hellman Group          |
   | SHIM_AF_FAMILY      | The preferred locator family. a single
   ULID-locator pair.  The default   |
   |                     | family resolver handles this by repeating the ULD as
   many time as needed.  For example, let us consider a case where the
   resolver finds an ULID that is AF_ANY.                           |
   | SHIM_FAST_FALLBACK  | If set associated to one, use two locators.  In such a
   case, the extensions in        |
   |                     | [I-D.lindqvist-hip-opportunistic]           |
   | SHIM_FAST_HANDSHAKE | If set to one, use resolver outputs two sockaddr_shim structures with the extensions in        |
   |                     | [I-D.lindqvist-hip-tcp-piggybacking]        |
   +---------------------+---------------------------------------------+

                                  Table 2

4. same
   ULID but different locators.

5.  IANA Considerations

   No IANA considerations.

5.

6.  Security Considerations

   To be done.

6.

7.  Acknowledgements

   Jukka Ylitalo and Pekka Nikander have contributed many ideas, time
   and effort to the native HIP API.  Thomas Henderson, Kristian Slavov, Julien
   Laganier, Jaakko Kangasharju, Mika Kousa, Jan Melen, Andrew McGregor,
   Sasu Tarkoma, Lars Eggert, Joe Touch, Antti Jaervinen, Anthony
   Joseph, Teemu Koponen and Juha-Matti Tapio have also provided
   valuable ideas and feedback.

7.  References

7.1.  Thanks for the APPS area folks,
   Stephane Bortzmeyer, Chris Newman, Tony Finch, "der Mouse" and
   especially Keith Moore for comments.

8.  Normative References

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

   [I-D.ietf-hip-base]
              Moskowitz, R.,

   [I-D.ietf-btns-c-api]
              Komu, M., "IPsec Application Programming Interfaces",
              draft-ietf-btns-c-api-00 (work in progress), June 2007.

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

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

   [I-D.komu-btns-api]
              Komu, M., "IPsec Application Programming Interfaces",
              draft-komu-btns-api-00 draft-ietf-shim6-multihome-shim-api-02
              (work in progress), October 2006. March 2007.

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

   [RFC3493]  Gilligan, R., Thomson, S., Bound, J., McCann, J., and W.

              Stevens, "Basic Socket Interface Extensions for IPv6",
              RFC 3493, February 2003.

7.2.  Informative References

   [I-D.lindqvist-hip-opportunistic]
              Lindqvist, J., "Establishing Host Identity Protocol
              Opportunistic Mode with TCP Option",
              draft-lindqvist-hip-opportunistic-01 (work in progress),
              March 2006.

   [I-D.lindqvist-hip-tcp-piggybacking]
              Lindqvist,

   [RFC4843]  Nikander, P., Laganier, J., "Piggybacking TCP to Host Identity
              Protocol", draft-lindqvist-hip-tcp-piggybacking-00 (work
              in progress), July 2006. and F. Dupont, "An IPv6 Prefix
              for Overlay Routable Cryptographic Hash Identifiers
              (ORCHID)", RFC 4843, April 2007.

Author's Address

   Miika Komu
   Helsinki Institute for Information Technology
   Tammasaarenkatu 3
   Helsinki
   Finland

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

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).