extensions/common/permissions/api_permission.h

   1 // Copyright 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_PERMISSIONS_API_PERMISSION_H_
   6 #define EXTENSIONS_COMMON_PERMISSIONS_API_PERMISSION_H_
   7
   8 #include <map>
   9 #include <set>
  10 #include <string>
  11
  12 #include "base/callback.h"
  13 #include "base/memory/scoped_ptr.h"
  14 #include "base/pickle.h"
  15 #include "base/values.h"
  16 #include "extensions/common/permissions/permission_message.h"
  17
  18 namespace IPC {
  19 class Message;
  20 }
  21
  22 namespace extensions {
  23
  24 class APIPermissionInfo;
  25 class ChromeAPIPermissions;
  26
  27 // APIPermission is for handling some complex permissions. Please refer to
  28 // extensions::SocketPermission as an example.
  29 // There is one instance per permission per loaded extension.
  30 class APIPermission {
  31  public:
  32   // The IDs of all permissions available to apps. Add as many permissions here
  33   // as needed to generate meaningful permission messages. Add the rules for the
  34   // messages to ChromePermissionMessageProvider.
  35   // Remove permissions from this list if they have no longer have a
  36   // corresponding API permission and no permission message.
  37   // TODO(sashab): Move this to a more central location, and rename it to
  38   // PermissionID.
  39   enum ID {
  40     // Error codes.
  41     kInvalid = -2,
  42     kUnknown = -1,
  43
  44     // Real permissions.
  45     kAccessibilityFeaturesModify,
  46     kAccessibilityFeaturesRead,
  47     kAccessibilityPrivate,
  48     kActiveTab,
  49     kActivityLogPrivate,
  50     kAlarms,
  51     kAlphaEnabled,
  52     kAlwaysOnTopWindows,
  53     kAppView,
  54     kAudio,
  55     kAudioCapture,
  56     kAutomation,
  57     kAutoTestPrivate,
  58     kBackground,
  59     kBluetoothPrivate,
  60     kBookmark,
  61     kBookmarkManagerPrivate,
  62     kBrailleDisplayPrivate,
  63     kBrowser,
  64     kBrowsingData,
  65     kCast,
  66     kCastStreaming,
  67     kChromeosInfoPrivate,
  68     kClipboardRead,
  69     kClipboardWrite,
  70     kCloudPrintPrivate,
  71     kCommandLinePrivate,
  72     kCommandsAccessibility,
  73     kContentSettings,
  74     kContextMenus,
  75     kCookie,
  76     kCopresence,
  77     kCopresencePrivate,
  78     kDiagnostics,
  79     kDial,
  80     kDebugger,
  81     kDeclarative,
  82     kDeclarativeContent,
  83     kDeclarativeWebRequest,
  84     kDesktopCapture,
  85     kDeveloperPrivate,
  86     kDevtools,
  87     kDns,
  88     kDocumentScan,
  89     kDownloads,
  90     kDownloadsInternal,
  91     kDownloadsOpen,
  92     kDownloadsShelf,
  93     kEasyUnlockPrivate,
  94     kEchoPrivate,
  95     kEmbeddedExtensionOptions,
  96     kEnterprisePlatformKeys,
  97     kEnterprisePlatformKeysPrivate,
  98     kExperienceSamplingPrivate,
  99     kExperimental,
 100     kExternallyConnectableAllUrls,
 101     kFeedbackPrivate,
 102     kFileBrowserHandler,
 103     kFileBrowserHandlerInternal,
 104     kFileManagerPrivate,
 105     kFileSystem,
 106     kFileSystemDirectory,
 107     kFileSystemProvider,
 108     kFileSystemRetainEntries,
 109     kFileSystemWrite,
 110     kFileSystemWriteDirectory,
 111     kFirstRunPrivate,
 112     kFontSettings,
 113     kFullscreen,
 114     kGcdPrivate,
 115     kGcm,
 116     kGeolocation,
 117     kHid,
 118     kHistory,
 119     kHomepage,
 120     kHotwordPrivate,
 121     kIdentity,
 122     kIdentityEmail,
 123     kIdentityPrivate,
 124     kIdltest,
 125     kIdle,
 126     kImeWindowEnabled,
 127     kInfobars,
 128     kInlineInstallPrivate,
 129     kInput,
 130     kInputMethodPrivate,
 131     kInterceptAllKeys,
 132     kLocation,
 133     kLogPrivate,
 134     kManagement,
 135     kMediaGalleries,
 136     kMediaGalleriesPrivate,
 137     kMediaPlayerPrivate,
 138     kMetricsPrivate,
 139     kMDns,
 140     kMusicManagerPrivate,
 141     kNativeMessaging,
 142     kNetworkingPrivate,
 143     kNotificationProvider,
 144     kNotifications,
 145     kOverrideEscFullscreen,
 146     kPageCapture,
 147     kPointerLock,
 148     kPlugin,
 149     kPower,
 150     kPreferencesPrivate,
 151     kPrincipalsPrivate,
 152     kPrinterProvider,
 153     kPrivacy,
 154     kProcesses,
 155     kProxy,
 156     kPushMessaging,
 157     kImageWriterPrivate,
 158     kReadingListPrivate,
 159     kRtcPrivate,
 160     kSearchProvider,
 161     kSerial,
 162     kSessions,
 163     kSignedInDevices,
 164     kSocket,
 165     kStartupPages,
 166     kStorage,
 167     kStreamsPrivate,
 168     kSyncFileSystem,
 169     kSyncedNotificationsPrivate,
 170     kSystemPrivate,
 171     kSystemDisplay,
 172     kSystemStorage,
 173     kTab,
 174     kTabCapture,
 175     kTabCaptureForTab,
 176     kTerminalPrivate,
 177     kTopSites,
 178     kTts,
 179     kTtsEngine,
 180     kUnlimitedStorage,
 181     kU2fDevices,
 182     kUsb,
 183     kUsbDevice,
 184     kVideoCapture,
 185     kVirtualKeyboardPrivate,
 186     kVpnProvider,
 187     kWallpaper,
 188     kWallpaperPrivate,
 189     kWebcamPrivate,
 190     kWebConnectable,  // for externally_connectable manifest key
 191     kWebNavigation,
 192     kWebRequest,
 193     kWebRequestBlocking,
 194     kWebrtcAudioPrivate,
 195     kWebrtcLoggingPrivate,
 196     kWebstorePrivate,
 197     kWebView,
 198     kWindowShape,
 199     kScreenlockPrivate,
 200     kSystemCpu,
 201     kSystemMemory,
 202     kSystemNetwork,
 203     kSystemInfoCpu,
 204     kSystemInfoMemory,
 205
 206     // Permission message IDs that are not currently valid permissions on their
 207     // own, but are needed by various manifest permissions to represent their
 208     // permission message rule combinations.
 209     // TODO(sashab): Move these in-line with the other permission IDs.
 210     kBluetooth,
 211     kBluetoothDevices,
 212     kFavicon,
 213     kFullAccess,
 214     kHostReadOnly,
 215     kHostReadWrite,
 216     kHostsAll,
 217     kHostsAllReadOnly,
 218     kOverrideBookmarksUI,
 219     kSocketAnyHost,
 220     kSocketDomainHostsSingular,
 221     kSocketDomainHostsPlural,
 222     kSocketSpecificHostsSingular,
 223     kSocketSpecificHostsPlural,
 224     kNetworkState,
 225
 226     kEnumBoundary
 227   };
 228
 229   struct CheckParam {
 230   };
 231
 232   explicit APIPermission(const APIPermissionInfo* info);
 233
 234   virtual ~APIPermission();
 235
 236   // Returns the id of this permission.
 237   ID id() const;
 238
 239   // Returns the name of this permission.
 240   const char* name() const;
 241
 242   // Returns the APIPermission of this permission.
 243   const APIPermissionInfo* info() const {
 244     return info_;
 245   }
 246
 247   // Returns true if this permission has any PermissionMessages.
 248   virtual bool HasMessages() const = 0;
 249
 250   // Returns the localized permission messages of this permission.
 251   virtual PermissionMessages GetMessages() const = 0;
 252
 253   // Returns true if the given permission is allowed.
 254   virtual bool Check(const CheckParam* param) const = 0;
 255
 256   // Returns true if |rhs| is a subset of this.
 257   virtual bool Contains(const APIPermission* rhs) const = 0;
 258
 259   // Returns true if |rhs| is equal to this.
 260   virtual bool Equal(const APIPermission* rhs) const = 0;
 261
 262   // Parses the APIPermission from |value|. Returns false if an error happens
 263   // and optionally set |error| if |error| is not NULL. If |value| represents
 264   // multiple permissions, some are invalid, and |unhandled_permissions| is
 265   // not NULL, the invalid ones are put into |unhandled_permissions| and the
 266   // function returns true.
 267   virtual bool FromValue(const base::Value* value,
 268                          std::string* error,
 269                          std::vector<std::string>* unhandled_permissions) = 0;
 270
 271   // Stores this into a new created |value|.
 272   virtual scoped_ptr<base::Value> ToValue() const = 0;
 273
 274   // Clones this.
 275   virtual APIPermission* Clone() const = 0;
 276
 277   // Returns a new API permission which equals this - |rhs|.
 278   virtual APIPermission* Diff(const APIPermission* rhs) const = 0;
 279
 280   // Returns a new API permission which equals the union of this and |rhs|.
 281   virtual APIPermission* Union(const APIPermission* rhs) const = 0;
 282
 283   // Returns a new API permission which equals the intersect of this and |rhs|.
 284   virtual APIPermission* Intersect(const APIPermission* rhs) const = 0;
 285
 286   // IPC functions
 287   // Writes this into the given IPC message |m|.
 288   virtual void Write(IPC::Message* m) const = 0;
 289
 290   // Reads from the given IPC message |m|.
 291   virtual bool Read(const IPC::Message* m, PickleIterator* iter) = 0;
 292
 293   // Logs this permission.
 294   virtual void Log(std::string* log) const = 0;
 295
 296  protected:
 297   // Returns the localized permission message associated with this api.
 298   // Use GetMessage_ to avoid name conflict with macro GetMessage on Windows.
 299   PermissionMessage GetMessage_() const;
 300
 301  private:
 302   const APIPermissionInfo* const info_;
 303 };
 304
 305
 306 // The APIPermissionInfo is an immutable class that describes a single
 307 // named permission (API permission).
 308 // There is one instance per permission.
 309 class APIPermissionInfo {
 310  public:
 311   enum Flag {
 312     kFlagNone = 0,
 313
 314     // Indicates if the permission implies full access (native code).
 315     kFlagImpliesFullAccess = 1 << 0,
 316
 317     // Indicates if the permission implies full URL access.
 318     kFlagImpliesFullURLAccess = 1 << 1,
 319
 320     // Indicates that extensions cannot specify the permission as optional.
 321     kFlagCannotBeOptional = 1 << 3,
 322
 323     // Indicates that the permission is internal to the extensions
 324     // system and cannot be specified in the "permissions" list.
 325     kFlagInternal = 1 << 4,
 326
 327     // Indicates that the permission may be granted to web contents by
 328     // extensions using the content_capabilities manifest feature.
 329     kFlagSupportsContentCapabilities = 1 << 5,
 330   };
 331
 332   typedef APIPermission* (*APIPermissionConstructor)(const APIPermissionInfo*);
 333
 334   typedef std::set<APIPermission::ID> IDSet;
 335
 336   ~APIPermissionInfo();
 337
 338   // Creates a APIPermission instance.
 339   APIPermission* CreateAPIPermission() const;
 340
 341   int flags() const { return flags_; }
 342
 343   APIPermission::ID id() const { return id_; }
 344
 345   // Returns the message id associated with this permission.
 346   PermissionMessage::ID message_id() const {
 347     return message_id_;
 348   }
 349
 350   // Returns the name of this permission.
 351   const char* name() const { return name_; }
 352
 353   // Returns true if this permission implies full access (e.g., native code).
 354   bool implies_full_access() const {
 355     return (flags_ & kFlagImpliesFullAccess) != 0;
 356   }
 357
 358   // Returns true if this permission implies full URL access.
 359   bool implies_full_url_access() const {
 360     return (flags_ & kFlagImpliesFullURLAccess) != 0;
 361   }
 362
 363   // Returns true if this permission can be added and removed via the
 364   // optional permissions extension API.
 365   bool supports_optional() const {
 366     return (flags_ & kFlagCannotBeOptional) == 0;
 367   }
 368
 369   // Returns true if this permission is internal rather than a
 370   // "permissions" list entry.
 371   bool is_internal() const {
 372     return (flags_ & kFlagInternal) != 0;
 373   }
 374
 375   // Returns true if this permission can be granted to web contents by an
 376   // extension through the content_capabilities manifest feature.
 377   bool supports_content_capabilities() const {
 378     return (flags_ & kFlagSupportsContentCapabilities) != 0;
 379   }
 380
 381  private:
 382   // Instances should only be constructed from within a PermissionsProvider.
 383   friend class ChromeAPIPermissions;
 384   friend class ExtensionsAPIPermissions;
 385   // Implementations of APIPermission will want to get the permission message,
 386   // but this class's implementation should be hidden from everyone else.
 387   friend class APIPermission;
 388
 389   // This exists to allow aggregate initialization, so that default values
 390   // for flags, etc. can be omitted.
 391   // TODO(yoz): Simplify the way initialization is done. APIPermissionInfo
 392   // should be the simple data struct.
 393   struct InitInfo {
 394     APIPermission::ID id;
 395     const char* name;
 396     int flags;
 397     int l10n_message_id;
 398     PermissionMessage::ID message_id;
 399     APIPermissionInfo::APIPermissionConstructor constructor;
 400   };
 401
 402   explicit APIPermissionInfo(const InitInfo& info);
 403
 404   // Returns the localized permission message associated with this api.
 405   // Use GetMessage_ to avoid name conflict with macro GetMessage on Windows.
 406   PermissionMessage GetMessage_() const;
 407
 408   const APIPermission::ID id_;
 409   const char* const name_;
 410   const int flags_;
 411   const int l10n_message_id_;
 412   const PermissionMessage::ID message_id_;
 413   const APIPermissionConstructor api_permission_constructor_;
 414 };
 415
 416 }  // namespace extensions
 417
 418 #endif  // EXTENSIONS_COMMON_PERMISSIONS_API_PERMISSION_H_