IdtEmulation.h File Reference

Header for Handlers of Guest's IDT Emulator. More...

Go to the source code of this file.

Classes
struct	_SIDT_ENTRY
struct	_KIDT_ENTRY
struct	_INTERRUPT_TRAP_FRAME
	Trap frame for interrupts. More...
struct	_HOST_EXCEPTION_INFO
	Filled out when a host exception occurs. More...

Macros
#define	USE_DEFAULT_OS_IDT_AS_HOST_IDT   FALSE
	Whether the hypervisor should use the default OS's IDT as the host IDT in VMCS or not.
#define	HOST_IDT_DESCRIPTOR_COUNT   256
	Maximum number of interrupt entries in IDT.

Typedefs
typedef struct _SIDT_ENTRY	SIDT_ENTRY
typedef struct _SIDT_ENTRY *	PSIDT_ENTRY
typedef struct _KIDT_ENTRY	KIDT_ENTRY
typedef struct _KIDT_ENTRY *	PKIDT_ENTRY
typedef struct _INTERRUPT_TRAP_FRAME	INTERRUPT_TRAP_FRAME
	Trap frame for interrupts.
typedef struct _INTERRUPT_TRAP_FRAME *	PINTERRUPT_TRAP_FRAME
typedef struct _HOST_EXCEPTION_INFO	HOST_EXCEPTION_INFO
	Filled out when a host exception occurs.
typedef struct _HOST_EXCEPTION_INFO *	PHOST_EXCEPTION_INFO

Functions
VOID	IdtEmulationPrepareHostIdt (_Inout_ VIRTUAL_MACHINE_STATE *VCpu)
	Prepare Host IDT.
VOID	IdtEmulationHandleExceptionAndNmi (_Inout_ VIRTUAL_MACHINE_STATE *VCpu, _In_ VMEXIT_INTERRUPT_INFORMATION InterruptExit)
	Handle NMI and exception vm-exits.
VOID	IdtEmulationHandleExternalInterrupt (_Inout_ VIRTUAL_MACHINE_STATE *VCpu, _In_ VMEXIT_INTERRUPT_INFORMATION InterruptExit)
	external-interrupt vm-exit handler
VOID	IdtEmulationHandleNmiWindowExiting (_Inout_ VIRTUAL_MACHINE_STATE *VCpu)
	Handle NMI-window exitings.
VOID	IdtEmulationHandleInterruptWindowExiting (_Inout_ VIRTUAL_MACHINE_STATE *VCpu)
	Handle interrupt-window exitings.
VOID	IdtEmulationQueryIdtEntriesRequest (PINTERRUPT_DESCRIPTOR_TABLE_ENTRIES_PACKETS IdtQueryRequest, BOOLEAN ReadFromVmxRoot)
	Perform query for IDT entries.

Detailed Description

Header for Handlers of Guest's IDT Emulator.

Author

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

Version

0.1

Date

2020-06-10

Copyright

This project is released under the GNU Public License v3.

Macro Definition Documentation

HOST_IDT_DESCRIPTOR_COUNT

#define HOST_IDT_DESCRIPTOR_COUNT   256

Maximum number of interrupt entries in IDT.

USE_DEFAULT_OS_IDT_AS_HOST_IDT

#define USE_DEFAULT_OS_IDT_AS_HOST_IDT   FALSE

Whether the hypervisor should use the default OS's IDT as the host IDT in VMCS or not.

Typedef Documentation

HOST_EXCEPTION_INFO

typedef struct _HOST_EXCEPTION_INFO HOST_EXCEPTION_INFO

Filled out when a host exception occurs.

INTERRUPT_TRAP_FRAME

typedef struct _INTERRUPT_TRAP_FRAME INTERRUPT_TRAP_FRAME

Trap frame for interrupts.

KIDT_ENTRY

typedef struct _KIDT_ENTRY KIDT_ENTRY

PHOST_EXCEPTION_INFO

typedef struct _HOST_EXCEPTION_INFO * PHOST_EXCEPTION_INFO

PINTERRUPT_TRAP_FRAME

typedef struct _INTERRUPT_TRAP_FRAME * PINTERRUPT_TRAP_FRAME

PKIDT_ENTRY

