sandbox.h 9.5 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225
  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. // Sandbox is a sandbox library for windows processes. Use when you want a
  5. // 'privileged' process and a 'locked down process' to interact with.
  6. // The privileged process is called the broker and it is started by external
  7. // means (such as the user starting it). The 'sandboxed' process is called the
  8. // target and it is started by the broker. There can be many target processes
  9. // started by a single broker process. This library provides facilities
  10. // for both the broker and the target.
  11. //
  12. // The design rationale and relevant documents can be found at http://go/sbox.
  13. //
  14. // Note: this header does not include the SandboxFactory definitions because
  15. // there are cases where the Sandbox library is linked against the main .exe
  16. // while its API needs to be used in a DLL.
  17. #ifndef SANDBOX_WIN_SRC_SANDBOX_H_
  18. #define SANDBOX_WIN_SRC_SANDBOX_H_
  19. #include <stddef.h>
  20. #include <memory>
  21. #include <vector>
  22. #include "base/memory/ref_counted.h"
  23. #include "base/strings/string_piece.h"
  24. #if !defined(SANDBOX_FUZZ_TARGET)
  25. #include "base/win/windows_types.h"
  26. #else
  27. #include "sandbox/win/fuzzer/fuzzer_types.h"
  28. #endif
  29. #include "sandbox/win/src/sandbox_policy.h"
  30. #include "sandbox/win/src/sandbox_types.h"
  31. // sandbox: Google User-Land Application Sandbox
  32. namespace sandbox {
  33. class PolicyDiagnosticsReceiver;
  34. class ProcessState;
  35. class TargetPolicy;
  36. class TargetServices;
  37. // BrokerServices exposes all the broker API.
  38. // The basic use is to start the target(s) and wait for them to end.
  39. //
  40. // This API is intended to be called in the following order
  41. // (error checking omitted):
  42. // BrokerServices* broker = SandboxFactory::GetBrokerServices();
  43. // broker->Init();
  44. // PROCESS_INFORMATION target;
  45. // broker->SpawnTarget(target_exe_path, target_args, &target);
  46. // ::ResumeThread(target->hThread);
  47. // // -- later you can call:
  48. // broker->WaitForAllTargets(option);
  49. //
  50. // We need [[clang::lto_visibility_public]] because instances of this class are
  51. // passed across module boundaries. This means different modules must have
  52. // compatible definitions of the class even when LTO is enabled.
  53. class [[clang::lto_visibility_public]] BrokerServices {
  54. public:
  55. // Initializes the broker. Must be called before any other on this class.
  56. // returns ALL_OK if successful. All other return values imply failure.
  57. // If the return is ERROR_GENERIC, you can call ::GetLastError() to get
  58. // more information.
  59. virtual ResultCode Init() = 0;
  60. // Returns the interface pointer to a new, empty policy object. Use this
  61. // interface to specify the sandbox policy for new processes created by
  62. // SpawnTarget().
  63. virtual std::unique_ptr<TargetPolicy> CreatePolicy() = 0;
  64. // Returns the interface pointer to a new, empty policy object. Use this
  65. // interface to specify the sandbox policy for new processes created by
  66. // SpawnTarget().
  67. //
  68. // The first time a specific value of `tag` is provided an empty policy will
  69. // be returned, and both TargetConfig and TargetPolicy methods should be
  70. // called to populate the object before passing it to SpawnTarget().
  71. //
  72. // The second and subsequent times a given `tag` is provided, the object will
  73. // share the backing data for state configured by TargetConfig methods (with
  74. // the first instance) and those methods should not be called for this policy.
  75. // TargetConfig::IsConfigured() will return `true` for the second and
  76. // subsequent objects created with a given `tag`. Methods on TargetPolicy
  77. // should continue to be called to populate the per-instance configuration.
  78. //
  79. // Provide an empty `tag` (or call CreatePolicy() with no tag) to create a
  80. // policy which never shares its TargetConfig state with another policy
  81. // object. For such an object both its TargetConfig and TargetPolicy methods
  82. // must be called every time.
  83. virtual std::unique_ptr<TargetPolicy> CreatePolicy(base::StringPiece tag) = 0;
  84. // Creates a new target (child process) in a suspended state and takes
  85. // ownership of |policy|.
  86. // Parameters:
  87. // exe_path: This is the full path to the target binary. This parameter
  88. // can be null and in this case the exe path must be the first argument
  89. // of the command_line.
  90. // command_line: The arguments to be passed as command line to the new
  91. // process. This can be null if the exe_path parameter is not null.
  92. // policy: This is the pointer to the policy object for the sandbox to
  93. // be created.
  94. // last_warning: The argument will contain an indication on whether
  95. // the process security was initialized completely, Only set if the
  96. // process can be used without a serious compromise in security.
  97. // last_error: If an error or warning is returned from this method this
  98. // parameter will hold the last Win32 error value.
  99. // target: returns the resulting target process information such as process
  100. // handle and PID just as if CreateProcess() had been called. The caller is
  101. // responsible for closing the handles returned in this structure.
  102. // Returns:
  103. // ALL_OK if successful. All other return values imply failure.
  104. virtual ResultCode SpawnTarget(
  105. const wchar_t* exe_path, const wchar_t* command_line,
  106. std::unique_ptr<TargetPolicy> policy, ResultCode* last_warning,
  107. DWORD* last_error, PROCESS_INFORMATION* target) = 0;
  108. // This call blocks (waits) for all the targets to terminate.
  109. // Returns:
  110. // ALL_OK if successful. All other return values imply failure.
  111. // If the return is ERROR_GENERIC, you can call ::GetLastError() to get
  112. // more information.
  113. virtual ResultCode WaitForAllTargets() = 0;
  114. // This call creates a snapshot of policies managed by the sandbox and
  115. // returns them via a helper class.
  116. // Parameters:
  117. // receiver: The |PolicyDiagnosticsReceiver| implementation will be
  118. // called to accept the results of the call.
  119. // Returns:
  120. // ALL_OK if the request was dispatched. All other return values
  121. // imply failure, and the responder will not receive its completion
  122. // callback.
  123. virtual ResultCode GetPolicyDiagnostics(
  124. std::unique_ptr<PolicyDiagnosticsReceiver> receiver) = 0;
  125. protected:
  126. ~BrokerServices() {}
  127. };
  128. // TargetServices models the current process from the perspective
  129. // of a target process. To obtain a pointer to it use
  130. // Sandbox::GetTargetServices(). Note that this call returns a non-null
  131. // pointer only if this process is in fact a target. A process is a target
  132. // only if the process was spawned by a call to BrokerServices::SpawnTarget().
  133. //
  134. // This API allows the target to gain access to resources with a high
  135. // privilege token and then when it is ready to perform dangerous activities
  136. // (such as download content from the web) it can lower its token and
  137. // enter into locked-down (sandbox) mode.
  138. // The typical usage is as follows:
  139. //
  140. // TargetServices* target_services = Sandbox::GetTargetServices();
  141. // if (target_services) {
  142. // // We are the target.
  143. // target_services->Init();
  144. // // Do work that requires high privileges here.
  145. // // ....
  146. // // When ready to enter lock-down mode call LowerToken:
  147. // target_services->LowerToken();
  148. // }
  149. //
  150. // For more information see the BrokerServices API documentation.
  151. class [[clang::lto_visibility_public]] TargetServices {
  152. public:
  153. // Initializes the target. Must call this function before any other.
  154. // returns ALL_OK if successful. All other return values imply failure.
  155. // If the return is ERROR_GENERIC, you can call ::GetLastError() to get
  156. // more information.
  157. virtual ResultCode Init() = 0;
  158. // Discards the impersonation token and uses the lower token, call before
  159. // processing any untrusted data or running third-party code. If this call
  160. // fails the current process could be terminated immediately.
  161. virtual void LowerToken() = 0;
  162. // Returns the ProcessState object. Through that object it's possible to have
  163. // information about the current state of the process, such as whether
  164. // LowerToken has been called or not.
  165. virtual ProcessState* GetState() = 0;
  166. // Attempts to create a socket in the broker process, and duplicates it back
  167. // to the target. The socket will be created with default flags and no group.
  168. // Only TCP/UDP and IPV4/IPV6 sockets are supported by the broker.
  169. // The socket will be created with WSA_FLAG_OVERLAPPED flags.
  170. virtual SOCKET CreateBrokeredSocket(int af, int family, int protocol) = 0;
  171. protected:
  172. ~TargetServices() {}
  173. };
  174. class PolicyInfo {
  175. public:
  176. // Returns a JSON representation of the policy snapshot.
  177. // This pointer has the same lifetime as this PolicyInfo object.
  178. virtual const char* JsonString() = 0;
  179. virtual ~PolicyInfo() {}
  180. };
  181. // This is returned by BrokerServices::GetPolicyDiagnostics().
  182. // PolicyInfo entries need not be ordered.
  183. class PolicyList {
  184. public:
  185. virtual std::vector<std::unique_ptr<PolicyInfo>>::iterator begin() = 0;
  186. virtual std::vector<std::unique_ptr<PolicyInfo>>::iterator end() = 0;
  187. virtual size_t size() const = 0;
  188. virtual ~PolicyList() {}
  189. };
  190. // This class mediates calls to BrokerServices::GetPolicyDiagnostics().
  191. class PolicyDiagnosticsReceiver {
  192. public:
  193. // ReceiveDiagnostics() should return quickly and should not block the
  194. // thread on which it is called.
  195. virtual void ReceiveDiagnostics(std::unique_ptr<PolicyList> policies) = 0;
  196. // OnError() is passed any errors encountered and |ReceiveDiagnostics|
  197. // will not be called.
  198. virtual void OnError(ResultCode code) = 0;
  199. virtual ~PolicyDiagnosticsReceiver() {}
  200. };
  201. } // namespace sandbox
  202. #endif // SANDBOX_WIN_SRC_SANDBOX_H_