SerialConnection.c File Reference

Serial port connection from debuggee to debugger. More...

#include "pch.h"

Functions
VOID	SerialConnectionTest ()
	A simple connection test.
VOID	SerialConnectionSendEndOfBuffer ()
	Send end of buffer packet.
BOOLEAN	SerialConnectionCheckForTheEndOfTheBuffer (PUINT32 CurrentLoopIndex, BYTE *Buffer)
	compares the buffer with a string
BOOLEAN	SerialConnectionRecvBuffer (CHAR *BufferToSave, UINT32 *LengthReceived)
	Receive packet from the debugger.
BOOLEAN	SerialConnectionSend (CHAR *Buffer, UINT32 Length)
	Perform sending buffer over serial.
BOOLEAN	SerialConnectionSendTwoBuffers (CHAR *Buffer1, UINT32 Length1, CHAR *Buffer2, UINT32 Length2)
	Perform sending 2 not appended buffers over serial.
BOOLEAN	SerialConnectionSendThreeBuffers (CHAR *Buffer1, UINT32 Length1, CHAR *Buffer2, UINT32 Length2, CHAR *Buffer3, UINT32 Length3)
	Perform sending 3 not appended buffers over serial.
BOOLEAN	SerialConnectionCheckBaudrate (DWORD Baudrate)
	Check if baud rate is valid or not.
BOOLEAN	SerialConnectionCheckPort (UINT32 SerialPort)
	Check if serial port address.
NTSTATUS	SerialConnectionPrepare (PDEBUGGER_PREPARE_DEBUGGEE DebuggeeRequest)
	Perform tasks relating to stepping (step-in & step-out) requests.

Detailed Description

Serial port connection from debuggee to debugger.

Author

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

Version

0.1

Date

2020-12-15

Copyright

This project is released under the GNU Public License v3.

Function Documentation

SerialConnectionCheckBaudrate()

BOOLEAN SerialConnectionCheckBaudrate

(

DWORD

Baudrate

)

Check if baud rate is valid or not.

Parameters

Baudrate

Returns

BOOLEAN return TRUE if it's correct and returns FALSE if it's not correct

{
    if (Baudrate == CBR_110 || Baudrate == CBR_300 || Baudrate == CBR_600 ||
        Baudrate == CBR_1200 || Baudrate == CBR_2400 || Baudrate == CBR_4800 ||
        Baudrate == CBR_9600 || Baudrate == CBR_14400 || Baudrate == CBR_19200 ||
        Baudrate == CBR_38400 || Baudrate == CBR_56000 || Baudrate == CBR_57600 ||
        Baudrate == CBR_115200 || Baudrate == CBR_128000 ||
        Baudrate == CBR_256000)
    {
        return TRUE;
    }
    return FALSE;
}

SerialConnectionCheckForTheEndOfTheBuffer()

BOOLEAN SerialConnectionCheckForTheEndOfTheBuffer	(	PUINT32	CurrentLoopIndex,
		BYTE *	Buffer )

compares the buffer with a string

Parameters

CurrentLoopIndex	Number of previously read bytes
Buffer

Returns

BOOLEAN

{
    UINT32 ActualBufferLength;
 
    ActualBufferLength = *CurrentLoopIndex;
 
    //
    // End of buffer is 4 character long
    //
    if (*CurrentLoopIndex <= 3)
    {
        return FALSE;
    }
 
    if (Buffer[ActualBufferLength] == SERIAL_END_OF_BUFFER_CHAR_4 &&
        Buffer[ActualBufferLength - 1] == SERIAL_END_OF_BUFFER_CHAR_3 &&
        Buffer[ActualBufferLength - 2] == SERIAL_END_OF_BUFFER_CHAR_2 &&
        Buffer[ActualBufferLength - 3] == SERIAL_END_OF_BUFFER_CHAR_1)
    {
        //
        // Clear the end character
        //
        Buffer[ActualBufferLength - 3] = NULL_ZERO;
        Buffer[ActualBufferLength - 2] = NULL_ZERO;
        Buffer[ActualBufferLength - 1] = NULL_ZERO;
        Buffer[ActualBufferLength]     = NULL_ZERO;
 
        //
        // Set the new length
        //
        *CurrentLoopIndex = ActualBufferLength - 3;
 
        return TRUE;
    }
    return FALSE;
}

SerialConnectionCheckPort()

BOOLEAN SerialConnectionCheckPort

(

UINT32

SerialPort

)

Check if serial port address.

Parameters

SerialPort

Returns