typedef struct _KIDT_ENTRY * PKIDT_ENTRY

PSIDT_ENTRY

typedef struct _SIDT_ENTRY * PSIDT_ENTRY

SIDT_ENTRY

typedef struct _SIDT_ENTRY SIDT_ENTRY

Function Documentation

IdtEmulationHandleExceptionAndNmi()

VOID IdtEmulationHandleExceptionAndNmi	(	_Inout_ VIRTUAL_MACHINE_STATE *	VCpu,
		_In_ VMEXIT_INTERRUPT_INFORMATION	InterruptExit )

Handle NMI and exception vm-exits.

Parameters

VCpu	The virtual processor's state
InterruptExit	interrupt exit information

Returns

VOID

{
    //
    // Exception or non-maskable interrupt (NMI). Either:
    //  1: Guest software caused an exception and the bit in the exception bitmap associated with exception's vector was set to 1
    //  2: An NMI was delivered to the logical processor and the "NMI exiting" VM-execution control was 1.
    //
    // VMCS_VMEXIT_INTERRUPTION_INFORMATION shows the exit information about event that occurred and causes this exit
    // Don't forget to read VMCS_VMEXIT_INTERRUPTION_ERROR_CODE in the case of re-injectiong event
    //
 
    switch (InterruptExit.Vector)
    {
    case EXCEPTION_VECTOR_BREAKPOINT:
 
        //
        // Handle software breakpoints
        //
        {
            UINT64 GuestRip  = NULL64_ZERO;
            BYTE   TargetMem = NULL_ZERO;
 
            VmxVmread64P(VMCS_GUEST_RIP, &GuestRip);
 
            MemoryMapperReadMemorySafe(GuestRip, &TargetMem, sizeof(BYTE));
 
            if (!EptCheckAndHandleBreakpoint(VCpu) || TargetMem == 0xcc)
            {
                if (!DebuggingCallbackHandleBreakpointException(VCpu->CoreId))
                {
                    //
                    // Don't increment rip
                    //
                    HvSuppressRipIncrement(VCpu);
 
                    //
                    // Kernel debugger (debugger-mode) is not attached, re-inject the breakpoint
                    //
                    EventInjectBreakpoint();
                }
            }
        }
 
        break;
 
    case EXCEPTION_VECTOR_UNDEFINED_OPCODE:
 
        //
        // Handle the #UD, checking if this exception was intentional.
        //
        if (!SyscallHookHandleUD(VCpu))
        {
            //
            // If this #UD was found to be unintentional, inject a #UD interruption into the guest.
            //
            EventInjectUndefinedOpcode(VCpu);
        }
 
        break;
 
    case EXCEPTION_VECTOR_PAGE_FAULT:
 
        //
        // Handle page-faults (#PFs)
        //
        IdtEmulationHandlePageFaults(VCpu, InterruptExit);
 
        break;
 
    case EXCEPTION_VECTOR_DEBUG_BREAKPOINT:
 
        //
        // Check if syscall callback is enabled and if so, then we need to
        // check whether the this trap flag is set because of intercepting
        // the result of a system-call or not
        //
        if (g_SyscallCallbackStatus &&
            SyscallCallbackCheckAndHandleAfterSyscallTrapFlags(VCpu,
                                                               HANDLE_TO_UINT32(PsGetCurrentProcessId()),
                                                               HANDLE_TO_UINT32(PsGetCurrentThreadId())))
        {
            //
            // Being here means that this #DB was caused by a trap flag of
            // the system-call in the syscall callback, so no need to further handle
            // it (nothing to do)
            //
        }
        else if (!DebuggingCallbackHandleDebugBreakpointException(VCpu->CoreId))
        {
            //
            // It's not because of thread change detection, so re-inject it
            //
            EventInjectInterruptOrException(InterruptExit);
        }
 
        break;
 
    case EXCEPTION_VECTOR_NMI:
 
        if (VCpu->EnableExternalInterruptsOnContinue ||
            VCpu->EnableExternalInterruptsOnContinueMtf ||
            VCpu->InstrumentationStepInMtf)
        {
            //
            // Ignore the nmi
            //
        }
        else
        {
            //
            // Re-inject the interrupt/exception because it doesn't relate to us
            //
            EventInjectInterruptOrException(InterruptExit);
        }
 
        break;
 
    default:
 
        //
        // Re-inject the interrupt/exception, nothing special to handle
        //
        EventInjectInterruptOrException(InterruptExit);
 
        break;
    }
}

