draft.xml

<?xml version="1.0" encoding="US-ASCII"?>

<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [

<!ENTITY RFC2119 SYSTEM
         "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC3552 SYSTEM
         "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3552.xml">
<!ENTITY RFC4429 SYSTEM
         "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4429.xml">
<!ENTITY RFC7873 SYSTEM
         "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7873.xml">
<!ENTITY RFC7934 SYSTEM
         "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7934.xml">

]>

<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- For a complete list and description of processing instructions (PIs),
     please see http://xml.resource.org/authoring/README.html. -->
<?rfc strict="yes" ?>
<?rfc toc="yes"?>
<?rfc tocdepth="4"?>
<?rfc symrefs="yes"?>
<?rfc sortrefs="yes" ?>
<?rfc compact="yes" ?>
<?rfc subcompact="no" ?>

<rfc category="exp"
     docName="draft-kline-6man-v6addrs-api-00"
     ipr="trust200902">

    <front>
        <title abbrev="IPv6 Addrs API">
IPv6 Multiple Addresses API
        </title>

        <author fullname="Erik Kline" initials="E." surname="Kline">
            <organization>Google Japan, G.K.</organization>

            <address>
                <postal>
                    <street>6-10-1 Roppongi</street>
                    <city>Minato</city>
                    <region>Tokyo</region>
                    <code>106-6144</code>
                    <country>JP</country>
                </postal>

                <phone>+81 03 6384 9000</phone>

                <email>ek@google.com</email>
            </address>
        </author>

        <date year="2017"/>

        <area>General</area>
        <workgroup>Internet Engineering Task Force</workgroup>

        <keyword>IPv6</keyword>
        <keyword>addresses</keyword>
        <keyword>API</keyword>

        <abstract>
            <t>
<xref target="RFC7934">RFC 7934</xref> recommends that general-purpose hosts
be given multiple addresses for current and future application needs. This
document describes the requirements for an API by which applications can
request multiple addresses and the requirements for host operating systems
supporting such an API.
            </t>
        </abstract>
    </front>

<!--

- specify what happens to requests at process fork time
- specify that they are all privacy addrs, period.
- add per-origin example
- perhaps add ifup/ifdown API, since ifname might be a required argument

-->

    <middle>
        <section title="Introduction">
            <t>
<xref target="RFC7934">RFC 7934</xref> recommends that general-purpose hosts
be given multiple addresses for current and future application needs. This
document describes the requirements for an API by which applications can
request multiple addresses and the requirements for host operating systems
supporting such an API.
            </t>
            <t>
XXX: expound a bit more?
            </t>

            <section title="Requirements Language">
                <t>
The key words "MUST", "MUST NOT", "REQUIRED", "SHALL", "SHALL NOT", "SHOULD",
"SHOULD NOT", "RECOMMENDED", "MAY", and "OPTIONAL" in this document are to be
interpreted as described in <xref target="RFC2119">RFC 2119</xref>.
                </t>
            </section>
        </section>

        <section title="Motivating Use Cases">
            <section title="Ephemeral Addresses">
                <t>
Applications may want to obtain an address for some ephemeral use case.
These may be desirable for privacy purposes, injecting some measure of
randomness into communications, or for tracking application activity on a
per-application basis. One hypothetical example might be a DNS recursive
resolver that spreads queries across multiple addresses in order to increase
its resistance to cache-poisoning attacks in situations where
<xref target="RFC7873">DNS cookies</xref> may not be reliably available.
                </t>
                <t>
In these cases, specific port reservations are not required. This may be
because some explicit bind() will take place upon notification of the
availability of a new address, or because a listening socket is bound to
a wildcard address and the operating system is expected to deliver traffic
at the listening port on the new address to the application.
                </t>
                <t>
XXX: the cleanup from this, where other applications may have used an address
and it cannot easily be freed may indicate that this use case is not really
worth the effort. Alternatively, there might be some policy limiting the
number of simultaneous "shared" addresses.
                </t>
            </section>

            <section title="Exclusive-use Addresses">
                <t>
