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