draft.xml

<?xml version="1.0" encoding="US-ASCII"?>
<!-- This template is for creating an Internet Draft using xml2rfc,
     which is available here: http://xml.resource.org. -->
<!DOCTYPE rfc SYSTEM "rfc2629.dtd" [
<!-- One method to get references from the online citation libraries.
     There has to be one entity for each item to be referenced.
     An alternate method (rfc include) is described in the references. -->

<!ENTITY RFC1122 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1122.xml">
<!ENTITY RFC1918 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.1918.xml">
<!ENTITY RFC2119 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.2119.xml">
<!ENTITY RFC3493 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3493.xml">
<!ENTITY RFC3879 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.3879.xml">
<!ENTITY RFC4191 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.4191.xml">
<!ENTITY RFC6418 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6418.xml">
<!ENTITY RFC6724 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.6724.xml">
<!ENTITY RFC7556 SYSTEM "http://xml.resource.org/public/rfc/bibxml/reference.RFC.7556.xml">
]>
<?xml-stylesheet type='text/xsl' href='rfc2629.xslt' ?>
<!-- used by XSLT processors -->
<!-- For a complete list and description of processing instructions (PIs),
     please see http://xml.resource.org/authoring/README.html. -->
<!-- Below are generally applicable Processing Instructions (PIs) that most I-Ds might want to use.
     (Here they are set differently than their defaults in xml2rfc v1.32) -->
<?rfc strict="yes" ?>
<!-- give errors regarding ID-nits and DTD validation -->
<!-- control the table of contents (ToC) -->
<?rfc toc="yes"?>
<!-- generate a ToC -->
<?rfc tocdepth="4"?>
<!-- the number of levels of subsections in ToC. default: 3 -->
<!-- control references -->
<?rfc symrefs="yes"?>
<!-- use symbolic references tags, i.e, [RFC2119] instead of [1] -->
<?rfc sortrefs="yes" ?>
<!-- sort the reference entries alphabetically -->
<!-- control vertical white space
     (using these PIs as follows is recommended by the RFC Editor) -->
<?rfc compact="yes" ?>
<!-- do not start each main section on a new page -->
<?rfc subcompact="no" ?>
<!-- keep one blank line between list items -->
<!-- end of list of popular I-D processing instructions -->
<rfc category="info"
     ipr="trust200902"
     docName="draft-kline-mpvd-endsystem-model-00">

  <!-- category values: std, bcp, info, exp, and historic
     ipr values: full3667, noModification3667, noDerivatives3667
     you can add the attributes updates="NNNN" and obsoletes="NNNN"
     they will automatically be output with "(if approved)" -->

    <!-- NOTES

    End System model

    - it's about keeping separate routing and addressing information
      per pvd

    - both the weak and strong ES models are special cases of the MPVD model:
        - Weak ES has one and only one provisioning domain
        - Strong ES enforces one (and only one) provisioning domain per
          interface.
        - PVD-aware ES permits m:n pvds to interfaces

    - what to do about loopback.  either it's its own PVD, or part of all PVDs

    - walk through 7556 section 5 and try to be slightly more specific?
        - phrase things

    - use of the word "originating" for packets to distinguish
      clear from forwarding.

    - rfc1122#section-3.3.4.2
        - re (1) SHOULD send from destination address and MUST send from
          an address associated with the provisioning domain by which the
          packet was received

        - application must be able to specify the pvd to use for route and
          source address selection

    - Jen's multihoming draft, and fred's document to find MUST behaviour

    - use uRPF to find which pvd applies for incoming / outgoing traffic

     -->

  <front>
    <title abbrev="MPvD Aware End System Model"
      >Multiple Provisioning Domain Aware End System Model</title>

    <author fullname="Erik Kline"
            initials="E." surname="Kline">
      <organization>Google Japan GK</organization>
      <address>
        <postal>
          <street>6-10-1 Roppongi</street>
          <street>Mori Tower, 44th floor</street>
          <city>Minato</city>
          <region>Tokyo</region>
          <code>106-6144</code>
          <country>JP</country>
        </postal>
        <phone></phone>
        <email>ek@google.com</email>
      </address>
    </author>

    <date/>

    <!-- Meta-data Declarations -->

    <area>General</area>

    <workgroup>Internet Engineering Task Force</workgroup>

    <!-- WG name at the upperleft corner of the doc,
         IETF is fine for individual submissions.
	 If this element is not present, the default is "Network Working Group",
         which is used by the RFC Editor as a nod to the history of the IETF. -->

    <keyword>api</keyword>
    <keyword>application</keyword>
    <keyword>mif</keyword>
    <keyword>mpvd</keyword>
    <keyword>pvd</keyword>

    <abstract>
      <t>
