Link Search Menu Expand Document

SQLCipher: AES 256 Bit

SQLCipher was developed by Zetetic LLC and initially released in 2008. It is a 256 bit AES encryption in CBC mode.

The encryption key is derived from the passphrase using a random salt (stored in the first 16 bytes of the database file) and the standardized PBKDF2 algorithm with an SHA1, SHA256, or SHA512 hash function.

A random 16 bytes initial vector (nonce) for the encryption of each database page is used for the AES algorithm. Additionally, an authentication tag per database page is calculated:

  • SQLCipher version 1 used no tag (0 bytes).
  • SQLCipher version 2 to 3 used a SHA1 tag (20 bytes).
  • SQLCipher version 4 uses a SHA512 tag (64 bytes), allowing to optionally choose a SHA256 tag (32 bytes) instead.

Therefore this cipher requires 16, 48 or 80 reserved bytes per database page (since the number of reserved bytes is rounded to the next multiple of the AES block size of 16 bytes).

The following table lists all parameters related to this cipher that can be set before activating database encryption.

ParameterDefaultMinMaxDescription
kdf_iter2560001 Number of iterations for key derivation
fast_kdf_iter21 Number of iterations for HMAC key derivation
hmac_use101Flag whether a HMAC should be used
hmac_pgno102Storage type for page number in HMAC:
0 = native, 1 = little endian, 2 = big endian
hmac_salt_mask0x3a0255Mask byte for HMAC salt
legacy004SQLCipher version to be used in legacy mode
legacy_page_size4096065536Page size to use in legacy mode, 0 = default SQLite page size
kdf_algorithm202Hash algoritm for key derivation function
0 = SHA1, 1 = SHA256, 2 = SHA512
hmac_algorithm202Hash algoritm for HMAC calculation
0 = SHA1, 1 = SHA256, 2 = SHA512
plaintext_header_size00100Size of plaintext database header
must be multiple of 16, i.e. 32

The following table shows the parameter settings for the various legacy versions of SQLCipher. The columns labelled v4, v3, v2, and v1 correspond to legacy SQLCipher versions 4, 3, 2, and 1 respectively. To access databases encrypted with a certain SQLCipher version the listed parameters have to be set explicitly. However, the default legacy mode for the various SQLCipher versions can be easily set using just the parameter legacy set to the requested version number. That is, all other parameters have to be specified only, if their requested value deviates from the default value of the respective SQLCipher version.

Parameterv4v3v2v1
kdf_iter2560006400040004000
fast_kdf_iter2222
hmac_use1110
hmac_pgno111n/a
hmac_salt_mask0x3a0x3a0x3an/a
legacy4321
legacy_page_size4096102410241024
kdf_algorithm2000
hmac_algorithm2000
plaintext_header_size0n/an/an/a

Notes

  • It is not recommended to use legacy mode for encrypting new databases. It is supported for compatibility reasons only, so that databases that were encrypted in legacy mode can be accessed.
  • Version 4 of SQLCipher introduced a new parameter plain_text_header_size to overcome an issue with shared encrypted databases under iOS. If this parameter is set to a non-zero value (like 16 or 32), the corresponding number of bytes at the beginning of the database header are not encrypted allowing iOS to identify the file as a SQLite database file. The drawback of this approach is that the cipher salt used for the key derivation can’t be stored in the database header any longer. Therefore it is necessary to retrieve the cipher salt on creating a new database, and to specify the salt on opening an existing database. In SQLite3 Multiple Ciphers the cipher salt can be retrieved with the function sqlite3mc_codec_data using parameter cipher_salt, and has to be supplied on opening a database via the database URI parameter cipher_salt.

Copyright © 2020-2021 Ulrich Telle. Distributed under an MIT license.