Merge Chromium + Blink git repositories
[chromium-blink-merge.git] / extensions / common / extension.h
blob4d7f568577a1dd3a9c7bc467fe51856f3c51cc58
1 // Copyright (c) 2013 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.
5 #ifndef EXTENSIONS_COMMON_EXTENSION_H_
6 #define EXTENSIONS_COMMON_EXTENSION_H_
8 #include <algorithm>
9 #include <iosfwd>
10 #include <map>
11 #include <set>
12 #include <string>
13 #include <utility>
14 #include <vector>
16 #include "base/containers/hash_tables.h"
17 #include "base/files/file_path.h"
18 #include "base/memory/linked_ptr.h"
19 #include "base/memory/ref_counted.h"
20 #include "base/memory/scoped_ptr.h"
21 #include "base/synchronization/lock.h"
22 #include "base/threading/thread_checker.h"
23 #include "extensions/common/extension_resource.h"
24 #include "extensions/common/install_warning.h"
25 #include "extensions/common/manifest.h"
26 #include "extensions/common/url_pattern_set.h"
27 #include "ui/base/accelerators/accelerator.h"
28 #include "url/gurl.h"
30 #if !defined(ENABLE_EXTENSIONS)
31 #error "Extensions must be enabled"
32 #endif
34 namespace base {
35 class DictionaryValue;
36 class Version;
39 namespace extensions {
40 class PermissionSet;
41 class PermissionsData;
42 class PermissionsParser;
44 // Uniquely identifies an Extension, using 32 characters from the alphabet
45 // 'a'-'p'. An empty string represents "no extension".
47 // Note: If this gets used heavily in files that don't otherwise need to include
48 // extension.h, we should pull it into a dedicated header.
49 typedef std::string ExtensionId;
51 // Represents a Chrome extension.
52 // Once created, an Extension object is immutable, with the exception of its
53 // RuntimeData. This makes it safe to use on any thread, since access to the
54 // RuntimeData is protected by a lock.
55 class Extension : public base::RefCountedThreadSafe<Extension> {
56 public:
57 struct ManifestData;
59 typedef std::map<const std::string, linked_ptr<ManifestData> >
60 ManifestDataMap;
62 enum State {
63 DISABLED = 0,
64 ENABLED,
65 // An external extension that the user uninstalled. We should not reinstall
66 // such extensions on startup.
67 EXTERNAL_EXTENSION_UNINSTALLED,
68 // DEPRECATED: Special state for component extensions.
69 // Maintained as a placeholder since states may be stored to disk.
70 ENABLED_COMPONENT_DEPRECATED,
71 // Add new states here as this enum is stored in prefs.
72 NUM_STATES
75 // Used to record the reason an extension was disabled.
76 enum DeprecatedDisableReason {
77 DEPRECATED_DISABLE_UNKNOWN,
78 DEPRECATED_DISABLE_USER_ACTION,
79 DEPRECATED_DISABLE_PERMISSIONS_INCREASE,
80 DEPRECATED_DISABLE_RELOAD,
81 DEPRECATED_DISABLE_LAST, // Not used.
84 // Reasons an extension may be disabled. These are used in histograms, so do
85 // not remove/reorder entries - only add at the end just before
86 // DISABLE_REASON_LAST (and update the shift value for it). Also remember to
87 // update the enum listing in tools/metrics/histograms.xml.
88 enum DisableReason {
89 DISABLE_NONE = 0,
90 DISABLE_USER_ACTION = 1 << 0,
91 DISABLE_PERMISSIONS_INCREASE = 1 << 1,
92 DISABLE_RELOAD = 1 << 2,
93 DISABLE_UNSUPPORTED_REQUIREMENT = 1 << 3,
94 DISABLE_SIDELOAD_WIPEOUT = 1 << 4,
95 DISABLE_UNKNOWN_FROM_SYNC = 1 << 5,
96 // DISABLE_PERMISSIONS_CONSENT = 1 << 6, // Deprecated.
97 // DISABLE_KNOWN_DISABLED = 1 << 7, // Deprecated.
98 DISABLE_NOT_VERIFIED = 1 << 8, // Disabled because we could not verify
99 // the install.
100 DISABLE_GREYLIST = 1 << 9,
101 DISABLE_CORRUPTED = 1 << 10,
102 DISABLE_REMOTE_INSTALL = 1 << 11,
103 DISABLE_INACTIVE_EPHEMERAL_APP = 1 << 12, // Cached ephemeral apps are
104 // disabled to prevent activity.
105 DISABLE_EXTERNAL_EXTENSION = 1 << 13, // External extensions might be
106 // disabled for user prompting.
107 DISABLE_UPDATE_REQUIRED_BY_POLICY = 1 << 14, // Doesn't meet minimum
108 // version requirement.
109 DISABLE_REASON_LAST = 1 << 15, // This should always be the last value
112 // A base class for parsed manifest data that APIs want to store on
113 // the extension. Related to base::SupportsUserData, but with an immutable
114 // thread-safe interface to match Extension.
115 struct ManifestData {
116 virtual ~ManifestData() {}
119 // Do not change the order of entries or remove entries in this list
120 // as this is used in UMA_HISTOGRAM_ENUMERATIONs about extensions.
121 enum InitFromValueFlags {
122 NO_FLAGS = 0,
124 // Usually, the id of an extension is generated by the "key" property of
125 // its manifest, but if |REQUIRE_KEY| is not set, a temporary ID will be
126 // generated based on the path.
127 REQUIRE_KEY = 1 << 0,
129 // Requires the extension to have an up-to-date manifest version.
130 // Typically, we'll support multiple manifest versions during a version
131 // transition. This flag signals that we want to require the most modern
132 // manifest version that Chrome understands.
133 REQUIRE_MODERN_MANIFEST_VERSION = 1 << 1,
135 // |ALLOW_FILE_ACCESS| indicates that the user is allowing this extension
136 // to have file access. If it's not present, then permissions and content
137 // scripts that match file:/// URLs will be filtered out.
138 ALLOW_FILE_ACCESS = 1 << 2,
140 // |FROM_WEBSTORE| indicates that the extension was installed from the
141 // Chrome Web Store.
142 FROM_WEBSTORE = 1 << 3,
144 // |FROM_BOOKMARK| indicates the extension is a bookmark app which has been
145 // generated from a web page. Bookmark apps have no permissions or extent
146 // and launch the web page they are created from when run.
147 FROM_BOOKMARK = 1 << 4,
149 // |FOLLOW_SYMLINKS_ANYWHERE| means that resources can be symlinks to
150 // anywhere in the filesystem, rather than being restricted to the
151 // extension directory.
152 FOLLOW_SYMLINKS_ANYWHERE = 1 << 5,
154 // |ERROR_ON_PRIVATE_KEY| means that private keys inside an
155 // extension should be errors rather than warnings.
156 ERROR_ON_PRIVATE_KEY = 1 << 6,
158 // |WAS_INSTALLED_BY_DEFAULT| installed by default when the profile was
159 // created.
160 WAS_INSTALLED_BY_DEFAULT = 1 << 7,
162 // Unused - was part of an abandoned experiment.
163 REQUIRE_PERMISSIONS_CONSENT = 1 << 8,
165 // Unused - this flag has been moved to ExtensionPrefs.
166 IS_EPHEMERAL = 1 << 9,
168 // |WAS_INSTALLED_BY_OEM| installed by an OEM (e.g on Chrome OS) and should
169 // be placed in a special OEM folder in the App Launcher. Note: OEM apps are
170 // also installed by Default (i.e. WAS_INSTALLED_BY_DEFAULT is also true).
171 WAS_INSTALLED_BY_OEM = 1 << 10,
173 // |WAS_INSTALLED_BY_CUSTODIAN| means this extension was installed by the
174 // custodian of a supervised user.
175 WAS_INSTALLED_BY_CUSTODIAN = 1 << 11,
177 // |MAY_BE_UNTRUSTED| indicates that this extension came from a potentially
178 // unsafe source (e.g., sideloaded from a local CRX file via the Windows
179 // registry). Such extensions may be subjected to additional constraints
180 // before they are fully installed and enabled.
181 MAY_BE_UNTRUSTED = 1 << 12,
183 // When adding new flags, make sure to update kInitFromValueFlagBits.
186 // This is the highest bit index of the flags defined above.
187 static const int kInitFromValueFlagBits;
189 static scoped_refptr<Extension> Create(const base::FilePath& path,
190 Manifest::Location location,
191 const base::DictionaryValue& value,
192 int flags,
193 std::string* error);
195 // In a few special circumstances, we want to create an Extension and give it
196 // an explicit id. Most consumers should just use the other Create() method.
197 static scoped_refptr<Extension> Create(const base::FilePath& path,
198 Manifest::Location location,
199 const base::DictionaryValue& value,
200 int flags,
201 const ExtensionId& explicit_id,
202 std::string* error);
204 // Valid schemes for web extent URLPatterns.
205 static const int kValidWebExtentSchemes;
207 // Valid schemes for bookmark app installs.
208 static const int kValidBookmarkAppSchemes;
210 // Valid schemes for host permission URLPatterns.
211 static const int kValidHostPermissionSchemes;
213 // The mimetype used for extensions.
214 static const char kMimeType[];
216 // See Type definition in Manifest.
217 Manifest::Type GetType() const;
219 // Returns an absolute url to a resource inside of an extension. The
220 // |extension_url| argument should be the url() from an Extension object. The
221 // |relative_path| can be untrusted user input. The returned URL will either
222 // be invalid() or a child of |extension_url|.
223 // NOTE: Static so that it can be used from multiple threads.
224 static GURL GetResourceURL(const GURL& extension_url,
225 const std::string& relative_path);
226 GURL GetResourceURL(const std::string& relative_path) const {
227 return GetResourceURL(url(), relative_path);
230 // Returns true if the resource matches a pattern in the pattern_set.
231 bool ResourceMatches(const URLPatternSet& pattern_set,
232 const std::string& resource) const;
234 // Returns an extension resource object. |relative_path| should be UTF8
235 // encoded.
236 ExtensionResource GetResource(const std::string& relative_path) const;
238 // As above, but with |relative_path| following the file system's encoding.
239 ExtensionResource GetResource(const base::FilePath& relative_path) const;
241 // |input| is expected to be the text of an rsa public or private key. It
242 // tolerates the presence or absence of bracking header/footer like this:
243 // -----(BEGIN|END) [RSA PUBLIC/PRIVATE] KEY-----
244 // and may contain newlines.
245 static bool ParsePEMKeyBytes(const std::string& input, std::string* output);
247 // Does a simple base64 encoding of |input| into |output|.
248 static bool ProducePEM(const std::string& input, std::string* output);
250 // Expects base64 encoded |input| and formats into |output| including
251 // the appropriate header & footer.
252 static bool FormatPEMForFileOutput(const std::string& input,
253 std::string* output,
254 bool is_public);
256 // Returns the base extension url for a given |extension_id|.
257 static GURL GetBaseURLFromExtensionId(const ExtensionId& extension_id);
259 // Whether context menu should be shown for page and browser actions.
260 bool ShowConfigureContextMenus() const;
262 // Returns true if this extension or app includes areas within |origin|.
263 bool OverlapsWithOrigin(const GURL& origin) const;
265 // Returns true if the extension requires a valid ordinal for sorting, e.g.,
266 // for displaying in a launcher or new tab page.
267 bool RequiresSortOrdinal() const;
269 // Returns true if the extension should be displayed in the app launcher.
270 bool ShouldDisplayInAppLauncher() const;
272 // Returns true if the extension should be displayed in the browser NTP.
273 bool ShouldDisplayInNewTabPage() const;
275 // Returns true if the extension should be displayed in the extension
276 // settings page (i.e. chrome://extensions).
277 bool ShouldDisplayInExtensionSettings() const;
279 // Returns true if the extension should not be shown anywhere. This is
280 // mostly the same as the extension being a component extension, but also
281 // includes non-component apps that are hidden from the app launcher and ntp.
282 bool ShouldNotBeVisible() const;
284 // Get the manifest data associated with the key, or NULL if there is none.
285 // Can only be called after InitValue is finished.
286 ManifestData* GetManifestData(const std::string& key) const;
288 // Sets |data| to be associated with the key. Takes ownership of |data|.
289 // Can only be called before InitValue is finished. Not thread-safe;
290 // all SetManifestData calls should be on only one thread.
291 void SetManifestData(const std::string& key, ManifestData* data);
293 // Accessors:
295 const base::FilePath& path() const { return path_; }
296 const GURL& url() const { return extension_url_; }
297 Manifest::Location location() const;
298 const ExtensionId& id() const;
299 const base::Version* version() const { return version_.get(); }
300 const std::string VersionString() const;
301 const std::string GetVersionForDisplay() const;
302 const std::string& name() const { return name_; }
303 const std::string& short_name() const { return short_name_; }
304 const std::string& non_localized_name() const { return non_localized_name_; }
305 // Base64-encoded version of the key used to sign this extension.
306 // In pseudocode, returns
307 // base::Base64Encode(RSAPrivateKey(pem_file).ExportPublicKey()).
308 const std::string& public_key() const { return public_key_; }
309 const std::string& description() const { return description_; }
310 int manifest_version() const { return manifest_version_; }
311 bool converted_from_user_script() const {
312 return converted_from_user_script_;
314 PermissionsParser* permissions_parser() { return permissions_parser_.get(); }
315 const PermissionsParser* permissions_parser() const {
316 return permissions_parser_.get();
319 const PermissionsData* permissions_data() const {
320 return permissions_data_.get();
323 // Appends |new_warning[s]| to install_warnings_.
324 void AddInstallWarning(const InstallWarning& new_warning);
325 void AddInstallWarnings(const std::vector<InstallWarning>& new_warnings);
326 const std::vector<InstallWarning>& install_warnings() const {
327 return install_warnings_;
329 const extensions::Manifest* manifest() const {
330 return manifest_.get();
332 bool wants_file_access() const { return wants_file_access_; }
333 // TODO(rdevlin.cronin): This is needed for ContentScriptsHandler, and should
334 // be moved out as part of crbug.com/159265. This should not be used anywhere
335 // else.
336 void set_wants_file_access(bool wants_file_access) {
337 wants_file_access_ = wants_file_access;
339 int creation_flags() const { return creation_flags_; }
340 bool from_webstore() const { return (creation_flags_ & FROM_WEBSTORE) != 0; }
341 bool from_bookmark() const { return (creation_flags_ & FROM_BOOKMARK) != 0; }
342 bool was_installed_by_default() const {
343 return (creation_flags_ & WAS_INSTALLED_BY_DEFAULT) != 0;
345 bool was_installed_by_oem() const {
346 return (creation_flags_ & WAS_INSTALLED_BY_OEM) != 0;
348 bool was_installed_by_custodian() const {
349 return (creation_flags_ & WAS_INSTALLED_BY_CUSTODIAN) != 0;
352 // Type-related queries.
353 bool is_app() const;
354 bool is_platform_app() const;
355 bool is_hosted_app() const;
356 bool is_legacy_packaged_app() const;
357 bool is_extension() const;
358 bool is_shared_module() const;
359 bool is_theme() const;
361 void AddWebExtentPattern(const URLPattern& pattern);
362 const URLPatternSet& web_extent() const { return extent_; }
364 private:
365 friend class base::RefCountedThreadSafe<Extension>;
367 // Chooses the extension ID for an extension based on a variety of criteria.
368 // The chosen ID will be set in |manifest|.
369 static bool InitExtensionID(extensions::Manifest* manifest,
370 const base::FilePath& path,
371 const ExtensionId& explicit_id,
372 int creation_flags,
373 base::string16* error);
375 Extension(const base::FilePath& path,
376 scoped_ptr<extensions::Manifest> manifest);
377 virtual ~Extension();
379 // Initialize the extension from a parsed manifest.
380 // TODO(aa): Rename to just Init()? There's no Value here anymore.
381 // TODO(aa): It is really weird the way this class essentially contains a copy
382 // of the underlying DictionaryValue in its members. We should decide to
383 // either wrap the DictionaryValue and go with that only, or we should parse
384 // into strong types and discard the value. But doing both is bad.
385 bool InitFromValue(int flags, base::string16* error);
387 // The following are helpers for InitFromValue to load various features of the
388 // extension from the manifest.
390 bool LoadRequiredFeatures(base::string16* error);
391 bool LoadName(base::string16* error);
392 bool LoadVersion(base::string16* error);
394 bool LoadAppFeatures(base::string16* error);
395 bool LoadExtent(const char* key,
396 URLPatternSet* extent,
397 const char* list_error,
398 const char* value_error,
399 base::string16* error);
401 bool LoadSharedFeatures(base::string16* error);
402 bool LoadDescription(base::string16* error);
403 bool LoadManifestVersion(base::string16* error);
404 bool LoadShortName(base::string16* error);
406 bool CheckMinimumChromeVersion(base::string16* error) const;
408 // The extension's human-readable name. Name is used for display purpose. It
409 // might be wrapped with unicode bidi control characters so that it is
410 // displayed correctly in RTL context.
411 // NOTE: Name is UTF-8 and may contain non-ascii characters.
412 std::string name_;
414 // A non-localized version of the extension's name. This is useful for
415 // debug output.
416 std::string non_localized_name_;
418 // A short version of the extension's name. This can be used as an alternative
419 // to the name where there is insufficient space to display the full name. If
420 // an extension has not explicitly specified a short name, the value of this
421 // member variable will be the full name rather than an empty string.
422 std::string short_name_;
424 // The version of this extension's manifest. We increase the manifest
425 // version when making breaking changes to the extension system.
426 // Version 1 was the first manifest version (implied by a lack of a
427 // manifest_version attribute in the extension's manifest). We initialize
428 // this member variable to 0 to distinguish the "uninitialized" case from
429 // the case when we know the manifest version actually is 1.
430 int manifest_version_;
432 // The absolute path to the directory the extension is stored in.
433 base::FilePath path_;
435 // Defines the set of URLs in the extension's web content.
436 URLPatternSet extent_;
438 // The parser for the manifest's permissions. This is NULL anytime not during
439 // initialization.
440 // TODO(rdevlin.cronin): This doesn't really belong here.
441 scoped_ptr<PermissionsParser> permissions_parser_;
443 // The active permissions for the extension.
444 scoped_ptr<PermissionsData> permissions_data_;
446 // Any warnings that occurred when trying to create/parse the extension.
447 std::vector<InstallWarning> install_warnings_;
449 // The base extension url for the extension.
450 GURL extension_url_;
452 // The extension's version.
453 scoped_ptr<base::Version> version_;
455 // The extension's user visible version name.
456 std::string version_name_;
458 // An optional longer description of the extension.
459 std::string description_;
461 // True if the extension was generated from a user script. (We show slightly
462 // different UI if so).
463 bool converted_from_user_script_;
465 // The public key used to sign the contents of the crx package.
466 std::string public_key_;
468 // The manifest from which this extension was created.
469 scoped_ptr<Manifest> manifest_;
471 // Stored parsed manifest data.
472 ManifestDataMap manifest_data_;
474 // Set to true at the end of InitValue when initialization is finished.
475 bool finished_parsing_manifest_;
477 // Ensures that any call to GetManifestData() prior to finishing
478 // initialization happens from the same thread (this can happen when certain
479 // parts of the initialization process need information from previous parts).
480 base::ThreadChecker thread_checker_;
482 // Should this app be shown in the app launcher.
483 bool display_in_launcher_;
485 // Should this app be shown in the browser New Tab Page.
486 bool display_in_new_tab_page_;
488 // Whether the extension has host permissions or user script patterns that
489 // imply access to file:/// scheme URLs (the user may not have actually
490 // granted it that access).
491 bool wants_file_access_;
493 // The flags that were passed to InitFromValue.
494 int creation_flags_;
496 DISALLOW_COPY_AND_ASSIGN(Extension);
499 typedef std::vector<scoped_refptr<const Extension> > ExtensionList;
500 typedef std::set<ExtensionId> ExtensionIdSet;
501 typedef std::vector<ExtensionId> ExtensionIdList;
503 // Handy struct to pass core extension info around.
504 struct ExtensionInfo {
505 ExtensionInfo(const base::DictionaryValue* manifest,
506 const ExtensionId& id,
507 const base::FilePath& path,
508 Manifest::Location location);
509 ~ExtensionInfo();
511 scoped_ptr<base::DictionaryValue> extension_manifest;
512 ExtensionId extension_id;
513 base::FilePath extension_path;
514 Manifest::Location extension_location;
516 private:
517 DISALLOW_COPY_AND_ASSIGN(ExtensionInfo);
520 struct InstalledExtensionInfo {
521 // The extension being installed - this should always be non-NULL.
522 const Extension* extension;
524 // True if the extension is being updated; false if it is being installed.
525 bool is_update;
527 // True if the extension was previously installed ephemerally and is now
528 // a regular installed extension.
529 bool from_ephemeral;
531 // The name of the extension prior to this update. Will be empty if
532 // |is_update| is false.
533 std::string old_name;
535 InstalledExtensionInfo(const Extension* extension,
536 bool is_update,
537 bool from_ephemeral,
538 const std::string& old_name);
541 struct UnloadedExtensionInfo {
542 // TODO(DHNishi): Move this enum to ExtensionRegistryObserver.
543 enum Reason {
544 REASON_UNDEFINED, // Undefined state used to initialize variables.
545 REASON_DISABLE, // Extension is being disabled.
546 REASON_UPDATE, // Extension is being updated to a newer version.
547 REASON_UNINSTALL, // Extension is being uninstalled.
548 REASON_TERMINATE, // Extension has terminated.
549 REASON_BLACKLIST, // Extension has been blacklisted.
550 REASON_PROFILE_SHUTDOWN, // Profile is being shut down.
551 REASON_LOCK_ALL, // All extensions for the profile are blocked.
554 Reason reason;
556 // The extension being unloaded - this should always be non-NULL.
557 const Extension* extension;
559 UnloadedExtensionInfo(const Extension* extension, Reason reason);
562 // The details sent for EXTENSION_PERMISSIONS_UPDATED notifications.
563 struct UpdatedExtensionPermissionsInfo {
564 enum Reason {
565 ADDED, // The permissions were added to the extension.
566 REMOVED, // The permissions were removed from the extension.
569 Reason reason;
571 // The extension who's permissions have changed.
572 const Extension* extension;
574 // The permissions that have changed. For Reason::ADDED, this would contain
575 // only the permissions that have added, and for Reason::REMOVED, this would
576 // only contain the removed permissions.
577 const PermissionSet* permissions;
579 UpdatedExtensionPermissionsInfo(
580 const Extension* extension,
581 const PermissionSet* permissions,
582 Reason reason);
585 } // namespace extensions
587 #endif // EXTENSIONS_COMMON_EXTENSION_H_