<xref target="RFC7556">RFC 7556</xref> provides the essential conceptual
guidance an API designer would need to support use of PvDs.  This document
aims to capture the requirements for an API that can be used by applications
that would be considered "advanced", according to
<eref target="https://tools.ietf.org/html/rfc7556#section-6.3"
      >section 6.3</eref> of <xref target="RFC7556">RFC 7556</xref>.  The
<eref target="https://tools.ietf.org/html/rfc7556#section-6.1"
      >"basic"</eref> and
<eref target="https://tools.ietf.org/html/rfc7556#section-6.2"
      >"intermediate"</eref> API support levels can in principle be implemented
by means of layers wrapping the advanced API.
      </t>
    </abstract>
  </front>


  <middle>
    <section title="Introduction">
      <t>
<xref target="RFC7556">RFC 7556</xref> provides the essential conceptual
guidance an API designer would need to support use of PvDs.  This document
aims to capture the requirements for an API that can be used by applications
that would be considered "advanced", according to
<eref target="https://tools.ietf.org/html/rfc7556#section-6.3"
      >section 6.3</eref> of <xref target="RFC7556">RFC 7556</xref>.  The
<eref target="https://tools.ietf.org/html/rfc7556#section-6.1"
      >"basic"</eref> and
<eref target="https://tools.ietf.org/html/rfc7556#section-6.2"
      >"intermediate"</eref> API support levels can in principle be implemented
by means of layers wrapping the advanced API.
      </t>
      <t>
This document also attempts to make some of the API implementation requirements
more concrete by discussion and example.
      </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 anchor="high_level" title="High level requirements">
      <t>
As described in
<eref target="https://tools.ietf.org/html/rfc7556#section-2">section 2</eref>
of <xref target="RFC7556">RFC 7556</xref>, a Provisioning Domain ("PvD") is
fundamentally a "consistent set of network configuration information."
This includes information like:
        <list style="symbols">
<t>the list of participating interfaces</t>
<t>IPv4 and IPv6 addresses</t>
<t>IPv4 and IPv6 routes: both default routes and more specifics
   (such as may be learned via <xref target="RFC4191">RFC 4191</xref>
    Route Information Options ("RIOs"))</t>
<t>DNS nameservers, search path, et cetera</t>
<t>HTTP proxy configuration</t>
        </list>
and undoubtedly many more configuration elements yet to be specified (like
metering hints, transmission medium and speed, captive portal URL, et cetera).
      </t>
      <t>
This configuration information as a whole may not be able to be learned
atomically, may need to be synthesized from multiple sources including
administrative provisioning, and cannot be presumed to be unchanging over the
lifetime of a node's association with a given PvD.
      </t>
      <t>
In order for an application to make
<eref target="https://tools.ietf.org/html/rfc7556#section-5.2"
  >consistent use</eref> of a given PvD's network configuration several
requirements are placed upon the API itself and the host operating system
providing the API.
      </t>

      <section anchor="hi_api" title="Requirements for an API">
        <t>
At the highest level, the requirements for an API that enables applications to
make sophisticated use of multiple PvDs amount to providing mechanisms by
which they can:
          <list counter="reqs" hangIndent="4" style="format R%d">
            <t>
observe accessible PvDs
<vspace blankLines="1"/>
It MUST be possible for an application to be informed of the set of all PvDs it
can currently access, and to be informed of changes to this set.
            </t>
            <t>
observe configuration elements of an accessible PvD
<vspace blankLines="1"/>
It MUST be possible to learn requested configuration information of any
accessible PvD, and to be informed of any changes to the configuration
information comprising an accessible PvD.
            </t>
            <t>
scope networking functionality to a specified PvD
<vspace blankLines="1"/>
For every existing API function that interacts with the node's networking
stack, be it at a relatively high level like
<eref target="https://tools.ietf.org/html/rfc3493#section-6.1"
  >getaddrinfo()</eref> or at the level of something like Sockets API's
