sandbox_policy.h 13 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285
  1. // Copyright (c) 2012 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. #ifndef SANDBOX_WIN_SRC_SANDBOX_POLICY_H_
  5. #define SANDBOX_WIN_SRC_SANDBOX_POLICY_H_
  6. #include <stddef.h>
  7. #include <stdint.h>
  8. #include <string>
  9. #include "base/memory/scoped_refptr.h"
  10. #include "sandbox/win/src/sandbox_types.h"
  11. #include "sandbox/win/src/security_level.h"
  12. namespace sandbox {
  13. class AppContainer;
  14. // Windows subsystems that can have specific rules.
  15. // Note: The process subsystem (kProcess) does not evaluate the request
  16. // exactly like the CreateProcess API does. See the comment at the top of
  17. // process_thread_dispatcher.cc for more details.
  18. enum class SubSystem {
  19. kFiles, // Creation and opening of files and pipes.
  20. kNamedPipes, // Creation of named pipes.
  21. kProcess, // Creation of child processes.
  22. kWin32kLockdown, // Win32K Lockdown related policy.
  23. kSignedBinary, // Signed binary policy.
  24. kSocket // Socket brokering policy.
  25. };
  26. // Allowable semantics when a rule is matched.
  27. enum class Semantics {
  28. kFilesAllowAny, // Allows open or create for any kind of access that
  29. // the file system supports.
  30. kFilesAllowReadonly, // Allows open or create with read access only.
  31. kFilesAllowQuery, // Allows access to query the attributes of a file.
  32. kNamedPipesAllowAny, // Allows creation of a named pipe.
  33. kFakeGdiInit, // Fakes user32 and gdi32 initialization. This can
  34. // be used to allow the DLLs to load and initialize
  35. // even if the process cannot access that subsystem.
  36. kSignedAllowLoad, // Allows loading the module when CIG is enabled.
  37. kSocketAllowBroker // Allows brokering of sockets.
  38. };
  39. // Policy configuration that can be shared over multiple targets of the same tag
  40. // (see BrokerServicesBase::CreatePolicy(tag)). Methods in TargetConfig will
  41. // only need to be called the first time a TargetPolicy object with a given tag
  42. // is configured.
  43. //
  44. // We need [[clang::lto_visibility_public]] because instances of this class are
  45. // passed across module boundaries. This means different modules must have
  46. // compatible definitions of the class even when LTO is enabled.
  47. class [[clang::lto_visibility_public]] TargetConfig {
  48. public:
  49. virtual ~TargetConfig() {}
  50. // Returns `true` when the TargetConfig of this policy object has been
  51. // populated. Methods in TargetConfig should not be called.
  52. //
  53. // Returns `false` if TargetConfig methods do need to be called to configure
  54. // this policy object.
  55. virtual bool IsConfigured() const = 0;
  56. // Adds a policy rule effective for processes spawned using this policy.
  57. // subsystem: One of the above enumerated windows subsystems.
  58. // semantics: One of the above enumerated FileSemantics.
  59. // pattern: A specific full path or a full path with wildcard patterns.
  60. // The valid wildcards are:
  61. // '*' : Matches zero or more character. Only one in series allowed.
  62. // '?' : Matches a single character. One or more in series are allowed.
  63. // Examples:
  64. // "c:\\documents and settings\\vince\\*.dmp"
  65. // "c:\\documents and settings\\*\\crashdumps\\*.dmp"
  66. // "c:\\temp\\app_log_?????_chrome.txt"
  67. virtual ResultCode AddRule(SubSystem subsystem,
  68. Semantics semantics,
  69. const wchar_t* pattern) = 0;
  70. // Adds a dll that will be unloaded in the target process before it gets
  71. // a chance to initialize itself. Typically, dlls that cause the target
  72. // to crash go here.
  73. virtual ResultCode AddDllToUnload(const wchar_t* dll_name) = 0;
  74. };
  75. // We need [[clang::lto_visibility_public]] because instances of this class are
  76. // passed across module boundaries. This means different modules must have
  77. // compatible definitions of the class even when LTO is enabled.
  78. class [[clang::lto_visibility_public]] TargetPolicy {
  79. public:
  80. virtual ~TargetPolicy() {}
  81. // Fetches the backing TargetConfig for this policy.
  82. virtual TargetConfig* GetConfig() = 0;
  83. // Sets the security level for the target process' two tokens.
  84. // This setting is permanent and cannot be changed once the target process is
  85. // spawned.
  86. // initial: the security level for the initial token. This is the token that
  87. // is used by the process from the creation of the process until the moment
  88. // the process calls TargetServices::LowerToken() or the process calls
  89. // win32's RevertToSelf(). Once this happens the initial token is no longer
  90. // available and the lockdown token is in effect. Using an initial token is
  91. // not compatible with AppContainer, see SetAppContainer.
  92. // lockdown: the security level for the token that comes into force after the
  93. // process calls TargetServices::LowerToken() or the process calls
  94. // RevertToSelf(). See the explanation of each level in the TokenLevel
  95. // definition.
  96. // Return value: SBOX_ALL_OK if the setting succeeds and false otherwise.
  97. // Returns false if the lockdown value is more permissive than the initial
  98. // value.
  99. //
  100. // Important: most of the sandbox-provided security relies on this single
  101. // setting. The caller should strive to set the lockdown level as restricted
  102. // as possible.
  103. virtual ResultCode SetTokenLevel(TokenLevel initial, TokenLevel lockdown) = 0;
  104. // Returns the initial token level.
  105. virtual TokenLevel GetInitialTokenLevel() const = 0;
  106. // Returns the lockdown token level.
  107. virtual TokenLevel GetLockdownTokenLevel() const = 0;
  108. // Sets the security level of the Job Object to which the target process will
  109. // belong. This setting is permanent and cannot be changed once the target
  110. // process is spawned. The job controls the global security settings which
  111. // can not be specified in the token security profile.
  112. // job_level: the security level for the job. See the explanation of each
  113. // level in the JobLevel definition.
  114. // ui_exceptions: specify what specific rights that are disabled in the
  115. // chosen job_level that need to be granted. Use this parameter to avoid
  116. // selecting the next permissive job level unless you need all the rights
  117. // that are granted in such level.
  118. // The exceptions can be specified as a combination of the following
  119. // constants:
  120. // JOB_OBJECT_UILIMIT_HANDLES : grant access to all user-mode handles. These
  121. // include windows, icons, menus and various GDI objects. In addition the
  122. // target process can set hooks, and broadcast messages to other processes
  123. // that belong to the same desktop.
  124. // JOB_OBJECT_UILIMIT_READCLIPBOARD : grant read-only access to the clipboard.
  125. // JOB_OBJECT_UILIMIT_WRITECLIPBOARD : grant write access to the clipboard.
  126. // JOB_OBJECT_UILIMIT_SYSTEMPARAMETERS : allow changes to the system-wide
  127. // parameters as defined by the Win32 call SystemParametersInfo().
  128. // JOB_OBJECT_UILIMIT_DISPLAYSETTINGS : allow programmatic changes to the
  129. // display settings.
  130. // JOB_OBJECT_UILIMIT_GLOBALATOMS : allow access to the global atoms table.
  131. // JOB_OBJECT_UILIMIT_DESKTOP : allow the creation of new desktops.
  132. // JOB_OBJECT_UILIMIT_EXITWINDOWS : allow the call to ExitWindows().
  133. //
  134. // Return value: SBOX_ALL_OK if the setting succeeds and false otherwise.
  135. //
  136. // Note: JOB_OBJECT_XXXX constants are defined in winnt.h and documented at
  137. // length in:
  138. // http://msdn2.microsoft.com/en-us/library/ms684152.aspx
  139. //
  140. // Note: the recommended level is JobLevel::kLockdown.
  141. virtual ResultCode SetJobLevel(JobLevel job_level,
  142. uint32_t ui_exceptions) = 0;
  143. // Returns the job level.
  144. virtual JobLevel GetJobLevel() const = 0;
  145. // Sets a hard limit on the size of the commit set for the sandboxed process.
  146. // If the limit is reached, the process will be terminated with
  147. // SBOX_FATAL_MEMORY_EXCEEDED (7012).
  148. virtual ResultCode SetJobMemoryLimit(size_t memory_limit) = 0;
  149. // Specifies the desktop on which the application is going to run. If the
  150. // desktop does not exist, it will be created. If alternate_winstation is
  151. // set to true, the desktop will be created on an alternate window station.
  152. virtual ResultCode SetAlternateDesktop(bool alternate_winstation) = 0;
  153. // Returns the name of the alternate desktop used. If an alternate window
  154. // station is specified, the name is prepended by the window station name,
  155. // followed by a backslash.
  156. virtual std::wstring GetAlternateDesktop() const = 0;
  157. // Precreates the desktop and window station, if any.
  158. virtual ResultCode CreateAlternateDesktop(bool alternate_winstation) = 0;
  159. // Destroys the desktop and windows station.
  160. virtual void DestroyAlternateDesktop() = 0;
  161. // Sets the integrity level of the process in the sandbox. Both the initial
  162. // token and the main token will be affected by this. If the integrity level
  163. // is set to a level higher than the current level, the sandbox will fail
  164. // to start.
  165. virtual ResultCode SetIntegrityLevel(IntegrityLevel level) = 0;
  166. // Returns the initial integrity level used.
  167. virtual IntegrityLevel GetIntegrityLevel() const = 0;
  168. // Sets the integrity level of the process in the sandbox. The integrity level
  169. // will not take effect before you call LowerToken. User Interface Privilege
  170. // Isolation is not affected by this setting and will remain off for the
  171. // process in the sandbox. If the integrity level is set to a level higher
  172. // than the current level, the sandbox will fail to start.
  173. virtual ResultCode SetDelayedIntegrityLevel(IntegrityLevel level) = 0;
  174. // Sets the LowBox token for sandboxed process. This is mutually exclusive
  175. // with SetAppContainer method.
  176. virtual ResultCode SetLowBox(const wchar_t* sid) = 0;
  177. // Sets the mitigations enabled when the process is created. Most of these
  178. // are implemented as attributes passed via STARTUPINFOEX. So they take
  179. // effect before any thread in the target executes. The declaration of
  180. // MitigationFlags is followed by a detailed description of each flag.
  181. virtual ResultCode SetProcessMitigations(MitigationFlags flags) = 0;
  182. // Returns the currently set mitigation flags.
  183. virtual MitigationFlags GetProcessMitigations() = 0;
  184. // Sets process mitigation flags that don't take effect before the call to
  185. // LowerToken().
  186. virtual ResultCode SetDelayedProcessMitigations(MitigationFlags flags) = 0;
  187. // Returns the currently set delayed mitigation flags.
  188. virtual MitigationFlags GetDelayedProcessMitigations() const = 0;
  189. // Disconnect the target from CSRSS when TargetServices::LowerToken() is
  190. // called inside the target.
  191. virtual ResultCode SetDisconnectCsrss() = 0;
  192. // Sets the interceptions to operate in strict mode. By default, interceptions
  193. // are performed in "relaxed" mode, where if something inside NTDLL.DLL is
  194. // already patched we attempt to intercept it anyway. Setting interceptions
  195. // to strict mode means that when we detect that the function is patched we'll
  196. // refuse to perform the interception.
  197. virtual void SetStrictInterceptions() = 0;
  198. // Set the handles the target process should inherit for stdout and
  199. // stderr. The handles the caller passes must remain valid for the
  200. // lifetime of the policy object. This only has an effect on
  201. // Windows Vista and later versions. These methods accept pipe and
  202. // file handles, but not console handles.
  203. virtual ResultCode SetStdoutHandle(HANDLE handle) = 0;
  204. virtual ResultCode SetStderrHandle(HANDLE handle) = 0;
  205. // Adds a handle that will be closed in the target process after lockdown.
  206. // A nullptr value for handle_name indicates all handles of the specified
  207. // type. An empty string for handle_name indicates the handle is unnamed.
  208. virtual ResultCode AddKernelObjectToClose(const wchar_t* handle_type,
  209. const wchar_t* handle_name) = 0;
  210. // Adds a handle that will be shared with the target process. Does not take
  211. // ownership of the handle.
  212. virtual void AddHandleToShare(HANDLE handle) = 0;
  213. // Locks down the default DACL of the created lockdown and initial tokens
  214. // to restrict what other processes are allowed to access a process' kernel
  215. // resources.
  216. virtual void SetLockdownDefaultDacl() = 0;
  217. // Adds a restricting random SID to the restricted SIDs list as well as
  218. // the default DACL.
  219. virtual void AddRestrictingRandomSid() = 0;
  220. // Configure policy to use an AppContainer profile. |package_name| is the
  221. // name of the profile to use. Specifying True for |create_profile| ensures
  222. // the profile exists, if set to False process creation will fail if the
  223. // profile has not already been created.
  224. virtual ResultCode AddAppContainerProfile(const wchar_t* package_name,
  225. bool create_profile) = 0;
  226. // Get the configured AppContainer.
  227. virtual scoped_refptr<AppContainer> GetAppContainer() = 0;
  228. // Set effective token that will be used for creating the initial and
  229. // lockdown tokens. The token the caller passes must remain valid for the
  230. // lifetime of the policy object.
  231. virtual void SetEffectiveToken(HANDLE token) = 0;
  232. // Allows the launch of the the target process to proceed even if no job can
  233. // be created.
  234. virtual void SetAllowNoSandboxJob() = 0;
  235. // Returns true if target process launch should proceed if job creation fails.
  236. virtual bool GetAllowNoSandboxJob() = 0;
  237. };
  238. } // namespace sandbox
  239. #endif // SANDBOX_WIN_SRC_SANDBOX_POLICY_H_