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 5 // Sandbox is a sandbox library for windows processes. Use when you want a 6 // 'privileged' process and a 'locked down process' to interact with. 7 // The privileged process is called the broker and it is started by external 8 // means (such as the user starting it). The 'sandboxed' process is called the 9 // target and it is started by the broker. There can be many target processes 10 // started by a single broker process. This library provides facilities 11 // for both the broker and the target. 12 // 13 // The design rationale and relevant documents can be found at http://go/sbox. 14 // 15 // Note: this header does not include the SandboxFactory definitions because 16 // there are cases where the Sandbox library is linked against the main .exe 17 // while its API needs to be used in a DLL. 18 19 #ifndef SANDBOX_WIN_SRC_SANDBOX_H_ 20 #define SANDBOX_WIN_SRC_SANDBOX_H_ 21 22 #if !defined(SANDBOX_FUZZ_TARGET) 23 #include <windows.h> 24 #else 25 #include "sandbox/win/fuzzer/fuzzer_types.h" 26 #endif 27 28 #include "base/memory/ref_counted.h" 29 #include "sandbox/win/src/sandbox_policy.h" 30 #include "sandbox/win/src/sandbox_types.h" 31 32 // sandbox: Google User-Land Application Sandbox 33 namespace sandbox { 34 35 class BrokerServices; 36 class ProcessState; 37 class TargetPolicy; 38 class TargetServices; 39 40 // BrokerServices exposes all the broker API. 41 // The basic use is to start the target(s) and wait for them to end. 42 // 43 // This API is intended to be called in the following order 44 // (error checking omitted): 45 // BrokerServices* broker = SandboxFactory::GetBrokerServices(); 46 // broker->Init(); 47 // PROCESS_INFORMATION target; 48 // broker->SpawnTarget(target_exe_path, target_args, &target); 49 // ::ResumeThread(target->hThread); 50 // // -- later you can call: 51 // broker->WaitForAllTargets(option); 52 // 53 class 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 61 // Returns the interface pointer to a new, empty policy object. Use this 62 // interface to specify the sandbox policy for new processes created by 63 // SpawnTarget() 64 virtual scoped_refptr<TargetPolicy> CreatePolicy() = 0; 65 66 // Creates a new target (child process) in a suspended state. 67 // Parameters: 68 // exe_path: This is the full path to the target binary. This parameter 69 // can be null and in this case the exe path must be the first argument 70 // of the command_line. 71 // command_line: The arguments to be passed as command line to the new 72 // process. This can be null if the exe_path parameter is not null. 73 // policy: This is the pointer to the policy object for the sandbox to 74 // be created. 75 // last_warning: The argument will contain an indication on whether 76 // the process security was initialized completely, Only set if the 77 // process can be used without a serious compromise in security. 78 // last_error: If an error or warning is returned from this method this 79 // parameter will hold the last Win32 error value. 80 // target: returns the resulting target process information such as process 81 // handle and PID just as if CreateProcess() had been called. The caller is 82 // responsible for closing the handles returned in this structure. 83 // Returns: 84 // ALL_OK if successful. All other return values imply failure. 85 virtual ResultCode SpawnTarget(const wchar_t* exe_path, 86 const wchar_t* command_line, 87 base::EnvironmentMap& env_map, 88 scoped_refptr<TargetPolicy> policy, 89 ResultCode* last_warning, 90 DWORD* last_error, 91 PROCESS_INFORMATION* target) = 0; 92 93 // This call blocks (waits) for all the targets to terminate. 94 // Returns: 95 // ALL_OK if successful. All other return values imply failure. 96 // If the return is ERROR_GENERIC, you can call ::GetLastError() to get 97 // more information. 98 virtual ResultCode WaitForAllTargets() = 0; 99 100 // Adds an unsandboxed process as a peer for policy decisions (e.g. 101 // HANDLES_DUP_ANY policy). 102 // Returns: 103 // ALL_OK if successful. All other return values imply failure. 104 // If the return is ERROR_GENERIC, you can call ::GetLastError() to get 105 // more information. 106 virtual ResultCode AddTargetPeer(HANDLE peer_process) = 0; 107 108 protected: ~BrokerServices()109 ~BrokerServices() {} 110 }; 111 112 // TargetServices models the current process from the perspective 113 // of a target process. To obtain a pointer to it use 114 // Sandbox::GetTargetServices(). Note that this call returns a non-null 115 // pointer only if this process is in fact a target. A process is a target 116 // only if the process was spawned by a call to BrokerServices::SpawnTarget(). 117 // 118 // This API allows the target to gain access to resources with a high 119 // privilege token and then when it is ready to perform dangerous activities 120 // (such as download content from the web) it can lower its token and 121 // enter into locked-down (sandbox) mode. 122 // The typical usage is as follows: 123 // 124 // TargetServices* target_services = Sandbox::GetTargetServices(); 125 // if (target_services) { 126 // // We are the target. 127 // target_services->Init(); 128 // // Do work that requires high privileges here. 129 // // .... 130 // // When ready to enter lock-down mode call LowerToken: 131 // target_services->LowerToken(); 132 // } 133 // 134 // For more information see the BrokerServices API documentation. 135 class TargetServices { 136 public: 137 // Initializes the target. Must call this function before any other. 138 // returns ALL_OK if successful. All other return values imply failure. 139 // If the return is ERROR_GENERIC, you can call ::GetLastError() to get 140 // more information. 141 virtual ResultCode Init() = 0; 142 143 // Discards the impersonation token and uses the lower token, call before 144 // processing any untrusted data or running third-party code. If this call 145 // fails the current process could be terminated immediately. 146 virtual void LowerToken() = 0; 147 148 // Returns the ProcessState object. Through that object it's possible to have 149 // information about the current state of the process, such as whether 150 // LowerToken has been called or not. 151 virtual ProcessState* GetState() = 0; 152 153 // Requests the broker to duplicate the supplied handle into the target 154 // process. The target process must be an active sandbox child process 155 // and the source process must have a corresponding policy allowing 156 // handle duplication for this object type. 157 // Returns: 158 // ALL_OK if successful. All other return values imply failure. 159 // If the return is ERROR_GENERIC, you can call ::GetLastError() to get 160 // more information. 161 virtual ResultCode DuplicateHandle(HANDLE source_handle, 162 DWORD target_process_id, 163 HANDLE* target_handle, 164 DWORD desired_access, 165 DWORD options) = 0; 166 167 protected: ~TargetServices()168 ~TargetServices() {} 169 }; 170 171 } // namespace sandbox 172 173 #endif // SANDBOX_WIN_SRC_SANDBOX_H_ 174