IdtEmulationHandleExternalInterrupt()

VOID IdtEmulationHandleExternalInterrupt	(	_Inout_ VIRTUAL_MACHINE_STATE *	VCpu,
		_In_ VMEXIT_INTERRUPT_INFORMATION	InterruptExit )

external-interrupt vm-exit handler

Parameters

VCpu	The virtual processor's state
InterruptExit	interrupt info from vm-exit

Returns

VOID

{
    BOOLEAN                    Interruptible         = TRUE;
    VMX_INTERRUPTIBILITY_STATE InterruptibilityState = {0};
    RFLAGS                     GuestRflags           = {0};
 
    //
    // In order to enable External Interrupt Exiting we have to set
    // IA32_VMX_PINBASED_CTLS_EXTERNAL_INTERRUPT_EXITING_FLAG in vmx
    // pin-based controls (PIN_BASED_VM_EXEC_CONTROL) and also
    // we should enable IA32_VMX_EXIT_CTLS_ACKNOWLEDGE_INTERRUPT_ON_EXIT_FLAG
    // on vmx vm-exit controls (VMCS_CTRL_VMEXIT_CONTROLS), also this function
    // might not always be successful if the guest is not in the interruptible
    // state so it wait for and interrupt-window exiting to re-inject
    // the interrupt into the guest
    //
    if (VCpu->EnableExternalInterruptsOnContinue ||
        VCpu->EnableExternalInterruptsOnContinueMtf)
    {
        //
        // Ignore the interrupt as it's suppressed because of instrumentation step-in
        //
 
        //
        // During developing HyperDbg, we realized that if we just ignore the interrupts completely
        // while we are waiting on 'i' instrumentation step-in command, then the serial device becomes
        // unresponsive, to solve this issue we hold the details of interrupts so we can re-inject
        // and process them when we decide to continue the debuggee (guest interrupt windows is open)
        // this way, the serial device works normally and won't become unresponsive
        //
        IdtEmulationInjectInterruptWhenInterruptWindowIsOpen(VCpu, InterruptExit);
 
        //
        // avoid incrementing rip
        //
        HvSuppressRipIncrement(VCpu);
    }
 
    else if (InterruptExit.Valid && InterruptExit.InterruptionType == INTERRUPT_TYPE_EXTERNAL_INTERRUPT)
    {
        VmxVmread64P(VMCS_GUEST_RFLAGS, &GuestRflags.AsUInt);
        VmxVmread32P(VMCS_GUEST_INTERRUPTIBILITY_STATE, &InterruptibilityState.AsUInt);
 
        //
        // External interrupts cannot be injected into the
        // guest if guest isn't interruptible (e.g.: guest
        // is blocked by "mov ss", or EFLAGS.IF == 0).
        //
        Interruptible = GuestRflags.InterruptEnableFlag && !InterruptibilityState.BlockingByMovSs;
 
        if (Interruptible)
        {
            //
            // Re-inject the interrupt/exception
            //
            EventInjectInterruptOrException(InterruptExit);
        }
        else
        {
            //
            // We can't inject interrupt because the guest's state is not interruptible
            // we have to queue it an re-inject it when the interrupt window is opened!
            //
            IdtEmulationInjectInterruptWhenInterruptWindowIsOpen(VCpu, InterruptExit);
 
            //
            // Enable Interrupt-window exiting.
            //
            HvSetInterruptWindowExiting(TRUE);
        }
 
        //
        // avoid incrementing rip
        //
        HvSuppressRipIncrement(VCpu);
    }
    else
    {
        Interruptible = FALSE;
 
        LogError("Err, why we are here? it's a vm-exit due to the external"
                 "interrupt and its type is not external interrupt? weird!");
    }
}

IdtEmulationHandleInterruptWindowExiting()

VOID IdtEmulationHandleInterruptWindowExiting

(

_Inout_ VIRTUAL_MACHINE_STATE *

VCpu

)

Handle interrupt-window exitings.

Parameters

VCpu	The virtual processor's state

