Subject: complete the advanced API (rfc2292bis)

From: JINMEI Tatuya / 神明達哉<[email-masked]>
Date: Mon, 25 Jun 2001 23:34:29 +0900

Hello,

As an IPv6 stack/application programmer, I'd really like to fix the
advanced API.  The current situation is really mess, because
rfc2292bis does not provide backward compatibility to the old RFC
2292, and some OSes has already shipped with rfc2292bis while some
other OSes still keep RFC 2292.  I believe we should basically go with
rfc2292bis, since it has fixed many issues (bugs, in fact) in the old
RFC spec, and some of them are essential for some applications
(e.g. the IPV6_USE_MIN_MTU option for DNS servers).

The most difficult issue would be the one for extension headers.
According to a recent discussion about MIP6 issues, the API should be
flexible enough to send/receive extension headers in any order, whereas
rfc2292bis basically assumes the recommended order of the headers
specified in RFC2460.  Since it could be a fundamental change of the
API spec, I'm not sure if we can get a consensus so smoothly.
Anyways, I'll raise this issue later in a separate thread.

Apart from the extension header issue, I'd like to start with the TODO
and open issues list in draft-ietf-ipngwg-rfc2292bis-02.txt (which has
already expired, but you can still get it at
ftp://ftp.kame.net/pub/internet-drafts/) with some comments.  If
you're intested in this topic, please review them and tell me your
opinions.

If possible, I'd like to see the next revision of the draft before the
next IETF meeting in London.  So my question is:

does anyone (especially in the authors) try to revise the draft now?

If not, and if no one have time to do it for the moment, I'll be a
volunteer to edit the text for the next revision.  Please let me know
your opinions.

Thanks,

					JINMEI, Tatuya
					Communication Platform Lab.
					Corporate R&D Center, Toshiba Corp.
					[email-masked]

from TODO/Open list in the previous version of the draft:
18.  TODO and Open Issues

   Items left to do:

    -  Add macros for ip6_hdr to access the traffic class and flow label
       fields.

I don't recall the discussion (if any), but I think it's just a naming
issue.

    -  Should we remove the 1, 2, 4, 8 byte restriction for
       inet6_opt_set_val and inet6_opt_get_val?  Option values can be
       any size even though there alignment must be a power of two.

Yes, I think so.  And,

       Issue of how natural alignment is defined for sizes that are not
       a power of two.

this can be left as implementors' choice, IMO.

    -  Perhaps we should add a note to point out that robust receivers
       should verify alignment before calling inet6_opt_get_val().  Or
       require that inet6_opt_get_val() should check the alignment and
       fail by returning -1?

I believe the draft just note possible unaligned data, and the library
implementation itself should be careful about the alignment issue.

    -  Should we change IPV6_USE_MIN_MTU to IPV6_USEMTU taking a
       uint32_t Should we add IPV6_DONTFRAG option for traceroute??

Through a former discussion, we should just go with the
IPV6_USE_MIN_MTU.  I'm still not sure about the IPV6_DONTFRAG option.

    -  Add credits for UDP MTU stuff
    -  Move information about mapping from inet6_opt to setsockopt and
       cmsg.

What exactly do these two items mean?

    -  Clarify IPV6_RTHDRDSTOPTS's interaction with IPV6_RTHDR.

This would be the most difficult issue.  We'll discuss it separately
later.

    -  Make the new inet6_opt_set_val() and inet6_opt_get_val() check
       the length of the data item.

It would be just an editorial issue.

    -  Add sending and receiving sections for routing header text just
       like destination options?

This should be a part of difficult issue.

    -  Include sample implementation of inet6_opt_XXX.

We (KAME) can contribute our implementation as sample code.

    -  Fix Authors address wrt Rich.

It's an editorial issue.  (But what is the best "address" for him?)

   Open issues:

    -  Add ICMP name lookups definitions?

Since the standardization has not proceeded, I think we should fix the
API without the definition.

    -  Add site-prefixes definitions?

Ditto.

    -  Add flow label allocation API as requested in draft-berson-rsvp-
       ipv6-fl-00.txt?  Draft has expired!

We now have a separate draft on this issue
(draft-itojun-ipv6-flowlabel-api-01.txt).  As described in the draft,
I think we should fix the advanced API without this "more-advanced"
stuff.

    -  Anything special for mobility options?  Restrict setting at API?
       Filter out on receipt?  If received what does the home address
       option contain?

IMO, we should fix the API without the restriction and filtering.  As
for reception of the address, I recall some discussion on this.
Someone proposed that the remote address (such as the one returned by
recvfrom(2)) should be the home address, and that the care-of address
should be in the corresponding home-address option when some
RECVDSTOPTS variants are specified.  However, I'd rather leave the
destination address option as is, and introduce a separate RECVxxx
option if we really need to pass the option to the application.

    -  Specify "change" for TCP especially when there are multiple HBH
       option headers etc.

???  what does "multiple HBH option headers" mean?  The IPv6 spec
requirs a HBH option header appear only once in a single packet.  Is
this a typo, and should this be "multiple DST option headers"?

In any case, sending/receving extension headers is the most difficult
part.  We'll discuss this later.

    -  Specify binding to scope-id => implies filtering of addresses
       with that scope if the address you are bound to is link-local
       etc.  What about conflicts with bound scope-id and sendto/connect
       scope-id?

    -  Specify order for ifindex selection.  Put in separate section.
       Different cases for sending to link-local (scope_id including
       nexthop scope_id) and global.  Is multicast different?

    -  bind() and sin6_scope_id.  Should have been in Basic API.  Error
       checks when bind/sendto sin6_scope_id does not match?

These three would depend on the result of the discussion about the
semantics of the sin6_scope_id field (i.e. flat 32 vs 4+28 split).
We'll think about this issue once the semantics is fixed.

    -  Specify notion of default multicast interface?  In Basic API?

I don't think we should note it in the advanced API, but do not oppose
if someone really wants this.

    -  What about site names and site ids?  Need for interfaces to map?
       Requires that site-prefixes pass name - does name need to use DNS
       format to handle character sets?

I believe we should fix the API without this stuff, since this is a
highly advanced issue.

    -  If the home address option passed out in IPV6_RECVDSTOPTS?  If so
       what address value does it contain?

As I said above, I'd prefer a separate option if we really need to
pass the home address to applications.

					JINMEI, Tatuya
					Communication Platform Lab.
					Corporate R&D Center, Toshiba Corp.
					[email-masked]
--------------------------------------------------------------------
IETF IPng Working Group Mailing List
IPng Home Page:                      http://playground.sun.com/ipng
FTP archive:                      ftp://playground.sun.com/pub/ipng
Direct all administrative requests to [email-masked]
--------------------------------------------------------------------

---

From: Francis Dupont <[email-masked]>
Date: Tue, 26 Jun 2001 12:07:33 +0200

In your previous mail you wrote:

=> I agree. Obviously the current editor has not enough time to
do this but this must be done ASAP.

=> this is a deep change but not in a very used part of the spec so
perhaps we should split the advanced API into two parts in order to
be able to publish a document soon?

   If possible, I'd like to see the next revision of the draft before the
   next IETF meeting in London.

=> two procedural questions:
 - is the change of the name of the working group makes the counter to
   restart at 0?
 - if we split the document into two parts, can you keep the name?
I.e. is the deadline 13 July or not?

Thanks

[email-masked]

PS: we have a G6 meeting at the end of the week, I'll try to collect
comments at this occasion.
--------------------------------------------------------------------
IETF IPng Working Group Mailing List
IPng Home Page:                      http://playground.sun.com/ipng
FTP archive:                      ftp://playground.sun.com/pub/ipng
Direct all administrative requests to [email-masked]
--------------------------------------------------------------------

---

From: Erik Nordmark <[email-masked]>
Date: Tue, 26 Jun 2001 14:20:48 +0200 (CEST)

> does anyone (especially in the authors) try to revise the draft now?

I'd like to see the document finished. But I don't have any cycles
to actually drive the open issues to conclusion.
If folks can agree on text to add/change I can do the editing of the document.
Or I can take on a co-author that will help drive this to conclusion
and also do the edits.

> What exactly do these two items mean?

The issue about UDP MTU for DNS servers was brought up
by somebody on this list and there was a separate I-D (expired long time ago) 
which had one proposal for this. The document should give due credit to
that individual.

The second one is about the structure of the document.
The inet6_opt routines are described as having to do with ancillary data
and in a separate place it is pointed out that the routines
also apply to the same information in setsockopt. This organization could
be better.

> It's an editorial issue.  (But what is the best "address" for him?)

I don't know what is traditionally done in cases like this
thus any guidance would be quite helpful. If he is listed
as an author we need to say something in the address section.
Alternatively we can list him at the top of the acknowldgement section
e.g. with something like
	Previous versions of this document [RFC 2292] was co-authored by
	the late Rich Stevens.

> this a typo, and should this be "multiple DST option headers"?

I guess the comment is generic - applies indepedently of the type of
repeated extension headers.
Is there really something in RFC 2460 which says that packets with multiple
HBH headers should be dropped?
Being "liberal in what you receive" would hint that it would be good to
accept such packets. But then we need perhaps specify something - or at
least point out the issue - for TCP detecting when the set of extension
headers and their content is different in one segment than  the previous
segments.

>     -  If the home address option passed out in   If so

I'd be fine with that approach. This means adding some text to say that
the home address option should not be passed to the application when
the application has specified IPV6_RECVDSTOPTS?, right?
Or do you envision two different mechanisms by which the application can
receive this information?

   Erik

---

From: JINMEI Tatuya / 神明達哉<[email-masked]>
Date: Wed, 27 Jun 2001 18:03:35 +0900

>>>>> On Tue, 26 Jun 2001 12:07:33 +0200, 
>>>>> Francis Dupont <[email-masked]> said:

> be able to publish a document soon?

Well, actually, I was thinking about the same idea.  If we can split
this part, things will go quite smoothly.  How do others think of
this?

>  - is the change of the name of the working group makes the counter to

I don't think so, but I don't have the authoritative answer for this
question...

> I.e. is the deadline 13 July or not?

I'm not sure if this is acceptable, but I think we would be able to
keep the same draft name for the easier part (i.e. rfc2292bis-02 -
extension header related parts), just like when we separated jumbo
gram issues from the basic specification of IPv6.

					JINMEI, Tatuya

---

From: JINMEI Tatuya / 神明達哉<[email-masked]>
Date: Wed, 27 Jun 2001 22:27:07 +0900

>>>>> On Tue, 26 Jun 2001 14:20:48 +0200 (CEST), 
>>>>> Erik Nordmark <[email-masked]> said:

> Or I can take on a co-author that will help drive this to conclusion

Okay, then I'll try to drive the discussion, and, if necessary, will
contribute the result as text.

> which had one proposal for this. The document should give due credit to

I searched for the materials in the web, and got the following items:

Subject: (IPng 1494) BSD API spec/Path MTU 
From: "Thomas Narten" <[email-masked]> 
Date: Wed, 28 Feb 1996 09:22:43 -0400 
http://www.wcug.wwu.edu/lists/ipng/199602/msg00158.html

"Forcing Fragmentation to Network MTU" by Mark Andrews
<draft-ietf-ipngwg-bsd-frag-01.txt>
which can be found at
http://www.join.uni-muenster.de/JOIN/ipv6/drafts/draft-ietf-ipngwg-bsd-frag-01.txt

Are these the ones we are looking for?

> also apply to the same information in setsockopt. This organization could

I'm still not sure about it, but (for example) are you talking about
the following paragraph,

   When using ancillary data a Hop-by-hop options is passed between the
   application and the kernel as follows:  The cmsg_level member will be
   IPPROTO_IPV6 and the cmsg_type member will be IPV6_HOPOPTS.  These
   options are then processed by calling the inet6_opt_next(),
   inet6_opt_find(), and inet6_opt_get_val() functions, described in
   Section 10.6.
(in Section 8.1)

intending that we should mention socket option cases as well?

By the way, I found some typo in the 02 version:

8.2.  Sending Hop-by-Hop Options
   All the Hop-by-Hop options must specified by a single ancillary data
   object.  The cmsg_level member is set to IPPROTO_IPV6 and the
   cmsg_type member is set to IPV6_HOPOPTS.  The option is normally
   constructed using the inet6_opt_init(), inet6_opt_append(),
   inet6_opt_finish(), and inet6_set_val() functions, described in

inet6_set_val() should be inet6_opt_set_val().

9.2.  Sending Destination Options
   The Destination options are normally constructed using the
   inet6_opt_init(), inet6_opt_append(), inet6_opt_finish(), and
   inet6_set_val() functions, described in Section 10.

Same here.

> 	Previous versions of this document [RFC 2292] was co-authored by

I don't know a common sense in such a case, either.  rfc2553bis has
the same issue, and the latest draft simply removed his address.

> HBH headers should be dropped?

I believe the last sentence of the following paragraph in RFC2460
specifies the behavior:

   If, as a result of processing a header, a node is required to proceed
   to the next header but the Next Header value in the current header is
   unrecognized by the node, it should discard the packet and send an
   ICMP Parameter Problem message to the source of the packet, with an
   ICMP Code value of 1 ("unrecognized Next Header type encountered")
   and the ICMP Pointer field containing the offset of the unrecognized
   value within the original packet.  The same action should be taken if
   a node encounters a Next Header value of zero in any header other
   than an IPv6 header.

So, we should be able to assume we'll never see multiple hop-by-hop
options headers in the API layer.

BTW, I mentioned a same kind of issue for the sending size far back in
the past, and your answer was "implentation defined", with which I'm
okay (see a comment about Section 8.2 in the attached message below.)

> receive this information?

Oops, sorry, I was a bit confused.  I meant how to pass the care-of
address to the application.  As for the home address, it should be
passed to the application as if it was really in the source address
field of the IPv6 header (e.g. in the "from" address returned by
recvmsg, or through the getpeername function), if I remember correclty
a succeeding discussion.

Anyway, the home address option (if any) should be passed 'as is' to
the application that specifies IPV6_RECVDSTOPTS, IMO.

					JINMEI, Tatuya

Subject: Re: comments on ipngwg-rfc2292bis-01
From: Erik Nordmark <[email-masked]>
To: [email-masked]
Cc: [email-masked], [email-masked], [email-masked]
Date: Wed, 5 Jan 2000 16:27:42 -0800 (PST)

Thanks for all the careful comments. I'll fix the ones I'm not explicitly
including in the reply (and most of the ones below as well - I just thought
I should respond to your comments explicitly on these ones).

> 2.1.2.  IPv6 Extension Headers
> 
> I think it would be useful to define a generic structure to specify
> IPv6 extension headers, since we sometimes encounter a situation where
> we can't detect the type of an extension header but should deal with
> the header. As an example, here is the KAME's structure for this
> purpose:
> 
> struct	ip6_ext {
> 	u_char	ip6e_nxt;
> 	u_char	ip6e_len;
> };

I will add that unless somebody disagrees.

> 2.1.3.  IPv6 Options
> (snip)
>        /* IPv6 options */
>        structip6_opt {
>            uint8_tip6o_type;
>            uint8_tip6o_len;
>        };
> 
> There seems to be lack of white spaces in the above code.

Yes, lots of whitespace is missing in the structures.
I sent an email about this to ipng back in November when I realized the
bug.

> 2.2.1.  ICMPv6 Type and Code Values
> ...
>        #define ICMP6_MEMBERSHIP_QUERY      130
>        #define ICMP6_MEMBERSHIP_REPORT     131
>        #define ICMP6_MEMBERSHIP_REDUCTION  132
> 
> These macro names are based on terms of IGMPv2, not MLD. So I prefer
> the names like the followings:
> 
> #define MLD_LISTENER_QUERY		130
> #define MLD_LISTENER_REPORT		131
> #define MLD_LISTENER_DONE		132
> 
> I don't necessarily argue that the old names should be removed. I'm
> glad if the latter names are *added* in the specification.

I'll switch to the new ones. If implementations want to provide the old
as well as new they can do that. But we don't want to clutter up the 
specification.

> 2.2.2.  ICMPv6 Neighbor Discovery Type and Code Values
> 
>        #define ND_OPT_PI_FLAG_ONLINK        0x80
>        #define ND_OPT_PI_FLAG_AUTO          0x40
> 
> We may have to define macro names for the "Router Address bit" used in
> mobile-ipv6 and the "Site Prefix flag" used in the
> ipngwg-site-prefixes draft.
> (I'm not sure this is good since they are not officially
>  standardized. This is just a comment.)

My take is that if we are pretty sure that things will become a standard
we can add it to the API.
Thus I added router renumbering stuff and I should add the mobile IPv6
pieces.
But I might hold off for a while on icmp name lookups and site prefixes
so we can see what will happen with those.
If somebody wants to convince me that the WG will approve of that work
I'm game to add it to the API spec.

So I'll add ND_OPT_PI_FLAG_ROUTER.
Is there something else missing from the mobile IPv6 specification?

> 2.2.3.  Multicast Listener Discovery Type and Code Values
> 
> Although the section title contains "Type and Code Values", there are
> no such definitions in this section. Only a struture for MLD headers
> and short cut macros are defined. Is this your intention?
> (it may be good to define MLD_LISTENER_QUERY, etc in this section.)

OK. I'll move the type definition down to be consistent across the section.

> 2.2.4.  ICMPv6 Router Renumbering Type and Code Values
> 
> Again, there are no "Type and Code Values" definitions in this
> section.
> 
> FYI, we use the following definition to specify the type of router
> renumbering in the KAME implementation:
> 
> #define ICMP6_ROUTER_RENUMBERING	138	/* router renumbering */

I'll add that one.

>        /* PCI code values */
>        #define RPM_PCO_ADD              1
>        #define RPM_PCO_CHANGE           2
>        #define RPM_PCO_SETGLOBAL        3
> 
> I think that "PCI" in the comment line is misspelled and should be
> "PCO" (Prefix Control Operations).

Ack.

> 4.  Access to IPv6 and Extension Headers
> 
>    Two different mechanisms exist for sending this optional information:
> 
>     1.  Using setsockopt to specify the option content for a socket.
>         These are known an "sticky" options since they affect all
>         transmitted packets on the socket until either the a new
>         setsockopt is done or the options are overridden using ancillary
>         data.
> 
> When an error occurs during a process of setting a sticky option
> (e.g. length mismatch), should a previously specified value of the
> option (if any) be kept or be cleared anyway? I guess it should be
> kept, but I'm not sure about this point from the draft. (Note that
> IPv4 implementation in 4.4 BSD always clears existing IPv4 options
> regardless of the result of overriding procedure.)

