Subject: Re: [Hipsec] Re: API draft

From: Ari Keränen <[email-masked]>
Date: Thu, 01 Nov 2007 13:21:25 +0200

Hi Miika,

It was a bit unclear to me from the latest revision of the draft 
(03-pre3) how the application can now create a HIT to locator mapping in 
case they are found by some other means than DNS. Is the idea now to use 
shim6-multihome-shim-api-03 draft's setsockopt with SHIM_LOC_PEER_PREF 
or similar? I guess that's in line with the discussion we had earlier 
but I'd rather see it stated more explicitly.

Then some minor issues and nits (they are in the order as they appear in 
the draft):

The wrong definition of Locator is still in the Table 1 (now it's 
defined twice).

The draft text and the Figure 3 aren't consistent. In the text (before 
the figure) you have "hip_family", "sins_port" and "sins_hit", while in 
the Figure 3 they are apparently called "ship_family", "ship_port" and 
"ship_hit".

Is the definition of "hip_locator_t" in the Figure 3 needed anymore? If 
it is, perhaps it should be in the summary table (Table 3) too.

"The application can HIP_HIT_ "
s/can/can use the/

"The ai_family field is set to AF_HIP the addrinfo structure when"
s/AF_HIP the/AF_HIP in the/
Also, in the comments of the struct it says that the value could be 
e.g., PF_HIP. It might be better to use either AF or PF consistently.

-Ari

Miika Komu wrote:
> the feedback for the draft is here:
> 
> http://www1.ietf.org/mail-archive/web/hipsec/current/msg02250.html
> http://www1.ietf.org/mail-archive/web/hipsec/current/msg02230.html
> http://www1.ietf.org/mail-archive/web/hipsec/current/msg02224.html
> 
> I believe that I have addressed all of the comments in the next 
> preversion of the draft:
> 
> http://www.iki.fi/miika/docs/draft-ietf-hip-native-api-03-pre3.txt
> 
> A quick summary of the changes:
> 
> * The locator was removed from the HIT data structure
> * Replaced SHIM generalization with just "HIP"
> * Dependencies to SHIM6 removed and/or referenced better now
> * AI_PASSIVE clafications; added AI_PASSIVE_PUB and AI_PASSIVE_ANON * 
> Added HIP_IS_IPV6_ADDR_ANON_HIT macro
> * Comments on hostname mapping to multiple HITs
> * Comments on HIT mapping to multiple locators
> * Rewording and hopefully better explanations
> 
> Thanks for the reviewers and looking forward for further comments.
> 

_______________________________________________
Hipsec mailing list
[email-masked]
https://www1.ietf.org/mailman/listinfo/hipsec

---

From: Miika Komu <[email-masked]>
Date: Sat, 10 Nov 2007 00:18:40 +0200 (EET)

On Thu, 1 Nov 2007, Ari Keränen wrote:

Ari, appreciate your comments. Some comments below.

> Hi Miika,
>
> It was a bit unclear to me from the latest revision of the draft (03-pre3) 
> how the application can now create a HIT to locator mapping in case they are 
> found by some other means than DNS. Is the idea now to use 
> shim6-multihome-shim-api-03 draft's setsockopt with SHIM_LOC_PEER_PREF or 
> similar? I guess that's in line with the discussion we had earlier but I'd 
> rather see it stated more explicitly.

When the application implements its own locator policies, it can control 
the locators bindings with SHIM_LOC_PEER_PREF socket option as defined in 
[I-D.ietf-shim6-multihome-shim-api].

> Then some minor issues and nits (they are in the order as they appear in the 
> draft):
>
> The wrong definition of Locator is still in the Table 1 (now it's defined 
> twice).

Now it is:

    | Locator | Routable IPv4 or IPv6 address used at the lower layers  |
>
> The draft text and the Figure 3 aren't consistent. In the text (before the 
> figure) you have "hip_family", "sins_port" and "sins_hit", while in the 
> Figure 3 they are apparently called "ship_family", "ship_port" and 
> "ship_hit".

Fixed.

> Is the definition of "hip_locator_t" in the Figure 3 needed anymore? If it 
> is, perhaps it should be in the summary table (Table 3) too.
>
> Also, in the comments of the struct it says that the value could be e.g., 
> PF_HIP. It might be better to use either AF or PF consistently.

Fixed.

The next preversion of the draft is here:

