Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Introduce 'webrtc' as a simple on/off switch #457

Merged
merged 27 commits into from
Apr 22, 2022
Merged
Changes from 24 commits
Commits
Show all changes
27 commits
Select commit Hold shift + click to select a range
b509df0
Introduce 'webrtc-src'.
mikewest Jan 17, 2018
2c3220b
Merge remote-tracking branch 'origin/master' into webrtc-src
zenhack Jan 18, 2021
71fb900
Make pre-connect checks used by webrtc a simple on/off switch
zenhack Jan 18, 2021
0ac40aa
Simplify overview description of webrtc-src
zenhack Jan 18, 2021
166733f
Don't check default-src or connect-src for webrtc.
zenhack Feb 3, 2021
cb0a72d
Grammar: Add a missing word
zenhack Feb 3, 2021
97cb5d8
s/webrtc-src/webrtc/
zenhack Feb 3, 2021
5751132
Update webrtc example to use 'none'
zenhack Feb 3, 2021
73d1cd1
Update build output
zenhack Feb 3, 2021
2b4e78b
Merge remote-tracking branch 'origin/main' into webrtc-src
zenhack May 23, 2021
c5c9d1b
Get rid of some extraneous info.
zenhack May 23, 2021
96d384c
Fill out webrtc integration section.
zenhack May 30, 2021
daf7deb
Rename pre-connect check to webrtc pre-connect check.
zenhack Jun 1, 2021
6c57f56
Incorporate suggested style changes
zenhack Jun 1, 2021
663eebd
Merge remote-tracking branch 'origin/main' into webrtc-src
zenhack Nov 9, 2021
e3f4bee
webrtc: change */'none' to 'allow'/'block'
zenhack Jan 20, 2022
fabf401
Merge remote-tracking branch 'origin/main' into webrtc-src
zenhack Jan 20, 2022
b655e24
s/none/block/
zenhack Jan 21, 2022
7935cdf
Remove superfluous step
zenhack Jan 21, 2022
d025cfe
Update webrtc integration bitrot.
zenhack Jan 21, 2022
48a19ab
Remove now-unnecessary links to RTCPeerConnection
zenhack Jan 21, 2022
9e77c0a
Various markup fixes.
zenhack Jan 24, 2022
aeb2b5e
Add backticks, for consistency.
zenhack Jan 25, 2022
baf2119
Move webrtc into a new "Other Directives" section.
zenhack Jan 25, 2022
a3fef1d
Improve addIceCandidate example.
zenhack Feb 5, 2022
84ef7b8
Avoid some unused parameters/arguments.
zenhack Feb 5, 2022
9405e95
nits
annevk Apr 22, 2022
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
91 changes: 91 additions & 0 deletions index.bs
Original file line number Diff line number Diff line change
Expand Up @@ -154,6 +154,10 @@ spec: WebAssembly-web-api-api; urlPrefix: https://webassembly.github.io/spec/web
type: exception
text: WebAssembly.CompileError; url: #exceptiondef-compileerror

spec: WebRTC; urlPrefix: https://www.w3.org/TR/webrtc/
type:dfn
text: administratively-prohibited; url: #dfn-administratively-prohibited