What do others think?
Should we specify this amount of detail?

> 6.  Packet Information
> 
>    An
>    application can clear any sticky IPV6_PKTINFO option by either doing
>    a setsockopt for option with optlen being zero, or by doing a
>    "regular" setsockopt with ipi6_addr being in6addr_any and
>    ipi6_ifindex being zero.
> 
> Is the latter way necessary? This prohibits implementation from
> specifing the unspecified address as source address. (I'm not sure if
> it should be allowed, but it might be useful for some purposes.)

Since PKTINFO contains two pieces of information (ifindex and source address)
and applications might only want to set one of the two the semantics of
	ipi6_ifindex = X (X != 0) and ipi6_addr is all zero (unpspecified)
must mean "the application does not want to control the source address".
Thus you can't really use this to set the source address to the unspecified
address.

> 6.1.  Specifying/Receiving the Interface
> 
>    When the IPV6_PKTINFO socket option is enabled, the received
>    interface index is always returned as the ipi6_ifindex member of the
>    in6_pktinfo structure.
> 
> Is the option name (IPV6_PKTINFO) correct? Shouldn't it be
> IPV6_RECVPKTINFO?

Yes. Good catch. I'll fix.

> 6.3.  Specifying/Receiving the Hop Limit
> 
> In this section, there is no (explicit) description of how to clear an
> existing IPV6_HOPLIMIT sticky option. If specifying -1 is the only
> way, it would be better to clearly state the fact in the draft.

