Extension to Sockets API for Mobile IPv6
draft-ietf-mip6-mipext-advapi-07

[Note]: '1/9/2006:  Sent ping to Sam and Bill to clarify any outstanding issues.  1/23/06:  Need to send mail to attempt to bridge gap in understanding between Sam and authors.' added by Margaret Wasserman

[Note]: '1/9/2006:  Sent ping to Sam and Bill to clarify any outstanding issues.  1/23/06:  Need to send mail to attempt to bridge gap in understanding between Sam and authors.' added by Margaret Wasserman

[Ballot discuss]
My issues are fixed except for two minor problems, easily fixed by an RFC-Editor's note:

1. There's an instance of IPV6_MIPSTOPTS, which is a typo of IP_MIPDSTOPTS

2. There's a leftover description of what inet6_rth_gettype() returns, but I think it's superceded by the example of how to access rth_type.

[Ballot comment]
Throughout the document, I find myself confused about whether a section is talking about a system with Mobile-IP implemented in the kernel.  For example, 3.2.1 says

  The received ancillary data object for Home Address destination
  option SHOULD contain the Care-Of-Address of the mobile node.
...
  Note that whether or not these new APIs are used, the senders home
  address is contained in the source address

However, if the kernel doesn't implement Mobile-IP, then the HA option will have the HA, and the IP source address will be the COA, right?

Another example is:
    For TCP data packets with Home Address destination option may be
    used with "sticky" option for all transmitted packets. However,
    at this point, it is unknown why an application  would want to
    set Home Address option or Route Header Type 2 extension header
    along with its data packets as Mobile IPv6 protocol takes care of
    them transparently at the protocol stack.