http://www.iki.fi/miika/docs/draft-ietf-hip-native-api-03-pre4.txt

-- 
Miika Komu                                       http://www.iki.fi/miika/

---

From: Shinta Sugimoto <[email-masked]>
Date: Sat, 10 Nov 2007 14:51:09 +0900

Hi Miika,

Thank you for updating the draft.  I checked it and I am basically fine with
the content of the draft.  There are some minor comments (mostly editorial).
Please find them inline:

> Host Identity Protocol                                           M. Komu
> Internet-Draft                        Helsinki Institute for Information
> Intended status: Informational                                Technology
> Expires: May 1, 2008                                    October 29, 2007
> 
> 
>    Native Application Programming Interfaces (APIs) for Host Identity
>                              Protocol (HIP)
>                       draft-ietf-hip-native-api-03
> 

(snip)

> Abstract
> 
>    This document defines extensions to the current sockets API for Host
>    Identity Protocol (HIP).  The extensions focus on the initial
>    discovery of public-key based identifiers.  Using the extensions, the
>    application can verify that the identifier is a Host Identity Tag
> 
> 
> 
> Komu                       Expires May 1, 2008                  [Page 1]
> 
> Internet-Draft             Native APIs for HIP              October 2007
> 
> 
>    (HIT) and it can require the system resolver to return only HITs from
>    DNS.  The application can also to explicitly allow 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 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 Model . . . . . . . . . . . . . . . . . . . . . .  4
>      3.2.  Namespace Model  . . . . . . . . . . . . . . . . . . . . .  5
>      3.3.  Interaction with the Resolver  . . . . . . . . . . . . . .  5
> 
>    4.  API Syntax and Semantics . . . . . . . . . . . . . . . . . . .  6
>      4.1.  Socket Family and Address Structure Extensions . . . . . .  7
>      4.2.  Resolver Extensions  . . . . . . . . . . . . . . . . . . .  8
> 
>    5.  Summary of New Definitions . . . . . . . . . . . . . . . . . . 10
> 
>    6.  IANA Considerations  . . . . . . . . . . . . . . . . . . . . . 11
> 
>    7.  Security Considerations  . . . . . . . . . . . . . . . . . . . 11
> 
>    8.  Acknowledgements . . . . . . . . . . . . . . . . . . . . . . . 11
> 
>    9.  Normative References . . . . . . . . . . . . . . . . . . . . . 12
> 
>    Author's Address . . . . . . . . . . . . . . . . . . . . . . . . . 12
>    Intellectual Property and Copyright Statements . . . . . . . . . . 14
> 

(snip)

> 
> Komu                       Expires May 1, 2008                  [Page 2]
> 
> Internet-Draft             Native APIs for HIP              October 2007
> 
> 
> 1.  Terminology
> 
>    The terms used in this document are summarized in Table 1.
> 
>    +---------+---------------------------------------------------------+
>    | Term    | Explanation                                             |
>    +---------+---------------------------------------------------------+
>    | HIP     | Host Identity Protocol                                  |
>    | Locator | Non-routable IPv4 or IPv6 address used at the lower     |
>    |         | layers                                                  |

s/Non-routable/Routable/

>    | FQDN    | Fully Qualified Domain Name                             |

I guess abbreviation of FQDN is widely known.

>    | HIT     | Host Identity Tag, a 100-bit hash 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 or IPv6 address                           |
>    +---------+---------------------------------------------------------+

definition of "Locator" is given twice in the table.

