 |
Trust No Program |
|
Trust No Program |
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:
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.
typedef LONG (__stdcall *P_SbieApi_EnumBoxes)(
LONG index, // initialize to -1
WCHAR *box_name); // pointer to WCHAR [34]
SbieApi_EnumBoxes
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.
Returns the next value to use for the index parameter.
Returns -1 when there is nothing left to enumerate.
WCHAR name[34];
int index = -1;
while (1) {
index = SbieApi_EnumBoxes(index, name);
if (index == -1)
break;
SandboxNames_StringArray.add(name);
}
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);
SbieApi_QueryBoxPath
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.
Returns zero on success, a non-zero value on error.
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);
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);
SbieApi_QueryProcessPath
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.
Returns zero on success, a non-zero value on error.
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 [512]
SbieApi_EnumProcessEx
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.
Returns zero on success, a non-zero value on error.
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);
SbieApi_QueryProcess
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.
Returns zero on success, a non-zero value on error.
typedef BOOLEAN (__stdcall *P_SbieDll_KillOne)(
HANDLE process_id);
SbieDll_KillOne
process_id [in] specifies the process ID for the sandboxed
process that should be terminated.
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).
typedef BOOLEAN (__stdcall *P_SbieDll_KillAll)(
ULONG session_id,
const WCHAR *box_name);
SbieDll_KillAll
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.
Returns TRUE on success, FALSE on failure.
The target processes are terminated in the fashion described
above; see SbieDll_KillOne.
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)
SbieApi_QueryConf
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.
Returns zero on success. Returns 0xC000008B if the setting
was not found. Any other return value indicates some other error.
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
SbieDll_UpdateConf
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.
Returns zero on success.
typedef LONG (__stdcall *P_SbieApi_ReloadConf)(
ULONG session_id);
SbieApi_ReloadConf
session_id [in] specifies the logon session number to which
Sandboxie will log any error messages. Pass -1 for the current
logon session.
Returns zero on success, a non-zero value on error.
typedef void *(__stdcall *P_SbieDll_Hook)(
const char *name,
void *source_func,
void *detour_func);
SbieDll_Hook
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.
Returns a function pointer which can be used by the detour
function to invoke the source function.
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);
}
typedef void (__stdcall *P_DllCallback)(const WCHAR *ImageName, HMODULE ImageBase);
typedef BOOLEAN *(__stdcall *P_SbieDll_RegisterDllCallback)( P_DllCallback pCallback);
SbieDll_RegisterDllCallback
This API is available starting with version 3.46 of Sandboxie.
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.
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.
typedef LONG *(__stdcall *P_SbieApi_GetHomePath)(
WCHAR *NtPath,
ULONG NtPathMaxLen,
WCHAR *DosPath,
ULONG DosPathMaxLen);
SbieApi_GetHomePath
This API is available starting with version 3.52 of Sandboxie.
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.
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.
Sandboxie is Copyright © 2004-2019 by Sandboxie Holdings, LLC. All rights reserved.
Sandboxie.com | Contact Author