changeset 440 fcbaadc4fd54
parent 438 d66ca00fe7d9
child 441 b4b2569b4e9b
--- a/discovery-api/Overview.src.html	Thu Aug 08 14:41:34 2013 -0400
+++ b/discovery-api/Overview.src.html	Mon Aug 12 16:20:17 2013 +1000
@@ -217,7 +217,8 @@
-        For more detailed examples see the <a href="#examples">Examples</a> section.
+        For more detailed examples, including examples of communicating with obtained networked services, see the
+        <a href="#examples">Examples</a> section.
     <section id='conformance'>
@@ -329,6 +330,67 @@
+        Security and privacy considerations
+      </h2>
+      <p>
+        The API defined in this specification can be used to find and connect to devices and services within a user's
+        current network. This discloses information related to a user's network: devices available on their network and
+        the publicly-accessible services ("networked services") currently running and available on those devices. The
+        distribution of this information could potentially compromise the user's privacy. A conforming implementation
+        of this specification MUST provide a mechanism that protects the user's privacy. This mechanism MUST ensure
+        that no networked service information is retrievable without the user's express permission.
+      </p>
+      <section>
+        <h3>
+          Privacy considerations for API implementations
+        </h3>
+        <p>
+          A <a>user agent</a> MUST NOT provide networked service information to web sites without the express
+          permission of the user. A user agent MUST acquire permission through a user interface, unless they have
+          prearranged trust relationships with users, as described below. The user interface MUST include the document
+          base URL. Those permissions that are acquired through the user interface and that are preserved beyond the
+          current browsing session (i.e. beyond the time when the browsing context is navigated to another URL) MUST be
+          revocable and a user agent MUST respect revoked permissions.
+        </p>
+        <p>
+          Obtaining the user's express permission to access one API method does not imply the user has granted
+          permission for the same web site to access any other methods that may be provided by this API, or to access
+          the same method with a different set of arguments, as part of the same permission context. If a user has
+          expressed permission for an implementation to, e.g. find a set of existing networked services, the
+          implementation MUST seek the user's express permission if and when any subsequent functions are called on
+          this API.
+        </p>
+        <p>
+          A user agent MAY have prearranged trust relationships that do not require such user interfaces. For example,
+          while a web browser will present a user interface when a web site performs a networked service lookup, a
+          different runtime may have a prearranged, delegated security relationship with the user and, as such, a
+          suitable alternative security and privacy mechanism with which to authorise the retrieval of networked
+          service information.
+        </p>
+      </section>
+      <section class="informative">
+        <h3>
+          Additional API implementation considerations
+        </h3>
+        <p>
+          Further to the requirements listed in the previous section, implementors of the Network Service Discovery API
+          are also advised to consider the following aspects that can negatively affect the privacy of their users: in
+          certain cases, users can inadvertently grant permission to the user agent to disclose networked services to
+          Web sites. In other cases, the content hosted at a certain URL changes in such a way that previously granted
+          networked service permissions no longer apply as far as the user is concerned. Or the users might simply
+          change their minds.
+        </p>
+        <p>
+          Predicting or preventing these situations is inherently difficult. Mitigation and in-depth defensive measures
+          are an implementation responsibility and not prescribed by this specification. However, in designing these
+          measures, implementers are advised to enable user awareness of networked service sharing, and to provide easy
+          access to interfaces that enable revocation of permissions that web applications have for accessing networked
+          services via this API.
+        </p>
+      </section>
+    </section>
+    <section>
+      <h2>
         Requesting networked services
       <pre class="widl">
@@ -1029,7 +1091,7 @@
         The <dfn>list of available service records</dfn> is a single dynamic internal lookup table within user agents
         that is used to track all the services that have been discovered and are available in the current network at
-        the current time. At any point during the running of either of the two <a>service discovery mechanisms</a> then
+        the current time. At any point during the running of any of the <a>service discovery mechanisms</a> then
         existing entries within this table can be updated, entries can be added and entries can be removed as the
         status of networked services changes according to the rules defined in this specification.