install.h File Reference

Main interface to connect applications to driver headers. More...

Go to the source code of this file.

Macros
#define	LIBHYPERDBG_API   __declspec(dllimport)
#define	DRIVER_FUNC_INSTALL   0x01
#define	DRIVER_FUNC_STOP   0x02
#define	DRIVER_FUNC_REMOVE   0x03

Functions
BOOLEAN	InstallDriver (SC_HANDLE SchSCManager, LPCTSTR DriverName, LPCTSTR ServiceExe)
	Install driver.
BOOLEAN	RemoveDriver (SC_HANDLE SchSCManager, LPCTSTR DriverName)
	Remove Driver.
BOOLEAN	StartDriver (SC_HANDLE SchSCManager, LPCTSTR DriverName)
	Start Driver.
BOOLEAN	StopDriver (SC_HANDLE SchSCManager, LPCTSTR DriverName)
	Stop driver.
BOOLEAN	ManageDriver (_In_ LPCTSTR DriverName, _In_ LPCTSTR ServiceName, _In_ UINT16 Function)
BOOLEAN	SetupPathForFileName (const CHAR *FileName, _Inout_updates_bytes_all_(BufferLength) PCHAR FileLocation, ULONG BufferLength, BOOLEAN CheckFileExists)
	Setup file name.

Detailed Description

Main interface to connect applications to driver headers.

Author

Sina Karvandi (sina@.nosp@m.hype.nosp@m.rdbg..nosp@m.org)

Version

0.1

Date

2020-04-11

Copyright

This project is released under the GNU Public License v3.

Macro Definition Documentation

DRIVER_FUNC_INSTALL

#define DRIVER_FUNC_INSTALL   0x01

DRIVER_FUNC_REMOVE

#define DRIVER_FUNC_REMOVE   0x03

DRIVER_FUNC_STOP

#define DRIVER_FUNC_STOP   0x02

LIBHYPERDBG_API

#define LIBHYPERDBG_API   __declspec(dllimport)

Function Documentation

InstallDriver()

BOOLEAN InstallDriver	(	SC_HANDLE	SchSCManager,
		LPCTSTR	DriverName,
		LPCTSTR	ServiceExe )

Install driver.

Parameters

SC_HANDLE
LPCTSTR
LPCTSTR

Returns

BOOLEAN

{
    SC_HANDLE SchService;
    DWORD     LastError;
 
    //
    // NOTE: This creates an entry for a standalone driver. If this
    //       is modified for use with a driver that requires a Tag,
    //       Group, and/or Dependencies, it may be necessary to
    //       query the registry for existing driver information
    //       (in order to determine a unique Tag, etc.)
    //
 
    //
    // Create a new a service object
    //
    SchService = CreateService(SchSCManager,          // handle of service control manager database
                               DriverName,            // address of name of service to start
                               DriverName,            // address of display name
                               SERVICE_ALL_ACCESS,    // type of access to service
                               SERVICE_KERNEL_DRIVER, // type of service
                               SERVICE_DEMAND_START,  // when to start service
                               SERVICE_ERROR_NORMAL,  // severity if service fails to start
                               ServiceExe,            // address of name of binary file
                               NULL,                  // service does not belong to a group
                               NULL,                  // no tag requested
                               NULL,                  // no dependency names
                               NULL,                  // use LocalSystem account
                               NULL                   // no password for service account
    );
 
    if (SchService == NULL)
    {
        LastError = GetLastError();
 
        if (LastError == ERROR_SERVICE_EXISTS)
        {
            //
            // The service is already been created
            // means that, the driver is previously installed
            //
            ShowMessages("the service (driver) already exists\n");
 
            //
            // We need to remove the old instance of the driver first
            // Because the version of the driver might be different from the
            // user-mode application
            //
            ShowMessages("trying to remove the old instance of the driver first\n");
 
            //
            // Stop the driver
            //
            ManageDriver(DriverName, NULL, DRIVER_FUNC_STOP);
 
            //
            // Remove the driver
            //
            if (ManageDriver(DriverName, NULL, DRIVER_FUNC_REMOVE))
            {
                ShowMessages("the old instance of the driver is removed successfully\n");
            }
            else
            {
                ShowMessages("err, failed to remove the old instance of the driver\n");
                return FALSE;
            }
 
            //
            // Try to install the driver again
            //
            ShowMessages("installing the driver again\n");
 
            if (InstallDriver(SchSCManager, DriverName, ServiceExe))
            {
                return TRUE;
            }
            else
            {
                ShowMessages("err, failed to install the driver after removing the old instance\n");
                return FALSE;
            }
        }
        else if (LastError == ERROR_SERVICE_MARKED_FOR_DELETE)
        {
            //
            // Previous instance of the service is not fully deleted so sleep
            // and try again
            //
            ShowMessages("err, previous instance of the service is not fully deleted. Try "
                         "again...\n");
            return FALSE;
        }
        else
        {
            ShowMessages("err, CreateService failed (%x)\n", LastError);
 
            //
            // Indicate an error
            //
            return FALSE;
        }
    }
 
    //
    // Close the service object
    //
    if (SchService)
    {
        CloseServiceHandle(SchService);
    }
 
    //
    // Indicate success
    //
    return TRUE;
}

