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* const featureName; |
| 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 |