Skip to content

Commit

Permalink
Move isolated streams to identity spec
Browse files Browse the repository at this point in the history 
Fixes #1929
  • Loading branch information
@alvestrand
alvestrand committed Jul 15, 2018
1 parent fbf23b7 commit 164246a
Show file tree
Hide file tree
Showing 2 changed files with 204 additions and 199 deletions.
205 changes: 203 additions & 2 deletions identity.html
View file
Expand Up @@ -106,7 +106,8 @@ <h2>Terminology</h2>
<dfn>target peer identity</dfn>,
<dfn data-dfn-for="rtcpeerconnection">setRemoteDescription</dfn>,
<dfn data-dfn-for="rtcpeerconnection">createOffer</dfn>,
<dfn data-dfn-for="rtcpeerconnection">createAnswer</dfn> and
<dfn data-dfn-for="rtcpeerconnection">createAnswer</dfn>,
<dfn data-dfn-for="rtcpeerconnection">addTrack</dfn> and
<dfn data-lt="rtcerror">RTCError</dfn> are defined in [[!WEBRTC]].
</p>
</section>
Expand Down Expand Up @@ -902,7 +903,207 @@ <h2><dfn>RTCIdentityAssertion</dfn> Attributes</h2>
</div>
</section>
<section>
<h3>Identity Examples</h3>
<h2>Media Stream API Extensions for Network Use</h2>