BOOLEAN return TRUE if it's correct and returns FALSE if it's not correct

{
    if (SerialPort == COM1_PORT || SerialPort == COM2_PORT || SerialPort == COM3_PORT ||
        SerialPort == COM4_PORT)
    {
        return TRUE;
    }
    return FALSE;
}

SerialConnectionPrepare()

NTSTATUS SerialConnectionPrepare

(

PDEBUGGER_PREPARE_DEBUGGEE

DebuggeeRequest

)

Perform tasks relating to stepping (step-in & step-out) requests.

Parameters

DebuggerPrintRequest

Request to prepare debuggee

Returns

NTSTATUS

{
    //
    // Check if baud rate is valid or not
    //
    if (!SerialConnectionCheckBaudrate(DebuggeeRequest->Baudrate))
    {
        //
        // Baud rate is invalid, set the status and return
        //
        DebuggeeRequest->Result = DEBUGGER_ERROR_PREPARING_DEBUGGEE_INVALID_BAUDRATE;
        return STATUS_UNSUCCESSFUL;
    }
 
    //
    // Check if port address is valid or not
    //
    if (!SerialConnectionCheckPort(DebuggeeRequest->PortAddress))
    {
        //
        // Port address is invalid, set the status and return
        //
        DebuggeeRequest->Result = DEBUGGER_ERROR_PREPARING_DEBUGGEE_INVALID_SERIAL_PORT;
        return STATUS_UNSUCCESSFUL;
    }
 
    //
    // Prepare the structures needed for connecting remote port
    //
    KdHyperDbgPrepareDebuggeeConnectionPort(DebuggeeRequest->PortAddress, DebuggeeRequest->Baudrate);
 
    //
    // Initialize kernel debugger
    //
    KdInitializeKernelDebugger();
 
    //
    // Send "Start" packet along with Windows Name
    //
    KdResponsePacketToDebugger(DEBUGGER_REMOTE_PACKET_TYPE_DEBUGGEE_TO_DEBUGGER,
                               DEBUGGER_REMOTE_PACKET_REQUESTED_ACTION_DEBUGGEE_STARTED,
                               (CHAR *)DebuggeeRequest,
                               MAXIMUM_CHARACTER_FOR_OS_NAME);
 
    //
    // Set status to successful
    //
    DebuggeeRequest->Result = DEBUGGER_OPERATION_WAS_SUCCESSFUL;
 
    return STATUS_SUCCESS;
}

SerialConnectionRecvBuffer()

BOOLEAN SerialConnectionRecvBuffer	(	CHAR *	BufferToSave,
		UINT32 *	LengthReceived )

Receive packet from the debugger.

Parameters

BufferToSave
LengthReceived

Returns

BOOLEAN

{
    UINT32 Loop = 0;
 
    //
    // Read data and store in a buffer
    //
    while (TRUE)
    {
        UCHAR RecvChar = NULL_ZERO;
 
        if (!KdHyperDbgRecvByte(&RecvChar))
        {
            continue;
        }
 
        //
        // We already now that the maximum packet size is MaxSerialPacketSize
        // Check to make sure that we don't pass the boundaries
        //
        if (!(MaxSerialPacketSize > Loop))
        {
            //
            // Invalid buffer (size of buffer exceeds the limitation)
            //
            LogError("Err, a buffer received in debuggee which exceeds the buffer limitation");
            return FALSE;
        }
 
        BufferToSave[Loop] = RecvChar;
 
        if (SerialConnectionCheckForTheEndOfTheBuffer(&Loop, (BYTE *)BufferToSave))
        {
            break;
        }
 
        Loop++;
    }
 
    //
    // Set the length
    //
    *LengthReceived = Loop;
 
    return TRUE;
}

SerialConnectionSend()

BOOLEAN SerialConnectionSend	(	CHAR *	Buffer,
		UINT32	Length )

Perform sending buffer over serial.

Parameters

Buffer	buffer to send
Length	length of buffer to send

Returns

BOOLEAN

{
    //
    // Check if buffer not pass the boundary
    //
    if (Length + SERIAL_END_OF_BUFFER_CHARS_COUNT > MaxSerialPacketSize)
    {
        LogError("Err, buffer is above the maximum buffer size that can be sent to debuggee (%d > %d), "
                 "for more information, please visit https://docs.hyperdbg.org/tips-and-tricks/misc/increase-communication-buffer-size",
                 Length + SERIAL_END_OF_BUFFER_CHARS_COUNT,
                 MaxSerialPacketSize);
        return FALSE;
    }
 
    for (size_t i = 0; i < Length; i++)
    {
        KdHyperDbgSendByte(Buffer[i], TRUE);
    }
 
    //
    // Send the end buffer
    //
    SerialConnectionSendEndOfBuffer();
 
    return TRUE;
}

