The Tor Browser: comparison security/sandbox/win/src/sandbox.h

--1:000000000000
+:3d8bc4e96512
+// Copyright (c) 2012 The Chromium Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style license that can be
+// found in the LICENSE file.
+// Sandbox is a sandbox library for windows processes. Use when you want a
+// 'privileged' process and a 'locked down process' to interact with.
+// The privileged process is called the broker and it is started by external
+// means (such as the user starting it). The 'sandboxed' process is called the
+// target and it is started by the broker. There can be many target processes
+// started by a single broker process. This library provides facilities
+// for both the broker and the target.
+//
+// The design rationale and relevant documents can be found at http://go/sbox.
+//
+// Note: this header does not include the SandboxFactory definitions because
+// there are cases where the Sandbox library is linked against the main .exe
+// while its API needs to be used in a DLL.
+#ifndef SANDBOX_WIN_SRC_SANDBOX_H_
+#define SANDBOX_WIN_SRC_SANDBOX_H_
+#include <windows.h>
+#include "base/basictypes.h"
+#include "sandbox/win/src/sandbox_policy.h"
+#include "sandbox/win/src/sandbox_types.h"
+// sandbox: Google User-Land Application Sandbox
+namespace sandbox {
+class BrokerServices;
+class ProcessState;
+class TargetPolicy;
+class TargetServices;
+// BrokerServices exposes all the broker API.
+// The basic use is to start the target(s) and wait for them to end.
+//
+// This API is intended to be called in the following order
+// (error checking omitted):
+//  BrokerServices* broker = SandboxFactory::GetBrokerServices();
+//  broker->Init();
+//  PROCESS_INFORMATION target;
+//  broker->SpawnTarget(target_exe_path, target_args, &target);
+//  ::ResumeThread(target->hThread);
+//  // -- later you can call:
+//  broker->WaitForAllTargets(option);
+//
+class BrokerServices {
+public:
+// Initializes the broker. Must be called before any other on this class.
+// returns ALL_OK if successful. All other return values imply failure.
+// If the return is ERROR_GENERIC, you can call ::GetLastError() to get
+// more information.
+virtual ResultCode Init() = 0;
+// Returns the interface pointer to a new, empty policy object. Use this
+// interface to specify the sandbox policy for new processes created by
+// SpawnTarget()
+virtual TargetPolicy* CreatePolicy() = 0;
+// Creates a new target (child process) in a suspended state.
+// Parameters:
+//   exe_path: This is the full path to the target binary. This parameter
+//   can be null and in this case the exe path must be the first argument
+//   of the command_line.
+//   command_line: The arguments to be passed as command line to the new
+//   process. This can be null if the exe_path parameter is not null.
+//   policy: This is the pointer to the policy object for the sandbox to
+//   be created.
+//   target: returns the resulting target process information such as process
+//   handle and PID just as if CreateProcess() had been called. The caller is
+//   responsible for closing the handles returned in this structure.
+// Returns:
+//   ALL_OK if successful. All other return values imply failure.
+virtual ResultCode SpawnTarget(const wchar_t* exe_path,
+const wchar_t* command_line,
+TargetPolicy* policy,
+PROCESS_INFORMATION* target) = 0;
+// This call blocks (waits) for all the targets to terminate.
+// Returns:
+//   ALL_OK if successful. All other return values imply failure.
+//   If the return is ERROR_GENERIC, you can call ::GetLastError() to get
+//   more information.
+virtual ResultCode WaitForAllTargets() = 0;
+// Adds an unsandboxed process as a peer for policy decisions (e.g.
+// HANDLES_DUP_ANY policy).
+// Returns:
+//   ALL_OK if successful. All other return values imply failure.
+//   If the return is ERROR_GENERIC, you can call ::GetLastError() to get
+//   more information.
+virtual ResultCode AddTargetPeer(HANDLE peer_process) = 0;
+// Install the AppContainer with the specified sid an name. Returns ALL_OK if
+// successful or an error code if the AppContainer cannot be installed.
+virtual ResultCode InstallAppContainer(const wchar_t* sid,
+const wchar_t* name) = 0;
+// Removes from the system the AppContainer with the specified sid.
+// Returns ALL_OK if successful or an error code otherwise.
+virtual ResultCode UninstallAppContainer(const wchar_t* sid) = 0;
+};
+// TargetServices models the current process from the perspective
+// of a target process. To obtain a pointer to it use
+// Sandbox::GetTargetServices(). Note that this call returns a non-null
+// pointer only if this process is in fact a target. A process is a target
+// only if the process was spawned by a call to BrokerServices::SpawnTarget().
+//
+// This API allows the target to gain access to resources with a high
+// privilege token and then when it is ready to perform dangerous activities
+// (such as download content from the web) it can lower its token and
+// enter into locked-down (sandbox) mode.
+// The typical usage is as follows:
+//
+//   TargetServices* target_services = Sandbox::GetTargetServices();
+//   if (NULL != target_services) {
+//     // We are the target.
+//     target_services->Init();
+//     // Do work that requires high privileges here.
+//     // ....
+//     // When ready to enter lock-down mode call LowerToken:
+//     target_services->LowerToken();
+//   }
+//
+// For more information see the BrokerServices API documentation.
+class TargetServices {
+public:
+// Initializes the target. Must call this function before any other.
+// returns ALL_OK if successful. All other return values imply failure.
+// If the return is ERROR_GENERIC, you can call ::GetLastError() to get
+// more information.
+virtual ResultCode Init() = 0;
+// Discards the impersonation token and uses the lower token, call before
+// processing any untrusted data or running third-party code. If this call
+// fails the current process could be terminated immediately.
+virtual void LowerToken() = 0;
+// Returns the ProcessState object. Through that object it's possible to have
+// information about the current state of the process, such as whether
+// LowerToken has been called or not.
+virtual ProcessState* GetState() = 0;
+// Requests the broker to duplicate the supplied handle into the target
+// process. The target process must be an active sandbox child process
+// and the source process must have a corresponding policy allowing
+// handle duplication for this object type.
+// Returns:
+//   ALL_OK if successful. All other return values imply failure.
+//   If the return is ERROR_GENERIC, you can call ::GetLastError() to get
+//   more information.
+virtual ResultCode DuplicateHandle(HANDLE source_handle,
+DWORD target_process_id,
+HANDLE* target_handle,
+DWORD desired_access,
+DWORD options) = 0;
+};
+}  // namespace sandbox
+#endif  // SANDBOX_WIN_SRC_SANDBOX_H_

The Tor Browser / file comparison

comparison: security/sandbox/win/src/sandbox.h

security/sandbox/win/src/sandbox.h