Premature Destructor Execution in SQLite create_module_v2 Leading to Use-After-Free Vulnerabilities

Understanding the Lifecycle Mismatch Between Module Destructors and xDisconnect in SQLite Virtual Tables

Issue Overview: Destructor Invocation Precedes xDisconnect in create_module_v2 Workflow

The core issue revolves around the timing of the destructor function registered via SQLite’s sqlite3_create_module_v2 API. This destructor is designed to release resources associated with the client data pointer provided during virtual table module registration. However, under specific conditions, SQLite’s internal cleanup sequence triggers the destructor before invoking the xDisconnect method of the associated sqlite3_module structure. This premature destruction creates a critical vulnerability when the module structure itself is dynamically allocated and its memory is freed within the destructor.

When a virtual table is disconnected (a routine process during database closure or schema changes), SQLite’s internal function sqlite3VtabUnlock initiates two operations:

1. It decrements the reference count of the module via sqlite3VtabModuleUnref, which triggers the registered destructor if the reference count reaches zero.
2. It subsequently calls the xDisconnect method of the sqlite3_module structure to finalize the virtual table instance.

If the module structure is dynamically allocated and the destructor frees its memory, the xDisconnect call dereferences a dangling pointer to the now-freed sqlite3_module structure. This results in undefined behavior, typically manifesting as segmentation faults, heap corruption, or silent data inconsistencies.

The problem is exacerbated in environments where dynamic allocation of the sqlite3_module structure is necessary, such as when supporting multiple module configurations, eponymous-only virtual tables, or version-specific behavior (e.g., differing iVersion values). The SQLite documentation historically recommended using statically allocated modules, but modern use cases increasingly require dynamic lifetime management, exposing this lifecycle mismatch.

Root Causes: Reference Counting Logic and Documentation Assumptions

The premature destructor invocation stems from two interrelated factors:

1. Incorrect Order of Operations in SQLite’s Internal Cleanup Routines
   The sqlite3VtabUnlock function first unreferences the module (potentially triggering destruction) and then calls xDisconnect. This sequence assumes that the sqlite3_module structure remains valid throughout the xDisconnect call, which is only true if the module is statically allocated or intentionally leaked. When the module is dynamically allocated and its lifetime is tied to the destructor, this assumption fails catastrophically.

2. Ambiguity in Documentation Regarding Module Lifetime Management
   SQLite’s documentation for sqlite3_create_module_v2 states that the destructor is for "client data" associated with the module, not the module structure itself. A separate section notes that the sqlite3_module pointer should be "persistent and unmodified," implying static allocation. However, this guidance conflicts with legitimate use cases requiring dynamic module allocation, such as:

   • Modules that alter their behavior based on runtime configuration (e.g., different xCreate or xConnect methods).
   • Libraries that generate modules programmatically to avoid global state.
   • Multi-threaded environments where static modules could lead to race conditions.

3. Legacy Design Choices Prioritizing Static Allocation
   The original sqlite3_create_module API (without a destructor) implicitly required static modules, as there was no mechanism to notify the caller when the module was no longer needed. The create_module_v2 extension added destructor support but retained the original cleanup sequence, prioritizing backward compatibility over dynamic allocation scenarios.

Resolution Strategies: Code Modifications, Workarounds, and Version Upgrades

Immediate Workaround: Leak the Module Structure

If upgrading to a fixed SQLite version is not immediately feasible, the simplest workaround is to treat the sqlite3_module structure as a singleton that is never freed. This avoids the use-after-free by ensuring the module remains valid throughout its lifetime, including during xDisconnect:

static sqlite3_module* g_module = NULL;

void register_module(sqlite3* db) {
    if (!g_module) {
        g_module = (sqlite3_module*)sqlite3_malloc(sizeof(sqlite3_module));
        // Initialize g_module fields...
    }
    sqlite3_create_module_v2(db, "my_module", g_module, NULL, /*xDestroy=*/sqlite3_free);
}

This approach permanently leaks the module structure. While technically a memory leak, the overhead is negligible for most applications, as a single module instance is typically small (around 100 bytes) and persists for the database connection’s duration.

Upgrade to SQLite Version 3.42.0 or Later