> 
>                                   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 "SHIM" layer to the
>    TCP/IP stack.  SHIM6 [I-D.ietf-shim6-proto] is another protocol based
>    on identity-locator split.  The API specified in this document is
>    specific to HIP but it has been designed keeping generality in mind
>    as much as possible so as not to preclude compatibility with other
>    protocols.  The use of this API in the context 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] discusses the lowest levels of
>    visibility in which applications are completely unaware of underlying
>    the 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 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 to the initial discovery of the
>    identifiers, i.e., DNS resolution step.
> 
> 
> 
> 
> Komu                       Expires May 1, 2008                  [Page 3]
> 
> Internet-Draft             Native APIs for HIP              October 2007
> 
> 
>    The API extensions introduce a new address family, AF_HIP, and a new
>    socket address structure for sockets using Host Identity Tags (HITs)
>    explicitly.  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.
> 
>    Some applications may accept incoming communications from any
>    identifier.  Other applications may initiate outgoing communications
>    without 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
>    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.  First goal
>    is to allow HIP-aware applications to resolve HITs explicitly.
>    Second goal is to allow an application to explicitly accept
>    communications with an unknown peer identifier.
> 
> 
> 3.  Design Model
> 
>    In this section, the native HIP APIs design is described from a
>    design point of view.  We describe the layering and namespace models.
>    We 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 HIP APIs 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.
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> 
> Komu                       Expires May 1, 2008                  [Page 4]
> 
> Internet-Draft             Native APIs for HIP              October 2007
> 
> 
>                          +--------------------------------+
>       Application Layer  |           Application          |
>                          +----------+----------+----------+
>            Socket Layer  | IPv4 API | IPv6 API |  HIP API |
>                          +----------+----+-----+----------+
>         Transport Layer  |      TCP      |      UDP       |
>                          +---------------+----------------+
>                HIP Layer |              HIP               |
>                          +---------------+----------------+
>           Network Layer  |     IPv4      |     IPv6       |
>                          +---------------+----------------+
>              Link Layer  |   Ethernet    |     Etc        |
>                          +---------------+----------------+
> 
>                                  Figure 1
> 
>    The HIP layer is as a shim/wedge layer between the transport and
>    network layers.  The datagrams delivered between the transport and
>    network layers are intercepted by the HIP layer for transformation
>    from from identifiers to locators or vice versa.
> 
> 3.2.  Namespace Model
> 
>    The namespace model is shown in Table 2 from HIP point of view.  The
>    namespace identifiers are described in this section.
> 
>              +-------------------+---------------------------+
>              | Layer             | Identifier                |
>              +-------------------+---------------------------+
>              | User Interface    | Relative hostname or FQDN |
>              | Application Layer | HIT, port and protocol    |
>              | Transport Layer   | HIT, port                 |
>              | HIP Layer         | HIT or HI                 |
>              | 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 at the application layer, and
>    transport-layer pseudo checksums are based on HITs.  The HIP layer
>    transforms the HITs to locators for the network layer and vice versa.
> 
> 3.3.  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
> 
> 
> 
> Komu                       Expires May 1, 2008                  [Page 5]
> 
> Internet-Draft             Native APIs for HIP              October 2007
> 
> 
>    must translate the name into the corresponding identifier(s).  DNS
>    based hostname-to-identifier translation is illustrated in Figure 2.
>    The application calls the resolver (step a.) to resolve an FQDN (step
>    b.).  The DNS server responds with a list of HITs and a set of
>    locators (step c.).  Optionally (in step 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.
> 
>                                             +----------+
>                                             |          |
>                                             |   DNS    |
>                                             |          |
>                                             +----------+
>                                                 ^  |
>                                       b. <FQDN> |  | c. <HITs + locators
>                                                 |  v      = HITs+locs>
>      +-------------+ a. getaddrinfo(<FQDN>)  +----------+
>      |             |------------------------>|          |
>      | Application |                         | Resolver |
>      |             |<------------------------|          |
>      +-------------+        e. <HITs>        +----------+
>              |                                    |
>              |                                    |
>              | f. connect(<HIT>)                  | d. <HITs+locs>
>              v                                    v
>       +----------+                           +----------+
>       |          |                           |          |
>       |  Stack   |                           |   HIP    |
>       |          |                           |          |
>       +----------+                           +----------+

s/Stack/TCP\/IP Stack/

> 
>                                  Figure 2
> 
>    In practice, the resolver functionality can implemented in different

s/can/can be/

>    ways.  For example, it may be implemented in existing resolver
>    libraries or as a DNS proxy.
> 
> 
> 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 is otherwise identical to the

s/is/are/

>    sockets API [POSIX].

when you refer to "API" in the document, I think singular form is more
suitable.

> 
> 
> 
> 
> 
> Komu                       Expires May 1, 2008                  [Page 6]
> 
> Internet-Draft             Native APIs for HIP              October 2007
> 
> 
> 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 application can also use the new AF_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
>    AF_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 3.  The family of the socket, hip_family, is set to PF_HIP.
>    The port number sins_port is two octets and the sins_hit is four
>    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;
>          typedef struct in6_addr hip_locator_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 3
> 
>    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 and HIP_HIT_ANY_ANON.  They denote a HIT
>    value associated with a wildcard HIT of any, public, or anonymous
>    type.  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 application can use macro HIP_IS_IPV6_ADDR_ANON_HIT to verify
> 
> 
> 
> Komu                       Expires May 1, 2008                  [Page 7]
> 
> Internet-Draft             Native APIs for HIP              October 2007
> 
> 
>    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 anonymity status is not available.
> 
>    The application can HIP_HIT_ 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_ macros correspond to the sockets API macros INADDR_ANY and
>    IN6ADDR_ANY_INIT, but they are applicable at the HIP layer.  After
>    initial contact with the peer, the local and peer HITs can be
>    discovered using getsockname() and getpeername() calls for connection
>    oriented sockets.
> 
>    The application uses also the the HIP_HIT_ANY macro in ship_hit field

s/uses also/also uses/

>    to establish outgoing communications in Opportunistic mode
>    [I-D.ietf-hip-base], 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, the local and peer HITs can be
>    discovered using getsockname() and getpeername() calls for
>    connection-oriented sockets.
> 
>    The HIP_HIT_ANY_ macros allow also non-ORCHID based communications to

s/allow also/also allow/

>    maximize backwards compatibility.  To distinguish between ORCHID
>    [RFC4843] and non-ORCHID-based communications, it can call
>    HIP_IS_IPV6_ADDR_ORCHID macro.  The macro inputs a pointer to 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 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
> 
>    The HIP API introduces a new addrinfo flag, AI_HIP, 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 4.
> 
> 
> 
> 
> 
> 
> Komu                       Expires May 1, 2008                  [Page 8]
> 
> Internet-Draft             Native APIs for HIP              October 2007
> 
> 
>           #include <netdb.h>
> 
>           struct addrinfo {
>               int    ai_flags;          /* e.g. AI_HIP */
>               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 */
>           };
> 
>                                  Figure 4
> 
>    The flag AI_HIP must be set to the ai_flags, or otherwise the
>    resolver does not return sockaddr_hip data structures.  The
>    simultaneous use of both AI_HIP and AI_PASSIVE flags equals to the
>    use HIP_HIT_ANY macro as described in section Section 4.1.
>    Similarly, the use of AI_PASSIVE_PUB and AI_PASSIVE_ANON flag equals
>    to the use of HIP_HIT_ANY_PUB and HIP_HIT_ANY_ANON.

maybe you had better provide a table which enumerates the newly defined
ai_flags for HIP with brief explanation (rather than showing everything
in Table 3).

> 
>    The ai_family field is set to AF_HIP the addrinfo structure when
>    ai_addr points to a sockaddr_hip structure.
> 
>    When ai_protocol field is set to zero, the resolver returns also

s/returns also/also returns/

>    locators in sockaddr_in and sockaddr_in6 structures in addition to
>    sockaddr_hip structures.  The resolver returns only sockaddr_hip

s/returns only/only returns/

>    structures when ai_protocol field is set to IPPROTO_HIP or a
>    sockaddr_hip structure is given as the hint argument to the resolver.
> 
>    A HIP-aware application creates the sockaddr_hip structures manually
>    or obtains them from the resolver.  The manual configuration is
>    described in [I-D.ietf-shim6-proto].  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
> 
>    As described in [RFC3493], the getaddrinfo function takes the
>    nodename, servname, and hints as its input arguments.  It places the
> 
> 
> 
> Komu                       Expires May 1, 2008                  [Page 9]
> 
> Internet-Draft             Native APIs for HIP              October 2007
> 
> 
>    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

s/acts/act/

>    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 flag set.  The resolver inserts HITs before
>    any locators.
> 
>    Resolving of a hostname can result in a HIT which maps to multiple

s/Resolving of/Resolution of/

>    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.  When the application implements its own
>    locator policies, it can control the locators bindings with the
>    extensions defined in [I-D.ietf-shim6-proto].

should be [I-D.ietf-shim6-multihome-shim-api], instead of
[I-D.ietf-shim6-protocol].

That's it from me.  Hope it helps.

Regards,
Shinta

---

From: Miika Komu <[email-masked]>
Date: Sun, 11 Nov 2007 17:43:10 +0200 (EET)

> the content of the draft.  There are some minor comments (mostly editorial).

Thanks Shinta for the review,

I adjusted the draft according to your suggestions and the new version is 
here:

http://www.iki.fi/miika/docs/draft-ietf-hip-native-api-03-pre5.txt

> definition of "Locator" is given twice in the table.

Ok.

>>    new, because the native HIP APIs is otherwise identical to the

Ok.

> when you refer to "API" in the document, I think singular form is more

It depends how one wants to think about it. Originally Nikander suggested 
plular. I guess APIs in plular is more approate if each interface 
(function call) is though as a separate API. Neverthless, I think what 
matters is that the plularity is used consistently in the document.

>>    The HIP_HIT_ANY_ macros allow also non-ORCHID based communications to

Ok.

> ai_flags for HIP with brief explanation (rather than showing everything

I think there would too much redundancy because there are descriptions 
already both in the text and in appendix.

>>    The input argument hints acts like a filter that defines the

Ok.

> s/Resolving of/Resolution of/

Change to active,    Resolver can return a HIT which maps to multiple 
locators.

> [I-D.ietf-shim6-protocol].

Ok.

> That's it from me.  Hope it helps.

I appreciate your review. Thanks!

---

From: Gonzalo Camarillo <[email-masked]>
Date: Sun, 11 Nov 2007 18:42:50 +0200

Hi Miika,

a few comments on this pre-version.

Expand API in the Introduction as well.

Fix grammar: "The application can also to explicitly allow..."

The draft says:

"Note that the APIs specified in this document are not specific to HIP"

The 'not' should be removed (check the text I sent to the list a while 
ago, which was agreed with the ADs).

Please, fix these and submit the draft before the cut-off date. I will 
WG last call the version you submit so that the group has a last chance 
to provide comments.

Cheers,

Gonzalo

Miika Komu wrote:
> I adjusted the draft according to your suggestions and the new version 
> is here:
> 
> It depends how one wants to think about it. Originally Nikander 
> suggested plular. I guess APIs in plular is more approate if each 
> interface (function call) is though as a separate API. Neverthless, I 
> think what matters is that the plularity is used consistently in the 
> document.
> 
>> s/uses also/also uses/
>>

---

From: Miika Komu <[email-masked]>
Date: Mon, 12 Nov 2007 09:38:55 +0200 (EET)

On Sun, 11 Nov 2007, Gonzalo Camarillo wrote:

Hi Gonzalo,

the new version based on your comments is in here:

http://www.iki.fi/miika/docs/draft-ietf-hip-native-api-03-pre6.txt

> Fix grammar: "The application can also to explicitly allow..."

The second goal is that applications can explicitly accept
communications with unknown peer identifiers.

> The 'not' should be removed (check the text I sent to the list a while ago, 
> which was agreed with the ADs).

Removed "not". Please tell explicitly if there are other problems with 
this. I mentioned this already in the summary of changes on the mailing 
list, but I removed the SHIM generalization in lack of any other concrete 
examples where the generalization could be useful. Also, I think it is 
better to explicitly specify the SHIM protocol to avoid ambiguous protocol 
bindings. Nobody seemed to object against this change.

> Please, fix these and submit the draft before the cut-off date. I will WG 
> last call the version you submit so that the group has a last chance to 
> provide comments.

Cut-off is in one week. Comments are still welcome.

---

From: "Henderson, Thomas R" <[email-masked]>
Date: Mon, 19 Nov 2007 07:37:56 -0800

I posted some comments on the API draft to Miika privately, and am
reposting the more substantive ones here for any WG list discussion of
them.

- overall, I think it is improved without so much shim6 reliance, but
perhaps more dependency needs to be removed?  (next comment)

- referring to Figure 2, the biggest piece that seems to be missing in
the draft is a discussion about step f (connect).  The draft basically
implies that the application deals only with HITs, but I think that the
API should also support passing locators along with HITs.  These
locators need not be learned in the resolution step.  The draft needs to
be extended to spell out the details (how are locators conveyed, and
associated with a HIT, and what are semantics if the HIT is not
reachable at those locators).  

It may be that you feel it is out of scope (section 2, para.3) but I
think it needs to be in scope, or if you feel that it is in
shim6-multihome, more of an overview presented here.  

- Also, what happens when the application has skipped the resolution
step and passes a HIT that cannot be successfully resolved?

- step e, I think it is correct to pass back only HITs, but the draft
ought to have more to say about how an application finds locator
bindings that may have been in the DNS but hidden from the application.
There is only a reference to shim6 that it can control the bindings with
LOC_PEER_PREF.

- section 4.2, I do not see why it is important to support non-ORCHID
HITs for backward compatibility.  Maybe for forward compatibility?  I
would just suggest to remove that paragraph, though.