Returns

VOID

{
    VMEXIT_INTERRUPT_INFORMATION InterruptExit   = {0};
    BOOLEAN                      InjectPageFault = FALSE;
 
    //
    // Check if page-fault needs to be injected or not
    //
    if (g_WaitingForInterruptWindowToInjectPageFault)
    {
        InjectPageFault = IdtEmulationInjectPageFaultWhenInterruptWindowsIsOpen(VCpu);
    }
 
    //
    // Check if another interrupt (page-fault) needed to injected or not
    //
    if (!InjectPageFault)
    {
        for (SIZE_T i = 0; i < PENDING_INTERRUPTS_BUFFER_CAPACITY; i++)
        {
            //
            // Find an empty space
            //
            if (VCpu->PendingExternalInterrupts[i] != NULL_ZERO)
            {
                //
                // Save it for re-injection (interrupt-window exiting)
                //
                InterruptExit.AsUInt = VCpu->PendingExternalInterrupts[i];
 
                //
                // Free the entry
                //
                VCpu->PendingExternalInterrupts[i] = NULL_ZERO;
                break;
            }
        }
 
        if (InterruptExit.AsUInt == 0)
        {
            //
            // Nothing left in pending state, let's disable the interrupt window exiting
            //
            HvSetInterruptWindowExiting(FALSE);
        }
        else
        {
            //
            // Inject the interrupt/exception
            //
 
            EventInjectInterruptOrException(InterruptExit);
        }
    }
 
    //
    // avoid incrementing rip
    //
    HvSuppressRipIncrement(VCpu);
}

IdtEmulationHandleNmiWindowExiting()

VOID IdtEmulationHandleNmiWindowExiting

(

_Inout_ VIRTUAL_MACHINE_STATE *

VCpu

)

Handle NMI-window exitings.

Parameters

VCpu	The virtual processor's state

Returns

VOID

{
    //
    // Inject the NMI into the guest
    //
    EventInjectNmi(VCpu);
 
    //
    // Disable NMI-window exiting since we have no more NMIs to inject
    //
    HvSetNmiWindowExiting(FALSE);
}

IdtEmulationPrepareHostIdt()

VOID IdtEmulationPrepareHostIdt

(

_Inout_ VIRTUAL_MACHINE_STATE *

VCpu

)

Prepare Host IDT.

Parameters

VCpu	The virtual processor's state

Returns

VOID

