SBIE DLL API
This page describes the callable entrypoints in the SbieDll.dll dynamically-linked library (DLL). These entrypoints expose some functionality of Sandboxie that can be accessed programmatically, that is, through other programs rather than through a person interacting with Sandboxie.
There are three aspects to using Sandboxie programmatically:
- Driving some functionality using the Start.exe program. See Start Command Line.
- Injecting custom DLLs into sandboxed programs. See InjectDll.
- Calling Sandboxie entrypoints from programs running (sandboxed or not). Described here.
The entrypoints described here are all exported by SbieDll.dll. To access an entrypoint, you should dynamically load this DLL into your program, and get the address of the desired entrypoint. For example,
__declspec(dllexport) void __stdcall InjectDllMain(HINSTANCE hSbieDll, ULONG_PTR UnusedParameter)
{
//
// locate the address of SbieDll_Hook in SbieDll.dll
//
typedef void *(__stdcall *P_SbieDll_Hook)(
const char *ApiName, void *ApiFunc, void *NewFunc);
P_SbieDll_Hook p_SbieDll_Hook = GetProcAddress(hSbieDll, "SbieDll_Hook");
//
// invoke SbieDll_Hook through the function pointer
//
p_SbieDll_Hook(...);
}
Note the use of InjectDllMain (see Inject Dll) to get a handle to the loaded instance of SbieDll. That is the recommended approach. However, using LoadLibrary or GetModuleHandle to look up SbieDll by name is also fine.
Enumerate Sandbox Names
- Prototype:
typedef LONG (__stdcall *P_SbieApi_EnumBoxes)(
LONG index, // initialize to -1
WCHAR *box_name); // pointer to WCHAR [34]
- Export Name:
SbieApi_EnumBoxes
- Parameters:
index [in] specifies which sandbox to return. Initialize to -1.
Sandboxes are enumerated in the order they appear in Sandboxie.ini.
box_name [out] receives the sandbox name.
Note: this function cannot be used by a sandboxed program.
- Return Value:
Returns the next value to use for the index parameter.
Returns -1 when there is nothing left to enumerate.
- Sample Code:
WCHAR name[34];
int index = -1;
while (1) {
index = SbieApi_EnumBoxes(index, name);
if (index == -1)
break;
SandboxNames_StringArray.add(name);
}
Query Sandbox Paths by Sandbox Name
- Prototype:
typedef LONG (__stdcall *P_SbieApi_QueryBoxPath)(
const WCHAR *box_name, // pointer to WCHAR [34]
WCHAR *file_path,
WCHAR *key_path,
WCHAR *ipc_path,
ULONG *file_path_len,
ULONG *key_path_len,
ULONG *ipc_path_len);
- Export Name:
SbieApi_QueryBoxPath
- Parameters:
box_name [in] specifies the name of the sandbox for which
to return path information.
file_path [out] receives the path to the root directory of
the sandbox, as set by the FileRootPath setting.
The buffer receives at most the number of bytes specified
by the file_path_len parameter. Pass NULL to ignore this
parameter.
key_path [out] receives the path to the root key of the
sandbox registry, as set by the KeyRootPath setting.
The buffer receives at most the number of bytes specified
by the key_path_len parameter. Pass NULL to ignore this
parameter.
ipc_path [out] receives the path to the root object directory
of the sandbox, as set by the IpcRootPath setting.
The buffer receives at most the number of bytes specified
by the ipc_path_len parameter. Pass NULL to ignore this
parameter.
file_path_len [in/out] specifies the length in bytes of the
file_path buffer. On return, receives the length in bytes
needed to receive a complete buffer.
key_path_len [in/out] specifies the length in bytes of the
key_path buffer. On return, receives the length in bytes
needed to receive a complete buffer.
ipc_path_len [in/out] specifies the length in bytes of the
ipc_path buffer. On return, receives the length in bytes
needed to receive a complete buffer.
- Return Value:
Returns zero on success, a non-zero value on error.
- Sample Code:
ULONG FileLen = 0;
ULONG KeyLen = 0;
ULONG IpcLen = 0;
SbieApi_QueryBoxPath(
NULL, NULL, NULL, NULL, &FileLen, &KeyLen, &IpcLen);
// note that lengths are returned as the number of bytes,
// rather than number of WCHAR characters
WCHAR *FileBuf = malloc(FileLen);
WCHAR *KeyBuf = malloc(KeyLen);
WCHAR *IpcBuf = malloc(IpcLen);
SbieApi_QueryBoxPath(
FileBuf, KeyBuf, IpcBuf, &FileLen, &KeyLen, &IpcLen);
// now use wcslen to count the number of characters
FileLen = wcslen(FileBuf);
KeyLen = wcslen(KeyBuf);
IpcLen = wcslen(IpcBuf);
Query Sandbox Paths by Process ID
- Prototype:
typedef LONG (__stdcall *P_SbieApi_QueryProcessPath)(
HANDLE process_id,
WCHAR *file_path,
WCHAR *key_path,
WCHAR *ipc_path,
ULONG *file_path_len,
ULONG *key_path_len,
ULONG *ipc_path_len);
- Export Name:
SbieApi_QueryProcessPath
- Parameters:
process_id [in] specifies the ID of the sandboxed process to query.
file_path [out]
key_path [out]
ipc_path [out]
file_path_len [in/out]
key_path_len [in/out]
ipc_path_len [in/out]
The last six parameters are similar to the last six parameters for
the QueryBoxPath function, discussed above. However, QueryProcessPath
(this function) returns the sandbox paths that are in use by a running
program, whereas QueryBoxPath returns the paths as they are recorded
in the Sandboxie configuration.
Or put another way: Suppose a sandboxed program starts with PID 124,
and then some sandbox path (for instance FileRootPath) is set to a
new value. At this point, QueryBoxPath will return the new value, but
QueryProcessPath for PID 124 will return the old value.
- Return Value:
Returns zero on success, a non-zero value on error.
Enumerate Running Processes
- Prototype:
typedef LONG (__stdcall *P_SbieApi_EnumProcessEx)(
const WCHAR *box_name, // pointer to WCHAR [34]
BOOLEAN all_sessions,
ULONG which_session,
ULONG *boxed_pids, // pointer to ULONG []
ULONG *boxed_count);
- Export Name:
SbieApi_EnumProcessEx
- Parameters:
box_name [in] specifies the name of the sandbox in which
processes will be enumerated.
all_sessions [in] specifies TRUE to enumerate processes in all
logon sessions or only in a particular logon session
which_session [in] specifies the logon session number in which
processes will be enumerated. Ignored if all_sessions if TRUE.
Pass the value -1 to specify the current logon session.
boxed_pids [out] receives the process ID (PID) numbers.
The first ULONG receives the number of processes enumerated.
The second ULONG receives the first PID, the third ULONG receives
the second PID, and so on.
- Return Value:
Returns zero on success, a non-zero value on error.
Query Process Information
- Prototype:
typedef LONG (__stdcall *P_SbieApi_QueryProcess)(
HANDLE process_id,
WCHAR *box_name, // pointer to WCHAR [34]
WCHAR *image_name, // pointer to WCHAR [96]
WCHAR *sid_string, // pointer to WCHAR [96]
ULONG *session_id);
- Export Name:
SbieApi_QueryProcess
- Parameters:
process_id [in] specifies the ID of the sandboxed process to query.
box_name [out] receives the name of the sandbox in which the
process is running. Pass NULL to ignore this parameter.
image_name [out] receives the process name. Pass NULL to ignore
this parameter.
sid_string [out] receives the SID string for the process.
Pass NULL to ignore this parameter.
session_id [out] receives the logon session number in which
the process is running. Pass NULL to ignore this parameter.
- Return Value:
Returns zero on success, a non-zero value on error.
Terminate a Single Sandboxed Process
- Prototype:
typedef BOOLEAN (__stdcall *P_SbieDll_KillOne)(
HANDLE process_id);
- Export Name:
SbieDll_KillOne
- Parameters:
process_id [in] specifies the process ID for the sandboxed
process that should be terminated.
- Return Value:
Returns TRUE on success, FALSE on failure.
The target process is terminated by the Sandboxie service
(SbieSvc) with exit code 1 through a call to the Windows API
TerminateProcess (ProcessId, 1).
Terminate All Sandboxed Processes
- Prototype:
typedef BOOLEAN (__stdcall *P_SbieDll_KillAll)(
ULONG session_id,
const WCHAR *box_name);
- Export Name:
SbieDll_KillAll
- Parameters:
session_id [in] specifies the logon session number in which
sandboxed programs should be terminated.
box_name [in] specifies the sandbox name in which sandboxed
programs should be terminated. Specify -1 to indicate the
current logon session.
- Return Value:
Returns TRUE on success, FALSE on failure.
The target processes are terminated in the fashion described
above; see SbieDll_KillOne.
Query Configuration from Sandboxie.ini
- Prototype:
typedef LONG (__stdcall *P_SbieApi_QueryConf)(
const WCHAR *section_name, // pointer to WCHAR [34]
const WCHAR *setting_name, // pointer to WCHAR [66]
ULONG setting_index,
WCHAR *value,
ULONG value_len)
- Export Name:
SbieApi_QueryConf
- Parameters:
section_name [in] specifies the section name that contains
the setting to query.
setting_name [in] specifies the setting name to query.
setting_index [in] specifies the zero-based index number
for a setting that may appear multiple times. The index
number can be logically OR'ed with these special values:
0x40000000 - do not scan the [GlobalSettings] section
if the specified setting name does appear in the
specified section.
0x20000000 - do not expand any variables in the result.
0x10000000 - ignore any settings that originate from
a template (typically defined in the Templates.ini file).
only query those settings that appear explicitly in the
Sandboxie.ini file.
value [out] receives the value of the specified setting.
value_len [in] specifies the maximum length in bytes of
the buffer pointed to by the value parameter.
- Return Value:
Returns zero on success. Returns 0xC000008B if the setting
was not found. Any other return value indicates some other error.
Update Configuration in Sandboxie.ini
- Prototype:
typedef LONG (__stdcall *P_SbieDll_UpdateConf)(
WCHAR operation_code,
const WCHAR *password, // limited to 64 chars
const WCHAR *section_name, // limited to 32 chars
const WCHAR *setting_name, // limited to 64 chars
const WCHAR *value) // limited to 2000 chars
- Export Name:
SbieDll_UpdateConf
- Parameters:
operation_code [in] specifies how to update the request setting:
's' to set (overwrite), replacing any existing values
'a' to append the new value at the bottom of a list of values
(or simply set the new value if there isn't one already)
'i' to insert the new value at the top of a list of values
(or simply set the new value if there isn't one already)
'd' to delete an existing value in a list of values
password [in] specifies the password to use if one is required,
or NULL or an empty string otherwise.
section_name [in] is a required parameter which specifies the
section name that contains the setting to set.
setting_name [in] is a required parameter which specifies the
setting name to set.
value [ini] is an optional parameter specifies the new value.
If operation_code is 's' and value is omitted, the corresponding
setting in the specified section will be deleted.
If operation_code is 's' and setting_name is "*" (wildcard star)
and value is omitted, this function deletes a complete section
from the configuration file.
- Return Value:
Returns zero on success.
Reload Configuration from Sandboxie.ini
- Prototype:
typedef LONG (__stdcall *P_SbieApi_ReloadConf)(
ULONG session_id);
- Export Name:
SbieApi_ReloadConf
- Parameters:
session_id [in] specifies the logon session number to which
Sandboxie will log any error messages. Pass -1 for the current
logon session.
- Return Value:
Returns zero on success, a non-zero value on error.
Hook a User-Mode Entrypoint
- Prototype:
typedef void *(__stdcall *P_SbieDll_Hook)(
const char *name,
void *source_func,
void *detour_func);
- Export Name:
SbieDll_Hook
- Parameters:
name [in] specifies an ASCII-string naming the entrypoint to
be hooked. In case of error, SbieDll_Hook logs a Sandboxie
error message which includes this descriptive name.
source_func [in] pointer to the function to hook.
detour_func [in] pointer to the hook code.
This function will cause the source function to invoke the detour
function. In other words, the detour function will intercept all
calls to the source function.
- Return Value:
Returns a function pointer which can be used by the detour
function to invoke the source function.
- Sample Code:
typedef BOOL (__stdcall *P_DeleteFileW)(const WCHAR *Path);
P_DeleteFileW pDeleteFileW = NULL;
BOOL __stdcall MyDeleteFileW(const WCHAR *Path)
{
if (Path[0] == L'C') {
// silently ignore requests to delete any file on drive C
SetLastError(0);
return TRUE;
} else {
// otherwise invoke the original DeleteFileW function
return pDeleteFileW(Path);
}
}
main()
{
pDeleteFileW = GetProcAddress(kernel32dll, "DeleteFileW");
pDeleteFileW = SbieDll_Hook("DeleteFile",
pDeleteFileW,
MyDeleteFileW);
}
Register for DLL Load/Unload Callbacks
- Prototype:
typedef void (__stdcall *P_DllCallback)(const WCHAR *ImageName, HMODULE ImageBase);
typedef BOOLEAN *(__stdcall *P_SbieDll_RegisterDllCallback)(
P_DllCallback pCallback);
- Export Name:
SbieDll_RegisterDllCallback
This API is available starting with version 3.46 of Sandboxie.
- Parameters:
pCallback specifies a callback function to be invoked whenever
any DLL is loaded or unloaded in the process. The callback
function cannot be unregistered.
The ImageName (first) parameter to the callback function
specifies the UNICODE name string for the DLL that was loaded
or unloaded. The name string does not include a path.
The ImageBase (second) parameter to the callback function
specifies the load base address for the DLL, when the callback
function is invoked to notify of a DLL load. When the callback
function is invoked to notify of a DLL unload, this parameter
is set to zero.
- Return Value:
Returns TRUE on success, FALSE if the callback cannot be registered.
As of version 3.46, Sandboxie supports up to 8 registrations within
a single process.
Get Sandboxie Home Folder
- Prototype:
typedef LONG *(__stdcall *P_SbieApi_GetHomePath)(
WCHAR *NtPath,
ULONG NtPathMaxLen,
WCHAR *DosPath,
ULONG DosPathMaxLen);
- Export Name:
SbieApi_GetHomePath
This API is available starting with version 3.52 of Sandboxie.
- Parameters:
NtPath specifies a pointer to a buffer which will receive the
full path of the Sandboxie installation folder in NT-path syntax.
NtPathMaxLen specifies the size of the NtPath buffer. Specify
NULL for NtPath and zero for NtPathMaxLen to not receive the
NT path.
DosPath specifies a pointer to a buffer which will receive the
full path of the Sandboxie installation folder in DOS-path syntax.
DosPathMaxLen specifies the size of the DosPath buffer. Specify
NULL for DosPath and zero for DosPathMaxLen to not receive the
NT path.
- Return Value:
Returns zero on success, a non-zero value on error.
STATUS_BUFFER_TOO_SMALL (0xC0000023) indicates either NtPathMaxLen
or DosPathMaxLen specifies a buffer that is too small. Increase
the size of the input buffer and retry the call.