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