Integrity Protection on Android

I would like to know more about the integrity protection of SQLCipher on Android. The “Design” page and the FAQ haven’t been very helpful. I would like to know:

  • What type of operations are protected. i.e. only the integrity of rows or also the whole table (insert, delete) or even the whole database file?
  • When is the integrity verified and is there a way to verify it manually?
  • What algorithms are used?
  • What keys are used for integrity protection? Is the key derived from the encryption key?

Thank you very much,
best regards,
Herbert Waltraud

Hello Herbert,

Thank you for your interest in SQLCipher. The integrity protection within SQLCipher for Android is the same found within SQLCipher core. SQLCipher reads and writes pages of data representing the B-tree of the database. As it writes a page, it includes a hash-based message authentication code of the ciphertext and the random IV for that page. This follows the encrypt-then-mac approach of authenticated encryption. A different key, though derived from the encryption key is used to calculate the per page HMAC. The HMAC is then checked when a page is read back from disk to verify tampering of the data has not been performed.

Every page in the database includes a HMAC when enabled which is the default in SQLCipher 3.

This is performed automatically for you as you read content from the database. You could manually force this by querying all content from the database.

HMAC_SHA1

The key used to calculate page HMACs is different that the encryption key. It is derived from the encryption key and using PBKDF2 with 2 iterations and a variation of the random database salt.

Thank you very much!

What happens when tampering is detected while I read a page?

In my current use case I need to detect whether the database has changed unexpectedly (=tampered with) and then display an error message an recreate the DB from scratch (The requirement is “Do not display anything before displaying wrong data”)

Hi @Markus_Palcer

If you were attempting to perform a standard SQL operation against the database when that occurs, you would receive an error due to the HMAC check failing. In your particular case, you may be interested in a new feature we recently added called pragma cipher_integrity_check which will manually walk through all pages within the database and verify the HMAC check is correct, among other validations. It will provide the error results for you to further evaluate/report.