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
29namespace sandbox {
30
31class BrokerServices;
32class ProcessState;
33class TargetPolicy;
34class 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//
49class 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.
129class 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