sendmsg(), there MUST be a means by which an application can specify the
PvD within which networking operations are to be restricted.
            </t>
            <t>
use one and only specified scope per networking functionality invocation
<vspace blankLines="1"/>
For every unique invocation of a networking API function, there MUST only be
one specified PvD to which networking functionality is to be restricted.
At any given point in an application's lifetime there MAY be several
encapsulating layers of <xref target="unspec_pvd">unspecified PvDs</xref>
through which the implementation must progressively search to find a specified
PvD, but ultimately a networking function MUST use one and only one PvD for
its operations, even if that PvD is a
<xref target="null_pvd">"null PvD"</xref>.
            </t>
            <t>
make consistent use of programmatic references to PvDs
<vspace blankLines="1"/>
For uniformity and simplicity, every PvD-aware API functional element
SHOULD use (as return values of function calls, function arguments, et cetera)
the same programmatic reference for PvDs, e.g. a construct containing a
<eref target="https://tools.ietf.org/html/draft-ietf-mif-mpvd-id"
  >PvD identifier</eref> or some equivalent shorthand reference token
(see <xref target="tokens"/> for a discussion of implementation considerations).
Regardless of the implementation strategy chosen, a given programmatic
reference MUST remain constant over the lifetime of the node's continuous
attachment to the PvD to which it refers (until a disconnection or
disassociation event occurs).  Additionally, references MAY change
with successive re-associations to the same PvD whereas PvD identifiers,
by definition, will not.
            </t>
          </list>
It is important to note that there is always a provisioning domain within which
networking functionality is scoped. For simply-connected hosts this may be the
<eref target="https://tools.ietf.org/html/rfc7556#section-2.2"
  >implicit PvD</eref> created by a single networking interface connected to a
traditional, shared LAN segment. For multihomed hosts the
"default provisioning domain" is likely a matter of policy, but MAY be a
"null" PvD, i.e. one completely devoid of networking configuration information
(no addresses, no routes, et cetera). See <xref target="concept_pvds"/> for
further discussion.
        </t>
        <t>
The utility of such an API (allowing applications to learn of and control the
scope of networking functionality) suggests that the Provisioning Domain is
perhaps a more useful operational definition for the original IPv6 concept
of a "site-local scope" than the <xref target="RFC3879">ill-fated</xref>,
<eref target="https://tools.ietf.org/html/rfc3879#section-2.5"
  >"ill-defined concept"</eref> of a site. It also suggests one possible way
by which operating system support for a PvD-aware API might be implemented.
        </t>
      </section>

      <section title="Requirements for supporting operating systems">
        <t>
The multiple PvD model of host behaviour is perhaps closer to the Strong End
System Model than the Weak End System Model characterized in
<xref target="RFC1122">RFC 1122</xref>
<eref target="https://tools.ietf.org/html/rfc1122#section 3.3.4.2"
  >section 3.3.4.2</eref>, but owing to its recognition of a many-to-many
relationship between interfaces and PvDs should be considered a unique model
unto itself.
        </t>
        <t>
In the PvD-aware End System Model, the "two key requirement issues related to
multihoming" are restated as:
          <list hangIndent="4" style="letters">
            <t>
A host MAY silently discard an incoming datagram whose destination address
does not correspond to any PvD associated with the physical (or virtual)
interface through which it is received.
            </t>
            <t>
A host MUST restrict itself to sending (non-source-routed) IP datagrams only
through the physical (or virtual) interfaces that correspond to the PvD
associated with the IP source address of the datagrams.
            </t>
          </list>
        </t>

        <t>
In order to support a PvD-aware application's use of multiple PVDs, several
additional requirements must be met by the host operating system, especially
when performing functions on behalf of applications or when no direct
application intervention is possible, as discussed in the following sections.
        </t>

        <section title="Source address selection">
          <t>
Whenever a source address is to be selected on behalf of an application it
is essential for consistent use that only source addresses belonging to the
specified PvD be used a candidate set. (See <xref target="RFC6418">RFC
6418</xref> <eref target="https://tools.ietf.org/html/rfc6418#section-3.5"
  >section 3.5</eref> for references to issues arising from poor source
address selection.)
          </t>
          <t>
For nodes following the PvD-aware End System Model,
<xref target="RFC6724">RFC 6724</xref>
<eref target="https://tools.ietf.org/html/rfc6724#section-4">section 4</eref>
is amended as follows:
            <list counter="reqs" hangIndent="4" style="format R%d">
              <t>