{
    SEGMENT_DESCRIPTOR_INTERRUPT_GATE_64 * VmxHostIdt = (SEGMENT_DESCRIPTOR_INTERRUPT_GATE_64 *)VCpu->HostIdt;
    SEGMENT_DESCRIPTOR_INTERRUPT_GATE_64 * WindowsIdt = (SEGMENT_DESCRIPTOR_INTERRUPT_GATE_64 *)AsmGetIdtBase();
 
    //
    // Zero the memory
    //
    RtlZeroMemory(VmxHostIdt, HOST_IDT_DESCRIPTOR_COUNT * sizeof(SEGMENT_DESCRIPTOR_INTERRUPT_GATE_64));
 
    //
    // Copy OS interrupt (IDT) entries
    //
    RtlCopyBytes(VmxHostIdt,
                 WindowsIdt,
                 HOST_IDT_DESCRIPTOR_COUNT * sizeof(SEGMENT_DESCRIPTOR_INTERRUPT_GATE_64));
 
    /*
    for (SIZE_T i = 0; i < HOST_IDT_DESCRIPTOR_COUNT; i++)
    {
        SEGMENT_DESCRIPTOR_INTERRUPT_GATE_64 CurrentEntry = WindowsIdt[i];
 
        UINT64 Offset = 0;
        Offset |= ((UINT64)CurrentEntry.OffsetLow) << 0;
        Offset |= ((UINT64)CurrentEntry.OffsetMiddle) << 16;
        Offset |= ((UINT64)CurrentEntry.OffsetHigh) << 32;
 
        // LogInfo("IDT Entry [%d] at: %llx", i, Offset);
 
        IdtEmulationCreateInterruptGate((PVOID)Offset, &VmxHostIdt[i]);
    }
    */
 
    //
    // Function related to handling host IDT are a modified version of the following project:
    //      https://github.com/jonomango/hv/blob/main/hv
    //
 
    //
    // Add customize interrupt handlers
    //
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler0, &VmxHostIdt[EXCEPTION_VECTOR_DIVIDE_ERROR]);
    // IdtEmulationCreateInterruptGate((PVOID)InterruptHandler1, &VmxHostIdt[EXCEPTION_VECTOR_DEBUG_BREAKPOINT]); // #DB
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler2, &VmxHostIdt[EXCEPTION_VECTOR_NMI]);
    // IdtEmulationCreateInterruptGate((PVOID)InterruptHandler3, &VmxHostIdt[EXCEPTION_VECTOR_BREAKPOINT]); // #BP
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler4, &VmxHostIdt[EXCEPTION_VECTOR_OVERFLOW]);
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler5, &VmxHostIdt[EXCEPTION_VECTOR_BOUND_RANGE_EXCEEDED]);
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler6, &VmxHostIdt[EXCEPTION_VECTOR_UNDEFINED_OPCODE]);
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler7, &VmxHostIdt[EXCEPTION_VECTOR_NO_MATH_COPROCESSOR]);
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler8, &VmxHostIdt[EXCEPTION_VECTOR_DOUBLE_FAULT]);
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler10, &VmxHostIdt[EXCEPTION_VECTOR_INVALID_TASK_SEGMENT_SELECTOR]);
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler11, &VmxHostIdt[EXCEPTION_VECTOR_SEGMENT_NOT_PRESENT]);
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler12, &VmxHostIdt[EXCEPTION_VECTOR_STACK_SEGMENT_FAULT]);
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler13, &VmxHostIdt[EXCEPTION_VECTOR_GENERAL_PROTECTION_FAULT]);
    // IdtEmulationCreateInterruptGate((PVOID)InterruptHandler14, &VmxHostIdt[EXCEPTION_VECTOR_PAGE_FAULT]); // #PF
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler16, &VmxHostIdt[EXCEPTION_VECTOR_MATH_FAULT]);
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler17, &VmxHostIdt[EXCEPTION_VECTOR_ALIGNMENT_CHECK]);
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler18, &VmxHostIdt[EXCEPTION_VECTOR_MACHINE_CHECK]);
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler19, &VmxHostIdt[EXCEPTION_VECTOR_SIMD_FLOATING_POINT_NUMERIC_ERROR]);
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler20, &VmxHostIdt[EXCEPTION_VECTOR_VIRTUAL_EXCEPTION]);
    IdtEmulationCreateInterruptGate((PVOID)InterruptHandler30, &VmxHostIdt[EXCEPTION_VECTOR_RESERVED11]);
}

IdtEmulationQueryIdtEntriesRequest()

VOID IdtEmulationQueryIdtEntriesRequest	(	PINTERRUPT_DESCRIPTOR_TABLE_ENTRIES_PACKETS	IdtQueryRequest,
		BOOLEAN	ReadFromVmxRoot )

Perform query for IDT entries.

Parameters

IdtQueryRequest
ReadFromVmxRoot

Returns

VOID

{
    SIDT_ENTRY   IdtrReg;
    KIDT_ENTRY * IdtEntries;
 
    //
    // Read IDTR register
    //
 
    if (!ReadFromVmxRoot)
    {
        //
        // Since it's not in VMX Root, we can directly read the IDTR register
        //
        CpuSidt(&IdtrReg);
 
        //
        // Get the IDT base address
        //
        IdtEntries = (KIDT_ENTRY *)IdtrReg.IdtBase;
    }
    else
    {
        //
        // Since it's in VMX Root, we need to read the IDTR register from the VMCS
        //
        IdtEntries = (KIDT_ENTRY *)GetGuestIdtr();
    }
 
    //
    // Gather a list of IDT entries
    //
    for (UINT32 i = 0; i < MAX_NUMBER_OF_IDT_ENTRIES; i++)
    {
        IdtQueryRequest->IdtEntry[i] = (UINT64)((UINT64)IdtEntries[i].HighestPart << 32) |
                                       ((UINT64)IdtEntries[i].HighPart << 16) |
                                       (UINT64)IdtEntries[i].LowPart;
    }
}