</pre>
<pre class="biblio">
{
Expand Down Expand Up @@ -634,6 +638,10 @@ spec: WebAssembly-web-api-api; urlPrefix: https://webassembly.github.io/spec/web
or "`response`"), and a <a for="/">policy</a> as arguments, and is executed during
[[#should-block-navigation-response]]. It returns "`Allowed`" unless otherwise specified.

8. A <dfn for="directive" export>webrtc pre-connect check</dfn>, which takes a [=/policy=], and
is executed during [[#should-block-rtc-connection]]. It returns "`Allowed`" unless
otherwise specified.

<h4 id="framework-directive-source-list">Source Lists</h4>

Many <a>directives</a>' <a>values</a> consist of <dfn export>source lists</dfn>: <a>sets</a>
Expand Down Expand Up @@ -1396,6 +1404,41 @@ spec: WebAssembly-web-api-api; urlPrefix: https://webassembly.github.io/spec/web
3. Return |result|.
</ol>

<h3 id="webrtc-integration">Integration with WebRTC</h3>

<p>The [=administratively-prohibited=] algorithm calls [[#should-block-rtc-connection]]
when invoked, and prohibits all candidates if it returns "`Blocked`."</p>
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit:

  "`Blocked`".

(swap " and .)


<h4 id="should-block-rtc-connection">
Should RTC connections be blocked for |global|?
</h4>

Given a [=/global object=] (|global|), this algorithm returns "`Blocked`"
if the active policy for |global| blocks RTC connections, and "`Allowed`" otherwise:

<ol class="algorithm">
1. Let |result| be "`Allowed`".

2. For each |policy| in |global|'s [=global object/CSP list=]:
1. For each |directive| in |policy|:
1. If |directive|'s <a for="directive">webrtc pre-connect check</a>
returns "`Allowed`" when executed upon |global|, |policy|,
and |directive|'s [=directive/name=], skip to the next directive.
zenhack marked this conversation as resolved.
Show resolved Hide resolved

2. Otherwise, let |violation| be the result of executing
[[#create-violation-for-global]] on |global|, |policy|, and
|directive|'s <a for="directive">name</a>.

3. Set |violation|'s <a for="violation">resource</a> to null.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit:

 `null`

(with backquotes)


4. Execute [[#report-violation]] on |violation|.

5. If |policy|'s <a for="policy">disposition</a> is "`enforce`", then
set |result| to "`Blocked`".

3. Return |result|.
</ol>

<h3 id="ecma-integration">Integration with ECMAScript</h3>

ECMAScript defines a {{HostEnsureCanCompileStrings()}} abstract operation
Expand Down Expand Up @@ -3224,6 +3267,54 @@ this algorithm returns normally if compilation is allowed, and throws a

4. Return "`Allowed`".

<h3 id="directives-other">Other Directives</h3>

<h4 id="directive-webrtc">`webrtc`</h4>
zenhack marked this conversation as resolved.
Show resolved Hide resolved

The <dfn export>webrtc</dfn> directive restricts whether connections may be
established via WebRTC. The syntax for the directive's name and value is
described by the following ABNF:

<pre dfn-type="grammar" link-type="grammar">
directive-name = "webrtc"
directive-value = "<dfn>'allow'</dfn>" / "<dfn>'block'</dfn>"
</pre>

<div class="example">
Given a page with the following Content Security Policy:

<pre>
Content-Security-Policy: <a>webrtc</a> 'block'
</pre>

In the following code, creating the call to `addIceCandidate` will
treat the candidate as [=administratively-prohibited=] and silently
ignore it; `webrtc` does not allow connections:

<pre highlight="html">
&lt;script&gt;
const pc = new RTCPeerConnection();
pc.addIceCandidate("candidate:4234997325 1 udp 2043278322 192.168.0.56 44323 typ host");
&lt;/script&gt;
</pre>
zenhack marked this conversation as resolved.
Show resolved Hide resolved
</div>

<h5 algorithm id="webrtc-pre-connect">
`webrtc` Preconnect Check
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit: Pre-connect for consistency.

</h5>

This directive's <a for="directive">webrtc pre-connect check</a> is as follows:

Given a [=/policy=] (|policy|):

1. Assert: |policy| is unused.

2. If this directive's [=directive/value=] contains a single item which is an
<a>ASCII case-insensitive</a> match for the string "<a grammar>`'allow'`</a>",
return "Allowed"
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

nit:

 "`Allowed`".

(with backquotes, and dot at the end).


3. Return "`Blocked`".

<h4 id="directive-worker-src">`worker-src`</h4>

The <dfn export>worker-src</dfn> directive restricts the URLs which may be loaded as
Expand Down