core.h

#pragma once

/*
 * core.h — Global declarations and lifecycle contracts for the driver core.
 *
 * Core-owned globals
 * ------------------
 * g_DriverObject
 *   - Set exactly once in DriverEntry before any subsystem initialization.
 *   - Borrowed pointer owned by the I/O manager; never released by this driver.
 *   - Remains available for helpers that need driver identity/path metadata.
 *
 * g_FilterHandle
 *   - Becomes owned by core.c after FltRegisterFilter succeeds.
 *   - Mandatory resource: if registration, comm init, auth init, or
 *     FltStartFiltering fails, DriverEntry must release it before returning.
 *   - Released exactly once via FltUnregisterFilter on rollback/unload.
 *
 * g_Initialized
 *   - Process-wide readiness flag for "full startup reached".
 *   - 0 means either startup failed before the optional phase completed or
 *     unload has started/finished.
 *   - 1 means the mandatory path succeeded, filtering is active, and the
 *     optional/best-effort subsystem startup sequence has run to completion.
 *   - This flag does not own resources; it only publishes lifecycle phase.
 *
 * Startup phases
 * --------------
 * Phase 0: pre-entry state; all globals are NULL/0.
 * Phase 1: filter registration succeeds; g_FilterHandle is core-owned.
 * Phase 2: comm + auth succeed; filter is registered but not yet dispatching.
 * Phase 3: FltStartFiltering succeeds; callback routing is live.
 * Phase 4: optional subsystems (fs/mem/proc/reg/stealth) are attempted in
 *          sequence; failures are logged but do not fail DriverEntry.
 * Phase 5: g_Initialized flips to 1 after the optional phase finishes.
 * Teardown: unload publishes teardown first, then releases only the
 *           resources/subsystems whose init gates actually succeeded.
 *
 * Mandatory vs optional subsystems
 * --------------------------------
 * Mandatory for DriverEntry success:
 *   - Filter registration / g_FilterHandle ownership
 *   - CommInitialize / CommUninitialize
 *   - AuthModuleInitialize / AuthModuleUninitialize
 *   - FltStartFiltering
 *
 * Optional / best-effort after filtering starts:
 *   - FsModuleInitialize / FsModuleUninitialize
 *   - MemModuleInitialize / MemModuleUninitialize
 *   - ProcModuleInitialize / ProcModuleUninitialize
 *   - RegModuleInitialize / RegModuleUninitialize
 *   - StealthInitialize / StealthUninitialize
 *
 * Cleanup contract
 * ----------------
 * DriverEntry rollback cleans up only resources acquired in the current
 * mandatory phase prefix, using the same explicit state gates that tracked
 * successful initialization.
 *
 * CoreFilterUnload is the steady-state/full-unload path after a successful
 * DriverEntry return. It clears g_Initialized first, publishes teardown, then
 * releases exactly the subsystems/resources whose init gates ran. This keeps
 * teardown safe from intermediate init states while preserving the existing
 * callback-ordering contract once filtering is live.
 */

#include <fltKernel.h>

extern PFLT_FILTER     g_FilterHandle;
extern PDRIVER_OBJECT  g_DriverObject;
extern volatile LONG   g_Initialized;

NTSTATUS CommInitialize(_In_ PFLT_FILTER Filter);
VOID     CommUninitialize(VOID);
NTSTATUS CommCheckHandshake(
    _Inout_ PFLT_CALLBACK_DATA Data,
    _Out_   BOOLEAN *IsHandshake
);
/*
 * Cross-slice create-routing contract:
 * - core.c must call CommCheckHandshake() before any fs.c create-policy logic.
 * - A TRUE IsHandshake result means comm.c fully classified the create as the
 *   rendezvous path and core.c must complete the I/O with the returned status
 *   instead of falling through into fs.c policy.
 * - A FALSE IsHandshake result means the create is not the comm rendezvous and
 *   may continue through the normal file-policy path.
 */
NTSTATUS CommPostEvent(
    _In_ ULONG EventType,
    _In_ ULONG ProcessId,
    _In_opt_ PVOID Data,
    _In_ ULONG DataLength
);
BOOLEAN  CommIsAgentProcessId(_In_ ULONG ProcessId);

NTSTATUS MemModuleInitialize(VOID);
VOID     MemModuleUninitialize(VOID);
NTSTATUS MemHandleCommand(_Inout_ PRING_MESSAGE Msg);

NTSTATUS FsModuleInitialize(VOID);
VOID     FsModuleUninitialize(VOID);
/*
 * File-policy contract:
 * - These hooks never classify the comm rendezvous path; core.c resolves that
 *   boundary first through CommCheckHandshake().
 * - Confirm-mode enforcement is fail-safe: timeout, teardown wakeup, missing
 *   transport, or explicit deny all resolve to Block = TRUE for matched
 *   confirm paths.
 * - The system process and the authenticated agent identity are exempt through
 *   CommIsAgentProcessId() so policy bypass depends on the published comm
 *   session contract rather than each slice re-deriving PID semantics.
 */
NTSTATUS FsPreCreate(_Inout_ PFLT_CALLBACK_DATA Data, _Out_ BOOLEAN *Block);
NTSTATUS FsPreWrite(_Inout_ PFLT_CALLBACK_DATA Data, _Out_ BOOLEAN *Block);
NTSTATUS FsPreSetInfo(_Inout_ PFLT_CALLBACK_DATA Data, _Out_ BOOLEAN *Block);
NTSTATUS FsPostDirControl(
    _Inout_ PFLT_CALLBACK_DATA Data,
    _In_    FLT_POST_OPERATION_FLAGS Flags
);
NTSTATUS FsHandleCommand(_Inout_ PRING_MESSAGE Msg);
NTSTATUS FsHandleConfirmCommand(_Inout_ PRING_MESSAGE Msg, ULONG Cmd);
NTSTATUS FsCompleteConfirm(_In_ ULONG RequestId, _In_ BOOLEAN Approve);
ULONG    CommGetAgentPid(VOID);
const UCHAR *CommGetSessionKey(VOID);

NTSTATUS ProcModuleInitialize(VOID);
VOID     ProcModuleUninitialize(VOID);
NTSTATUS ProcHandleCommand(_Inout_ PRING_MESSAGE Msg);
NTSTATUS ProcAddProtectedPid(_In_ ULONG Pid);
NTSTATUS ProcRemoveProtectedPid(_In_ ULONG Pid);

NTSTATUS RegModuleInitialize(VOID);
VOID     RegModuleUninitialize(VOID);
/*
 * Registry confirm contract mirrors fs.c:
 * - the authenticated agent identity is exempt via CommIsAgentProcessId()
 * - confirm decisions are fail-safe: timeout, teardown wakeup, transport
 *   failure, or explicit deny resolve to access denied for matched paths
 */
NTSTATUS RegHandleConfirmCommand(_Inout_ PRING_MESSAGE Msg, ULONG Cmd);

NTSTATUS StealthInitialize(_In_ PDRIVER_OBJECT DriverObject);
VOID     StealthUninitialize(VOID);

NTSTATUS HwidHandleCommand(_Inout_ PRING_MESSAGE Msg);

NTSTATUS AuthModuleInitialize(VOID);
VOID     AuthModuleUninitialize(VOID);