Some applications may need "exclusive-use addresses". In these use cases, the
application wants to control both all traffic originating from and received
at this address. Such traffic may be originated and received by the application
itself, e.g. a 464xlat CLAT daemon. Alternatively, the application may wish to
delegate the flow of traffic to another application, likely in coordination
with other operating system functions, e.g. an application controlling a
virtual machine (VM) for which it is attempting to arrange minimal IPv6
network connectivity.
                </t>
            </section>
        </section>

        <section title="API Requirements">
            <t>
IPv6 addressing can change dynamically in response to changes in the network
(i.e. due to events other than administrative action on the host itself). If
IPv6 optimistic addresses (<xref target="RFC4429"/>) are used, an address might
fail Duplicate Address Detection and need to be withdrawn from use. Similarly,
IPv6 prefixes from which addresses are formed might become deprecated via
Router Advertisements (and may also transition from deprecated back to valid)
or they may expire when a delegated prefix expires (e.g. without a successful
DHCPv6 renewal).
            </t>
            <t>
Similarly, multiple IPv6 prefixes may be available for creating addresses via
this API.  There may also be multiple network interfaces with advertised
prefixes from which an address might be formed.
            </t>
            <t>
It is therefore a meta-requirement for this API that these complexities MUST
be explicitly supported. Failure to do so would mean the spread of inflexible
APIs yielding brittle applications, unable to adapt sensibly to changing
network conditions.
            </t>

            <section title="Request">
                <t>
An API implementation MUST include a method by which an application can request
an address ("ADDR_REQUEST").
                </t>
                <t>
TODO: possible arguments? address type, timeout, callback function, interface?
Should it be possible to request a specific prefix, or a specific IID on all
available prefixes?
                </t>
                <t>
The return type of the ADDR_REQUEST method must be either an error, if an
error can be quickly known (e.g. invalid arguments, insufficient permissions,
et cetera) or a token suitable for use in other API calls.
                </t>
            </section>
            <section title="Release">
                <t>
An API implementation MUST include a method by which an application can release
a previously allocated address ("ADDR_RELEASE"). This method SHOULD take as
input the non-error return value from the ADDR_REQUEST method.
                </t>
            </section>
            <section title="Asynchronous Notification">
                <t>
TODO: discussion of requirements for async notifications; callbacks?
signals? (shudder)
callback_mechanism
                </t>
                <t>
                    <list style="symbols">
                        <t>
MUST notify applications when an address request has been satisfied (if it was
not synchronously satisfiable at ADDR_REQUEST time).
                        </t>
                        <t>
MUST notify applications when an address is deprecated, when DAD fails (if
optimistic addrs are in use), ... any other time the address becomes unusable.
                        </t>
                        <t>
Similarly, MUST notify applications when an address that has not been released
via ADDR_RELEASE becomes usable after a prior unusable notification
(e.g. when "un-deprecated" if the prefix lifetime is renewed).
                        </t>
                    </list>
                </t>
            </section>
        </section>

        <section title="Requirements for Supporting Operating Systems">
            <t>
Supporting host operating systems MUST support an asynchronous API. The
dynamic nature of IPv6 means, among other things, that the prefix from which
an address was formed might become deprecated at any time (and similarly
could theoretically transition from deprecated back to valid). Applications
MUST be able to receive notifications of such changes.
            </t>
            <t>
The callback and asynchronous notification mechanisms SHOULD work well with
the operating systems' popular asynchronous event loop APIs.
            </t>
            <t>
At process exit: release and remove all exclusive-use addresses and mark
shared-use addresses as deprecated (unless they have been explicitly handed
out to another application via this API).
            </t>
            <t>
Shared-use addresses may be reused (given back to application in response to
another request) if no new addresses may be formed. Alternatively, an error
condition may be signaled.
            </t>
            <t>