ManageDriver()

BOOLEAN ManageDriver	(	_In_ LPCTSTR	DriverName,
		_In_ LPCTSTR	ServiceName,
		_In_ UINT16	Function )

RemoveDriver()

BOOLEAN RemoveDriver	(	SC_HANDLE	SchSCManager,
		LPCTSTR	DriverName )

Remove Driver.

Parameters

SC_HANDLE
LPCTSTR

Returns

BOOLEAN

{
    SC_HANDLE SchService;
    BOOLEAN   Res;
 
    //
    // Open the handle to the existing service
    //
    SchService = OpenService(SchSCManager, DriverName, SERVICE_ALL_ACCESS);
 
    if (SchService == NULL)
    {
        ShowMessages("err, OpenService failed (%x)\n", GetLastError());
 
        //
        // Indicate error
        //
        return FALSE;
    }
 
    //
    // Mark the service for deletion from the service control manager database
    //
    if (DeleteService(SchService))
    {
        //
        // Indicate success
        //
        Res = TRUE;
    }
    else
    {
        ShowMessages("err, DeleteService failed (%x)\n", GetLastError());
 
        //
        // Indicate failure.  Fall through to properly close the service handle
        //
        Res = FALSE;
    }
 
    //
    // Close the service object
    //
    if (SchService)
    {
        CloseServiceHandle(SchService);
    }
 
    return Res;
}

SetupPathForFileName()

BOOLEAN SetupPathForFileName	(	const CHAR *	FileName,
		_Inout_updates_bytes_all_(BufferLength) PCHAR	FileLocation,
		ULONG	BufferLength,
		BOOLEAN	CheckFileExists )

Setup file name.

Parameters

FileName
FileLocation
BufferLength
CheckFileExists

Returns

BOOLEAN

{
    HANDLE  FileHandle;
    DWORD   FileLocLen = 0;
    HMODULE ProcHandle = GetModuleHandle(NULL);
    CHAR *  Pos;
 
    //
    // Get the current directory.
    //
 
    /*
  //
  // We use the location of running exe instead of
  // finding driver based on current directory
  //
  FileLocLen = GetCurrentDirectory(BufferLength, DriverLocation);
 
  if (FileLocLen == 0) {
 
    ShowMessages("err, GetCurrentDirectory failed (%x)\n", GetLastError());
 
    return FALSE;
  }
  */
 
    GetModuleFileName(ProcHandle, FileLocation, BufferLength);
 
    Pos = strrchr(FileLocation, '\\');
    if (Pos != NULL)
    {
        //
        // this will put the null terminator here. you can also copy to
        // another string if you want, we can also use PathCchRemoveFileSpec
        //
        *Pos = '\0';
    }
 
    //
    // Setup path name to driver file
    //
    if (FAILED(
            StringCbCat(FileLocation, BufferLength, "\\")))
    {
        return FALSE;
    }
    if (FAILED(
            StringCbCat(FileLocation, BufferLength, FileName)))
    {
        return FALSE;
    }
 
    if (CheckFileExists)
    {
        //
        // ensure file is in the specified directory
        //
        if ((FileHandle = CreateFile(FileLocation, GENERIC_READ, 0, NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL, NULL)) == INVALID_HANDLE_VALUE)
        {
            ShowMessages("err, target file is not loaded\n");
 
            //
            // Indicate failure
            //
            return FALSE;
        }
 
        //
        // Close open file handle
        //
        if (FileHandle)
        {
            CloseHandle(FileHandle);
        }
    }
 
    //
    // Indicate success
    //
    return TRUE;
}