<section>
<h3>Isolated Media Streams</h3>
<p>A MediaStream acquired using <code>getUserMedia()</code> is, by
default, accessible to an application. This means that the application is
able to access the contents of tracks, modify their content, and send
that media to any peer it chooses.</p>
<p>WebRTC supports calling scenarios where media is sent to a
specifically identified peer, without the contents of media streams being
accessible to applications. This is enabled by use of the
<code>peerIdentity</code> parameter to <code>getUserMedia()</code>.</p>
<p>An application willingly relinquishes access to media by including a
<code>peerIdentity</code> parameter in the
<code>MediaStreamConstraints</code>. This attribute is set to a
<code>DOMString</code> containing the identity of a specific peer.</p>
<p>The <code>MediaStreamConstraints</code> dictionary is expanded to
include the <code>peerIdentity</code> parameter.</p>
<div>
<pre class="idl">partial dictionary MediaStreamConstraints {
DOMString peerIdentity;
};</pre>
<section>
<h2>Dictionary MediaStreamConstraints
Members</h2>
<dl data-link-for="MediaStreamConstraints" data-dfn-for=
"MediaStreamConstraints" class="dictionary-members">
<dt><dfn data-idl><code>peerIdentity</code></dfn> of type <span class=
"idlMemberType"><a>DOMString</a></span></dt>
<dd>
<p>If set, <code>peerIdentity</code> isolates media from the
application. Media can only be sent to the identified peer.</p>
</dd>
</dl>
</section>
</div>
<p>A user that is prompted to provide consent for access to a camera or
microphone can be shown the value of the <code>peerIdentity</code>
parameter, so that they can be informed that the consent is more narrowly
restricted.</p>
<p>When the <code><dfn>peerIdentity</dfn></code> option is supplied to
<code>getUserMedia()</code>, all of the <code>MediaStreamTrack</code>s in
the resulting <code>MediaStream</code> are isolated so that content is
not accessible to any application. Isolated
<code>MediaStreamTrack</code>s can be used for two purposes:</p>
<ul>
<li>
<p>Displayed in an appropriate media tag (e.g., a video or audio
element). The browser MUST ensure that content is inaccessible to the
application by ensuring that the resulting content is given the same
protections as content that is <a data-cite=
"!fetch#concept-cors-check">
CORS cross-origin</a>, as described in the relevant <a data-cite=
"!HTML51/semantics-embedded-content.html#security-and-privacy-considerations">
Security and privacy considerations section</a> of [[HTML51]].</p>
</li>
<li>
<p>Used as the argument to <a data-link-for=
"RTCPeerConnection">addTrack</a> on an
<code><a>RTCPeerConnection</a></code> instance, subject to the
restrictions in <a href="#isolated-pc">isolated streams and
RTCPeerConnection</a>.</p>
</li>
</ul>
<p>A <code>MediaStreamTrack</code> that is added to another
<code>MediaStream</code> remains isolated. When an isolated
<code>MediaStreamTrack</code> is added to a <code>MediaStream</code> with
a different peerIdentity, the <code>MediaStream</code> gets a combination
of isolation restrictions. A <code>MediaStream</code> containing
<code>MediaStreamTrack</code> instances with mixed isolation properties
can be displayed, but cannot be sent using
<code><a>RTCPeerConnection</a></code>.</p>
<p>Any <code>peerIdentity</code> property MUST be retained on cloned
copies of <code>MediaStreamTrack</code>s.</p>
<!-- Any stream or track that might be derived from an isolated stream,
such as
through <a href="https://www.w3.org/TR/streamproc/#media-element-extensions">captureStreamUntilEnded
or captureStream</a>, MUST also retain any isolation protections.
-->
<section id="isolated-track">
<h4>Extended MediaStreamTrack Properties</h4>
<p><code>MediaStreamTrack</code> is expanded to include an
<var>isolated</var> attribute and a corresponding event. This allows an
application to quickly and easily determine whether a track is
accessible.</p>
<div>
<pre class="idl">partial interface MediaStreamTrack {
readonly attribute boolean isolated;
attribute EventHandler onisolationchange;
};</pre>
<section>
<h2>Attributes</h2>
<dl data-link-for="MediaStreamTrack" data-dfn-for=
"MediaStreamTrack" class="attributes">
<dt><dfn data-idl><code>isolated</code></dfn> of type <span class=
"idlAttrType"><a>boolean</a></span>, readonly</dt>
<dd>
<p>A <code>MediaStreamTrack</code> is isolated (and the
corresponding <var>isolated</var> attribute set to
<var>true</var>) when content is inaccessible to the owning
document. This occurs as a result of setting the
<var>peerIdentity</var> option. A track is also isolated if it
comes from a cross origin source.</p>
</dd>
<dt><dfn data-idl><code>onisolationchange</code></dfn> of type
<span class="idlAttrType"><a>EventHandler</a></span></dt>
<dd>
<p>This event handler, of type <a>isolationchange</a>, is fired
when the value of the <var>isolated</var> attribute
changes.</p>
</dd>
</dl>
</section>
</div>
</section>
<section id="isolated-pc">
<h4>Isolated Streams and RTCPeerConnection</h4>
<p>A <code>MediaStreamTrack</code> with a <var>peerIdentity</var>
option set can be added to any <code><a>RTCPeerConnection</a></code>.
However, the content of an isolated track MUST NOT be transmitted
unless all of the following constraints are met:</p>
<ul>
<li>
<p>A <code>MediaStreamTrack</code> from a stream acquired using the
<var>peerIdentity</var> option can be transmitted if the
<code><a>RTCPeerConnection</a></code> has successfully <a href="#dfn-validate-the-identity">validated the identity</a> of the
peer AND that identity is the same identity that was used in the
<var>peerIdentity</var> option associated with the track. That is,
the <code>name</code> attribute of the <code>peerIdentity</code>
attribute of the <code><a>RTCPeerConnection</a></code> instance
MUST match the value of the <code>peerIdentity</code> option passed
to <code>getUserMedia()</code>.</p>
<p>Rules for matching identity are described in
[[!RTCWEB-SECURITY-ARCH]].</p>
</li>
<li>
<p>The peer has indicated that it will respect the isolation
properties of streams. That is, a DTLS connection with a promise to
respect stream confidentiality, as defined in [[!RTCWEB-ALPN]] has
been established.</p>
</li>
</ul>
<p>Failing to meet these conditions means that no media can be sent for
the affected <code>MediaStreamTrack</code>. Video MUST be replaced by
black frames, audio MUST be replaced by silence, and equivalently
information-free content MUST be provided for other media types.</p>
<p>Remotely sourced <code>MediaStreamTrack</code>s MUST be isolated if
they are received over a DTLS connection that has been negotiated with
track isolation. This protects isolated media from the application in
the receiving browser. These tracks MUST only be displayed to a user
using the appropriate media element (e.g., &lt;video&gt; or
&lt;audio&gt;).</p>
<p>Any <code>MediaStreamTrack</code> that has the
<var>peerIdentity</var> option set causes all tracks sent using the
same <code><a>RTCPeerConnection</a></code> to be isolated at the
receiving peer. All DTLS connections created for an
<code><a>RTCPeerConnection</a></code> with isolated local streams MUST
be negotiated so that media remains isolated at the remote peer. This
causes non-isolated media to become isolated at the receiving peer if
any isolated tracks are added to the same
<code><a>RTCPeerConnection</a></code>.</p>
<p class="note">Tracks that are not bound to a particular
<var>peerIdentity</var> do not cause other streams to be isolated,
these tracks simply do not have their content transmitted.</p>
<p>If a stream becomes isolated after initially being accessible, or an
isolated stream is added to an active session, then media for that
stream is replaced by information-free content (e.g., black frames or
silence).</p>
</section>
<section id="isolation-protection">
<h4>Protection Afforded by Media Isolation</h4>
<p>Media isolation ensures that the content of a
<code>MediaStreamTrack</code> is not accessible to web applications.
However, to ensure that media with a <var>peerIdentity</var> option set
can be sent to peers, some meta-information about the media will be
exposed to applications.</p>
<p>Applications will be able to observe the parameters of the media
that affect session negotiation and conversion into RTP. This includes
the codecs that might be supported by the track, the bitrate, the
number of packets, and the current settings that are set on the
<code>MediaStreamTrack</code>.</p>
<p>In particular, the <a href="#sec.stats-model">statistics</a> that
<code><a>RTCPeerConnection</a></code> records are not reduced in
capability. New statistics that might compromise isolation MUST be
avoided, or explicitly suppressed for isolated streams.</p>
<p>Most of these data are exposed to the network when the media is
transmitted. Only the settings for the <code>MediaStreamTrack</code>
present a new source of information. This can includes the frame rate
and resolution of video tracks, the bandwidth of audio tracks, and
other information about the source, which would not otherwise be
revealed to a network observer. Since settings don't change at a high
frequency or in response to changes in media content, settings only
reveal limited reveal information about the content of a track.
However, any setting that might change dynamically in response to the
content of an isolated <code>MediaStreamTrack</code> MUST have changes
suppressed.</p>
</section>
</section>
</section>
<section>
<h2>Identity Examples</h2>
<p>The identity system is designed so that applications need not take any
special action in order for users to generate and verify identity
assertions; if a user has configured an IdP into their browser, then the
Expand Down

0 comments on commit 164246a

Please sign in to comment.