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