The candidate source addresses MUST be restricted to the set of unicast
addresses associated with the concurrently specified PvD.
<vspace blankLines="1"/>
Additionally, source address selection policies from PvDs other than the
concurrently specified PvD MUST NOT be applied.
              </t>
            </list>
          </t>
        </section>

        <section title="Route isolation">
          <t>
Whenever a routing lookup for a given destination is to be performed, it is
essential that only routes belonging to the currently specified PvD be
consulted. Applications and libraries that use the inherent routing
reachability check (and subsequent source address selection) performed during
something like the Sockets API connect() call on a UDP socket to learn
reachability information cheaply cannot function correctly otherwise.
<xref target="RFC6418">RFC 6418</xref>
<eref target="https://tools.ietf.org/html/rfc6418#section-4.2"
  >section 4.2</eref> contains more discussion and references to issues
arising from insufficiently isolated routing information.
          </t>

          <t>
For nodes following the PvD-aware End System Model:
            <list counter="reqs" hangIndent="4" style="format R%d">
              <t>
The set of routes consulted for any routing decision MUST be restricted to the
routes associated with the concurrently specified PvD.
              </t>
            </list>
          </t>
        </section>

        <section title="Automatic PvD metadata marking">
          <t>
In many cases, an application can examine a source address or the
destination address of a received datagram and use that address's association
with a given PvD to learn, for example, the PvD with which an incoming
connection may be associated. It may, however, be impossible for an application
to make this determination on its own if, for example, an incoming TCP
connection is destined to a <xref target="RFC1918">RFC 1918</xref> address
that happens to be configured in multiple PvDs at the same time. In such
circumstances, the supporting operating system will need to provide additional
assistance.
          </t>
          <t>
For nodes following the PvD-aware End System Model:
            <list counter="reqs" hangIndent="4" style="format R%d">
              <t>
When performing networking functionality on behalf of an application, the
supporting operating system MUST record and make available to the
application either (1) all the information the application might need to make
a determination of the applicable PvD on its own or (2) the API's PvD
programmatic reference directly.
<vspace blankLines="1"/>
A supporting operating system SHOULD record and make
available the API's PvD programmatic reference; other approaches invite
ambiguity among applications' interpretation of available information.
              </t>
            </list>
          </t>
        </section>

        <section title="Additional system and library support">
          <t>
Frequently, operating systems have several additional supporting libraries and
services for more advance networking functionality. Using the system's own
PvD API, and fulfilling the above requirements, it should be possible to
extend these services to provide correct per-PvD isolation of information and
enable consistent application use of PvDs.
          </t>
        </section>
      </section>
    </section>

    <section anchor="concept_pvds" title="Conceptual PvDs">
      <section anchor="default_pvd" title="The 'default' PvD">
        <t>
Because there is always one specified provisioning domain to which an
individual invocation of networking functionality is restricted
(<xref target="hi_api"/>) there must necessarily exist a system "default PvD".
This provisioning domain is the one which networking functionality MUST use
when no other specified PvD can be determined.
        </t>
        <t>
Using the system's default PvD enables support of
<eref target="https://tools.ietf.org/html/rfc7556#section-6.1">basic</eref>
uses of the PvD API (i.e. backward compatibility for unmodified applications).
        </t>
        <t>
The operating system MAY change the default PvD accordingly to policy. It is
expected that nodes will use a variety of information, coupled with
administrative policy, to promote one of any number of concurrently available
PvDs to be the system's default PvD.
        </t>
        <t>
          <list counter="reqs" hangIndent="4" style="format R%d">
            <t>
A PvD-aware API implementation MUST include a mechanism for applications to
learn the programmatic reference to the system's concurrent default PvD.
            </t>
            <t>
A PvD-aware API implementation SHOULD contain a mechanism enabling an
application to be notified of changes to the concurrent default PvD
in a comparatively efficient manner (i.e. more efficient than polling).
            </t>
          </list>
        </t>
      </section>

      <section anchor="unspec_pvd" title="The 'unspecified' PvD">
        <t>
An application may at some times wish to be specific about which PvD should be
used for networking operations and at other times may prefer to defer the
choice of specific PvD to one specified elsewhere (including the system
default PvD).
        </t>
        <t>
