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.
5 #ifndef EXTENSIONS_COMMON_PERMISSIONS_API_PERMISSION_H_
6 #define EXTENSIONS_COMMON_PERMISSIONS_API_PERMISSION_H_
12 #include "base/callback.h"
13 #include "base/memory/scoped_ptr.h"
14 #include "base/pickle.h"
15 #include "base/values.h"
21 namespace extensions
{
23 class PermissionIDSet
;
24 class APIPermissionInfo
;
25 class ChromeAPIPermissions
;
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.
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 // Do not reorder this enumeration or remove any entries. If you need to add a
36 // new entry, add it just prior to kEnumBoundary, and ensure to update the
37 // "ExtensionPermission3" enum in tools/metrics/histograms/histograms.xml
38 // (by running update_extension_permission.py).
39 // TODO(sashab): Move this to a more central location, and rename it to
46 // Actual permission IDs. Not all of these are valid permissions on their
47 // own; some are just needed by various manifest permissions to represent
48 // their permission message rule combinations.
49 kAccessibilityFeaturesModify
,
50 kAccessibilityFeaturesRead
,
51 kAccessibilityPrivate
,
67 kBookmarkManagerPrivate
,
68 kBrailleDisplayPrivate
,
78 kCommandsAccessibility
,
91 kDeclarativeWebRequest
,
93 kDesktopCapturePrivate
,
104 kEmbeddedExtensionOptions
,
105 kEnterprisePlatformKeys
,
106 kEnterprisePlatformKeysPrivate
,
107 kExperienceSamplingPrivate
,
110 kExternallyConnectableAllUrls
,
113 kFileBrowserHandlerInternal
,
116 kFileSystemDirectory
,
118 kFileSystemRequestFileSystem
,
119 kFileSystemRetainEntries
,
121 kDeleted_FileSystemWriteDirectory
,
138 kInlineInstallPrivate
,
142 kLauncherSearchProvider
,
151 kMusicManagerPrivate
,
155 kNotificationProvider
,
157 kOverrideEscFullscreen
,
173 kSearchEnginesPrivate
,
198 kVirtualKeyboardPrivate
,
203 kWebConnectable
, // for externally_connectable manifest key
208 kWebrtcDesktopCapturePrivate
,
209 kWebrtcLoggingPrivate
,
211 kWebstoreWidgetPrivate
,
228 kMediaGalleriesAllGalleriesCopyTo
,
229 kMediaGalleriesAllGalleriesDelete
,
230 kMediaGalleriesAllGalleriesRead
,
232 kOverrideBookmarksUI
,
236 kSocketSpecificHosts
,
237 kDeleted_UsbDeviceList
,
238 kUsbDeviceUnknownProduct
,
239 kUsbDeviceUnknownVendor
,
242 kLanguageSettingsPrivate
,
243 kEnterpriseDeviceAttributes
,
244 kCertificateProvider
,
245 // Last entry: Add new entries above and ensure to update the
246 // "ExtensionPermission3" enum in tools/metrics/histograms/histograms.xml
247 // (by running update_extension_permission.py).
254 explicit APIPermission(const APIPermissionInfo
* info
);
256 virtual ~APIPermission();
258 // Returns the id of this permission.
261 // Returns the name of this permission.
262 const char* name() const;
264 // Returns the APIPermission of this permission.
265 const APIPermissionInfo
* info() const {
269 // The set of permissions an app/extension with this API permission has. These
270 // permissions are used by PermissionMessageProvider to generate meaningful
271 // permission messages for the app/extension.
273 // For simple API permissions, this will return a set containing only the ID
274 // of the permission. More complex permissions might have multiple IDs, one
275 // for each of the capabilities the API permission has (e.g. read, write and
276 // copy, in the case of the media gallery permission). Permissions that
277 // require parameters may also contain a parameter string (along with the
278 // permission's ID) which can be substituted into the permission message if a
279 // rule is defined to do so.
281 // Permissions with multiple values, such as host permissions, are represented
282 // by multiple entries in this set. Each permission in the subset has the same
283 // ID (e.g. kHostReadOnly) but a different parameter (e.g. google.com). These
284 // are grouped to form different kinds of permission messages (e.g. 'Access to
285 // 2 hosts') depending on the number that are in the set. The rules that
286 // define the grouping of related permissions with the same ID is defined in
287 // ChromePermissionMessageProvider.
288 virtual PermissionIDSet
GetPermissions() const = 0;
290 // Returns true if the given permission is allowed.
291 virtual bool Check(const CheckParam
* param
) const = 0;
293 // Returns true if |rhs| is a subset of this.
294 virtual bool Contains(const APIPermission
* rhs
) const = 0;
296 // Returns true if |rhs| is equal to this.
297 virtual bool Equal(const APIPermission
* rhs
) const = 0;
299 // Parses the APIPermission from |value|. Returns false if an error happens
300 // and optionally set |error| if |error| is not NULL. If |value| represents
301 // multiple permissions, some are invalid, and |unhandled_permissions| is
302 // not NULL, the invalid ones are put into |unhandled_permissions| and the
303 // function returns true.
304 virtual bool FromValue(const base::Value
* value
,
306 std::vector
<std::string
>* unhandled_permissions
) = 0;
308 // Stores this into a new created |value|.
309 virtual scoped_ptr
<base::Value
> ToValue() const = 0;
312 virtual APIPermission
* Clone() const = 0;
314 // Returns a new API permission which equals this - |rhs|.
315 virtual APIPermission
* Diff(const APIPermission
* rhs
) const = 0;
317 // Returns a new API permission which equals the union of this and |rhs|.
318 virtual APIPermission
* Union(const APIPermission
* rhs
) const = 0;
320 // Returns a new API permission which equals the intersect of this and |rhs|.
321 virtual APIPermission
* Intersect(const APIPermission
* rhs
) const = 0;
324 // Writes this into the given IPC message |m|.
325 virtual void Write(IPC::Message
* m
) const = 0;
327 // Reads from the given IPC message |m|.
328 virtual bool Read(const IPC::Message
* m
, base::PickleIterator
* iter
) = 0;
330 // Logs this permission.
331 virtual void Log(std::string
* log
) const = 0;
334 const APIPermissionInfo
* const info_
;
338 // The APIPermissionInfo is an immutable class that describes a single
339 // named permission (API permission).
340 // There is one instance per permission.
341 class APIPermissionInfo
{
346 // Indicates if the permission implies full access (native code).
347 kFlagImpliesFullAccess
= 1 << 0,
349 // Indicates if the permission implies full URL access.
350 kFlagImpliesFullURLAccess
= 1 << 1,
352 // Indicates that extensions cannot specify the permission as optional.
353 kFlagCannotBeOptional
= 1 << 3,
355 // Indicates that the permission is internal to the extensions
356 // system and cannot be specified in the "permissions" list.
357 kFlagInternal
= 1 << 4,
359 // Indicates that the permission may be granted to web contents by
360 // extensions using the content_capabilities manifest feature.
361 kFlagSupportsContentCapabilities
= 1 << 5,
364 typedef APIPermission
* (*APIPermissionConstructor
)(const APIPermissionInfo
*);
366 typedef std::set
<APIPermission::ID
> IDSet
;
368 ~APIPermissionInfo();
370 // Creates a APIPermission instance.
371 APIPermission
* CreateAPIPermission() const;
373 int flags() const { return flags_
; }
375 APIPermission::ID
id() const { return id_
; }
377 // Returns the name of this permission.
378 const char* name() const { return name_
; }
380 // Returns true if this permission implies full access (e.g., native code).
381 bool implies_full_access() const {
382 return (flags_
& kFlagImpliesFullAccess
) != 0;
385 // Returns true if this permission implies full URL access.
386 bool implies_full_url_access() const {
387 return (flags_
& kFlagImpliesFullURLAccess
) != 0;
390 // Returns true if this permission can be added and removed via the
391 // optional permissions extension API.
392 bool supports_optional() const {
393 return (flags_
& kFlagCannotBeOptional
) == 0;
396 // Returns true if this permission is internal rather than a
397 // "permissions" list entry.
398 bool is_internal() const {
399 return (flags_
& kFlagInternal
) != 0;
402 // Returns true if this permission can be granted to web contents by an
403 // extension through the content_capabilities manifest feature.
404 bool supports_content_capabilities() const {
405 return (flags_
& kFlagSupportsContentCapabilities
) != 0;
409 // Instances should only be constructed from within a PermissionsProvider.
410 friend class ChromeAPIPermissions
;
411 friend class ExtensionsAPIPermissions
;
412 // Implementations of APIPermission will want to get the permission message,
413 // but this class's implementation should be hidden from everyone else.
414 friend class APIPermission
;
416 // This exists to allow aggregate initialization, so that default values
417 // for flags, etc. can be omitted.
418 // TODO(yoz): Simplify the way initialization is done. APIPermissionInfo
419 // should be the simple data struct.
421 APIPermission::ID id
;
424 APIPermissionInfo::APIPermissionConstructor constructor
;
427 explicit APIPermissionInfo(const InitInfo
& info
);
429 const APIPermission::ID id_
;
430 const char* const name_
;
432 const APIPermissionConstructor api_permission_constructor_
;
435 } // namespace extensions
437 #endif // EXTENSIONS_COMMON_PERMISSIONS_API_PERMISSION_H_