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