For example, if an application has <xref target="scoping">specified the PvD
to be used for all functions called by its process and child processes</xref>,
it may indicate that certain invocations should instead use the system default
PvD by using a programmatic reference to the "unspecified PvD".

          <list counter="reqs" hangIndent="4" style="format R%d">
            <t>
API implementors MUST reserve a programmatic reference to represent an
"unspecified PvD": an indication that the application defers the selection of
a specific PvD.
            </t>
            <t>
When invoked without a specific PvD, or with a programmatic reference to the
"unspecified PvD", networking functionality MUST find a specific PvD to be used
by examining the successive encapsulating layers of possible specificity
supported by the API (<xref target="scoping"/>), e.g. look first for a
"fiber-specific default" PvD, then a "thread-specific default" PvD, a
"process-specific default" PvD, and ultimately use the system's default PvD
if no other specified PvD can be found.
            </t>
          </list>
        </t>
      </section>

      <section anchor="null_pvd" title="The 'null' PvD">
        <t>
If there are no PvDs accessible to an application, whether as a matter of
<xref target="policy">policy (insufficient privileges)</xref> or as a matter
of natural circumstance (the node is not connected to any network), the
construct of a 'null' PvD may be useful to ensure networking functions fail
(and fail quickly).
          <list counter="reqs" hangIndent="4" style="format R%d">
            <t>
API implementors MAY reserve a programmatic reference to represent a
"null PvD": an unchanging provisioning domain devoid of any and all
networking configuration information.
            </t>
          </list>
It is possible for operating systems to enforce that only PvD-aware
applications may function normally by administratively configuring the default
PvD to be the "null PvD".
        </t>
      </section>

      <section anchor="loopback_pvd" title="The 'loopback' PvD">
        <t>
TBD: is it useful to have a "loopback" PvD, i.e. one consisting solely of all
addresses configured on the node and all locally delivered routes?
        </t>
      </section>
    </section>

    <section title="Requirements for new API functionality">
      <section title="Learning PvD availability">
        <t>
          <list counter="reqs" hangIndent="4" style="format R%d">
            <t>
A PvD-aware API MUST implement a mechanism whereby an application can receive
a set of the API's PvD programmatic references representing the complete set of
PvDs (both
<eref target="https://tools.ietf.org/html/rfc7556#section-2.1"> explicit</eref>
and
<eref target="https://tools.ietf.org/html/rfc7556#section-2.2"> implicit</eref>)
with which the node is currently associated.
            </t>
            <t>
A PvD-aware API implementation SHOULD contain a mechanism enabling an
application to be notified of changes in the above set of actively associated
PvDs in a comparatively efficient manner (i.e. more efficient than polling).
            </t>
          </list>
In may also be of use to applications to receive notifications of pending
changes to the set of currently connected PvDs.  For example, if it is known
that a connection to a PvD is scheduled to be terminated shortly, an
application may be able to take some appropriate action (migrate connections
to another PvD, send notifications, et cetera).
        </t>
      </section>

      <section
          title="Learning network configuration information comprising a PvD">
        <t>
          <list counter="reqs" hangIndent="4" style="format R%d">
            <t>
A PvD-aware API MUST include a mechanism whereby by an application, using the
API's PvD programmatic reference, can receive elements of the network
configuration information that comprise a PvD.
At a minimum, this mechanism MUST be capable of answering queries for:
<list style="symbols">
<t>the PvD identifier</t>
<t>all participating interfaces</t>
<t>all IPv4 and all non-deprecated IPv6 addresses</t>
<t>all configured DNS nameservers</t>
</list>
            </t>
          </list>
        </t>

        <t>
A PvD's network configuration information is neither guaranteed to be learned
atomically nor is it guaranteed to be static. Addresses, routes, and even
DNS nameservers and participating interfaces may each change over the lifetime
of the node's association to a given PvD. Timely notification of such changes
may be of particular importance to some applications.
          <list counter="reqs" hangIndent="4" style="format R%d">
            <t>
A PvD-aware API implementation SHOULD contain a mechanism enabling an
application to be notified of changes in the networking configuration
information comprising a PvD in a comparatively efficient manner
(i.e. more efficient than polling).
            </t>
          </list>
        </t>

        <t>
          <list counter="reqs" hangIndent="4" style="format R%d">
            <t>
