Normalize error behavior for wrong key when first op tries modifying schema

sjlombardo · sjlombardo · commit 010e65a7470f · 2026-05-15T15:57:02.000-04:00
In previous versions of SQLCipher, if an incorrect key was used and the first
operation was a schema change (e.g. CREATE TABLE x(y)) then the error returned
up to the application would be SQLITE_NOMEM instead of SQLITE_NOTADB. While
this didn't cause any problems or insecurity, the inconsistency of the error
codes was undesirable.

Instead of immediately returning NULL from sqlite3Codec when a deferred
error condition is detected, SQLCipher now returns a zeroed out buffer instead.
This basically mirrors the existing failure mode for decryption. The zeroed
buffer is detected as invalid upstream and results in a SQLITE_NOTADB error
just like what would happen if a SELECT was executed as the first operation
with an incorrect key.
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -2,6 +2,8 @@
 Notable changes to this project are documented in this file.
 
 ## [4.17.0] - (? 2026 - [4.17.0 changes])
+- Normalize error behavior for incorrect keys when first operation
+  attempts to modfiy the schema
 
 ## [4.16.0] - (May 2026 - [4.16.0 changes])
 - Update baseline to SQLite 3.53.1
diff --git a/src/sqlcipher.c b/src/sqlcipher.c
@@ -3245,6 +3245,12 @@ static void* sqlite3Codec(void *iCtx, void *data, Pgno pgno, int mode) {
   if(ctx->error != SQLITE_OK) {
     sqlcipher_log(SQLCIPHER_LOG_ERROR, SQLCIPHER_LOG_CORE, "%s: identified deferred error condition: %d", __func__, rc);
     sqlcipher_codec_ctx_set_error(ctx, ctx->error);
+    /* if this is a read, we don't want to return NULL as it will be interpreted as a SQLITE_NOMEM condition,
+     * so instead return a zeroed out buffer that will fail the magic header check */
+    if(mode == CODEC_READ_OP) { 
+      sqlcipher_memset(pData, 0, ctx->page_sz);
+      out = pData;
+    }
     goto cleanup;
   }
 
diff --git a/test/sqlcipher-compatibility.test b/test/sqlcipher-compatibility.test
@@ -1213,7 +1213,7 @@ do_test migrate-failure-not-readable {
     PRAGMA cipher_test_off = fail_migrate;
     PRAGMA cipher_test;
   }]
-} {{ok 1} {1 {out of memory}} 0}
+} {{ok 1} {1 {file is not a database}} 0}
 db close
 file delete -force test.db 
 
