-
Notifications
You must be signed in to change notification settings - Fork 154
/
index.bs
1503 lines (1368 loc) · 76 KB
/
index.bs
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<pre class="metadata">
Title: Permissions Policy
Shortname: permissions-policy
Level: 1
Indent: 2
Status: ED
TR: https://www.w3.org/TR/permissions-policy/
Group: WebAppSec
URL: https://w3c.github.io/webappsec-permissions-policy/
Editor: Ian Clelland 76841, Google, [email protected]
Abstract: This specification defines a mechanism that allows developers to selectively enable and disable use of various browser features and APIs.
Repository: https://github.com/w3c/webappsec-permissions-policy/
Markup Shorthands: css no, markdown yes
Mailing List:
</pre>
<pre class="link-defaults">
spec:dom; type:interface; for:/; text:Document
spec:dom; type:dfn; for:/; text:element
spec:url; type:dfn; for:url; text:origin
spec:fetch; type:dfn; for:Response; text:response
spec:html; type:element; text:script
spec:html; type:element; text:link
spec:fetch; type:dfn; text:name
spec:fetch; type:dfn; text:value
spec:infra; type:dfn; text:list
spec:permissions; type:dfn; text:feature
</pre>
<pre class="anchors">
spec:payment-request; urlPrefix: https://w3c.github.io/payment-request/
type: dfn
text: PaymentRequest; url: dom-paymentrequest
spec:reporting; urlPrefix: https://w3c.github.io/reporting/
type: dfn
text: report type
text: visible to reportingobservers
spec: RFC8941; urlPrefix: https://datatracker.ietf.org/doc/html/rfc8941#
type: dfn
text: sf-dictionary; url: dictionary
</pre>
<pre class="biblio">
{
}
</pre>
<style>
.unstable::before {
content: "This section is not stable.";
float: right;
color: red;
}
.unstable {
background-image: url("data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' width='300' height='290'><text transform='rotate(-45)' text-anchor='middle' font-family='sans-serif' font-weight='bold' font-size='70' y='210' opacity='.1'>Unstable</text></svg>");
background-repeat: repeat
}
.unstable.example:not(.no-marker)::before {
content: "Example " counter(example) " (Unstable)";
float: none;
}
</style>
<section>
<h2 id="introduction">Introduction</h2>
<p>The web platform provides an ever-expanding set of features and APIs,
offering richer functionality, better developer ergonomics, and improved
performance. However, a missing piece is the ability for the developer to
selectively enable, disable, or modify the behavior of some of these browser
features and APIs within their application:</p>
<ol>
<li>The developer may want to selectively *disable* access to certain
browser features and APIs to "lock down" their application, as a security
or performance precaution, to prevent own and third-party content executing
within their application from introducing unwanted or unexpected behaviors
within their application.</li>
<li>The developer may want to selectively *enable* access to certain
browser features and APIs which may be disabled by default - e.g. some
features may be disabled by default in embedded context unless explicitly
enabled; some features may be subject to other policy requirements.</li>
<li>The developer may want to use the policy to assert a promise to a
client or an embedder about the use—or lack of thereof—of certain features
and APIs. For example, to enable certain types of "fast path" optimizations
in the browser, or to assert a promise about conformance with some
requirements set by other embedders - e.g. various social networks, search
engines, and so on.</li>
</ol>
<p>This specification defines a policy mechanism that addresses the above use
cases.</p>
<p class="note">This specification used to be named Feature Policy.</p>
</section>
<section>
<h2 id="examples">Examples</h2>
<div class="example">
<p>SecureCorp Inc. wants to disable use of Fullscreen and Geolocation APIs
within their application. It can do so by delivering the following HTTP
response header to define a permissions policy:</p>
<pre>
<a http-header>Permissions-Policy</a>: fullscreen=(), geolocation=()</pre>
<p>By specifying an empty origin list, the specified features will be
disabled for all documents, including nested documents, regardless of their
origin.</p>
</div>
<div class="example">
<p>Geolocation is disabled by default in all cross-origin frames. FastCorp
Inc. has a specific cross-origin iframe on their site for which it wants to
enable geolocation. It can do so by including an "<code>allow</code>"
attribute on the iframe element:</p>
<pre><iframe src="https://other.com/map" <a href="#iframe-allow-attribute">allow</a>="geolocation"></iframe></pre>
<p>Iframe attributes can selectively enable features in certain frames, and
not in others, even if those contain documents from the same origin.</p>
</div>
<div class="example">
<p>SecureCorp Inc. wants to completely disable use of the Geolocation API
within all [=Document/descendant navigables=] except for its own origin and
those whose origin is "<code>https://example.com</code>", even in the
presence of an attacker who can embed their own iframes on SecureCorp's
pages. It can do this by delivering the following HTTP response header to
define a restricted permissions policy for Geolocation:</p>
<pre>
<a http-header>Permissions-Policy</a>: geolocation=(self "https://example.com")</pre>
<p>The <a>allowlist</a> is a list of one or more origins, which can include
the application's origin, optionally with the keyword "<code>self</code>",
and any third-party origin.</p>
<p>With this policy in effect, it can then use the "<code>allow</code>"
iframe attribute as usual to grant geolocation to certain frames, but only
those frames hosting content from http://example.com or SecureCorp itself
will actually be granted the ability to use that API.</p>
</div>
<div class="example">
<p>SecureCorp Inc. restructured its domains and now needs to delegate
use of the Geolocation API to its origin ("<code>https://example.com</code>")
as well as three subdomains ("<code>https://geo.example.com</code>",
"<code>https://geo2.example.com</code>", and "<code>https://new.geo2.example.com</code>").
This needs to be accomplished while still disabling the use of the Geolocation API
within all other browsing contexts. It can do this by delivering the following HTTP response header:</p>
<pre>
<a http-header>Permissions-Policy</a>: geolocation=(self "https://example.com" "https://geo.example.com" "https://geo2.example.com" "https://new.geo2.example.com")
</pre>
<p>This works, but if SecureCorp Inc. feels safe delegating to any subdomains on
"<code>https://example.com</code>" the HTTP response header could instead be:</p>
<pre>
<a http-header>Permissions-Policy</a>: geolocation=(self "https://example.com" "https://*.example.com")
</pre>
<p>Not only would the above header permit "<code>https://geo.example.com</code>",
"<code>https://geo2.example.com</code>", and "<code>https://new.geo2.example.com</code>"
to use the Geolocation API, but any other subdomains of "<code>https://example.com</code>"
could use it too. Note that "<code>https://example.com</code>" is not covered by the
<a>allowlist</a> entry "<code>https://*.example.com</code>" and must also be added.</p>
</div>
<div class="example">
<p>SecureCorp Inc. restructured its services and now needs to needs to delegate
use of the Geolocation API to its origin ("<code>https://example.com</code>")
as well as three non-default ports ("<code>https://example.com:444</code>",
"<code>https://example.com:445</code>", and "<code>https://example.com:446</code>").
This needs to be accomplished while still disabling the use of the Geolocation API
within all other browsing contexts. It can do this by delivering the following HTTP response header:</p>
<pre>
<a http-header>Permissions-Policy</a>: geolocation=(self "https://example.com" "https://example.com:444" "https://example.com:445" "https://example.com:446")
</pre>
<p>This works, but if SecureCorp Inc. feels safe delegating to any ports on
"<code>https://example.com</code>" the HTTP response header could instead be:</p>
<pre>
<a http-header>Permissions-Policy</a>: geolocation=(self "https://example.com:*")
</pre>
<p>Not only would the above header permit "<code>https://example.com:444</code>",
"<code>https://example.com:444</code>", and "<code>https://example.com:445</code>"
to use the Geolocation API, but any other ports on "<code>https://example.com</code>"
could use it too.</p>
</div>
<div class="example">
<p>JSPlaygroundCorp Inc. wants to host user-generated web applications, but wants the
browser to manage their permissions to use [=powerful features=] in isolation of each other.
This can be accomplished by creating discrete subdomains for each piece of web-content
or web-content creator, and navigating them as top-level documents (framework and
user-content can still be separated using same-origin iframes).</p>
This is necessary since users grant permissions to the domain they perceive they
are interacting with in the browser, which is the top-level domain.
JSPlaygroundCorp should avoid iframing user-generated web applications using the
<{iframe/allow}> attribute from its own domain in this case, as this would grant
its domain permissions to all of them.
</div>
<div class="example">
<p>PlatformCorp Inc. wants to offer a marketplace of embeddable third-party
components to build from or games to play under its top-level domain. It wants to
delegate the use of [=powerful features=] like the {{MediaDevices/getUserMedia()}}
API responsibly. It accepts responsibility for tracking which of its component
applications need a feature, using bespoke "install" UX to keep end-users in
charge.</p>
<p>Camera and microphone are disabled by default in all cross-origin frames.
Each third-party component has a subdomain, and can be embedded in a
cross-origin iframe. PlatformCorp can use the <{iframe/allow}> attribute on
the <{iframe}> element to control whether to delegate camera or microphone
access or not to each subdomain.</p>
An iframe where the component "app1" should have camera access, "app2" should
have microphone access, and "app3" should have both might look like this:
<pre>
<iframe
allow="camera https://app1.site.com https://app3.site.com;
microphone https://app2.site.com https://app3.site.com"
src="https://doc1.site.com"
sandbox="allow-same-origin allow-scripts">
</iframe>
</pre>
<p>Iframe attributes can selectively enable features in certain frames, and
not in others, even if those contain documents from the [=same origin=].
The list of sandbox tokens might be longer in practice.</p>
<p>Since browsers generally ask users to grant permissions to the top-level
domain, there might not be any additional permission prompt for the
components to request camera or microphone access if the user already
trusts PlatformCorp.</p>
</div>
</section>
<section>
<h2 id="other-and-related-mechanisms">Other and related mechanisms</h2>
<p>[[HTML5]] defines a <{iframe/sandbox}> attribute for <{iframe}> elements
that allows developers to reduce the risk of including potentially untrusted
content by imposing restrictions on content's abilities - e.g. prevent it
from submitting forms, running scripts and plugins, and more. The
[=sandbox=] directive defined by [[CSP2]] extends this capability to any
resource, framed or not, to ask for the same set of restrictions - e.g. via an
HTTP response header (<code>Content-Security-Policy: sandbox</code>). These
mechanisms enable the developer to:</p>
<ul>
<li>Set and customize a sandbox policy on any resource via CSP.</li>
<li>Set and customize individual sandbox policies on each
<code>iframe</code> element within their application.</li>
</ul>
<p>However, there are several limitations to the above mechanism: the
developer cannot automatically apply a policy across all contexts, which
makes it hard or impossible to enforce consistently in some cases (e.g. due
to third-party content injecting frames, which the developer does not
control); there is no mechanism to selectively enable features that may be
off by default; the sandbox mechanism automatically disables all sandbox
features, and requires the developer to opt back in to each of them, so it is
impossible to extend the set of sandbox features without significant
compatibility risk.</p>
<p>Permissions Policy is intended to be used in combination with the sandbox
mechanism (i.e. it does not duplicate feature controls already covered by
sandbox), and provides an extensible mechanism that addresses the above
limitations.</p>
</section>
<section>
<h2 id="framework">Framework</h2>
<section>
<h3 id="features">Policy-controlled Features</h3>
<p>A <dfn export
data-lt="policy-controlled feature">policy-controlled feature</dfn> is an
API or behaviour which can be enabled or disabled in a document by referring
to it in a <a>permissions policy</a>.</p>
<div class="note">For brevity, policy-controlled features will often be
referred to in this document simply as "Features". Unless otherwise
indicated, the term "feature" refers to <a>policy-controlled features</a>.
Other specifications, defining such features, should use the longer term to
avoid any ambiguity.</div>
<div class="issue">This spec currently only deals with features defined in
Documents. We should figure out how to word this to include the possibility
of features and permissions policies in Workers and Worklets as well.</div>
<p><a>Policy-controlled features</a> are identified by <dfn export
for="policy-controlled-feature">tokens</dfn>, which are character strings
used in <a>policy directives</a>.</p>
<p>Each <a>policy-controlled feature</a> has a <a>default allowlist</a>,
which defines whether that feature is available in documents in top-level
traversables, and how access to that feature is inherited in child
navigables.</p>
<p>A user agent has a set of <dfn>supported features</dfn>, which is the set
of <a data-lt="policy-controlled feature">features</a> which it allows to be
controlled through policies. User agents are not required to support every
<a data-lt="policy-controlled feature">feature</a>.</p>
<div class="note">
The <a>policy-controlled features</a> themselves are not themselves part
of this framework. A non-normative list of currently-defined features is
maintained as a
<a href="https://github.com/w3c/webappsec-permissions-policy/blob/master/features.md">companion
document</a> alongside this specification.
</div>
</section>
<section>
<h3 id="policies">Policies</h3>
<p>A <dfn>declared policy</dfn> is a [=struct=] with the following
[=struct/items=]:</p>
<dl dfn-for="declared policy">
: <dfn>declarations</dfn>
:: an [=ordered map=] from [=policy-controlled features|features=] to [=allowlists=]
: <dfn>reporting configuration</dfn>
:: an [=ordered map=] from [=policy-controlled features|features=] to [=strings=]
</dl>
<p>A <dfn>permissions policy</dfn> is a [=struct=] with the following
[=struct/items=]:</p>
<dl dfn-for="permissions policy">
: <dfn>inherited policy</dfn>
:: an [=ordered map=] from [=policy-controlled features|features=] to "`Enabled`" or "`Disabled`"
: <dfn>declared policy</dfn>
:: a [=/declared policy=]
</dl>
<p>An <dfn export>empty permissions policy</dfn> is a <a>permissions
policy</a> that has an <a for="permissions policy">inherited policy</a> which
contains "<code>Enabled</code>" for every <a>supported feature</a>, a <a
for="permissions policy">declared policy</a> whose [=declared
policy/declarations=] and [=declared policy/reporting configuration=] are
both empty [=ordered maps=].</p>
</section>
<section>
<h3 id="inherited-policies">Inherited policies</h3>
<p>The <dfn export>inherited policy for a feature</dfn> <var>feature</var>
is the value in the <a for="permissions policy">inherited policy</a> whose
key is <var>feature</var>. After a <a>permissions policy</a> has been
initialized, its <a for="permissions policy">inherited policy</a> will
contain a value for each <a>supported feature</a>.</p>
<div class="note">
<p>Upon both creation and navigation, Each {{Document}} inherits a set of
policies from its parent frame, or in the case of the {{Document}} in a
[=/top-level traversable=], from the defined defaults for each
<a>policy-controlled feature</a>. This inherited policy determines the
initial state ("<code>Enabled</code>" or "<code>Disabled</code>") of each
feature, and whether it can be controlled by a <a for="permissions
policy">declared policy</a> in the {{Document}}.</p>
<p>In a {{Document}} in a [=/top-level traversable=], the inherited
policy is based on defined defaults for each feature.</p>
<p>In a {{Document}} in a [=child navigable=], the inherited policy is based
on the parent document's permissions policy, as well as the [=child
navigable=]'s <a>container policy</a>.</p>
</div>
</section>
<section>
<h3 id="header-policies">Header policies</h3>
<p>A <dfn>header policy</dfn> is a list of <a>policy directives</a>
delivered via an HTTP header with a document. This forms the document's
<a>permissions policy</a>'s <a for="permissions policy">declared
policy</a>.</p>
</section>
<section>
<h3 id="container-policies">Container policies</h3>
<p>In addition to the <a>header policy</a>, each [=child navigable=] has a
<dfn export>container policy</dfn>, which is a <a>policy directive</a>,
which may be empty. The <a>container policy</a> can be set by attributes on
the [=navigable container=].</p>
<p>The <a>container policy</a> for a [=child navigable=] influences the <a
for="permissions policy">inherited policy</a> of any {{Document}} loaded into
that navigable. (See [[#algo-define-inherited-policy-in-container]]).</p>
<div class="note">
Currently, the <a>container policy</a> cannot be set directly, but is
indirectly set by the <{iframe}> <{iframe/allowfullscreen}>, and
<{iframe/allow}> attributes. Future revisions to this spec may introduce a
mechanism to explicitly declare the full <a>container policy</a>.
</div>
</section>
<section>
<h3 id="policy-directives">Policy directives</h3>
<p>A <dfn data-lt="policy directive|policy directives">policy
directive</dfn> is an [=ordered map=], mapping <a>policy-controlled
features</a> to corresponding [=allowlists=] of origins.</p>
<p>A <a>policy directive</a> is represented in HTTP headers as the
serialization of an <a>sf-dictionary</a> structure, and in HTML attributes
as its ASCII serialization.</p>
</section>
<section>
<h3 id="allowlists">Allowlists</h3>
<p>A permissions policy <dfn export
lt="allowlist|allowlists">allowlist</dfn> is conceptually a set of
[=origins=]. An <a>allowlist</a> may be either:</p>
<ul>
<li><dfn>The special value <code>*</code></dfn>, which represents every
origin, or</li>
<li>A struct containing:</li>
<ul>
<li><dfn>expressions</dfn>, which is an ordered set of <a>permissions-source-expression</a></li>
<li><dfn>self-origin</dfn>, which is an [=origin=] or `null`</li>
<li><dfn>src-origin</dfn>, which is an [=origin=] or `null`</li>
</ul>
</ul>
<div class="note">
The keywords <code>'self'</code>, <code>'src'</code>, and
<code>'none'</code> can appear in the text representation of allowlists in
headers and attribute strings. These keywords are always interpreted in
context during parsing, and only the origins which they refer to are
stored in the allowlist. The keywords themselves are not part of the
allowlist.
</div>
<div algorithm="matches">
<p>To determine whether an <a>allowlist</a> <dfn>matches</dfn> an origin
<var>origin</var>, run these steps:</p>
1. If the <a>allowlist</a> is <a>the special value <code>*</code></a>,
then return true.
Note: We are not using the CSP variant of wildcard matching as it requires the HTTPS scheme.
1. If the <a>allowlist</a>'s <a>self-origin</a> is not null and it is
[=same origin-domain=] with <var>origin</var>, then return true.
1. If the <a>allowlist</a>'s <a>src-origin</a> is not null and it is
[=same origin-domain=] with <var>origin</var>, then return true.
1. If <var>origin</var> is an [=opaque origin=], return false.
1. Let <var>url</var> be the result of calling the [=url parser=] on the
[=serialization of an origin|serialization=] of <var>origin</var>.
1. [=set/For each=] <a>permissions-source-expression</a> |item| in the <a>allowlist</a>'s <a>expressions</a>:
1. If the result of running [=Does url match expression in origin with redirect count?=]
on <var>url</var>, |item|, <var>origin</var>, and 0 is true then return true.
1. Return false.
</div>
</section>
<section>
<h3 id="default-allowlists">Default Allowlists</h3>
<p>Every <a>policy-controlled feature</a> has a <dfn export
lt="default allowlist|default allowlists"
for="policy-controlled feature">default allowlist</dfn>. The <a>default
allowlist</a> determines whether the feature is allowed in a {{Document}} with
no <a for="permissions policy">declared policy</a> in a [=/top-level
traversable=], and also whether access to the feature is automatically
delegated to documents in [=child navigables=].</p>
<p>The <a>default allowlist</a> for a <a
data-lt="policy-controlled feature">feature</a> is one of these values:</p>
<dl>
<dt><dfn for="default allowlist" export><code>*</code></dfn></dt>
<dd>The feature is allowed in {{Document}}s in [=/top-level
traversables=] by default, as well as those in all [=child navigables=].
It can be disallowed in [=child navigables=] by explicitly supplying a
[=container policy=] on the [=navigable container=] that overrides this
default (or in any [=/navigable=], by delivering the {{Document}} with a
suitable <a http-header>`Permissions-Policy`</a> header).</dd>
<dt><dfn for="default allowlist" export><code>'self'</code></dfn></dt>
<dd>The feature is allowed in [=navigable/active document|documents=] in
[=/top-level traversables=] by default, as well as those in [=child
navigables=] whose [=navigable/active document|document=] is
[=same origin=] with its [=navigable/parent=]'s [=navigable/active
document|document=], when allowed in that {{Document}}. It is disallowed
by default in [=child navigables=] whose [=navigable/active
document|document=] is cross-origin with its [=navigable/parent=]'s
[=navigable/active document|document=].</dd>
</dl>
</section>
</section>
<section>
<h2 id="serialization">Permissions Policy Serialization</h2>
<section>
<h3 id="ascii-serialization">HTML attribute serialization</h3>
<p><a>Policy Directives</a> in HTML attributes are represented as their
ASCII serialization, with the following ABNF:</p>
<pre class="abnf">
<dfn noexport>serialized-permissions-policy</dfn> = <a>serialized-policy-directive</a> *(";" <a>serialized-policy-directive</a>)
<dfn>serialized-policy-directive</dfn> = <a>feature-identifier</a> RWS <a>allow-list</a>
<dfn>feature-identifier</dfn> = 1*( ALPHA / DIGIT / "-")
<dfn>allow-list</dfn> = <a>allow-list-value</a> *(RWS <a>allow-list-value</a>)
<dfn>allow-list-value</dfn> = <a>permissions-source-expression</a> / "*" / "'self'" / "'src'" / "'none'"
<dfn>permissions-source-expression</dfn> = <a grammar>scheme-source</a> / <a grammar>host-source</a>
</pre>
<div class="note">
The string "<code>'self'</code>" may be used as an origin in an
[=allowlist=]. When it is used in this way, it will refer to the
[=Document/origin=] of the {{Document}} which contains the [=permissions
policy=].
</div>
</section>
<section>
<h3 id="structured-header-serialization">Structured header serialization</h3>
<a>Policy Directives</a> in HTTP headers are represented as Structured
Fields. [[!RFC8941]]
In this representation, a <a>policy directive</a> is represented by a
Dictionary.
Each Dictionary Member associates a <a data-lt="policy-controlled feature">feature</a> with an <a>allowlist</a>.
The Member Names must be Tokens. If a token does not name one of the user
agent's [=supported features=], then the Dictionary Member will be ignored
by the processing steps.
The Member Values represent <a>allowlists</a>, and must be one of:
* a String containing the ASCII <a>permissions-source-expression</a>
* the Token `*`
* the Token `self`
* an Inner List containing zero or more of the above items.
Member Values may have a Parameter named `"report-to"`, whose value must be
a String. Any other parameters will be ignored.
Any other items inside of an Inner List will be ignored by the processing
steps, and the Member Value will be processed as if they were not present.
Member Values of any other form will cause the entire Dictionary Member to
be ignored by the processing steps.
</section>
</section>
<section>
<h2 id="delivery">Delivery</h2>
<section>
<h3 id="permissions-policy-http-header-field">\``Permissions-Policy`\` HTTP Header Field</h3>
<p>The \`<dfn export http-header
id="permissions-policy-header"><code>Permissions-Policy</code></dfn>\`
HTTP header field can be used in the [=response=] (server to client) to
communicate the <a>permissions policy</a> that should be enforced by the
client.</p>
<p>\`<a http-header><code>Permissions-Policy</code></a>\` is a structured
header. Its value must be a dictionary. It's ABNF is:</p>
<pre class="abnf">
PermissionsPolicy = <a>sf-dictionary</a>
</pre>
The semantics of the dictionary are defined in
[[#structured-header-serialization]].
The processing steps are defined in [[#algo-construct-policy]].
</section>
<section>
<h3 id="iframe-allow-attribute">The <code>allow</code> attribute of the <code>iframe</code> element</h3>
<p><{iframe}> elements have an <{iframe/allow}> attribute, which contains an
<a href="#serialized-policy-directive">ASCII-serialized policy
directive</a>.</p>
<p>The [=allowlist=] for the features named in the attribute may be empty; in
that case, the default value for the allowlist is <code>'src'</code>, which
represents the origin of the URL in the iframe's <{iframe/src}> attribute.</p>
<p>When not empty, the <{iframe/allow}> attribute will result in adding an
[=allowlist=] for each recognized <a data-lt="policy-controlled
feature">feature</a> to the <{iframe}> element's [=navigable
container/content navigable=]'s <a>container policy</a>, when it is
constructed.</p>
</section>
<section>
<h3 id="legacy-attributes">Additional attributes to support legacy features</h3>
<p>Some <a data-lt="policy-controlled feature">features</a> controlled by
Permissions Policy have existing iframe attributes defined. This
specification redefines these attributes to influence the <{iframe}>'s
[=content navigable=]'s [=container policy=].</p>
<section>
<h4 id="iframe-allowfullscreen-attribute">allowfullscreen</h4>
<p>The <{iframe/allowfullscreen}> <{iframe}> attribute controls access to
{{requestFullscreen()}}.</p>
<p>If the iframe element has an <{iframe/allow}> attribute whose value
contains the token "<code>fullscreen</code>", then the
<{iframe/allowfullscreen}> attribute must have no effect.</p>
<p>Otherwise, the presence of an <{iframe/allowfullscreen}> attribute
on an <{iframe}> will result in adding an <a>allowlist</a> of <code>*</code>
for the "<code>fullscreen</code>" feature to the <{iframe}> element's
[=navigable container/content navigable=]'s <a>container policy</a>, when
it is constructed.</p>
<div class="note">
This is different from the behaviour of <code><iframe
allow="fullscreen"></code>, and is for compatibility with existing
uses of <code>allowfullscreen</code>. If
<code>allow="fullscreen"</code> and <code>allowfullscreen</code> are
both present on an iframe element, then the more restrictive allowlist
of <code>allow="fullscreen"</code> will be used.
</div>
</section>
</section>
</section>
<section>
<h2 id="introspection">Policy Introspection from Scripts</h2>
<section class="non-normative">
<h3 id="introspection-overview">Overview</h3>
<p>The current policy which is in effect in a document can be observed by
scripts. This can be used to make decisions, for instance, about what user
interface to display, in cases where it is not possible to determine otherwise
whether a feature is enabled or not. (Some features may not have any
observable failure mode, or may have unwanted side effects to feature
detection.)</p>
<p>Documents and iframes both provide a {{PermissionsPolicy}} object which can
be used to inspect the permissions policies which apply to them.</p>
<h4 id="document-policies">Document policies</h4>
<p>To retreive the currently effective policy, use
<code>document.permissionsPolicy</code>. This returns a {{PermissionsPolicy}}
object, which can be used to:</p>
* query the state (allowed or denied) in the current document for a given
feature,
* get a list of all available features (allowed or not) in the current
document,
* get a list of all allowed features in the current document, or
* get the allowlist for a given feature in the current document.
<div class="example">
<pre>
<!doctype html>
<script>
const policy = document.permissionsPolicy;
// This will be true if this document can use WebUSB.
const can_use_usb = policy.allowsFeature('usb');
// True if a new frame at https://example.com will be allowed to use WebXR.
if (policy.allowsFeature('xr-spatial-tracking', 'https://example.com')) {
// Show UI to create frame at https://example.com.
} else {
// Show an alternative UI.
}
// Get the list of origins which are allowed to request payment. The result
// will be a list of explicit origins, or the single element ['*'] if all
// origins are allowed.
const allowed_payment_origins = policy.getAllowlistForFeature('payment');
// Get the list of all features supported in this document (even those
// which are not allowed). The result will be an array of strings, each
// representing a feature.
const all_features = policy.features();
if (all_features.includes('geolocation')) {
// Append a child frame to a third-party map service.
}
</script>
</pre>
</div>
<h4 id="frame-policies">Frame policies</h4>
<p>It is also possible to inspect the policy on an iframe element, from the
document which contains it. The policy object in this case represents the
<a>observable policy</a> for the frame, which depends only on the current
document and the attributes of the iframe element. It does not reveal whether
a feature is actually currently allowed in the frame, as the document in the
frame may have applied its own policy via an HTTP header, or may have
navigated away from its initial location to a new origin. Revealing the
effective policy in the iframe element's nested navigable in that case could
leak information about the behaviour of a cross-origin document.</p>
<div class="example">
<pre>
<!doctype html>
<iframe id="frame" allow="fullscreen; xr-spatial-tracking"></iframe>
<script>
const iframe_element = document.getElementById("frame");
const iframe_policy = iframe_element.permissionsPolicy;
// True if the framed document will be allowed to use WebXR
if (iframe_policy.allowsFeature('xr-spatial-tracking')) {
// display virtual reality controls
}
</script>
</pre>
</div>
<p>The <a>observable policy</a> on an iframe element is independent of any
actual content loaded into the frame (to avoid cross-origin information
leakage,) or even whether it is in a document tree.</p>
<div class="example">
<pre>
<!doctype html>
<!-- this frame should not be allowed to use fullscreen when the document
in its src attribute is loaded in it -->
<iframe id="frame" allow="fullscreen https://example.com" src="https://example.net/" ></iframe>
<script>
const iframe_element = document.getElementById("frame");
const iframe_policy = iframe_element.permissionsPolicy;
// This will be false, as the URL listed in the src attribute is not allowed
// by policy to use fullscreen.
const is_fullscreen_allowed_in_frame = iframe_policy.allowsFeature('fullscreen');
const new_frame = document.createElement('iframe');
new_frame.allow = 'sync-xhr';
// This will be true, as the iframe is allowed to use sync-xhr at whatever URL is
// mentioned in its src attribute, even though that attribute is not yet set.
const is_sync_xhr_allowed = new_frame.permissionsPolicy.allowsFeature('sync-xhr');
</script>
</pre>
</div>
</section>
<section>
<h3 id="the-policy-object">The permissionsPolicy object</h3>
<pre class="idl">
[Exposed=Window]
interface PermissionsPolicy {
boolean allowsFeature(DOMString feature, optional DOMString origin);
sequence<DOMString> features();
sequence<DOMString> allowedFeatures();
sequence<DOMString> getAllowlistForFeature(DOMString feature);
};
partial interface Document {
[SameObject] readonly attribute PermissionsPolicy permissionsPolicy;
};
partial interface HTMLIFrameElement {
[SameObject] readonly attribute PermissionsPolicy permissionsPolicy;
};
</pre>
<p>A {{PermissionsPolicy}} object has an <dfn>associated node</dfn>, which
is a {{Node}}. The <a>associated node</a> is set when the
{{PermissionsPolicy}} object is created.</p>
<p>A {{PermissionsPolicy}} object has a <dfn>default origin</dfn>, which is
an <a>origin</a>, whose value depends on the state of the
{{PermissionsPolicy}} object's <a>associated node</a>:</p>
* If the {{PermissionsPolicy}} object's <a>associated node</a> is a
{{Document}}, then its <a>default origin</a> is the {{Document}}'s
<a>origin</a>.
* If the {{PermissionsPolicy}} object's <a>associated node</a> is an
{{Element}}, then its <a>default origin</a> is the {{Element}}'s
<a>declared origin</a>.
<p>Each {{Document}} has a <dfn for="Document">policy object</dfn>, which is
a {{PermissionsPolicy}} instance whose <a>associated node</a> is that
{{Document}}.</p>
<p>A {{Document}}'s {{Document/permissionsPolicy}} IDL attribute, on
getting, must return the {{Document}}'s [=Document/policy object=].</p>
<p>Each <{iframe}> element has a <dfn for="iframe">policy object</dfn>,
which is a {{PermissionsPolicy}} instance whose <a>associated node</a> is
that element.</p>
<p>An <{iframe}>'s {{HTMLIFrameElement/permissionsPolicy}} IDL attribute, on
getting, must return the <{iframe}>'s [=iframe/policy object=].</p>
<p>The {{allowsFeature(feature, origin)}} method must run the following
steps:</p>
1. If |origin| is omitted, set |origin| to this {{PermissionsPolicy}}
object's <a>default origin</a>.
2. Let |policy| be the <a>observable policy</a> for this
{{PermissionsPolicy}} object's <a>associated node</a>.
3. If |feature| is allowed by |policy| for |origin|, return true.
4. Otherwise, return false.
<p>The {{features()}} method must run the following steps:</p>
1. Set |result| to an empty ordered set.
2. For each <a>supported feature</a> |feature|:
1. Append |feature| to |result|.
3. return result
<p>The {{allowedFeatures()}} method must run the following steps:</p>
1. Set |result| to an empty ordered set.
2. Let |origin| be this {{PermissionsPolicy}} object's <a>default
origin</a>.
3. Let |policy| be the <a>observable policy</a> for this
{{PermissionsPolicy}} object's <a>associated node</a>.
4. For each <a>supported feature</a> |feature|:
1. If |feature| is allowed by |policy| for |origin|, append |feature| to
|result|.
5. return result
<p>The {{getAllowlistForFeature(feature)}} method must run the following
steps:</p>
1. Set |result| to an empty list.
2. Let |origin| be this {{PermissionsPolicy}} object's <a>default
origin</a>.
3. Let |policy| be the <a>observable policy</a> for this
{{PermissionsPolicy}} object's <a>associated node</a>.
4. If |feature| is not allowed in |policy| for |origin|, return |result|
5. Let |allowlist| be |policy|'s [=/declared policy=][|feature|]'s
[=declared policy/declarations=].
6. If |allowlist| is the special value `*`:
1. Append "`*`" to |result|
2. Return |result|.
7. If the <a>allowlist</a>'s <a>self-origin</a> is not null,
append the <a lt="serialization of an origin">serialization</a> of it to
|result|.
8. If the <a>allowlist</a>'s <a>src-origin</a> is not null,
append the <a lt="serialization of an origin">serialization</a> of it to
|result|.
9. Otherwise, for each <a>permissions-source-expression</a> |item| in
|allowlist|'s <a>expressions</a>:
1. Append |item| to |result|
10. Return |result|.
<p>The <dfn>observable policy</dfn> for any Node is a <a>permissions
policy</a>, which contains the information about the policy in the navigable
represented by that Node which is visible from the current document.</p>
<p>To get the <a>observable policy</a> for a Document |document|, return
|document|'s permissions policy.</p>
<p>To get the <a>observable policy</a> for an Element |node|, run the
following steps:</p>
1. Let |inherited policy| be an empty [=ordered map=].
3. [=set/For each=] <a>supported feature</a> |feature|:
1. Let |isInherited| be the result of running <a abstract-op>Define
an inherited policy for feature in container at origin</a> on
|feature|, |node| and |node|'s <a>declared origin</a>.
2. Set |inherited policy|[|feature|] to |isInherited|.
4. Return a new <a>permissions policy</a> with <a for="permissions
policy">inherited policy</a> |inherited policy|, <a
for="permissions policy">declared policy</a> a [=struct=] with both
[=declared policy/declarations=] and [=declared policy/reporting
configuration=] new [=ordered maps=].
<p>To get the <dfn>declared origin</dfn> for an Element |node|, run the
following steps:</p>
1. If |node|'s <a>node document</a>'s <a>sandboxed origin browsing
context flag</a> is set, then return a new [=opaque origin=].
2. If |node|'s <{iframe/sandbox}> attribute is set, and does not contain
the <code>allow-same-origin</code> keyword, then return a new
[=opaque origin=].
3. If |node|'s <{iframe/srcdoc}> attribute is set, then return |node|'s
<a>node document</a>'s origin.
4. If |node|'s <{iframe/src}> attribute is set:
1. Let |url| be the result of parsing |node|'s src attribute,
relative to |node|'s <a>node document</a>.
2. If |url| is not failure, return |url|'s origin.
5. Return |node|'s <a>node document</a>'s origin.
<p class="note">
The <a>declared origin</a> concept is intended to represent the origin of
the document which the embedding page intends to load into a frame. This
means, for instance, that if the browser does not support the
<code>sandbox</code> or <code>srcdoc</code> attributes, it should not take
those attributes into account when computing the declared origin.</p>
</section>
</section>
<section>
<h2 id="reporting">Reporting</h2>
<p><dfn>Permissions policy violation reports</dfn> indicate that some behavior
of the <a>Document</a> has <a>violated</a> a permissions policy. It is up to
the specification of each individual policy-controlled feature to define what
it means to <dfn data-lt="violate|violation|violated">violate</dfn> that
policy, and how to determine when such a violation has occurred.</p>
<p><a>Permissions policy violation reports</a> have the <a>report type</a>
"permissions-policy-violation".</p>
<p><a>Permissions policy violation reports</a> are <a>visible to
<code>ReportingObserver</code>s</a>.</p>
<pre class="idl">
[Exposed=Window]
interface PermissionsPolicyViolationReportBody : ReportBody {
[Default] object toJSON();
readonly attribute DOMString featureId;
readonly attribute DOMString? sourceFile;
readonly attribute long? lineNumber;
readonly attribute long? columnNumber;
readonly attribute DOMString disposition;
readonly attribute DOMString? allowAttribute;
};
</pre>
A <a>permissions policy violation report</a>'s [=report/body=], represented in
JavaScript by {{PermissionsPolicyViolationReportBody}}, contains the following
fields:
- <dfn for="PermissionsPolicyViolationReportBody">featureId</dfn>: The
string identifying the <a>policy-controlled feature</a> whose policy has
been <a>violated</a>. This string can be used for grouping and counting
related reports.
- <dfn for="PermissionsPolicyViolationReportBody">sourceFile</dfn>: If
known, the file where the <a>violation</a> occured, or null otherwise.
- <dfn for="PermissionsPolicyViolationReportBody">lineNumber</dfn>: If
known, the line number in
[=PermissionsPolicyViolationReportBody/sourceFile=] where the
<a>violation</a> occured, or null otherwise.
- <dfn for="PermissionsPolicyViolationReportBody">columnNumber</dfn>: If
known, the column number in
[=PermissionsPolicyViolationReportBody/sourceFile=] where the
<a>violation</a> occured, or null otherwise.
- <dfn for="PermissionsPolicyViolationReportBody">disposition</dfn>: A
string indicating whether the <a>violated</a> permissions policy was
enforced in this case.
[=PermissionsPolicyViolationReportBody/disposition=] will be set to
"enforce" if the policy was enforced, or "report" if the <a>violation</a>
resulted only in this report being generated (with no further action taken
by the user agent in response to the violation).
- <dfn for="PermissionsPolicyViolationReportBody">allowAttribute</dfn>: For
reports of potential violations, which can be attributed to a specific
<{iframe}> element, the value of the <{iframe/allow}> attribute of that
element, or omitted otherwise.
<section>
<h3 id="permissions-policy-report-only-http-header-field">\``Permissions-Policy-Report-Only`\` HTTP Header Field</h3>
<p>The \`<dfn export http-header
id="permissions-policy-report-only-header"><code>Permissions-Policy-Report-Only</code></dfn>\`
HTTP header field can be used in the [=response=] (server to client) to
communicate a <a>permissions policy</a> that should not be enforced by the
client, but instead should be used to trigger reports to be sent if any
policy declared within it *would* have been violated, had the policy been
active.</p>
<p>\`<a http-header><code>Permissions-Policy-Report-Only</code></a>\` is a
structured header. Its value must be a dictionary.</p>
The semantics of the dictionary are defined in
[[#structured-header-serialization]].
The processing steps are defined in [[#algo-construct-policy]].
</section>
</section>
<section>
<h2 id="algorithms">Algorithms</h2>
<section>
## <dfn export abstract-op id="process-response-policy">Process response policy</dfn> ## {#algo-process-response-policy}
<div class="algorithm" data-algorithm="process-response-policy">
Given a [=response=] (|response|), an [=origin=] (|origin|), and a boolean
(|report-only|), this algorithm returns a [=/declared policy=].
1. Let |header name| be "<code>Permissions-Policy-Report-Only</code>" if
|report-only| is True, or "<code>Permissions-Policy</code>" otherwise.
1. Let |parsed header| be the result of executing <a>get a structured
field value</a> given |header name| and "dictionary" from |response|’s
[=response/header list=].
1. If |parsed header| is null, return an empty [=ordered map=].
1. Let |policy| be the result of executing <a abstract-op>Construct policy from
dictionary and origin</a> on |parsed header| and |origin|.
1. Return |policy|.
</div>
</section>
<section>
## <dfn export abstract-op id="construct-policy">Construct policy from dictionary and origin</dfn> ## {#algo-construct-policy}
<div class="algorithm" data-algorithm="construct-policy">
Given an <a>ordered map</a> (|dictionary|) and an [=origin=] (|origin|), this
algorithm will return a [=/declared policy=].
1. Let |declarations| be an empty [=ordered map=].
1. Let |reporting-config| be an empty [=ordered map=].
1. [=map/For each=] |feature-name| → (|value|, |params|) of |dictionary|:
1. If |feature-name| does not identify any recognized
<a>policy-controlled feature</a>, then [=iteration/continue=].
1. Let |feature| be the <a>policy-controlled feature</a> identified by
|feature-name|.
1. If |params|["report-to"] exists, and is a string, then set
|reporting-config|[|feature|] to |params|["report-to"].
1. Let |allowlist| be a new <a>allowlist</a>.
1. If |value| is the token `*`, or if |value| is a list which contains
the token `*`, set |allowlist| to <a>the special value
<code>*</code></a>.
1. Otherwise:
1. If |value| is the token `self`, let |allowlist|'s <a>self-origin</a> be |origin|.
1. Otherwise if |value| is a [=list=], then [=list/for each=]
|element| in |value|:
1. If |element| is the token `self`, let |allowlist|'s <a>self-origin</a> be |origin|.
1. If |element| is a valid <a>permissions-source-expression</a>, [=list/append=] |element| to |allowlist|'s <a>expressions</a>.
1. Set |declarations|[|feature|] to |allowlist|.
1. Return «|declarations|, |reporting-config|».
</div>
</section>
<section>
## <dfn export abstract-op id="parse-policy-directive">Parse policy directive</dfn> ## {#algo-parse-policy-directive}
<div class="algorithm" data-algorithm="parse-policy-directive">
Given a string (|value|), an [=origin=] (|container origin|), and an
optional [=origin=] (|target origin|), this algorithm returns a <a>policy
directive</a>.
1. Let |directive| be an empty [=ordered map=].
1. For each |serialized-declaration| returned by <a
lt="strictly split">strictly splitting |value| on the delimiter
U+003B (;)</a>:
1. Let |tokens| be the result of <a
lt="split on ascii whitespace">splitting |serialized-declaration| on
ASCII whitespace.</a>
1. If |tokens| is an empty list, then [=iteration/continue=].
1. Let |feature-name| be the first element of |tokens|.
1. If |feature-name| does not identify any recognized
<a>policy-controlled feature</a>, then [=iteration/continue=].
1. Let |feature| be the <a>policy-controlled feature</a> identified by
|feature-name|.
1. Let |targetlist| be the remaining elements, if any, of |tokens|.
1. Let |allowlist| be a new <a>allowlist</a>.
1. If any element of |targetlist| is the string "<code>*</code>", set
|allowlist| to <a>the special value <code>*</code></a>.
1. Otherwise:
1. If |targetlist| is empty and |target origin| is given,
let |allowlist|'s <a>src-origin</a> be |target origin|.
1. For each |element| in |targetlist|:
1. If |element| is an <a>ASCII case-insensitive</a> match for
"<code>'self'</code>":
1. Let |allowlist|'s <a>self-origin</a> be |container origin|.
1. Continue to the next |element|.
1. If |target origin| is given, and |element| is an <a>ASCII
case-insensitive</a> match for "<code>'src'</code>":
1. Let |allowlist|'s <a>src-origin</a> be |target origin|.
1. Continue to the next |element|.
1. Let |result| be the result of executing the <a>URL parser</a> on |element|.
1. If |result| is not failure:
1. Let |target| be the [=url/origin=] of |result|.
1. If |target| is not an [=opaque origin=], [=list/append=]
the <a lt="serialization of an origin">serialization</a>
of |target| to |allowlist|'s <a>expressions</a>.
1. Set |directive|[|feature|] to |allowlist|.
1. Return |directive|
</div>
</section>
<section>
## <dfn export abstract-op id="process-policy-attributes">Process permissions policy attributes</dfn> ## {#algo-process-policy-attributes}
<div class="algorithm" data-algorithm="process-policy-attributes">
Given an element (|element|), this algorithm returns a <a>container
policy</a>, which may be empty.
1. If |element| is not an <{iframe}> element, then return an empty [=policy
directive=].
1. Let |container policy| be the result of running <a abstract-op>Parse policy
directive</a> given the value of |element|'s <{iframe/allow}> attribute,
the [=Document/origin=] of |element|'s [=node document=], and |element|'s
<a>declared origin</a>.
1. If |element|'s <{iframe/allowfullscreen}> attribute is specified, and
|container policy| does not [=map/contain=] an entry for the
<code>fullscreen</code> [=policy-controlled feature|feature=].
1. [=map/Set=] |container policy|[<code>fullscreen</code>] = <a>the
special value <code>*</code></a>.
1. Return |container policy|.