A network configuration query API implementation SHOULD take extensibility
into account, to support querying for configuration information not yet
conceived of with minimal adverse impact to applications.
            </t>
          </list>
        </t>
      </section>

      <section anchor="scoping"
               title="Scoping functionality to a specific PvD">
        <t>
          <list counter="reqs" hangIndent="4" style="format R%d">
            <t>
A PvD-aware API implementation MUST include a mechanism for an application
to specify the programmatic reference of the PvD to which all networking
functionality MUST be restricted when not otherwise explicitly specified
(a configurable, application-specific "default PvD").
            </t>
            <t>
The API implementation MUST support setting such a "default PvD" for an
application's entire process (and by extension its child processes).
Additionally, the API SHOULD support an application setting a "default PvD"
at every granularity of "programming parallelization", i.e. not only
per-process, but also per-thread, per-fiber, et cetera. At every supported
layer of granularity, if no PvD reference has been set the next coarser
layer's setting MUST be consulted (up to and including the system's
default PvD) when identifying the specified PvD to be used.
            </t>
            <t>
For every degree of granularity at which an application may specify a
"default PvD" there MUST exist a corresponding mechanism to retrieve any
concurrently specified implementation-specific PvD programmatic reference.
If no PvD has been specified for at the granularity of a given query, the
"unspecified PvD" must be returned.
            </t>
          </list>
        </t>
        <t>
With access to this functionality it is possible to start non-PvD-aware
applications within a single PvD context with no adverse impact. Furthermore,
with judicious use of a sufficiently granular API, existing general purpose
networking APIs can be wrapped to appear PvD-aware.
        </t>
      </section>

      <section anchor="exp_vs_imp" title="Explicit versus Implicit PvDs">
        <t>
          <list counter="reqs" hangIndent="4" style="format R%d">
            <t>
Because programmatic references to PvDs are returned for both explicit and
implicit PvDs, the MPvD API implementation MUST be equally applicable and
useful for any valid type of PvD; it MUST NOT be necessary for a PvD-aware
application to distinguish between explicit and implicit PvDs to function
properly.
            </t>
          </list>
        </t>
      </section>

      <section anchor="policy" title="Policy restrictions">
        <t>
This document does not make recommendations about policies governing the use
of any or all elements of a PvD API, save only to note that some restrictions
on use may be deemed necessary or appropriate.
          <list counter="reqs" hangIndent="4" style="format R%d">
            <t>
A PvD API implementation MAY implement policy controls whereby access to
PvD availability information, configuration elements, and/or explicit scoping
requests is variously permitted or denied to certain applications.
            </t>
          </list>
        </t>
      </section>

      <section anchor="tokens"
               title="Programmatic reference implementation considerations">
        <t>
PvD identifiers may be of a length or form not easily handled directly in
some programming environments, and unauthenticated PvD identifiers are
assumed to be only
<eref target="https://tools.ietf.org/html/rfc7556#section-2.4"
  >probabilistically unique</eref>.  As such, API implementations should
consider using some alternative programmatic reference (a node-specific
"handle" or "token"), which is fully under the control of the operating
system, to identify an instance of a single provisioning domain's network
configuration information.
        </t>

        <t>
Even though a PvD identifier may uniquely correspond to, say, a network
operator, there is no guarantee that the configuration information
(delegated prefixes, configured IP addresses, and so on) will be the same with
every successive association to the same PvD identifier. An implementation may
elect to change the value of the programmatic reference to a given
PvD identifier for each temporally distinct association. Doing so presents
some advantages worth considering:
          <list style="empty">
            <t>
Collisions in the PvD identifier space will inherently be treated as
distinct by applications not concerned solely with identifiers.
            </t>

            <t>
Changing the value of a reference can disabuse application writers of
inappropriately caching configuration information from one association
instance to another.
            </t>

            <t>
Whether two PvDs are "identical" is perhaps better left to applications to
decide since "PvD equivalence" for a given application may alternatively be
determined by successfully accessing some restricted resource.
            </t>
          </list>
        </t>

        <t>
This document makes no specific requirement on the type of programmatic
reference used by the API.
        </t>
      </section>
    </section>

    <section title="Existing networking APIs">
      <section title="Updating existing APIs">
        <t>
From the perspective of a PvD-aware operating system, all previously existing
non-PvD-enabled networking functionality had historically been executed within
the context of a single, implicit provisioning domain.

