Trust No Program

SBIE DLL API


     •  Overview
     •  Enumerate Sandbox Names
     •  Query Sandbox Paths by Sandbox Name
     •  Query Sandbox Paths by Process ID
     •  Enumerate Running Processes
     •  Query Process Information
     •  Terminate a Single Sandboxed Process
     •  Terminate All Sandboxed Processes
     •  Query Configuration from Sandboxie.ini
     •  Update Configuration in Sandboxie.ini
     •  Reload Configuration from Sandboxie.ini
     •  Hook a User-Mode Entrypoint
     •  Register for DLL Load/Unload Callbacks
     •  Get Sandboxie Home Folder

Overview

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.


Enumerate Sandbox Names

        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);
	}

Query Sandbox Paths by Sandbox 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);

Query Sandbox Paths by Process ID

        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.

Enumerate Running Processes

        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.

Query Process Information

        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.

Terminate a Single Sandboxed Process

        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).

Terminate All Sandboxed Processes

        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.

Query Configuration from Sandboxie.ini

        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.

Update Configuration in Sandboxie.ini

        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.

Reload Configuration from Sandboxie.ini

        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.

Hook a User-Mode Entrypoint

        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);
        }

Register for DLL Load/Unload Callbacks

	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.

Get Sandboxie Home Folder

	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-2012 by Sandboxie Holdings, LLC.  All rights reserved.
Sandboxie.com | Contact Author
This site has been viewed 261,046,488 times since June 2004