An operating system MAY satisfy ADDR_REQUEST calls with optimistic addresses.
If this is supported, notifications of the failure of this address to become
validated (DAD) MUST be delivered to the application.
            </t>
            <t>
An operating system MAY perform additional "usability" checks on an address
(beyond just DAD) when asynchronously satisfying an ADDR_REQUEST call. This
might include, for example, verifying Neighbor Unreachability Detection from
this address to on-link routers completes successfully. The operating system
might even perform a captive portal connectivity check from this address.
            </t>
        </section>

        <section title="Open Issues">
            <t>
This section will be replaced by a summary of discussion of issues rejected
here.  Decisions adopted will necessarily be incorporated elsewhere in this
document.
            </t>
            <t>
Should all requests be exclusive, even if not required? This is likely to be
simpler to implement and manage. Might make it harder to share address use
among multiple apps if that were desired.
            </t>
            <t>
How to specify requests when multiple prefixes could theoretically be used
to satisfy the request? Avoid giving the same IID on multiple prefixes, for
sure.  But otherwise?
            </t>
        </section>
<!--
    <section anchor="simple_list" title="Simple List">
      <t>List styles: 'empty', 'symbols', 'letters', 'numbers', 'hanging',
      'format'.</t>

      <t><list style="symbols">
          <t>First bullet</t>

          <t>Second bullet</t>
        </list> You can write text here as well.</t>
    </section>

    <section title="Figures">
      <t>Figures should not exceed 69 characters wide to allow for the indent
      of sections.</t>

      <figure align="center" anchor="xml_happy">
        <preamble>Preamble text - can be omitted or empty.</preamble>

        <artwork align="left"><![CDATA[
._______________________.
| Use XML, be Happy :-) |
|_______________________|
            ]]></artwork>

        <postamble>Cross-references allowed in pre- and postamble.</postamble>
      </figure>

      <t>The CDATA means you don't need to escape meta-characters (especially
      &lt;&nbsp;(&amp;lt;) and &amp;&nbsp;(&amp;amp;)) but is not essential.
      Figures may also have a title attribute but it won't be displayed unless
      there is also an anchor. White space, both horizontal and vertical, is
      significant in figures even if you don't use CDATA.</t>
    </section>
-->

<!--
This PI places the pagebreak correctly (before the section title) in the text output.
<?rfc needLines="8" ?>
-->

<!--
    <section title="Subsections and Tables">
      <section title="A Subsection">
        <t>By default 3 levels of nesting show in table of contents but that
        can be adjusted with the value of the "tocdepth" processing
        instruction.</t>
      </section>

      <section title="Tables">
        <t>.. are very similar to figures:</t>

        <texttable anchor="table_example" title="A Very Simple Table">
          <preamble>Tables use ttcol to define column headers and widths.
          Every cell then has a "c" element for its content.</preamble>

          <ttcol align="center">ttcol #1</ttcol>

          <ttcol align="center">ttcol #2</ttcol>

          <c>c #1</c>

          <c>c #2</c>

          <c>c #3</c>

          <c>c #4</c>

          <c>c #5</c>

          <c>c #6</c>

          <postamble>which is a very simple example.</postamble>
        </texttable>
      </section>
    </section>

    <section anchor="nested_lists" title="More about Lists">
      <t>Lists with 'hanging labels': the list item is indented the amount of
      the hangIndent: <list hangIndent="8" style="hanging">
          <t hangText="short">With a label shorter than the hangIndent.</t>

          <t hangText="fantastically long label">With a label longer than the
          hangIndent.</t>

          <t hangText="vspace_trick"><vspace blankLines="0" />Forces the new
          item to start on a new line.</t>
        </list></t>
-->

<!--
It would be nice to see the next piece (12 lines) all on one page.
<?rfc needLines="12" ?>
-->

