v2.6.1 Android AAR: external NDK C API and encrypted backup portability

[esk-joule]

Does the project support linking an app's own NDK shared library directly to libsqliteX from the published sqlite3mc-2.6.1-sqlite-3.54.0-android.aar, without rebuilding the engine? The app would own the connection and statements on that same engine. If only the Android bindings are supported, a simple confirmation would help.

1. If direct use is supported, which header from this release matches the AAR, which Android ABIs and minimum API level are supported, and is there a documented NDK/CMake link and packaging example that avoids loading a second SQLite engine?
2. Does that interface expose sqlite3_open_v2, sqlite3_key or sqlite3_key_v2, sqlite3_prepare_v2, sqlite3_bind_{blob,int64,null,text}, sqlite3_step, sqlite3_column_{count,type,int64,text,bytes}, sqlite3_changes, sqlite3_finalize, sqlite3_next_stmt, sqlite3_get_autocommit, sqlite3_errcode, sqlite3_extended_errcode, sqlite3_errmsg and sqlite3_close? Are there any ABI-specific exceptions?
3. The v2.6.1 release notes describe a ChaCha20 counter-overflow issue and recommend disabling hardware acceleration for new writes. For a new encrypted database, when and on which connections should that setting be applied with this AAR? For a consistent backup restored on a different Android device/ABI, what cipher, keying, and other settings must match, and which cross-device cases have you verified? If a file may already contain pages written with acceleration enabled, what supported check or recovery procedure is needed before relying on the restored data?

A link to version-specific documentation or a sample would be very helpful. Thank you.

[utelle]

Thanks for the detailed questions. I should be upfront: I’m not an Android/NDK developer. The AAR is built with the Android build process provided by SQLite itself and is intended to be used through its Java/Kotlin bindings. Linking an app’s own NDK library directly against the shared library in the AAR is not something I have tested or documented, so I can’t give a supported answer to questions 1 and 2 (matching header, ABIs, minimum API level, CMake/packaging example, exported C API functions, ABI-specific exceptions). The .so files in the AAR and their exported symbols (e.g. via nm -D) would show what is actually available, but I can’t promise that this is a supported use case. If you investigate this, I’d be glad to hear your findings, and a documentation contribution would be welcome.

Question 3:

• The ChaCha20 counter-overflow issue affects only the chacha20 cipher scheme. All other cipher schemes are not affected. So, you may use a different cipher scheme (like ascon128, aegis, or sqlcipher) until the next version is released.
• Version 2.7.0, which will be released soon, fixes the issue.
• Workaround for 2.6.1: The hardware acceleration setting applies per database connection. It is not stored in the database file. After opening a connection, execute PRAGMA mc_chacha20_hwaccel=off;. This should be done on every connection that may write to the database, including new ones, before any data is written.
• The probability of a damaged page is low and refers to a single page write. With the default page size of 4 KB it is about 1 in 46 million. With larger page sizes (up to 64 KB) it rises to about 1 in 6 million. Since every page write carries this risk, the overall exposure grows with the number of pages written, i.e. with database size and write activity.
• A small tool is expected to be provided that allows you to check whether a given database file is affected at all. I can’t give a date yet. Until then, I can’t offer a verified check or recovery procedure for files that may already contain affected pages.
• For backup portability, the restoring side must use the same cipher scheme and the same key and key-derivation settings (passphrase handling, KDF iterations, page size, and any legacy/compatibility parameters). The hardware acceleration setting itself does not affect the file format, so it does not need to match between devices. I have not specifically verified cross-device or cross-ABI restores on Android, so I can’t list verified cases.