1.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
1.2 +++ b/security/sandbox/win/src/sandbox.h Wed Dec 31 06:09:35 2014 +0100
1.3 @@ -0,0 +1,165 @@
1.4 +// Copyright (c) 2012 The Chromium Authors. All rights reserved.
1.5 +// Use of this source code is governed by a BSD-style license that can be
1.6 +// found in the LICENSE file.
1.7 +
1.8 +// Sandbox is a sandbox library for windows processes. Use when you want a
1.9 +// 'privileged' process and a 'locked down process' to interact with.
1.10 +// The privileged process is called the broker and it is started by external
1.11 +// means (such as the user starting it). The 'sandboxed' process is called the
1.12 +// target and it is started by the broker. There can be many target processes
1.13 +// started by a single broker process. This library provides facilities
1.14 +// for both the broker and the target.
1.15 +//
1.16 +// The design rationale and relevant documents can be found at http://go/sbox.
1.17 +//
1.18 +// Note: this header does not include the SandboxFactory definitions because
1.19 +// there are cases where the Sandbox library is linked against the main .exe
1.20 +// while its API needs to be used in a DLL.
1.21 +
1.22 +#ifndef SANDBOX_WIN_SRC_SANDBOX_H_
1.23 +#define SANDBOX_WIN_SRC_SANDBOX_H_
1.24 +
1.25 +#include <windows.h>
1.26 +
1.27 +#include "base/basictypes.h"
1.28 +#include "sandbox/win/src/sandbox_policy.h"
1.29 +#include "sandbox/win/src/sandbox_types.h"
1.30 +
1.31 +// sandbox: Google User-Land Application Sandbox
1.32 +namespace sandbox {
1.33 +
1.34 +class BrokerServices;
1.35 +class ProcessState;
1.36 +class TargetPolicy;
1.37 +class TargetServices;
1.38 +
1.39 +// BrokerServices exposes all the broker API.
1.40 +// The basic use is to start the target(s) and wait for them to end.
1.41 +//
1.42 +// This API is intended to be called in the following order
1.43 +// (error checking omitted):
1.44 +// BrokerServices* broker = SandboxFactory::GetBrokerServices();
1.45 +// broker->Init();
1.46 +// PROCESS_INFORMATION target;
1.47 +// broker->SpawnTarget(target_exe_path, target_args, &target);
1.48 +// ::ResumeThread(target->hThread);
1.49 +// // -- later you can call:
1.50 +// broker->WaitForAllTargets(option);
1.51 +//
1.52 +class BrokerServices {
1.53 + public:
1.54 + // Initializes the broker. Must be called before any other on this class.
1.55 + // returns ALL_OK if successful. All other return values imply failure.
1.56 + // If the return is ERROR_GENERIC, you can call ::GetLastError() to get
1.57 + // more information.
1.58 + virtual ResultCode Init() = 0;
1.59 +
1.60 + // Returns the interface pointer to a new, empty policy object. Use this
1.61 + // interface to specify the sandbox policy for new processes created by
1.62 + // SpawnTarget()
1.63 + virtual TargetPolicy* CreatePolicy() = 0;
1.64 +
1.65 + // Creates a new target (child process) in a suspended state.
1.66 + // Parameters:
1.67 + // exe_path: This is the full path to the target binary. This parameter
1.68 + // can be null and in this case the exe path must be the first argument
1.69 + // of the command_line.
1.70 + // command_line: The arguments to be passed as command line to the new
1.71 + // process. This can be null if the exe_path parameter is not null.
1.72 + // policy: This is the pointer to the policy object for the sandbox to
1.73 + // be created.
1.74 + // target: returns the resulting target process information such as process
1.75 + // handle and PID just as if CreateProcess() had been called. The caller is
1.76 + // responsible for closing the handles returned in this structure.
1.77 + // Returns:
1.78 + // ALL_OK if successful. All other return values imply failure.
1.79 + virtual ResultCode SpawnTarget(const wchar_t* exe_path,
1.80 + const wchar_t* command_line,
1.81 + TargetPolicy* policy,
1.82 + PROCESS_INFORMATION* target) = 0;
1.83 +
1.84 + // This call blocks (waits) for all the targets to terminate.
1.85 + // Returns:
1.86 + // ALL_OK if successful. All other return values imply failure.
1.87 + // If the return is ERROR_GENERIC, you can call ::GetLastError() to get
1.88 + // more information.
1.89 + virtual ResultCode WaitForAllTargets() = 0;
1.90 +
1.91 + // Adds an unsandboxed process as a peer for policy decisions (e.g.
1.92 + // HANDLES_DUP_ANY policy).
1.93 + // Returns:
1.94 + // ALL_OK if successful. All other return values imply failure.
1.95 + // If the return is ERROR_GENERIC, you can call ::GetLastError() to get
1.96 + // more information.
1.97 + virtual ResultCode AddTargetPeer(HANDLE peer_process) = 0;
1.98 +
1.99 + // Install the AppContainer with the specified sid an name. Returns ALL_OK if
1.100 + // successful or an error code if the AppContainer cannot be installed.
1.101 + virtual ResultCode InstallAppContainer(const wchar_t* sid,
1.102 + const wchar_t* name) = 0;
1.103 +
1.104 + // Removes from the system the AppContainer with the specified sid.
1.105 + // Returns ALL_OK if successful or an error code otherwise.
1.106 + virtual ResultCode UninstallAppContainer(const wchar_t* sid) = 0;
1.107 +};
1.108 +
1.109 +// TargetServices models the current process from the perspective
1.110 +// of a target process. To obtain a pointer to it use
1.111 +// Sandbox::GetTargetServices(). Note that this call returns a non-null
1.112 +// pointer only if this process is in fact a target. A process is a target
1.113 +// only if the process was spawned by a call to BrokerServices::SpawnTarget().
1.114 +//
1.115 +// This API allows the target to gain access to resources with a high
1.116 +// privilege token and then when it is ready to perform dangerous activities
1.117 +// (such as download content from the web) it can lower its token and
1.118 +// enter into locked-down (sandbox) mode.
1.119 +// The typical usage is as follows:
1.120 +//
1.121 +// TargetServices* target_services = Sandbox::GetTargetServices();
1.122 +// if (NULL != target_services) {
1.123 +// // We are the target.
1.124 +// target_services->Init();
1.125 +// // Do work that requires high privileges here.
1.126 +// // ....
1.127 +// // When ready to enter lock-down mode call LowerToken:
1.128 +// target_services->LowerToken();
1.129 +// }
1.130 +//
1.131 +// For more information see the BrokerServices API documentation.
1.132 +class TargetServices {
1.133 + public:
1.134 + // Initializes the target. Must call this function before any other.
1.135 + // returns ALL_OK if successful. All other return values imply failure.
1.136 + // If the return is ERROR_GENERIC, you can call ::GetLastError() to get
1.137 + // more information.
1.138 + virtual ResultCode Init() = 0;
1.139 +
1.140 + // Discards the impersonation token and uses the lower token, call before
1.141 + // processing any untrusted data or running third-party code. If this call
1.142 + // fails the current process could be terminated immediately.
1.143 + virtual void LowerToken() = 0;
1.144 +
1.145 + // Returns the ProcessState object. Through that object it's possible to have
1.146 + // information about the current state of the process, such as whether
1.147 + // LowerToken has been called or not.
1.148 + virtual ProcessState* GetState() = 0;
1.149 +
1.150 + // Requests the broker to duplicate the supplied handle into the target
1.151 + // process. The target process must be an active sandbox child process
1.152 + // and the source process must have a corresponding policy allowing
1.153 + // handle duplication for this object type.
1.154 + // Returns:
1.155 + // ALL_OK if successful. All other return values imply failure.
1.156 + // If the return is ERROR_GENERIC, you can call ::GetLastError() to get
1.157 + // more information.
1.158 + virtual ResultCode DuplicateHandle(HANDLE source_handle,
1.159 + DWORD target_process_id,
1.160 + HANDLE* target_handle,
1.161 + DWORD desired_access,
1.162 + DWORD options) = 0;
1.163 +};
1.164 +
1.165 +} // namespace sandbox
1.166 +
1.167 +
1.168 +#endif // SANDBOX_WIN_SRC_SANDBOX_H_
