OLD | NEW |
---|---|
(Empty) | |
1 // Copyright 2016 The Chromium Authors. All rights reserved. | |
2 // Use of this source code is governed by a BSD-style license that can be | |
3 // found in the LICENSE file. | |
4 | |
5 #ifndef FeaturePolicy_h | |
6 #define FeaturePolicy_h | |
7 | |
8 #include "platform/PlatformExport.h" | |
9 #include "platform/weborigin/SecurityOrigin.h" | |
10 #include "wtf/RefPtr.h" | |
11 #include "wtf/Vector.h" | |
12 #include "wtf/text/WTFString.h" | |
13 | |
14 #include <memory> | |
15 | |
16 namespace blink { | |
17 | |
18 // Feature Policy is a mechanism for controlling the availability of web | |
19 // platform features in a frame, including all embedded frames. It can be used | |
20 // to remove features, automatically refuse API permission requests, or modify | |
21 // the behaviour of features. (The specific changes which are made depend on the | |
22 // feature; see the specification for details). | |
23 // | |
24 // Policies can be defined in the HTTP header stream, with the |Feature-Policy| | |
25 // HTTP header, or can be set by |enable| and |disable| attributes on the iframe | |
26 // element which embeds the document. | |
27 // | |
28 // See https://wicg.github.io/FeaturePolicy/ | |
29 // | |
30 // Key concepts: | |
31 // | |
32 // Features | |
33 // -------- | |
34 // Features which can be controlled by policy are defined as instances of the | |
35 // FeaturePoliicy::Feature struct. The features are referenced by pointer, so | |
36 // only a single instance of each feature should be defined. The features which | |
37 // are declared in the feature policy specification are all defined in | |
38 // |FeaturePolicy.cpp|. | |
39 // | |
40 // Whitelists | |
41 // ---------- | |
42 // Policies are defined as a mapping of feaure names to whitelists. Whitelists | |
43 // are collections of origins, although two special terms can be used when | |
44 // declaring them: | |
45 // "self" refers to the orgin of the frame which is declaring the policy. | |
46 // "*" refers to all origins; any origin will match a whitelist which contains | |
47 // it. | |
48 // | |
49 // Defaults | |
50 // -------- | |
51 // Each defined feature has a default policy, which determines whether the | |
52 // feature is available when no policy has been declared, ans determines how the | |
53 // feature is inherited across origin boundaries. | |
54 // | |
55 // If the default policy is in effect for a frame, then it controls how the | |
56 // feature is inherited by any cross-origin iframes embedded by the frame. (See | |
57 // the comments below in FeaturePolicy::DefaultPolicy for specifics) | |
58 // | |
59 // Policy Inheritance | |
60 // ------------------ | |
61 // Policies in effect for a frame are inherited by any child frames it embeds. | |
62 // Unless another policy is declared in the child, all same-origin children will | |
63 // receive the same set of enables features as the parent frame. Whether or not | |
64 // features are inherited by cross-origin iframes without an explicit policy is | |
65 // determined by the feature's default policy. (Again, see the comments in | |
66 // FeaturePolicy::DefaultPolicy for details) | |
67 | |
68 class PLATFORM_EXPORT FeaturePolicy final { | |
69 public: | |
70 // Represents a collection of origins which make up a whitelist in a feature | |
71 // policy. This collection may be set to match every origin (corresponding to | |
72 // the "*" syntax in the policy string, in which case the contains() method | |
73 // will always return true. | |
74 class Whitelist final { | |
75 public: | |
76 Whitelist(); | |
77 | |
78 // Adds a single origin to the whitelist. | |
79 void add(RefPtr<SecurityOrigin>); | |
80 | |
81 // Adds all origins to the whitelist. | |
82 void addAll(); | |
83 | |
84 // Returns true if the given origin has been added to the whitelist. | |
85 bool contains(const SecurityOrigin&) const; | |
86 String toString(); | |
87 | |
88 private: | |
89 bool m_matchesAllOrigins; | |
90 Vector<RefPtr<SecurityOrigin>> m_origins; | |
91 }; | |
92 | |
93 // The FeaturePolicy::FeatureDefault enum defines the default enable state for | |
94 // a feature when neither it nor any parent frame have declared an explicit | |
95 // policy. The three possibilities map directly to Feature Policy Whitelist | |
96 // semantics. | |
97 enum class FeatureDefault { | |
98 // Equivalent to []. If this default policy is in effect for a frame, then | |
99 // the feature will not be enabled for that frame or any of its children. | |
100 DisableForAll, | |
101 | |
102 // Equivalent to ["self"]. If this default policy is in effect for a frame, | |
103 // then the feature will be enabled for that frame, and any same-origin | |
104 // child frames, but not for any cross-origin child frames. | |
105 EnableForSelf, | |
106 | |
107 // Equivalent to ["*"]. If in effect for a frame, then the feature is | |
108 // enabled for that frame and all of its children. | |
109 EnableForAll | |
110 }; | |
111 | |
112 // The FeaturePolicy::Feature struct is used to define all features under | |
113 // control of Feature Policy. There should only be one instance of this struct | |
114 // for any given feature (declared below). | |
115 struct Feature { | |
116 // The name of the feature, as it should appear in a policy string | |
117 const char* featureName; | |
dcheng
2016/10/24 19:16:45
Nit: const char* const is slightly preferred (all
iclelland
2016/10/25 18:34:33
Makes sense, thanks - done.
| |
118 | |
119 // Controls whether the feature should be available in the platform by | |
120 // default, in the absence of any declared policy. | |
121 FeatureDefault defaultPolicy; | |
122 }; | |
123 | |
124 using FeatureList = const Vector<const FeaturePolicy::Feature*>; | |
125 | |
126 static std::unique_ptr<FeaturePolicy> createFromParentPolicy( | |
127 const FeaturePolicy* parent, | |
128 RefPtr<SecurityOrigin>); | |
129 | |
130 // Sets the declared policy from the Feature-Policy HTTP header. If the header | |
131 // cannot be parsed, errors will be appended to the |messages| vector. | |
132 void setHeaderPolicy(const String&, Vector<String>& messages); | |
133 | |
134 // Returns whether or not the given feature is enabled by this policy. | |
135 bool isFeatureEnabledForOrigin(const Feature*, const SecurityOrigin&) const; | |
136 | |
137 // Returns whether or not the given feature is enabled for the frame that owns | |
138 // the policy. | |
139 bool isFeatureEnabled(const Feature*) const; | |
140 | |
141 // Returns the list of features which can be controlled by Feature Policy. | |
142 static FeatureList& getDefaultFeatureList(); | |
143 | |
144 String toString(); | |
145 | |
146 private: | |
147 friend class FeaturePolicyTest; | |
148 | |
149 FeaturePolicy(RefPtr<SecurityOrigin>, FeatureList& features); | |
150 | |
151 static std::unique_ptr<FeaturePolicy> createFromParentPolicy( | |
152 const FeaturePolicy* parent, | |
153 RefPtr<SecurityOrigin>, | |
154 FeatureList& features); | |
155 | |
156 RefPtr<SecurityOrigin> m_origin; | |
157 | |
158 // Records whether or not each feature was enabled for this frame by its | |
159 // parent frame. | |
160 // TODO(iclelland): Generate, instead of this map, a set of bool flags, one | |
161 // for each feature, as all features are supposed to be represented here. | |
162 HashMap<const Feature*, bool> m_inheritedFeatures; | |
163 | |
164 // Map of feature names to declared whitelists. Any feature which is missing | |
165 // from this map should use the inherited policy. | |
166 HashMap<const Feature*, std::unique_ptr<Whitelist>> m_headerWhitelists; | |
167 | |
168 // Contains the set of all features which can be controlled by this policy. | |
169 FeatureList& m_features; | |
170 | |
171 DISALLOW_COPY_AND_ASSIGN(FeaturePolicy); | |
172 }; | |
173 | |
174 // Declarations for all features currently under control of the Feature Policy | |
175 // mechanism should be placed here. | |
176 extern const PLATFORM_EXPORT FeaturePolicy::Feature kDocumentCookie; | |
177 extern const PLATFORM_EXPORT FeaturePolicy::Feature kDocumentDomain; | |
178 extern const PLATFORM_EXPORT FeaturePolicy::Feature kDocumentWrite; | |
179 extern const PLATFORM_EXPORT FeaturePolicy::Feature kGeolocationFeature; | |
180 extern const PLATFORM_EXPORT FeaturePolicy::Feature kMidiFeature; | |
181 extern const PLATFORM_EXPORT FeaturePolicy::Feature kNotificationsFeature; | |
182 extern const PLATFORM_EXPORT FeaturePolicy::Feature kPaymentFeature; | |
183 extern const PLATFORM_EXPORT FeaturePolicy::Feature kPushFeature; | |
184 extern const PLATFORM_EXPORT FeaturePolicy::Feature kSyncScript; | |
185 extern const PLATFORM_EXPORT FeaturePolicy::Feature kSyncXHR; | |
186 extern const PLATFORM_EXPORT FeaturePolicy::Feature kUsermedia; | |
187 extern const PLATFORM_EXPORT FeaturePolicy::Feature kVibrateFeature; | |
188 extern const PLATFORM_EXPORT FeaturePolicy::Feature kWebRTC; | |
189 | |
190 } // namespace blink | |
191 | |
192 #endif // FeaturePolicy_h | |
OLD | NEW |