Internet Engineering Task Force                 Jun-ichiro itojun HaginoINTERNET-DRAFT                                   IIJ Research LaboratoryExpires: October 11, 2001                                 April 11, 2001                  Socket API for IPv6 flow label field                 draft-itojun-ipv6-flowlabel-api-01.txtStatus of this MemoThis document is an Internet-Draft and is in full conformance with allprovisions of Section 10 of RFC2026.Internet-Drafts are working documents of the Internet Engineering TaskForce (IETF), its areas, and its working groups.  Note that other groupsmay also distribute working documents as Internet-Drafts.Internet-Drafts are draft documents valid for a maximum of six monthsand may be updated, replaced, or obsoleted by other documents at anytime.  It is inappropriate to use Internet-Drafts as reference materialor to cite them other than as ``work in progress.''To view the list Internet-Draft Shadow Directories, seehttp://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.AbstractThe draft outlines a socket API proposal for controlling the flow labelfield in the IPv6 header.  The API uses the sin6_flowinfo member on theIPv6 socket address structure (sockaddr_in6).The draft is, at this moment, written separately from the IPv6basic/advanced API RFCs [Gilligan, 2000; Stevens, 1999] , as there canbe many discussion items.  The ultimate goal of the draft is to be apart of the IPv6 basic/advanced API.1.  BackgroundThe IPv6 flow label field is a 20bit field in the IPv6 header.  Thefield 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 aparticular source to a particular destination.  The flow label field isHAGINO                  Expires: October 11, 2001               [Page 1]DRAFT                 API for IPv6 flow label field           April 2001set by the originating IPv6 node, in a pseudorandom manner.  The valuewill help intermediate routers to identify "flows", without looking intopayload data or chasing an extension header chain.For the flow label field to be useful, the source node should carefullypick 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 byintermediate routers, or the field should be kept untouched.  It was tolet future QoS protocols make the choice.  For example, RSVP [Braden,1997] assumes that the field is kept untouched until the packet reachesthe final destination.  In this document, following the assumption inthe RSVP document, we assume that the field should not be modified byintermediate routers.There is no known application which needs to inspect the flow labelfield on inbound packet.  Also, there is no known application whichwants to put a specific value to the flow label field.NOTE: in IETF IPv6 working group, there is an ongoing discussion aboutthe semantics of flow label field.  There are three proposals: (1) thefield is for an end-to-end value (set by source, no rewrite onintermediate routers), (2) the field is an hop-by-hop value (rewritableon intermediate routers), or (3) hybrid.  As noted above, the draftassumes (1), based on existing uses of flow label field - which is RSVP.2.  Outbound trafficAfter the connect(2) system call is issued for a socket with a specificIPv6 address (non-unspecified address), the kernel will automaticallyfill in the flow label field, with a value selected for the socket.  Thevalue will be selected on connect(2), and will be used for subsequentoutgoing packets from the socket.  The kernel is responsible to pick asuitable (pseudorandom and unique) value for the flow label field.If no connect(2) system call was issued for a socket, the packets fromthe socket will have an unspecified flow label value (zero).  Whenmultiple connect(2) system calls were issued for a socket, a new valuemust 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 2001With getsockname(2), an application can grab the flow label value pickedby the kernel, into the sin6_flowinfo member.  sin6_flowinfo membercarries the value in network byteorder.  The topmost 12 bits of thesin6_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 touse an unspecified value (zero) in the flow label field, the applicationshould issue the following setsockopt(2), prior to the connect(2) systemcall.  The default value for the socket option is implementation-dependent.  A portable application should inspect the initial setting byusing 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 flowlabel field.  For example, let us consider the suggestion in the IPv6specification [Deering, 1998] .  In the following cases, the kernelshould make a special consideration.  The kernel should fill the flowlabel 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 trafficWe 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 withgetsockname(2), the value should not affect the socket selection againstinbound 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 fieldThe draft defines no valid operation where a value is passed, from anapplication to the kernel, via the sin6_flowinfo member.  When theapplication issues system calls to the kernel, the application shouldfill the sin6_flowinfo member with 0, as suggested in IPv6 basic API.5.  Issueso 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 20016.  Security considerationThe document introduces no new security issue.The presense of a flow label value may help wiretappers to identify aflow out of packets on the wire.ReferencesGilligan, 2000.R. Gilligan, S. Thomson, J. Bound, and W. Stevens, "Basic SocketInterface Extensions for IPv6," internet draft (May 2000). work inprogress material.Stevens, 1999.W. Richard Stevens, Matt Thomas, and Eric Nordmark, "Advanced SocketsAPI 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, "ResourceReSerVation Protocol (RSVP) -- Version 1 Functional Specification" inRFC2205 (September 1997). ftp://ftp.isi.edu/in-notes/rfc2205.txt.AcknowledgementsThe document was made possible by numerous invaluable comments frommembers of WIDE research group and KAME team.Change historyNone.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.netHAGINO                  Expires: October 11, 2001               [Page 5]DRAFT                 API for IPv6 flow label field           April 2001HAGINO                  Expires: October 11, 2001               [Page 6]