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