I'll add that.
Using a zero length option should also work.

> 6.4.  Specifying the Next Hop Address
> 
> There is no description of how to remove an existing IPV6_NEXTHOP
> sticky option in this section. I guess that it can be removed by
> specifying the option with optlen being zero.

I'll add that.

>    Three functions build a Routing header:
> 
>      inet6_rth_space()    - return #bytes required for Routing header
>      inet6_rth_init()     - initialize buffer data for Routing header
>      inet6_rth_add()      - add one IPv6 address to the Routing header
> 
> It might be better to define an additional function to finalize a
> Routing header, since we don't necessary know the number of
> intermediate hops when initialization. Actually, I encountered such a
> situtaion when implementing source routing in traceroute. Note that we
> don't necessarily have to define a new function; we can extend
> inet6_rth_add() so that the function updates all fields (at least
> including the header length field) of the routing header each time it
> is called.

If you don't know the number of hops before starting to build the routing
header you don't know how much memory to allocate for the option/ancillary
data.
Thus I think applications like traceroute first need to parse its arguments
to get a list of hops (e.g. stored in an array) and then build the routing
header.

>    To receive a Routing header the application must enable the
>    IPV6_RECVRTHDR socket option:
> 
>        int  on = 1;
>        setsockopt(fd, IPPROTO_IPV6, IPV6_RECVRTHDR, &on, sizeof(on));
> 
> There chould be two or more routing headers in a received packet
> (although this wouldn't usually happen). How can we access the second,
> third, ... routing headers? Is the each routing header stored in a
> separate ancillary data object? Or are all the routing headers stored
> in a single object? If the latter is the case, how do we access the
> second, third, ... routing headers in the single ancillary data object
> (with the defined library functions only)?

The API isn't really designed to deal with anything but the recommended
way of doing extension headers i.e. at most one hbh header,
at most one destination header before a routing header,
at most one routing header, and at most one destination header
after the routing header.
For transmitting it is impossible to construct something different than
the above using the API.

While the receive side could provide more I don't see any reason to specify
that in the API.
(But if I ever felt the urge to implement something like that
having one ancillary data item per extension header would make the most sense -
and keeping the ancillary data items in the order the extension headers were
received in the packet.)

> Also, the description of the function is a bit unclear to me. It only
> mentions how the address fields are changed. Are other fields
> (especially the segment-left field) also updated? Or should a caller
> adjust the fields by itself in order to reuse (e.g. resend) the
> header? In our implementation, I took the former approach; the value
> of the segment-left field will be changed to the number of segments in
> the function procedure.

The intent was the former. I will add:
The function reverses the
order of the addresses and sets the segleft member in the new Routing 
header to the number of segments.

> 8.2.  Sending Hop-by-Hop Options
> 
>    All the Hop-by-Hop options must specified by a single ancillary data
>    object.
> 
> What should the kernel do if an ancillary data contains multiple
> IPV6_HOPOPTS objects? Should it take just one of them or should it
> discard the entire ancillary data and return an error? If the former
> is the case, which one should the kernel take?

I don't really care and I don't see a good reason for nailing down
this behavior in the specification. "Implementation defined".

> 9.1.  Receiving Destination Options
> 
>    All the Destination options appearing before a Routing header are
>    returned as one ancillary data object described by a cmsghdr
>    structure (with cmsg_type set to IPV6_RTHDRDSTOPTS) and all the
>    Destination options appearing after a Routing header (or in a packet
>    without a Routing header) are returned as another ancillary data
>    object described by a cmsghdr structure (with cmsg_type set to
>    IPV6_DSTOPTS).
> 
> A same kind of question of receiving multiple routing headers can be
> applied to the destination options header as well; How can we access
> the second, third, ... destination options headers before/after a
> routing header? Also, if there is more than one routing header in a
> received packet and there is a destination options header between two
> routing headers, which part is the destination options header
> regarded as, before a routing header or after?

And the same type of answer applies.

> 9.2.  Sending Destination Options
> 
>    As described in Section 6 one set of Destination options can appear
>    before a Routing header, and one set can appear after a Routing
>    header (or in a packet with no Routing header).  Each set can consist
>    of one or more options but each set is a single extension header.
> 
> What should the kernel do if an ancillary data contains multiple
> IPV6_DSTOPTS or IPV6_RTHDRDSTOPTS objects? Should it take just one of
> them or should it discard the entire ancillary data and return an
> error? If the former is the case, which one should the kernel take?

Implementation defined.

> 10.1.  inet6_opt_init
> 
>        int inet6_opt_init(void *extbuf, size_t extlen);
> 
>    This function returns the number of bytes needed for the empty
>    extension header i.e. without any options.  If extbuf is not NULL it
>    also initializes the extension header to have the correct length
>    field.  If the extlen value is not a positive (i.e., non-zero)
>    multiple of 8 the function fails and returns -1.
> 
> In spite of the last sentence, the sample code in section 24.1 passes
> 0 as the second argument of the function:

The intent is that is extbuf is not NULL then extlen has to satisfy the above
requirement.
I'll clarify.

>    The align parameter must have a value of 1, 2, 4, or 8.  The align
>    value can not exceed the value of len.
> 
> Is this enough to implement all "Xn + Y" alignment requirements? For
> example, can we specify "4n + 3" as alignment requirement using a
> single alignment parameter?

It is sufficient to specify all alignments according to the rules of
appendix B in the IPv6 specification. In addition on Xn+Y that spec
says "order the fields from smallest to largest".

If you have an option with alignment 4n+3 it's size must be 4m+1 to follow
the rules in appendix B. In that case you set len to 4m+1 and align to 4.
(The rules in appendix B requires an option with alignment Xn+Y to end
at a multiple of X bytes, which is why Y doesn't have to be specified.)

> 10.4.  inet6_opt_set_val
> 
>    Databuf should be a pointer returned by inet6_opt_append().  This
>    function inserts data items of various sizes (1, 2, 4, or 8 bytes) in
>    the data portion of the option.
> 
> "(1, 2, 4, or 8 bytes)" seems confusing; it can be interpreted that
> only the 4 sizes can be specified. I think it would be better to
> simply remove the parenthesis.

While I see the point this statement in RFC 2460
      o  One desirable feature is that any multi-octet fields within the
         Option Data area of an option be aligned on their natural
         boundaries, i.e., fields of width n octets should be placed at
         an integer multiple of n octets from the start of the Hop-by-
         Hop or Destination Options header, for n = 1, 2, 4, or 8.
seems to imply that those are the only supported sizes of the
option data.

If we don't have that constraint you could interpret the above to mean that
a 5 octet value should be aligned on its natural boundary i.e. a 5 octet
alignment. While I think you could align it on a multiple of 5 from
the beginning of the option that carries that value, you can't both do this
and have it be aligned on a multiple of 5 bytes from the beginning of
the option header or from the beginning of the packet.

So if somebody is designing options with data items that are not a power
of two in size they need to decide which power of two they need for alignment.

But I guess your point is that they should be able to use inet6_opt_set_val
to set e.g. a 5 byte value. Point taken. 
I just have to think about how to describe this in a concise way.

> 10.5.  inet6_opt_next
> 
>    This function parses received extension headers returning the next
>    option.
> 
> Since the function is used only for HbH/Destination options headers,
> it would be better to replace "received extension headers" with "(a)
> received options header(s)".
> 
>    When there are no more options the return value is -1.
> 
> What if an error occurs?

Also -1. I'll add that.

> 10.7.  inet6_opt_get_val
> 
>    This function extracts data items of various sizes
>    (1, 2, 4, or 8 bytes) in the data portion of the option.
> 
> Again, I think it would be better to remove the parenthesis (see the
> first comment on section 10.4.) 

I'll try to come up with concise text.

>    XXX Perhaps we should add a note to point out that
>    robust receivers should verify alignment before calling
>    inet6_opt_get_val().  XXX Or check alignment and fail by returning
>    -1?
> 
> I think the former is better, since we can't assume that the function
> knows the alignment requirements for all options (including ones
> defined in the future and unstandardized options.)

While the function doesn't know the alignment of future option content
it could verify that they have natural alignment i.e. that an N octet
field (for N = 1,2,4,8) is aligned on an N octet boundary.

> In our implementation the function always uses memcpy to copy the data
> (i.e. not using cast to a specific type) for safety.

My draft implementation also uses bcopy.

> 15.  Summary of New Definitions
> 
>      <netinet/in.h>    int inet6_opt_append(void *, size_t, int,
>                                             uint8_t, size_t, uint_8, void
> **);
> 
> I think the type of the sixth argument should be "uint8_t", not
> "uint_8".

Actually, uint_t is the correct type.

> 23.1.  Sending a Routing Header
> 
>    The six values in the column beneath node S are the values in the
>    Routing header specified by the sending application using sendmsg()
>    of setsockopt().  The function calls by the sender would look like:
> 
>        void  *extptr;
>        int   extlen;
>        struct msghdr  msg;
>        ...
> 
> The variable "extptr" is declared but unused in the example. This
> should be "optptr", or all the occurrences of "optptr" should be
> replaced with "extptr".

Ack. optlen/extlen has the same issue. I'll use "ext*" since it
is the length and pointer to the extension header.

  Erik

---

From: Robert Elz <[email-masked]>
Date: Wed, 27 Jun 2001 22:37:05 +0700

Date:        Wed, 27 Jun 2001 22:27:07 +0900
    From:        JINMEI Tatuya / =?ISO-2022-JP?B?GyRCP0BMQEMjOkgbKEI=?=
		 <[email-masked]>
    Message-ID:  <[email-masked]>

  | >> -  Fix Authors address wrt Rich.

  | I don't know a common sense in such a case, either.  rfc2553bis has
  | the same issue, and the latest draft simply removed his address.

I'd wait and see how much of the doc ends up changing.  If it is
comparatively little, leave him as an author for the next rfc version
then move him to acks for the one after that (if there ever is another).
If there are lots of changes, do it now.   If he stays as an author, in
the authors' address section, just list him as "W.Richard Stevens (deceased)"

  | > Is there really something in RFC 2460 which says that packets with
  | > multiple HBH headers should be dropped?
  | 
  | I believe the last sentence of the following paragraph in RFC2460
  | specifies the behavior:

Yes, looks right - certainly it is the sane way to define things.

  | > 2.1.2.  IPv6 Extension Headers
  | > 
  | > I think it would be useful to define a generic structure to specify
  | > IPv6 extension headers, since we sometimes encounter a situation where
  | > we can't detect the type of an extension header but should deal with
  | > the header.

Huh?   If you can't detect the type of the header, you can't do anything
with it at all, you certainly can't find its length, or what the next
header type will be (there's certainly no expectation that all future
headers will necessarily follow the most common layout of those fields,
and without that you're sunk).   Unknown headers are "drop the packet"
and always have been (as in the paragraph you quoted).

  | I will add that unless somebody disagrees.

So, count one disagreement.   In any case a u_char for the length is
not necessarily going to be enough.

  | But I might hold off for a while on icmp name lookups and site prefixes
  | so we can see what will happen with those.
  | If somebody wants to convince me that the WG will approve of that work
  | I'm game to add it to the API spec.

Add it to the drafts now, so the API can be considered, on the assumption
that the specs will be accepted.   It takes no time at all to yank that
part if that turns out to be an unwarranted assumption, but quite a long
time of review and updates to add it later if it turns out to be needed.

The name lookups spec in particular needs attention, as it needs to be
determined just how the name that is returned is obtained.  Is it always
to be the same value as hostname(2) or can a node set one name to be used
as the result of hostname() (to be used in local log reports, prompts, ...)
and another to be returned to other nodes?    No opinion at the minute,
just a question that needs an answer.

  | > 4.  Access to IPv6 and Extension Headers

  | What do others think?
  | Should we specify this amount of detail?

Yes.   That's one of the most important factors in an API spec - what
state the world will be left in when things go wrong.  Otherwise, on
any error, the only option is to close everything down and start again.
Often that's not practical.

  | > 6.3.  Specifying/Receiving the Hop Limit

  | I'll add that.
  | Using a zero length option should also work.

Pick one preferred way, and doc that one, not several variations that
all should work.

  | If you don't know the number of hops before starting to build the routing
  | header you don't know how much memory to allocate for the option/ancillary
  | data.

What this leads to is the question of who is responsible for the accounting.
That can be either way - it can be done inside the API, or by the application.
A decision just needs to be made (doing it inside the API functions makes for
a simpler interface, but generally one with greater overheads).

  | The API isn't really designed to deal with anything but the recommended
  | way of doing extension headers i.e. at most one hbh header,
  | at most one destination header before a routing header,

Yes - the "get the header by name" type interface is fine for some
applications, but not nearly powerful enough in general, what is most
likely needed is a "get the next header" interface, which returns the
header type, its length, and its data, as well as a cookie to hand to
the API the next time it is called (0 for the first call) so the API
knows where it was up to in the list.  The caller should provide space
for the data - with as much as fits being returned (the returned length
will indicate whether all of the data was included or not - by passing
a data buffer length of 0 the application just gets the header type/length
info back, so it can see what headers exist, and how big they are).

With that, the "get the routing header" can be implemented as library
routines rather than via the interface to the stack if desired.

  | While the receive side could provide more I don't see any reason to specify
  | that in the API.

if anything, this is what the API ought be specifying, that's more general
and more useful than the "get the routing header" types functions.  Knowing
what is in a header is typically only going to provide precise info as to
what it all means when the position in the sequence of headers, and often,
the actual data in the other headers, is examined.

  | (But if I ever felt the urge to implement something like that
  | having one ancillary data item per extension header would make the most
  | sense - and keeping the ancillary data items in the order the extension
  | headers were received in the packet.)

Perhaps - that's going to return the whole thing to the app in one hit,
right?   That would be appropriate for some apps, but it makes it hard to
work out how to provide adequate buffers.

  | > 8.2.  Sending Hop-by-Hop Options

  | > What should the kernel do if an ancillary data contains multiple
  | > IPV6_HOPOPTS objects?
  | 
  | I don't really care and I don't see a good reason for nailing down
  | this behavior in the specification. "Implementation defined".

That seems reasonable - it is an "only buggy apps do that" type thing.
But the doc needs to actually say that, not just ignore it.

  | > 9.1.  Receiving Destination Options

  | > A same kind of question of receiving multiple routing headers can be
  | > applied to the destination options header as well;
  | And the same type of answer applies.

Yes, the API needs to be able to deal with any sequence of known header
types (other than HBH, which is very precisely defined to make it easier
for the routers).

  | > 9.2.  Sending Destination Options
  | > What should the kernel do if an ancillary data contains multiple
  | > IPV6_DSTOPTS or IPV6_RTHDRDSTOPTS objects? 
  | Implementation defined.

This one is probably going to depend on what the API for sending
an arbitrary header sequence looks like.

  | > 10.4.  inet6_opt_set_val

  | While I see the point this statement in RFC 2460
  |       o  One desirable feature is that any multi-octet fields within the
  |          Option Data area of an option be aligned on their natural
  |          boundaries, i.e., fields of width n octets should be placed at
  |          an integer multiple of n octets from the start of the Hop-by-
  |          Hop or Destination Options header, for n = 1, 2, 4, or 8.
  | seems to imply that those are the only supported sizes of the
  | option data.

That's not how I read it.   I read it as requiring that an option that
happens to be 1 2 4 or 8 bytes should be naturally aligned, whereas options
of other lengths go wherever they best fit.

In practice, whenever a new option is defined, its layout will be specified
by those who define it - the 2460 comment is just trying to guide those
designers to "do the right thing".   But they will end up doing whatever
best suits the demands of the option they're creating, and if that means
defining a 7 byte option, that's what will happen - or an option containing
a 2 byte field followed by a 4 byte field, with 2 bytes of trailing padding
(so the 4 byte field is not aligned).  Nothing we do now can prevent that
from happening.

  | If we don't have that constraint you could interpret the above to mean that
  | a 5 octet value should be aligned on its natural boundary i.e. a 5 octet
  | alignment.

The "for n = ..." constraint avoids that conclusion.  It makes it clear that
the alignment only applies to data items of those lengths.

  | So if somebody is designing options with data items that are not a power
  | of two in size they need to decide which power of two they need for
  | alignment.

Yes, exactly - or more correctly, they need to define the layout of the
option data.  As does anyone designing an option.

  | While the function doesn't know the alignment of future option content
  | it could verify that they have natural alignment i.e. that an N octet
  | field (for N = 1,2,4,8) is aligned on an N octet boundary.

That's probably not a good idea - just in case some future spec, for
what are good reasons at the time, decides to do away with that suggestion
from 2460.   It is only a suggestion after all (and cannot possibly be more).

kre

---

From: JINMEI Tatuya / 神明達哉<[email-masked]>
Date: Thu, 28 Jun 2001 01:55:13 +0900

>>>>> On Wed, 27 Jun 2001 22:37:05 +0700, 
>>>>> Robert Elz <[email-masked]> said:

> Huh?

oops...the attache message was too old, and most of them have already
been discussed.  I only noted a possibility of "multiple HbH issue" in
the sending side by citing the old message.

Sorry for taking your time...but thanks for the comments, anyway.
I'll read and reply to them later.

					JINMEI, Tatuya

---

From: JINMEI Tatuya / 神明達哉<[email-masked]>
Date: Thu, 28 Jun 2001 22:15:59 +0900

> the authors' address section, just list him as "W.Richard Stevens (deceased)"

I think it's a reasonable approach.

> Huh?

Please forget about this topic.  It was once discussed, and the
discussion was over with the result that you just want (i.e. we do not
include this structure).

> just a question that needs an answer.

Hmm, as I wrote in a previous message, I myself we should fix the API
without these "ongoing" stuff.  If we're taking this approach, we'd
have to include structures for
draft-ietf-ipngwg-router-selection-00.txt
or even
draft-vida-mld-v2-00.txt
(although the latter one is an individual draft at this moment),
and probably more.

> Pick one preferred way, and doc that one, not several variations that

The 02 draft has the following text.

   In order to clear a sticky IPV6_HOPLIMIT option the application can
   specify -1 as the value.  Alternatively, the application can specify
   an IPV6_HOPLIMIT socket option with a zero length.

I'm okay with this text, although this provides two different ways.

> a simpler interface, but generally one with greater overheads).

I agreed with the current spec in the past discussion, so let's keep
this point.

> routines rather than via the interface to the stack if desired.

We actually have to reconsider the extension header issues, as I said
in the first message in this thread.  Your idea above seems to be a
good candidate.  We'll discuss the issue in a separate thread later.

(So I'll basically skip the discussions below related to this issue)

> But the doc needs to actually say that, not just ignore it.

I don't think so.  I believe the protocol stack (normally the kernel)
should prevent (at least) non-privileged users from sending invalid
packets according to the protocol specification.

					JINMEI, Tatuya

---

From: JINMEI Tatuya / 神明達哉<[email-masked]>
Date: Thu, 28 Jun 2001 22:49:09 +0900

>>>>> On Wed, 27 Jun 2001 18:03:35 +0900, 
>>>>> JINMEI Tatuya <[email-masked]> said:

> this part, things will go quite smoothly.  How do others think of

Does anyone have an objection to this idea?  If not, the procedure
would be:

1. remove extension header issues from the current draft.
2. solve (a part of) open issues except extension header ones.
3. based on the result of 2, issue a revised version of the rfc2292bis
   draft.  The draft name would be either
   draft-ietf-ipngwg-rfc2292bis-03.txt
   or
   draft-ietf-ipv6-rfc2292bis-00.txt
4. solve extension header issues, and issue a new draft entitled
   (e.g.) draft-ietf-ipv6-exthdr-api-00.txt

					JINMEI, Tatuya

---

From: Robert Elz <[email-masked]>
Date: Fri, 29 Jun 2001 12:29:06 +0700

Date:        Thu, 28 Jun 2001 22:15:59 +0900
    From:        JINMEI Tatuya / =?ISO-2022-JP?B?GyRCP0BMQEMjOkgbKEI=?=
		 <[email-masked]>
    Message-ID:  <[email-masked]>

  | Please forget about this topic.

Done...   Apologies for sending lengthy comments on stuff that was
old - I half thought I'd seen it before, but my memory just isn't that
good...

  | Hmm, as I wrote in a previous message, I myself we should fix the API
  | without these "ongoing" stuff.

OK.

  | I don't think so.  I believe the protocol stack (normally the kernel)
  | should prevent (at least) non-privileged users from sending invalid
  | packets according to the protocol specification.

Sure.   But that wasn't the point - the point is exactly what does get
sent (if anything) when the user does something invalid.   I think it is
OK to say that that is implementation defined.  No correct application will
ever care.   That broken applications behave differently on different stacks
should be a feature, not a bug - it helps identify them as broken sooner.

I certainly wasn't suggesting that the stack should be creating invalid
packets out of invalid user input, and sending that.

kre

---

From: JINMEI Tatuya / 神明達哉<[email-masked]>
Date: Sat, 30 Jun 2001 02:12:35 +0900

>>>>> On Fri, 29 Jun 2001 12:29:06 +0700, 

> old - I half thought I'd seen it before, but my memory just isn't that

No, that was my bad, I should've cited the related part only.  Anyway,
thanks for the kind reply.

> packets out of invalid user input, and sending that.

Hmm, I see.  So, "the API does not prohibit the bad behavior, but the
underlying kernel would (or might) prevent the bad packets from beiing
sent on the wire."  Right?  Then, I'm perhaps okay with it.

					JINMEI, Tatuya

---

From: Robert Elz <[email-masked]>
Date: Sat, 30 Jun 2001 23:18:34 +0700

Date:        Sat, 30 Jun 2001 02:12:35 +0900
    From:        JINMEI Tatuya / =?ISO-2022-JP?B?GyRCP0BMQEMjOkgbKEI=?=
		 <[email-masked]>
    Message-ID:  <[email-masked]>

  | Hmm, I see.  So, "the API does not prohibit the bad behavior, but the
  | underlying kernel would (or might) prevent the bad packets from beiing
  | sent on the wire."  Right?  Then, I'm perhaps okay with it.

It isn't so much that the API doesn't prohibit the bad behaviour, it
can - but whether the API says something is legal or not, people are
still going to do it.

Sometimes it is important to specify exactly what does happen when the
user does something stupid, other times it isn't.

So, you could say "if the ancillary data contains multiple IPV6_HOPOPTS
objects" (which was the particular case in question) "only the first is
used", or "only the last is used", or "E2BIG is returned" or ...

But there's no real need - allow any of those the implementation prefers
and just say it is "implementation defined".

This is generally a reasonable response to what are programming errors.
On the other hand, errors that the programmer didn't cause (like sending
into a socket that has been reset, or to a mobile node's care of address,
after it has moved again, or to a global address before the node has acquired
one of its own, or ...) need to be specified more precisely, as for those
a careful program can look at what happens, and proceed accordingly.

And (other than use of raw sockets and similar) the kernel certainly should
be avoiding sending bad packets on the wire (not just might).  No matter
what I do as an idiot programmer, the kernel shouldn't be allowing my mess
to escape - or not where it can tell it is wrong.

kre

---

From: JINMEI Tatuya / 神明達哉<[email-masked]>
Date: Sun, 01 Jul 2001 12:50:54 +0900

>>>>> On Sat, 30 Jun 2001 23:18:34 +0700, 

> and just say it is "implementation defined".

Okay, thanks for the explanation.  Actually, I did not intend to
require the spec to clearly state that "the underlying kernel would
(or might) prevent the bad packets...", but just would like to make
the background intention clear.  Thanks for the explanation.

					JINMEI, Tatuya