src/sandbox/win/src/sandbox.h

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