sandbox/win/src/restricted_token.h

   1 // Copyright (c) 2010 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 SANDBOX_SRC_RESTRICTED_TOKEN_H_
   6 #define SANDBOX_SRC_RESTRICTED_TOKEN_H_
   7
   8 #include <windows.h>
   9 #include <vector>
  10
  11 #include "base/basictypes.h"
  12 #include "base/strings/string16.h"
  13 #include "base/win/scoped_handle.h"
  14 #include "sandbox/win/src/restricted_token_utils.h"
  15 #include "sandbox/win/src/security_level.h"
  16 #include "sandbox/win/src/sid.h"
  17
  18 // Flags present in the Group SID list. These 2 flags are new in Windows Vista
  19 #ifndef SE_GROUP_INTEGRITY
  20 #define SE_GROUP_INTEGRITY (0x00000020L)
  21 #endif
  22 #ifndef SE_GROUP_INTEGRITY_ENABLED
  23 #define SE_GROUP_INTEGRITY_ENABLED (0x00000040L)
  24 #endif
  25
  26 namespace sandbox {
  27
  28 // Handles the creation of a restricted token using the effective token or
  29 // any token handle.
  30 // Sample usage:
  31 //    RestrictedToken restricted_token;
  32 //    DWORD err_code = restricted_token.Init(NULL);  // Use the current
  33 //                                                   // effective token
  34 //    if (ERROR_SUCCESS != err_code) {
  35 //      // handle error.
  36 //    }
  37 //
  38 //    restricted_token.AddRestrictingSid(ATL::Sids::Users().GetPSID());
  39 //    base::win::ScopedHandle token_handle;
  40 //    err_code = restricted_token.GetRestrictedToken(&token_handle);
  41 //    if (ERROR_SUCCESS != err_code) {
  42 //      // handle error.
  43 //    }
  44 //    [...]
  45 class RestrictedToken {
  46  public:
  47   // Init() has to be called before calling any other method in the class.
  48   RestrictedToken();
  49   ~RestrictedToken();
  50
  51   // Initializes the RestrictedToken object with effective_token.
  52   // If effective_token is NULL, it initializes the RestrictedToken object with
  53   // the effective token of the current process.
  54   DWORD Init(HANDLE effective_token);
  55
  56   // Creates a restricted token.
  57   // If the function succeeds, the return value is ERROR_SUCCESS. If the
  58   // function fails, the return value is the win32 error code corresponding to
  59   // the error.
  60   DWORD GetRestrictedToken(base::win::ScopedHandle* token) const;
  61
  62   // Creates a restricted token and uses this new token to create a new token
  63   // for impersonation. Returns this impersonation token.
  64   //
  65   // If the function succeeds, the return value is ERROR_SUCCESS. If the
  66   // function fails, the return value is the win32 error code corresponding to
  67   // the error.
  68   //
  69   // The sample usage is the same as the GetRestrictedToken function.
  70   DWORD GetRestrictedTokenForImpersonation(
  71       base::win::ScopedHandle* token) const;
  72
  73   // Lists all sids in the token and mark them as Deny Only except for those
  74   // present in the exceptions parameter. If there is no exception needed,
  75   // the caller can pass an empty list or NULL for the exceptions
  76   // parameter.
  77   //
  78   // If the function succeeds, the return value is ERROR_SUCCESS. If the
  79   // function fails, the return value is the win32 error code corresponding to
  80   // the error.
  81   //
  82   // Sample usage:
  83   //    std::vector<Sid> sid_exceptions;
  84   //    sid_exceptions.push_back(ATL::Sids::Users().GetPSID());
  85   //    sid_exceptions.push_back(ATL::Sids::World().GetPSID());
  86   //    restricted_token.AddAllSidsForDenyOnly(&sid_exceptions);
  87   // Note: A Sid marked for Deny Only in a token cannot be used to grant
  88   // access to any resource. It can only be used to deny access.
  89   DWORD AddAllSidsForDenyOnly(std::vector<Sid> *exceptions);
  90
  91   // Adds a user or group SID for Deny Only in the restricted token.
  92   // Parameter: sid is the SID to add in the Deny Only list.
  93   // The return value is always ERROR_SUCCESS.
  94   //
  95   // Sample Usage:
  96   //    restricted_token.AddSidForDenyOnly(ATL::Sids::Admins().GetPSID());
  97   DWORD AddSidForDenyOnly(const Sid &sid);
  98
  99   // Adds the user sid of the token for Deny Only in the restricted token.
 100   // If the function succeeds, the return value is ERROR_SUCCESS. If the
 101   // function fails, the return value is the win32 error code corresponding to
 102   // the error.
 103   DWORD AddUserSidForDenyOnly();
 104
 105   // Lists all privileges in the token and add them to the list of privileges
 106   // to remove except for those present in the exceptions parameter. If
 107   // there is no exception needed, the caller can pass an empty list or NULL
 108   // for the exceptions parameter.
 109   //
 110   // If the function succeeds, the return value is ERROR_SUCCESS. If the
 111   // function fails, the return value is the win32 error code corresponding to
 112   // the error.
 113   //
 114   // Sample usage:
 115   //    std::vector<base::string16> privilege_exceptions;
 116   //    privilege_exceptions.push_back(SE_CHANGE_NOTIFY_NAME);
 117   //    restricted_token.DeleteAllPrivileges(&privilege_exceptions);
 118   DWORD DeleteAllPrivileges(const std::vector<base::string16> *exceptions);
 119
 120   // Adds a privilege to the list of privileges to remove in the restricted
 121   // token.
 122   // Parameter: privilege is the privilege name to remove. This is the string
 123   // representing the privilege. (e.g. "SeChangeNotifyPrivilege").
 124   // If the function succeeds, the return value is ERROR_SUCCESS. If the
 125   // function fails, the return value is the win32 error code corresponding to
 126   // the error.
 127   //
 128   // Sample usage:
 129   //    restricted_token.DeletePrivilege(SE_LOAD_DRIVER_NAME);
 130   DWORD DeletePrivilege(const wchar_t *privilege);
 131
 132   // Adds a SID to the list of restricting sids in the restricted token.
 133   // Parameter: sid is the sid to add to the list restricting sids.
 134   // The return value is always ERROR_SUCCESS.
 135   //
 136   // Sample usage:
 137   //    restricted_token.AddRestrictingSid(ATL::Sids::Users().GetPSID());
 138   // Note: The list of restricting is used to force Windows to perform all
 139   // access checks twice. The first time using your user SID and your groups,
 140   // and the second time using your list of restricting sids. The access has
 141   // to be granted in both places to get access to the resource requested.
 142   DWORD AddRestrictingSid(const Sid &sid);
 143
 144   // Adds the logon sid of the token in the list of restricting sids for the
 145   // restricted token.
 146   //
 147   // If the function succeeds, the return value is ERROR_SUCCESS. If the
 148   // function fails, the return value is the win32 error code corresponding to
 149   // the error.
 150   DWORD AddRestrictingSidLogonSession();
 151
 152   // Adds the owner sid of the token in the list of restricting sids for the
 153   // restricted token.
 154   //
 155   // If the function succeeds, the return value is ERROR_SUCCESS. If the
 156   // function fails, the return value is the win32 error code corresponding to
 157   // the error.
 158   DWORD AddRestrictingSidCurrentUser();
 159
 160   // Adds all group sids and the user sid to the restricting sids list.
 161   //
 162   // If the function succeeds, the return value is ERROR_SUCCESS. If the
 163   // function fails, the return value is the win32 error code corresponding to
 164   // the error.
 165   DWORD AddRestrictingSidAllSids();
 166
 167   // Sets the token integrity level. This is only valid on Vista. The integrity
 168   // level cannot be higher than your current integrity level.
 169   DWORD SetIntegrityLevel(IntegrityLevel integrity_level);
 170
 171  private:
 172   // The list of restricting sids in the restricted token.
 173   std::vector<Sid> sids_to_restrict_;
 174   // The list of privileges to remove in the restricted token.
 175   std::vector<LUID> privileges_to_disable_;
 176   // The list of sids to mark as Deny Only in the restricted token.
 177   std::vector<Sid> sids_for_deny_only_;
 178   // The token to restrict. Can only be set in a constructor.
 179   base::win::ScopedHandle effective_token_;
 180   // The token integrity level. Only valid on Vista.
 181   IntegrityLevel integrity_level_;
 182   // Tells if the object is initialized or not (if Init() has been called)
 183   bool init_;
 184
 185   DISALLOW_COPY_AND_ASSIGN(RestrictedToken);
 186 };
 187
 188 }  // namespace sandbox
 189
 190 #endif  // SANDBOX_SRC_RESTRICTED_TOKEN_H_