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 #include <windows.h> 23 24 #include "base/basictypes.h" 25 #include "sandbox/win/src/sandbox_policy.h" 26 #include "sandbox/win/src/sandbox_types.h" 27 28 // sandbox: Google User-Land Application Sandbox 29 namespace sandbox { 30 31 class BrokerServices; 32 class ProcessState; 33 class TargetPolicy; 34 class TargetServices; 35 36 // BrokerServices exposes all the broker API. 37 // The basic use is to start the target(s) and wait for them to end. 38 // 39 // This API is intended to be called in the following order 40 // (error checking omitted): 41 // BrokerServices* broker = SandboxFactory::GetBrokerServices(); 42 // broker->Init(); 43 // PROCESS_INFORMATION target; 44 // broker->SpawnTarget(target_exe_path, target_args, &target); 45 // ::ResumeThread(target->hThread); 46 // // -- later you can call: 47 // broker->WaitForAllTargets(option); 48 // 49 class BrokerServices { 50 public: 51 // Initializes the broker. Must be called before any other on this class. 52 // returns ALL_OK if successful. All other return values imply failure. 53 // If the return is ERROR_GENERIC, you can call ::GetLastError() to get 54 // more information. 55 virtual ResultCode Init() = 0; 56 57 // Returns the interface pointer to a new, empty policy object. Use this 58 // interface to specify the sandbox policy for new processes created by 59 // SpawnTarget() 60 virtual TargetPolicy* CreatePolicy() = 0; 61 62 // Creates a new target (child process) in a suspended state. 63 // Parameters: 64 // exe_path: This is the full path to the target binary. This parameter 65 // can be null and in this case the exe path must be the first argument 66 // of the command_line. 67 // command_line: The arguments to be passed as command line to the new 68 // process. This can be null if the exe_path parameter is not null. 69 // policy: This is the pointer to the policy object for the sandbox to 70 // be created. 71 // target: returns the resulting target process information such as process 72 // handle and PID just as if CreateProcess() had been called. The caller is 73 // responsible for closing the handles returned in this structure. 74 // Returns: 75 // ALL_OK if successful. All other return values imply failure. 76 virtual ResultCode SpawnTarget(const wchar_t* exe_path, 77 const wchar_t* command_line, 78 TargetPolicy* policy, 79 PROCESS_INFORMATION* target) = 0; 80 81 // This call blocks (waits) for all the targets to terminate. 82 // Returns: 83 // ALL_OK if successful. All other return values imply failure. 84 // If the return is ERROR_GENERIC, you can call ::GetLastError() to get 85 // more information. 86 virtual ResultCode WaitForAllTargets() = 0; 87 88 // Adds an unsandboxed process as a peer for policy decisions (e.g. 89 // HANDLES_DUP_ANY policy). 90 // Returns: 91 // ALL_OK if successful. All other return values imply failure. 92 // If the return is ERROR_GENERIC, you can call ::GetLastError() to get 93 // more information. 94 virtual ResultCode AddTargetPeer(HANDLE peer_process) = 0; 95 96 // Install the AppContainer with the specified sid an name. Returns ALL_OK if 97 // successful or an error code if the AppContainer cannot be installed. 98 virtual ResultCode InstallAppContainer(const wchar_t* sid, 99 const wchar_t* name) = 0; 100 101 // Removes from the system the AppContainer with the specified sid. 102 // Returns ALL_OK if successful or an error code otherwise. 103 virtual ResultCode UninstallAppContainer(const wchar_t* sid) = 0; 104 }; 105 106 // TargetServices models the current process from the perspective 107 // of a target process. To obtain a pointer to it use 108 // Sandbox::GetTargetServices(). Note that this call returns a non-null 109 // pointer only if this process is in fact a target. A process is a target 110 // only if the process was spawned by a call to BrokerServices::SpawnTarget(). 111 // 112 // This API allows the target to gain access to resources with a high 113 // privilege token and then when it is ready to perform dangerous activities 114 // (such as download content from the web) it can lower its token and 115 // enter into locked-down (sandbox) mode. 116 // The typical usage is as follows: 117 // 118 // TargetServices* target_services = Sandbox::GetTargetServices(); 119 // if (NULL != target_services) { 120 // // We are the target. 121 // target_services->Init(); 122 // // Do work that requires high privileges here. 123 // // .... 124 // // When ready to enter lock-down mode call LowerToken: 125 // target_services->LowerToken(); 126 // } 127 // 128 // For more information see the BrokerServices API documentation. 129 class TargetServices { 130 public: 131 // Initializes the target. Must call this function before any other. 132 // returns ALL_OK if successful. All other return values imply failure. 133 // If the return is ERROR_GENERIC, you can call ::GetLastError() to get 134 // more information. 135 virtual ResultCode Init() = 0; 136 137 // Discards the impersonation token and uses the lower token, call before 138 // processing any untrusted data or running third-party code. If this call 139 // fails the current process could be terminated immediately. 140 virtual void LowerToken() = 0; 141 142 // Returns the ProcessState object. Through that object it's possible to have 143 // information about the current state of the process, such as whether 144 // LowerToken has been called or not. 145 virtual ProcessState* GetState() = 0; 146 147 // Requests the broker to duplicate the supplied handle into the target 148 // process. The target process must be an active sandbox child process 149 // and the source process must have a corresponding policy allowing 150 // handle duplication for this object type. 151 // Returns: 152 // ALL_OK if successful. All other return values imply failure. 153 // If the return is ERROR_GENERIC, you can call ::GetLastError() to get 154 // more information. 155 virtual ResultCode DuplicateHandle(HANDLE source_handle, 156 DWORD target_process_id, 157 HANDLE* target_handle, 158 DWORD desired_access, 159 DWORD options) = 0; 160 }; 161 162 } // namespace sandbox 163 164 165 #endif // SANDBOX_WIN_SRC_SANDBOX_H_ 166
