LeechCore_API

The LeechCore native C/C++ API

All functionality in the LeechCore library is exported in a C/C++ API for use by developers. The header file is named: leechcore.h which use leechcore.dll / leechcore.lib on Windows and leechcore.so on Linux.

NB! Currently 64-bit Linux and 32-bit and 64-bit versions of Windows are supported. The Windows version have somewhat better performance than Linux for select memory acquisition methods - such as FPGA DMA due to better driver support.

This wiki entry contains an overview of the LeechCore API. The complete documentation is found in leechcore.h If developing a plugin device for LeechCore please also see leechcore_device.h (not documented in this guide, but please see LeechCore-plugins repository for examples).

Example:

Examples how to use LeechCore may be found in the sources for PCILeech and MemProcFS which makes use of the LeechCore library.

Initialize / Close:

After leechcore.dll is loaded it has to be initialized by calling the LeechCore_Create function. When it no longer is in use LeechCore_Close should be called on all open handles before unloading the .dll.

The LeechCore_Create takes a pointer to a LC_CONFIG struct which contains initial configuration information - such as, but not limited to, the desired device type (in the .szDevice property) and possible remote connection configuration (in the .szRemote property). The LeechCore library, will upon success, update this struct with more values that are returned on success. NB! The caller must also fill in the required magic and struct version before making the call to LeechCore_Create. For a complete documentation of the LC_CONFIG struct please check out the definition in the leechcore.h header file

Upon initialization LeechCore tries to auto-identify the maximum physical memory address if it is previously unknown. To disable auto-identify please set the paMax member of the LC_CONFIG struct to a valid value.

HANDLE LcCreate(
    _Inout_ PLC_CONFIG pLcCreateConfig
);

VOID LcClose(
    _In_opt_ _Post_ptr_invalid_ HANDLE hLC
);

VOID LcMemFree(
    _Frees_ptr_opt_ PVOID pv
);

Read / Write:

The functionality below allows a the calling function to read and possibly write physical memory by using an initialized LeechCore library. The LcAllocScatter* functions are utility functions meant to ease the allocation of MEM_SCATTER used in LcReadScatter and LcWriteScatter. The preferred read function is LcReadScatter due to being more efficient than LcRead if multiple non-contiguous memory pages are to be read.

BOOL LcAllocScatter1(
    _In_ DWORD cMEMs,
    _Out_ PPMEM_SCATTER *pppMEMs
);

BOOL LcAllocScatter2(
    _In_ DWORD cbData,
    _Inout_updates_opt_(cbData) PBYTE pbData,
    _In_ DWORD cMEMs,
    _Out_ PPMEM_SCATTER *pppMEMs
);

BOOL LcAllocScatter3(
    _Inout_updates_opt_(0x1000) PBYTE pbDataFirstPage,
    _Inout_updates_opt_(0x1000) PBYTE pbDataLastPage,
    _In_ DWORD cbData,
    _Inout_updates_opt_(cbData) PBYTE pbData,
    _In_ DWORD cMEMs,
    _Out_ PPMEM_SCATTER *pppMEMs
);

BOOL LcRead(
    _In_ HANDLE hLC,
    _In_ QWORD pa,
    _In_ DWORD cb,
    _Out_writes_(cb) PBYTE pb
);

VOID LcReadScatter(
    _In_ HANDLE hLC,
    _In_ DWORD cMEMs,
    _Inout_ PPMEM_SCATTER ppMEMs
);

BOOL LcWrite(
    _In_ HANDLE hLC,
    _In_ QWORD pa,
    _In_ DWORD cb,
    _In_reads_(cb) PBYTE pb
);

VOID LcWriteScatter(
    _In_ HANDLE hLC,
    _In_ DWORD cMEMs,
    _Inout_ PPMEM_SCATTER ppMEMs
);

Get / Set Options:

Sometimes it's necessary to query the underlying devices for device specific configuration settings - or even set configurations settings. This is possible to do with the functions below. Numeric options are most often queried and set via the LcGetOption and LcSetOption functions. More complex actions are undertaken via the LcCommand function.

Options related to LcGetOption and LcSetOption are found in defines LC_OPT_* in the leechcore.h header. Options related to LcCommand are found in defines LC_CMD_* in the leechcore.h header.

BOOL LcGetOption(
    _In_ HANDLE hLC,
    _In_ QWORD fOption,
    _Out_ PQWORD pqwValue
);

BOOL LcSetOption(
    _In_ HANDLE hLC,
    _In_ QWORD fOption,
    _In_ QWORD qwValue
);

BOOL LcCommand(
    _In_ HANDLE hLC,
    _In_ QWORD fOption,
    _In_ DWORD cbDataIn,
    _In_reads_opt_(cbDataIn) PBYTE pbDataIn,
    _Out_opt_ PBYTE *ppbDataOut,
    _Out_opt_ PDWORD pcbDataOut
);