A sufficiently granular API to specify which PvD is to be used to
<xref target="scoping">scope subsequent networking functionality</xref> can be
used to wrap non-PvD-aware APIs, giving them this new PvD-aware capability.

However,
          <list counter="reqs" hangIndent="4" style="format R%d">
            <t>
Operating system implementors SHOULD consider updating existing networking
APIs to take or return programmatic references to PvDs directly.
            </t>
          </list>

This may mean creating new functions with an additional PvD programmatic
reference argument, adding a PvD programmatic reference field to an existing
structure or class that is itself an argument or return type, or finding other
means by which to use a programmatic reference with minimal or no disruption
to existing applications or libraries.
        </t>
      </section>

      <section title="Requirements for name resolution APIs">
        <t>
<xref target="RFC3493">RFC 3493</xref>
<eref target="https://tools.ietf.org/html/rfc3493#section-6.1"
  >getaddrinfo()</eref>
and
<eref target="https://tools.ietf.org/html/rfc3493#section-6.2"
  >getnameinfo()</eref>
APIs deserve explicit discussion. Previously stated requirements make it clear
that it MUST be possible for an application to perform normal name resolution
constrained to the DNS configuration within a specified PVD. This MUST be
possible using at least the techniques of <xref target="scoping"/>.
        </t>
        <t>
The following additional requirements are places on PvD-aware implementations
of these functions:
          <list counter="reqs" hangIndent="4" style="format R%d">
            <t>
All DNS protocol communications with a PvD's nameservers MUST be restricted
to use only source addresses and routes associated with the PvD.
            </t>
            <t>
If getaddrinfo() is called with the AI_ADDRCONFIG flag specified,
IPv4 addresses shall be returned only if an IPv4 address is configured within
the specified provisioning domain and IPv6 addresses shall be returned only if
an IPv6 address is configured within the specified provision domain.
The loopback address is (still) not considered for this case as valid as a
configured address.
            </t>
          </list>
        </t>
      </section>
    </section>

    <!-- Possibly a 'Contributors' section ... -->
    <section anchor="acks" title="Acknowledgements">
      <t>
The core concepts presented in this document were developed during the
Android multinetworking effort by Lorenzo Colitti, Robert Greenwalt,
Paul Jensen, and Sreeram Ramachandran.
      </t>
      <t>
Additional thanks to the coffee shops of Tokyo.
      </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>
An important new security impact of a PvD-aware API is that it becomes much
simpler (by design) to write a well-functioning application to create a
bridging data path between two PvDs that would not otherwise have been so
easily connected.
      </t>
      <t>
For some operating systems, existing APIs already make this bridging
possible, though some functionality like DNS resolution may have been
difficult to implement.  Indeed, the very aim of an MPvD API is to make
implementing a PvD-aware application simple and to make its functioning
more "correct" ("first class" support for such functionality).
      </t>
      <t>
Operating system implementations have several points of potential policy
control including:
        <list style="symbols">
          <t>
use of certain PvDs MAY be restricted by policy (e.g. only approved users,
groups, or applications might be permitted access), and/or
          </t>
          <t>
use of more than one PvD (or the MPvD API itself) MAY be similarly restricted.
          </t>
        </list>
      </t>
    </section>
  </middle>


  <back>
    <!-- References split into informative and normative -->

    <!-- There are 2 ways to insert reference entries from the citation libraries:
     1. define an ENTITY at the top, and use "ampersand character"RFC2629; here (as shown)
     2. simply use a PI "less than character"?rfc include="reference.RFC.2119.xml"?> here
        (for I-Ds: include="reference.I-D.narten-iana-considerations-rfc2434bis.xml")

     Both are cited textually in the same manner: by using xref elements.
     If you use the PI option, xml2rfc will, by default, try to find included files in the same
     directory as the including file. You can also define the XML_LIBRARY environment variable
     with a value containing a set of directories to search.  These can be either in the local
     filing system or remote ones accessed by http (http://domain/dir/... ).-->

    <references title="Normative References">
      &RFC1122;
      &RFC2119;
      &RFC3493;
      &RFC6724;
      &RFC7556;
    </references>

    <references title="Informative References">
      &RFC1918;
      &RFC3879;
      &RFC4191;
      &RFC6418;
    </references>

<!--
    <section anchor="android-comparison" title="Comparison with Android implementation">
      <t>This becomes an Appendix.</t>
    </section>
-->
  </back>
</rfc>