extensions/common/permissions/api_permission_set.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_SET_H_
   6 #define EXTENSIONS_COMMON_PERMISSIONS_API_PERMISSION_SET_H_
   7
   8 #include <set>
   9 #include <string>
  10 #include <vector>
  11
  12 #include "base/strings/string16.h"
  13 #include "extensions/common/permissions/api_permission.h"
  14 #include "extensions/common/permissions/base_set_operators.h"
  15
  16 namespace base {
  17 class ListValue;
  18 }  // namespace base
  19
  20 namespace extensions {
  21
  22 class APIPermissionSet;
  23 class Extension;
  24
  25 template<>
  26 struct BaseSetOperatorsTraits<APIPermissionSet> {
  27   typedef APIPermission ElementType;
  28   typedef APIPermission::ID ElementIDType;
  29 };
  30
  31 class APIPermissionSet : public BaseSetOperators<APIPermissionSet> {
  32  public:
  33   enum ParseSource {
  34     // Don't allow internal permissions to be parsed (e.g. entries in the
  35     // "permissions" list in a manifest).
  36     kDisallowInternalPermissions,
  37
  38     // Allow internal permissions to be parsed (e.g. from the "api" field of a
  39     // permissions list in the prefs).
  40     kAllowInternalPermissions,
  41   };
  42
  43   void insert(APIPermission::ID id);
  44
  45   // Insert |permission| into the APIPermissionSet. The APIPermissionSet will
  46   // take the ownership of |permission|,
  47   void insert(APIPermission* permission);
  48
  49   // Parses permissions from |permissions| and adds the parsed permissions to
  50   // |api_permissions|. If |source| is kDisallowInternalPermissions, treat
  51   // permissions with kFlagInternal as errors. If |unhandled_permissions| is
  52   // not NULL, the names of all permissions that couldn't be parsed will be
  53   // added to this vector. If |error| is NULL, parsing will continue with the
  54   // next permission if invalid data is detected. If |error| is not NULL, it
  55   // will be set to an error message and false is returned when an invalid
  56   // permission is found.
  57   static bool ParseFromJSON(
  58       const base::ListValue* permissions,
  59       ParseSource source,
  60       APIPermissionSet* api_permissions,
  61       base::string16* error,
  62       std::vector<std::string>* unhandled_permissions);
  63 };
  64
  65 // An ID representing a single permission that belongs to an app or extension.
  66 //
  67 // Each PermissionID has a required ID to identify the permission. For most
  68 // permissions, this is all they have.
  69 //
  70 // Some more complex permissions have a parameter, which acts like an argument
  71 // for the permission. For example, host permissions might have the ID
  72 // kReadOnlyHost and the argument 'www.google.com' (the host which is
  73 // read-only). Parameters are passed to the permission message rules for this
  74 // permission, so they can affect the displayed message.
  75 //
  76 // Note: Inheriting from std::pair automatically gives us an operator<
  77 // (required for putting these into an std::set).
  78 //
  79 // TODO(sashab): Move this to the same file as PermissionIDSet once that moves
  80 // to its own file.
  81 class PermissionID : public std::pair<APIPermission::ID, base::string16> {
  82  public:
  83   explicit PermissionID(APIPermission::ID id);
  84   PermissionID(APIPermission::ID id, const base::string16& parameter);
  85   virtual ~PermissionID();
  86
  87   const APIPermission::ID& id() const { return this->first; }
  88   const base::string16& parameter() const { return this->second; }
  89 };
  90
  91 // A set of permissions for an app or extension. Used for passing around groups
  92 // of permissions, such as required or optional permissions.
  93 //
  94 // Each permission can also store a string, such as a hostname or device number,
  95 // as a parameter that helps identify the permission. This parameter can then
  96 // be used when the permission message is generated. For example, the permission
  97 // kHostReadOnly might have the parameter "google.com", which means that the app
  98 // or extension has the permission to read the host google.com. This parameter
  99 // may then be included in the permission message when it is generated later.
 100 //
 101 // Example:
 102 //   // Create an empty PermissionIDSet.
 103 //   PermissionIDSet p;
 104 //   // Add a permission to the set.
 105 //   p.insert(APIPermission::kNetworkState);
 106 //   // Add a permission with a parameter to the set.
 107 //   p.insert(APIPermission::kHostReadOnly,
 108 //            base::ASCIIToUTF16("http://www.google.com"));
 109 //
 110 // TODO(sashab): Move this to its own file and rename it to PermissionSet after
 111 // APIPermission is removed, the current PermissionSet is no longer used, and
 112 // APIPermission::ID is the only type of Permission ID.
 113 class PermissionIDSet {
 114  public:
 115   using const_iterator = std::set<PermissionID>::const_iterator;
 116
 117   PermissionIDSet();
 118   virtual ~PermissionIDSet();
 119
 120   // Adds the given permission, and an optional parameter, to the set.
 121   void insert(APIPermission::ID permission_id);
 122   void insert(APIPermission::ID permission_id,
 123               const base::string16& permission_parameter);
 124   void InsertAll(const PermissionIDSet& permission_set);
 125
 126   void erase(APIPermission::ID permission_id);
 127
 128   // Returns the parameters for all PermissionIDs in this set.
 129   std::vector<base::string16> GetAllPermissionParameters() const;
 130
 131   // Check if the set contains a permission with the given ID.
 132   bool ContainsID(APIPermission::ID permission_id) const;
 133
 134   // Check if the set contains permissions with all the given IDs.
 135   bool ContainsAllIDs(const std::set<APIPermission::ID>& permission_ids) const;
 136
 137   // Check if the set contains any permission with one of the given IDs.
 138   bool ContainsAnyID(const std::set<APIPermission::ID>& permission_ids) const;
 139
 140   // Returns all the permissions in this set with the given ID.
 141   PermissionIDSet GetAllPermissionsWithID(
 142       APIPermission::ID permission_id) const;
 143
 144   // Returns all the permissions in this set with one of the given IDs.
 145   PermissionIDSet GetAllPermissionsWithIDs(
 146       const std::set<APIPermission::ID>& permission_ids) const;
 147
 148   // Convenience functions for common set operations.
 149   bool Includes(const PermissionIDSet& subset) const;
 150   bool Equals(const PermissionIDSet& set) const;
 151   static PermissionIDSet Difference(const PermissionIDSet& set_1,
 152                                     const PermissionIDSet& set_2);
 153
 154   size_t size() const;
 155   bool empty() const;
 156
 157   const_iterator begin() const { return permissions_.begin(); }
 158   const_iterator end() const { return permissions_.end(); }
 159
 160  private:
 161   PermissionIDSet(const std::set<PermissionID>& permissions);
 162
 163   std::set<PermissionID> permissions_;
 164 };
 165
 166 }  // namespace extensions
 167
 168 #endif  // EXTENSIONS_COMMON_PERMISSIONS_API_PERMISSION_SET_H_