<!--
      <t>Simulating more than one paragraph in a list item using
      &lt;vspace&gt;: <list style="letters">
          <t>First, a short item.</t>

          <t>Second, a longer list item.<vspace blankLines="1" /> And
          something that looks like a separate pararaph..</t>
        </list></t>

      <t>Simple indented paragraph using the "empty" style: <list
          hangIndent="10" style="empty">
          <t>The quick, brown fox jumped over the lazy dog and lived to fool
          many another hunter in the great wood in the west.</t>
        </list></t>

      <section title="Numbering Lists across Lists and Sections">
        <t>Numbering items continuously although they are in separate
        &lt;list&gt; elements, maybe in separate sections using the "format"
        style and a "counter" variable.</t>

        <t>First list: <list counter="reqs" hangIndent="4" style="format R%d">
            <t>#1</t>

            <t>#2</t>

            <t>#3</t>
          </list> Specify the indent explicitly so that all the items line up
        nicely.</t>

        <t>Second list: <list counter="reqs" hangIndent="4" style="format R%d">
            <t>#4</t>

            <t>#5</t>

            <t>#6</t>
          </list></t>
      </section>

      <section title="Where the List Numbering Continues">
        <t>List continues here.</t>

        <t>Third list: <list counter="reqs" hangIndent="4" style="format R%d">
            <t>#7</t>

            <t>#8</t>

            <t>#9</t>

            <t>#10</t>
          </list> The end of the list.</t>
      </section>
    </section>

    <section anchor="codeExample"
             title="Example of Code or MIB Module To Be Extracted">
      <figure>
        <preamble>The &lt;artwork&gt; element has a number of extra attributes
        that can be used to substitute a more aesthetically pleasing rendition
        into HTML output while continuing to use the ASCII art version in the
        text and nroff outputs (see the xml2rfc README for details). It also
        has a "type" attribute. This is currently ignored except in the case
        'type="abnf"'. In this case the "artwork" is expected to contain a
        piece of valid Augmented Backus-Naur Format (ABNF) grammar. This will
        be syntax checked by xml2rfc and any errors will cause a fatal error
        if the "strict" processing instruction is set to "yes". The ABNF will
        also be colorized in HTML output to highlight the syntactic
        components. Checking of additional "types" may be provided in future
        versions of xml2rfc.</preamble>

        <artwork><![CDATA[

/**** an example C program */

#include <stdio.h>

void
main(int argc, char *argv[])
{
    int i;

    printf("program arguments are:\n");
    for (i = 0; i < argc; i++) {
        printf("%d: \"%s\"\n", i, argv[i]);
    }

    exit(0);
} /* main */

/* end of file */

            ]]></artwork>
      </figure>
    </section>
-->

        <section anchor="Acknowledgements" title="Acknowledgements">
            <t>
            </t>
        </section>

        <section anchor="IANA" title="IANA Considerations">
            <t>
This memo includes no request to IANA.
            </t>
        </section>

        <section anchor="Security" title="Security Considerations">
            <t>
Oh dear, yes, the security implications...
            </t>
            <t>
All drafts are required to have a security considerations section.
See <xref target="RFC3552">RFC 3552</xref> for a guide.
            </t>
        </section>
    </middle>

    <back>
        <references title="Normative References">
            &RFC2119;

<!--
            <reference anchor="min_ref">
                <front>
                    <title>Minimal Reference</title>

                    <author initials="authInitials" surname="authSurName">
                        <organization></organization>
                    </author>

                    <date year="2006" />
                </front>
            </reference>
-->
        </references>

        <references title="Informative References">
            &RFC3552;
            &RFC4429;
            &RFC7873;
            &RFC7934;

<!--
            <reference anchor="DOMINATION"
                       target="http://www.example.com/dominator.html">
                <front>
                    <title>Ultimate Plan for Taking Over the World</title>

                    <author>
                        <organization>Mad Dominators, Inc.</organization>
                    </author>

                    <date year="1984" />
                </front>
            </reference>
-->
        </references>

        <section anchor="app-additional" title="Additional Stuff">
            <t>This becomes an Appendix.</t>
        </section>
    </back>
</rfc>