Internet Engineering Task Force                 Jun-ichiro itojun Hagino
INTERNET-DRAFT                                   IIJ Research Laboratory
Expires: October 11, 2001                                 April 11, 2001


                  Socket API for IPv6 flow label field
                 draft-itojun-ipv6-flowlabel-api-01.txt

Status of this Memo


This document is an Internet-Draft and is in full conformance with all
provisions of Section 10 of RFC2026.

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

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

To view the list Internet-Draft Shadow Directories, see
http://www.ietf.org/shadow.html.

Distribution of this memo is unlimited.

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

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



Abstract

The draft outlines a socket API proposal for controlling the flow label
field in the IPv6 header.  The API uses the sin6_flowinfo member on the
IPv6 socket address structure (sockaddr_in6).

The draft is, at this moment, written separately from the IPv6
basic/advanced API RFCs [Gilligan, 2000; Stevens, 1999] , as there can
be many discussion items.  The ultimate goal of the draft is to be a
part of the IPv6 basic/advanced API.


1.  Background

The IPv6 flow label field is a 20bit field in the IPv6 header.  The
field has no IPv4 counterpart.  The IPv6 specification [Deering, 1998]
supplies suggested usage of the field.

The field is intended to identify a "flow", a set of packets from a
particular source to a particular destination.  The flow label field is


HAGINO                  Expires: October 11, 2001               [Page 1]


DRAFT                 API for IPv6 flow label field           April 2001

set by the originating IPv6 node, in a pseudorandom manner.  The value
will help intermediate routers to identify "flows", without looking into
payload data or chasing an extension header chain.

For the flow label field to be useful, the source node should carefully
pick the value, to satisfy the following constraints:

o The value should be pseudorandom, to help routers make a hash table
  with it.

o The value should not be used for multiple different flows at the same
  time.

o The value should not be reused for some amonut of time, after a flow
  is terminated (otherwise, intermediate routers may mistakenly identify
  flows).

IPv6 specification does not define whether the field can be rewritten by
intermediate routers, or the field should be kept untouched.  It was to
let future QoS protocols make the choice.  For example, RSVP [Braden,
1997] assumes that the field is kept untouched until the packet reaches
the final destination.  In this document, following the assumption in
the RSVP document, we assume that the field should not be modified by
intermediate routers.

There is no known application which needs to inspect the flow label
field on inbound packet.  Also, there is no known application which
wants to put a specific value to the flow label field.

NOTE: in IETF IPv6 working group, there is an ongoing discussion about
the semantics of flow label field.  There are three proposals: (1) the
field is for an end-to-end value (set by source, no rewrite on
intermediate routers), (2) the field is an hop-by-hop value (rewritable
on intermediate routers), or (3) hybrid.  As noted above, the draft
assumes (1), based on existing uses of flow label field - which is RSVP.


2.  Outbound traffic

After the connect(2) system call is issued for a socket with a specific
IPv6 address (non-unspecified address), the kernel will automatically
fill in the flow label field, with a value selected for the socket.  The
value will be selected on connect(2), and will be used for subsequent
outgoing packets from the socket.  The kernel is responsible to pick a
suitable (pseudorandom and unique) value for the flow label field.

If no connect(2) system call was issued for a socket, the packets from
the socket will have an unspecified flow label value (zero).  When
multiple connect(2) system calls were issued for a socket, a new value
must be picked for the flow label field, every time the connect(2)
system call was issued.



HAGINO                  Expires: October 11, 2001               [Page 2]


DRAFT                 API for IPv6 flow label field           April 2001

With getsockname(2), an application can grab the flow label value picked
by the kernel, into the sin6_flowinfo member.  sin6_flowinfo member
carries the value in network byteorder.  The topmost 12 bits of the
sin6_flowinfo member must be set to 0.

Sample code would be as follows:

     struct sockaddr_in6 src, dst, altdst;
     u_int32_t value;  /* the value for flow label */
     int s;            /* socket */
     socklen_t slen;

     slen = sizeof(dst);
     dst.sin6_flowinfo = 0;  /* must be zero */
     connect(s, (struct sockaddr *)&dst, slen);

     /* sent with the flow label field filled */
     send(s, buf, buflen);

     /* obtain the flow label value */
     slen = sizeof(src);
     getsockname(s, (struct sockaddr *)&src, &slen);
     printf("flowlabel=%x\n", ntohl(src.sin6_flowinfo & IPV6_FLOWLABEL_MASK));