The SQLite trunk (as of 2023-01-25) corrected the cleanup sequence to invoke xDisconnect before unreferencing the module. This ensures the destructor runs only after all module methods, including xDisconnect, have completed. Upgrade steps:

1. Download the latest SQLite amalgamation from sqlite.org/download.html.
2. Replace existing SQLite headers and source files with the updated versions.
3. Recompile the application, ensuring all database handles are reinitialized.

Post-upgrade, dynamically allocated modules can safely free their memory in the destructor:

void module_destructor(void* ptr) {
    sqlite3_module* module = (sqlite3_module*)ptr;
    // Clean up module-specific resources...
    sqlite3_free(module);
}

void register_module(sqlite3* db) {
    sqlite3_module* module = (sqlite3_module*)sqlite3_malloc(sizeof(sqlite3_module));
    // Initialize module fields...
    sqlite3_create_module_v2(db, "my_module", module, NULL, module_destructor);
}

Refactor Module Initialization to Use Static Structures

If dynamic allocation is avoidable, revert to static sqlite3_module instances. This eliminates lifetime management complexity entirely:

static const sqlite3_module my_module = {
    .iVersion = 1,
    .xCreate = my_xCreate,
    .xConnect = my_xConnect,
    // ... other method initializers
};

void register_module(sqlite3* db) {
    sqlite3_create_module_v2(db, "my_module", &my_module, NULL, NULL);
}

Hybrid Approach: Module Pools for Dynamic Configurations

For scenarios requiring multiple module instances with varying configurations (e.g., different iVersion values), maintain a global pool of modules indexed by their configuration parameters. The pool persists for the application’s lifetime, and modules are reused across database connections:

#include <uthash.h>

typedef struct {
    int iVersion;
    sqlite3_module* module;
    UT_hash_handle hh;
} ModulePoolEntry;

static ModulePoolEntry* module_pool = NULL;

sqlite3_module* get_module(int iVersion) {
    ModulePoolEntry* entry = NULL;
    HASH_FIND_INT(module_pool, &iVersion, entry);
    if (!entry) {
        entry = (ModulePoolEntry*)sqlite3_malloc(sizeof(ModulePoolEntry));
        entry->iVersion = iVersion;
        entry->module = (sqlite3_module*)sqlite3_malloc(sizeof(sqlite3_module));
        // Initialize module based on iVersion...
        HASH_ADD_INT(module_pool, iVersion, entry);
    }
    return entry->module;
}

void cleanup_module_pool() {
    ModulePoolEntry *entry, *tmp;
    HASH_ITER(hh, module_pool, entry, tmp) {
        HASH_DEL(module_pool, entry);
        sqlite3_free(entry->module);
        sqlite3_free(entry);
    }
}

void register_module(sqlite3* db, int iVersion) {
    sqlite3_module* module = get_module(iVersion);
    sqlite3_create_module_v2(db, "my_module", module, NULL, NULL);
}

Diagnostic Measures: Detecting Use-After-Free

To identify instances where the module structure is accessed after destruction:

1. Enable SQLite’s Internal Diagnostics
   Compile SQLite with -DSQLITE_DEBUG and set sqlite3_config(SQLITE_CONFIG_LOG, ...) to log module reference count changes.

2. Use Address Sanitizers (ASan)
   Recompile the application and SQLite with -fsanitize=address to detect memory corruption:

   CFLAGS="-fsanitize=address -g" ./configure
   make
   

3. Valgrind Analysis
   Run the application under Valgrind to trace invalid memory accesses:

   valgrind --tool=memcheck --leak-check=full ./my_application
   

Long-Term Code Hygiene: Module Lifetime Assertions

Embed runtime assertions to validate module integrity during xDisconnect:

static void my_xDisconnect(sqlite3_vtab* vtab) {
    // Cast vtab->pModule to your module type
    MyModule* my_module = (MyModule*)vtab->pModule;
    assert(my_module->magic == MY_MODULE_MAGIC); // Validate module integrity
    // Proceed with disconnection...
}

Define a magic number in your module structure and initialize it during creation. This helps catch invalid modules early, though it does not prevent all forms of memory corruption.

By systematically addressing the module lifecycle mismatch through version upgrades, static allocation, or controlled dynamic management, developers can mitigate use-after-free risks while retaining flexibility in virtual table implementations.