[written assuming that there's a mip6 stack]; vs. later in the document,
      However, some
  embedded software implementations may require to implement the IPv6
  packet processing/sending at the user level; those implementations
  may choose to provide API spport for sending home-address option
  at the application layer.

I think it'd be nice to see clear statements about which parts would and wouldn't be used when there is or isn't a mip6 implementation in the stack.  Right now it's very wishy-washy, sometimes saying things like "this is handled by the mip6 stack" and sometimes saying things like "however you may have to do some other stuff".

[Ballot discuss]
I wonder about the need for

    int inet6_rth_gettype(const void *bp);

The advanced API gives examples of, e.g., accessing rth->ip6r_segleft directly in an ip6_rthdr; why not access rth->ip6r_type directly too?

Related to Sam's comments:
        uint8_t          ip6oha_addr[16];  /* Home Address */
It'd be really nice if this could be a struct in6_addr, but presumably it's this way because struct padding gets badly in the way given the 8n+6 alignment of this option.  It'd be nice if somehow the struct could contain the 6 so that you could use the aligned struct in6_addr.  Is this the first struct defined for an option with alignment requirements like this?


Moving the HA option automatically is a little weird; I'm uncomfortable about asking the kernel to parse the IPV6_DSTOPTS and move an HA option if found (especially with an 8n+6 padding, if there are other options packed in the IPV6_DSTOPTS things could get weird) - if this is a one-off then I'm inclined to let it go, but could there be another use for placing options between Routing and Frag headers?  In which case, would it be better to define another IPV6_???DSTOPTS option?

[Ballot discuss]
I wonder about the need for

    int inet6_rth_gettype(const void *bp);

The advanced API gives examples of, e.g., accessing rth->ip6r_segleft directly in an ip6_rthdr; why not access rth->ip6r_type directly too?

I'm going to defer this so that I can do a more complete review; this was just from skimming.

[Ballot comment]
citation/reference problems:
  !! Missing citation for Informative reference:
  P020 L028: [3]    Deering, S., Hinden, R., "Internet Protocol, Version 6

  !! Missing Reference for citation: [RFC-3493]
  P004 L038:    body, such as has been done with the Basic API [RFC-3493].

  !! Missing Reference for citation: [RFC3245]
  P004 L040:    [RFC3245], such standardization would make sense only if

[Ballot comment]
From Gen-ART review by Mark Allman:

  + Section 1: "mainly target user-level" --> "mainly targets
    user-level"

  + Section 1: While the document is fine without specifying error
    handling it might be nice to add a note that this is not good
    practice.

  + Section 1: "deployed among implementations, it" --> "deployed, it"

[Ballot comment]
In section 7: s/man in the middle/man-in-the-middle/

  Reference [1] contains two dates.  I believe the second one should
  be deleted.

  Section 11 should be deleted prior to publication.

[Ballot comment]
The document says:

Behavior of legacy IPv6 socket applications:

  Applications, whether or not they implement this specification, that
  use the Advanced API mechanisms to receive Destination options or
  Routing headers, need to ignore or otherwise properly handle the Home
  Address destination option and the type 2 routing headers according
  to this API specifications.


I found this pretty hard to parse.  I would suggest re-phrasing it.  Does "Legacy applications using
the Advanced API mechanisms to receive Destination options or Routing headers will ignore
the Home Address destination option and the type 2 routing headers specified here." capture
the intent?

IANA Comments:
As described in the IANA Considerations section, this document uses parameters in the protocol numbers registry but does not request any new IANA Actions.

[Ballot discuss]
ANSI C does not guarantee strict alignment of structs.  You can design
a struct that can hold all the fields of a packet, but you cannot
design a struct that if viewed as a buffer will represent a packet.  I
have included a review in the tracker that describes at least one case
where the structs in the draft do not actually align to wire formats.

The draft appears to believe that the structs do correspond to wire formats in two places.  First, section 4 seems to imply that you can receive the mobility header using a raw socket and use the structs in section 2.

Secondly, the description of section 2 claims that the structs do
correspond to wire formats.

At a minimum, the API needs to clarify the assumptions it makes.  In
addition, the document needs to clearly indicate which functions from
the advanced API return structs from section 2 and which functions
return bits from the wire.

From: Ken Raeburn
Subject: draft-ietf-mip6-mipext-advapi-04.txt and ANSI/ISO C

In gcc-3.4.0 (and going back to gcc 2 days, when I was hacking
compilers), at least one architecture aligns structures larger than 4
bytes to 8-byte boundaries, and thus pads to a multiple of 8 bytes.
So on that architecture, struct ip6_mh would have a couple padding
bytes added at the end.  It's not a common thing to do, and it's not a
popular chip any more, but this case highlights the theoretical
problem that the padding in an ISO C/POSIX implementation may not be
the same as on the authors' machines.  The draft would be better in
this regard if the various structures including struct ip6_mh instead
duplicated the fields.  (If the spec were loosened up a bit, instead
of saying "these are the structure definitions exactly", it might
allow an implementor to use the nested-structure form and define, for
example, "ip6mhbr_proto" to "ip6mhbr_hdr.ip6mh_proto" if it wanted,
much like is done for "s6_addr" in "struct in6_addr" on Solaris and
Linux; an implementor dealing with the stricter structure alignment I
described above would have to implement the flattened form.  If
portable static initialization is an issue, I'd have to go do a little
reading.)

If the authors are assuming that no additional padding is ever needed
in their structures beyond what they've added, and that the structures
are supposed to match the on-the-wire format of the data (which is
suggested by the discussion of raw sockets), they should say so
explicitly, and (ideally) allow some wiggle room in the specification
so that systems with different alignment rules can still have
implementations in ISO C that still match the wire protocol, without
having to resort to special compiler support, and without making
application writers adjust their code for these systems.

But if that's not practical, just document these assumptions, and some
platforms may just have to have special compiler support to implement
this API.



The updated C specification describing uint64_t and int64_t has been
out for more than five years, and at least a half dozen RFCs
(including RFC 3493, "Basic Socket Interface Extensions for IPv6", and
RFC 3542, "Advanced Sockets API for IPv6") have used them; why not use
them for the cookies instead of uint32_t[2]?


The last paragraph of section 1:

  Once the API specification becomes mature and is deployed among
  implementations, it may be formally standardized by a more appropriate
  body, such as has been done with the Basic API [RFC-3493]. However,
  since this specification largely builds upon the advanced API
  [RFC3245], such standardization would make sense only if the advanced
  API was also standardized.

... should refer to RFC 3542, not 3245.


Ken

AD review comments

High-level: I think the introduction would benefit from a clearer
applicability paragraph. I.e., one that explains what types of
applications would use the API and what for. This is not stated. Some
if this API is for home agents and infrastructure support, not for
general applications. But some may be for general applications to, I
think. (or no?) It would be good to make it more  clear _who_ the
extensions are of interest to.

I gather that this API is not used to allow applications to say "just
use my COA rather than pretend I'm at home". It would be good to say
that and point out that more API work is needed to target general
applications.


>    IPv6 as an extension to Advanced Socket API for IPv6.

s/to/to the/

>    Mobility Support in IPv6 introduces mobility protocol header

s/introduces/introduces a/

>    headers. This document is an extension to existing Advanced Sockets

s/to/to the/

>    protocol support. The target applications for this socket API is

s/is/are/? (or make applications singular)

>    It is anticipated that Mobile IPv6 will be used widely from mobile
>    devices to Server and Routing platforms. Thus it is useful to have
>    a standard API for portability of Mobile IPv6 applications on a
>    wide variety of platforms and operating systems.

do server and routing platforms also use this API? how?

>    most vendors. This is in conformance with Advanced Sockets API for
>    IPv6 [1].

What does "in conformance" mean here? Just "is consistent with"?

>    We note that many of the functions and socket options defined in this
>    document may have error returns that are not defined in this
>    document.  Many of these possible error returns will be recognized
>    only as implementations proceed.

error codes, or sub-codes? the latter is OK. But the former seems like
it needs to be specified here.

>    This document provides guidelines on Mobile IPv6 socket applications
>    and believes that some other appropriate standardization body will
>    standardize the APIs along with other IPv6 advanced socket APIs.

Probably better to reword or remove. AFAIK, the advanced API is not
being picked up for "standardization" by anyone. It's also not widely
(completely) implemented either, at least AFAIK. Or has that changed
recently?

>    This API assumes that the fields in the protocol headers are left in
>    the network byte order, which is big-endian for the Internet
>    protocols.  If not, then either these constants or the fields being
>    tested must be converted at run-time, using something like htons() or
>    htonl().

maybe make more clear, say something like:

It is the responsibility of applications (or the system) to ensure
that all fields are in network byte order across API invocations.

>    . This is fixed part of the Mobility Header.

s/is/is the/

>      at least one prefix option with the Rouer Address (R) bit set.

s/Rouer/Router/

>      As per Mobile IPv6 specification [2] a Home Agent MUST include
>      at least one prefix option with the Rouer Address (R) bit set.
>      Advanced Socket API [1] defines data structure for prefix option
>      as follows:

would be good to make more clear what text from [2] is being quoted
(since the MUST word is used here...)

>    Mobile IPv6 un-aware applications or existing IPv6 socket
>    applications that do not know about the new routing header type 2
>    and Home Address destination option, SHOULD ignore these new
>    routing header type and Home Address destination option upon
>    receipt of them.

here is a SHOULD, with no defintion (e.g. pointer to 2119).

Also, this text is a bit odd, because it applies to implementations of
this spec. Those that don't implement it can't be told what they
SHOULD do...

>    While accessing Routing header Type 2 extension header, one MUST
>    use type = 2 and segment = 1. The following existing functions
>    defined in Advanced API for IPv6 Sockets [1] are supported

This text presumably is quoting from another spec.. please make that
clear and cite the relevant document...

>    Detail description and examples of accessing a IPv6 Routing Header
>    are discussed in Advanced Sockets API for IPv6 [1].

s/discussed/discussed in/ note: I haven't flagged all occurances where
this correction is needed...

also s/Detail description/Detailed descriptions/

>    support API for sending routing header type 2. However, if any

s/API/the API/

>    user level, it can use the API mentioned in section 3.1 and set
>    value of routing header as the home-address as specified in [2].

s/value/the value/
s/of/of the/

>    For user level applications that receive routing header type 2,

s/user level/user-level/

>    not send Home Address Destination Option from the application level,

s/send/send a/

>    option and routing header type 2 at the kernel. However, some
>    embedded software implementations may require to implement the IPv6
>    packet processing/sending at the user level; those implementations

s/may require to/may/

>    All portable Mobile IPv6 aware applications MUST receive the
>    home-address as source address of the incoming packet from the
>    socket-level functions like recvfrom(), recvmsg(), accept() and
>    getpeername(). This is  necessary for:

don't understand what  this MUST means or who the MUST applies to.

>    accessed through a IPv6 RAW socket. A IPv6 RAW socket that is opened

s/A IPv6/An IPv6/ (multiple occurances)

>    packet to the receiving socket. Depending on the implementation
>    kernel may process the mobility header as well in addition to passing

s/implemention kernel/implementation, the kernel/

> 6.  IPv4-Mapped IPv6 Addresses
>
>    The same rule applies as described in section 13 of Advanced Sockets
>    API for IPv6 [1]. Thus processing of IPv4-mapped IPv6 addresses
>    for the Mobile IPv6 specific socket options are out of scope of this
>    document.

First sentence doesn't make sense by itself; you need a transition to
start of the new section.