StartDriver()

BOOLEAN StartDriver	(	SC_HANDLE	SchSCManager,
		LPCTSTR	DriverName )

Start Driver.

Parameters

SC_HANDLE
LPCTSTR

Returns

BOOLEAN

{
    SC_HANDLE SchService;
    DWORD     LastError;
    BOOLEAN   Status = TRUE;
 
    //
    // Open the handle to the existing service
    //
    SchService = OpenService(SchSCManager, DriverName, SERVICE_ALL_ACCESS);
 
    if (SchService == NULL)
    {
        ShowMessages("err, OpenService failed (%x)\n", GetLastError());
 
        //
        // Indicate failure
        //
        return FALSE;
    }
 
    //
    // Start the execution of the service (i.e. start the driver)
    //
    if (!StartService(SchService, // service identifier
                      0,          // number of arguments
                      NULL        // pointer to arguments
                      ))
    {
        LastError = GetLastError();
 
        if (LastError == ERROR_SERVICE_ALREADY_RUNNING)
        {
            //
            // Ignore this error
            //
        }
        else if (LastError == ERROR_PATH_NOT_FOUND)
        {
            //
            // Driver not found, or anti-virus limits the access to it
            //
            ShowMessages("err, path to the driver not found, or the access to the driver file is limited\n");
 
            ShowMessages("most of the time, it's because anti-virus software is not finished scanning the drivers, "
                         "so, if you try to load the driver again (re-enter the previous command), the problem will be solved\n");
 
            //
            // Indicate failure
            //
            Status = FALSE;
        }
        else if (LastError == ERROR_INVALID_IMAGE_HASH)
        {
            ShowMessages(
                "err, failed loading driver\n"
                "it's because either the driver signature enforcement is enabled or HVCI prevents the driver from loading\n"
                "you should disable the driver signature enforcement by attaching WinDbg or from the boot menu\n"
                "if the driver signature enforcement is disabled, HVCI might prevent the driver from loading\n"
                "HyperDbg is not compatible with Virtualization Based Security (VBS)\n"
                "please follow the instructions from: https://docs.hyperdbg.org/getting-started/build-and-install \n");
 
            //
            // Indicate failure.  Fall through to properly close the service handle
            //
            Status = FALSE;
        }
        else
        {
            ShowMessages("err, StartService failure (%x)\n", LastError);
 
            //
            // Indicate failure.  Fall through to properly close the service handle
            //
            Status = FALSE;
        }
    }
 
    //
    // Close the service object
    //
    if (SchService)
    {
        CloseServiceHandle(SchService);
    }
 
    return Status;
}

StopDriver()

BOOLEAN StopDriver	(	SC_HANDLE	SchSCManager,
		LPCTSTR	DriverName )

Stop driver.

Parameters

SC_HANDLE
LPCTSTR

Returns

BOOLEAN

{
    BOOLEAN        Res = TRUE;
    SC_HANDLE      SchService;
    SERVICE_STATUS serviceStatus;
 
    //
    // Open the handle to the existing service
    //
    SchService = OpenService(SchSCManager, DriverName, SERVICE_ALL_ACCESS);
 
    if (SchService == NULL)
    {
        ShowMessages("err, OpenService failed (%x)\n", GetLastError());
 
        return FALSE;
    }
 
    //
    // Request that the service stop
    //
    if (ControlService(SchService, SERVICE_CONTROL_STOP, &serviceStatus))
    {
        //
        // Indicate success
        //
        Res = TRUE;
    }
    else
    {
        ShowMessages("warning, failed to stop the driver. Possible reasons include the driver not currently running or an unsuccessful unload from a previous run. "
                     "This is not an error, HyperDbg tries to remove the previous driver and load it again (%x)\n",
                     GetLastError());
 
        //
        // Indicate failure.  Fall through to properly close the service handle
        //
        Res = FALSE;
    }
 
    //
    // Close the service object
    //
    if (SchService)
    {
        CloseServiceHandle(SchService);
    }
 
    return Res;
}