SerialConnectionSendEndOfBuffer()

VOID SerialConnectionSendEndOfBuffer

(

)

Send end of buffer packet.

Returns

VOID

{
    //
    // Send the end buffer
    //
    KdHyperDbgSendByte(SERIAL_END_OF_BUFFER_CHAR_1, TRUE);
    KdHyperDbgSendByte(SERIAL_END_OF_BUFFER_CHAR_2, TRUE);
    KdHyperDbgSendByte(SERIAL_END_OF_BUFFER_CHAR_3, TRUE);
    KdHyperDbgSendByte(SERIAL_END_OF_BUFFER_CHAR_4, TRUE);
}

SerialConnectionSendThreeBuffers()

BOOLEAN SerialConnectionSendThreeBuffers	(	CHAR *	Buffer1,
		UINT32	Length1,
		CHAR *	Buffer2,
		UINT32	Length2,
		CHAR *	Buffer3,
		UINT32	Length3 )

Perform sending 3 not appended buffers over serial.

Parameters

Buffer1	buffer to send
Length1	length of buffer to send
Buffer2	buffer to send
Length2	length of buffer to send
Buffer3	buffer to send
Length3	length of buffer to send

Returns

BOOLEAN

{
    //
    // Check if buffer not pass the boundary
    //
    if ((Length1 + Length2 + Length3 + SERIAL_END_OF_BUFFER_CHARS_COUNT) > MaxSerialPacketSize)
    {
        LogError("Err, buffer is above the maximum buffer size that can be sent to debuggee (%d > %d), "
                 "for more information, please visit https://docs.hyperdbg.org/tips-and-tricks/misc/increase-communication-buffer-size",
                 Length1 + Length2 + Length3 + SERIAL_END_OF_BUFFER_CHARS_COUNT,
                 MaxSerialPacketSize);
        return FALSE;
    }
 
    //
    // Send first buffer
    //
    for (size_t i = 0; i < Length1; i++)
    {
        KdHyperDbgSendByte(Buffer1[i], TRUE);
    }
 
    //
    // Send second buffer
    //
    for (size_t i = 0; i < Length2; i++)
    {
        KdHyperDbgSendByte(Buffer2[i], TRUE);
    }
 
    //
    // Send third buffer
    //
    for (size_t i = 0; i < Length3; i++)
    {
        KdHyperDbgSendByte(Buffer3[i], TRUE);
    }
 
    //
    // Send the end buffer
    //
    SerialConnectionSendEndOfBuffer();
 
    return TRUE;
}

SerialConnectionSendTwoBuffers()

BOOLEAN SerialConnectionSendTwoBuffers	(	CHAR *	Buffer1,
		UINT32	Length1,
		CHAR *	Buffer2,
		UINT32	Length2 )

Perform sending 2 not appended buffers over serial.

Parameters

Buffer1	buffer to send
Length1	length of buffer to send
Buffer2	buffer to send
Length2	length of buffer to send

Returns

BOOLEAN

{
    //
    // Check if buffer not pass the boundary
    //
    if ((Length1 + Length2 + SERIAL_END_OF_BUFFER_CHARS_COUNT) > MaxSerialPacketSize)
    {
        LogError("Err, buffer is above the maximum buffer size that can be sent to debuggee (%d > %d), "
                 "for more information, please visit https://docs.hyperdbg.org/tips-and-tricks/misc/increase-communication-buffer-size",
                 Length1 + Length2 + SERIAL_END_OF_BUFFER_CHARS_COUNT,
                 MaxSerialPacketSize);
        return FALSE;
    }
 
    //
    // Send first buffer
    //
    for (size_t i = 0; i < Length1; i++)
    {
        KdHyperDbgSendByte(Buffer1[i], TRUE);
    }
 
    //
    // Send second buffer
    //
    for (size_t i = 0; i < Length2; i++)
    {
        KdHyperDbgSendByte(Buffer2[i], TRUE);
    }
 
    //
    // Send the end buffer
    //
    SerialConnectionSendEndOfBuffer();
 
    return TRUE;
}

SerialConnectionTest()

VOID SerialConnectionTest

(

)

A simple connection test.

Returns

VOID

{
    for (size_t i = 0; i < 100; i++)
    {
        KdHyperDbgTest((UINT16)i);
    }
}