If an application wishes to disable the kernel behavior and wishes to
use an unspecified value (zero) in the flow label field, the application
should issue the following setsockopt(2), prior to the connect(2) system
call.  The default value for the socket option is implementation-
dependent.  A portable application should inspect the initial setting by
using getsockopt(2).

     const int off = 0;
     const int on = 1;
     int s;  /* socket */

     /* disables automatic flow label */
     setsockopt(s, IPPROTO_IPV6, IPV6_AUTOFLOWLABEL, &off, sizeof(off));
     /* enables automatic flow label */
     setsockopt(s, IPPROTO_IPV6, IPV6_AUTOFLOWLABEL, &on, sizeof(on));

The kernel should honor the definition of "flow" when filling in flow
label field.  For example, let us consider the suggestion in the IPv6
specification [Deering, 1998] .  In the following cases, the kernel
should make a special consideration.  The kernel should fill the flow
label field with an unspecified value (zero), or pick a new value.

(a) The packet goes to a different IPv6 destination, from the
    destination specified previously with a connect(2) system call.  The
    situation happens with sendto(2) or sendmsg(2) system calls with a
    destination specified.




HAGINO                  Expires: October 11, 2001               [Page 3]


DRAFT                 API for IPv6 flow label field           April 2001

(b) The packet uses a different IPv6 source address than before.  It
    happens when a bind(2) system call is issued.

(c) The packet carries different IPv6 extension headers from we have
    previously used.  The situation could be detected by the use of IPv6
    advanced API setsockopt(2), or by the presense of ancillary data
    items on sendmsg(2).


3.  Inbound traffic

We define no option to inspect the flow label field on inbound traffic,
at this moment.

Even though we are able to grab the outgoing flow label value with
getsockname(2), the value should not affect the socket selection against
inbound traffic.

Note:
     Even if we are to define some mechanism to inspect the value on
     inbound packets, we should not use the sin6_flowinfo member for
     this.  There are many applications which do connect(2) or
     sendto(2), with the value returned from recvfrom(2) or
     getpeername(2).


4.  sin6_flowinfo field

The draft defines no valid operation where a value is passed, from an
application to the kernel, via the sin6_flowinfo member.  When the
application issues system calls to the kernel, the application should
fill the sin6_flowinfo member with 0, as suggested in IPv6 basic API.


5.  Issues

o Interaction with RSVP.  Is getsockname(2) enough to implement RSVP
  application?

o Is it necessary for an application to specify the flow label value
  manually?  In this case, how should we check if the value is suitable
  enough?  (how to check the number collision?)

o The document assumes that the granularity of flows is equal to the
  granularity of sockets, or connect(2) system calls.  As we still do
  not have wide consensus about what the word "flow" means, this could
  be controversial; for example, some may want multiple flows for a TCP
  session, some may want to consider multiple TCP sessions as a single
  flow.





HAGINO                  Expires: October 11, 2001               [Page 4]


DRAFT                 API for IPv6 flow label field           April 2001

6.  Security consideration

The document introduces no new security issue.

The presense of a flow label value may help wiretappers to identify a
flow out of packets on the wire.


References

Gilligan, 2000.
R. Gilligan, S. Thomson, J. Bound, and W. Stevens, "Basic Socket
Interface Extensions for IPv6," internet draft (May 2000). work in
progress material.

Stevens, 1999.
W. Richard Stevens, Matt Thomas, and Eric Nordmark, "Advanced Sockets
API for IPv6," internet draft (October 1999). work in progress material.

Deering, 1998.
S. Deering and R. Hinden, "Internet Protocol, Version 6 (IPv6)
Specification" in RFC2460 (December 1998). ftp://ftp.isi.edu/in-
notes/rfc2460.txt.

Braden, 1997.
R. Braden, L. Zhang, S. Berson, S. Herzog, and S. Jamin, "Resource
ReSerVation Protocol (RSVP) -- Version 1 Functional Specification" in
RFC2205 (September 1997). ftp://ftp.isi.edu/in-notes/rfc2205.txt.


Acknowledgements

The document was made possible by numerous invaluable comments from
members of WIDE research group and KAME team.


Change history

None.


Author's address

     Jun-ichiro itojun HAGINO
     Research Laboratory, Internet Initiative Japan Inc.
     Takebashi Yasuda Bldg.,
     3-13 Kanda Nishiki-cho,
     Chiyoda-ku, Tokyo 101-0054, JAPAN
     Tel: +81-3-5259-6350
     Fax: +81-3-5259-6351
     Email: itojun@iijlab.net



HAGINO                  Expires: October 11, 2001               [Page 5]


DRAFT                 API for IPv6 flow label field           April 2001























































HAGINO                  Expires: October 11, 2001               [Page 6]