Update documentation

- describe new pragma cipher_salt
- adjust description of raw key material
- add FAQ item regarding iOS and encrypted databases (issue #209)

Author: utelle

_config.yml

@@ -30,7 +30,7 @@ aux_links:
     - "//github.com/utelle/SQLite3MultipleCiphers"
 
 # Footer content appears at the bottom of every page's main content
-footer_content: "Copyright &copy; 2020-2024 Ulrich Telle. Distributed under an <a href=\"https://github.com/utelle/SQLite3MultipleCiphers/tree/master/LICENSE\">MIT license.</a>"
+footer_content: "Copyright &copy; 2020-2025 Ulrich Telle. Distributed under an <a href=\"https://github.com/utelle/SQLite3MultipleCiphers/tree/master/LICENSE\">MIT license.</a>"
 
 # Color scheme currently only supports "dark" or nil (default)
 color_scheme: nil

docs/ciphers/cipher_aegis.md

@@ -24,6 +24,7 @@ The following table lists all parameters related to this cipher that can be set
 | `mcost`     | 19456   | 1     |       | Amount of memory in kB for key derivation with Argon2id |
 | `pcost`     | 1       | 1     |       | Parallelism, number of threads for key derivation with Argon2 |
 | `algorithm` | 4       | 1     | 6     | AEGIS variant to be used for page encryption |
+| `plaintext_header_size` | 0 | 0 | 100 | Size of plaintext database header<br/>must be a multiple of 16, i.e. 32 |
 
 **Notes**
 {: .label .label-red .ml-0 .mb-1 .mt-2 }

docs/ciphers/cipher_ascon.md

@@ -19,3 +19,4 @@ The following table lists all parameters related to this cipher that can be set
 | Parameter | Default | Min | Max | Description |
 | :--- | :---: | :---: | :---: | :---: | :--- |
 | `kdf_iter` | 64007 | 1 | | Number of iterations for the key derivation function |
+| `plaintext_header_size` | 0 | 0 | 100 | Size of plaintext database header<br/>must be a multiple of 16, i.e. 32 |

docs/ciphers/cipher_chacha20.md

@@ -23,6 +23,7 @@ The following table lists all parameters related to this cipher that can be set
 | `kdf_iter` | 64007 | 12345 | 1 | | Number of iterations for the key derivation function |
 | `legacy` | 0 | 1 | 0 | 1 | Boolean flag whether the legacy mode should be used |
 | `legacy_page_size` | 4096 | 4096 | 0 | 65536 | Page size to use in legacy mode, 0 = default SQLite page size |
+| `plaintext_header_size` | 0 | 0 | 100 | Size of plaintext database header<br/>must be a multiple of 16, i.e. 32 |
 
 **Note**
 {: .label .label-red .ml-0 .mb-1 .mt-2 }

docs/configuration/config_sql_pragmas.md

@@ -94,6 +94,8 @@ PRAGMA key = 'raw:54686973206973206D792076657279207365637265742070617373776F7264
 Note
 {: .label .label-red .ml-0 .mb-1 .mt-2 }
 Currently only the cipher schemes [sqleet: ChaCha20]({{ site.baseurl }}{% link docs/ciphers/cipher_chacha20.md %}) and [SQLCipher: AES 256 Bit]({{ site.baseurl }}{% link docs/ciphers/cipher_sqlcipher.md %}) support this method, requiring the literal syntax as given in the example.
+Starting with version [2.2.0](https://github.com/utelle/SQLite3MultipleCiphers/releases/tag/v2.2.0) the ciphers [Ascon128]({{ site.baseurl }}{% link docs/ciphers/cipher_ascon128.md %}) and [AEGIS]({{ site.baseurl }}{% link docs/ciphers/cipher_aegis.md %}) support this option, too.
+All named ciphers accept the raw key material in both forms shown in the example.
 
 <span class="label label-green">Example 3:</span> _Raw key data including salt (without key derivation)_
 
@@ -109,6 +111,8 @@ PRAGMA key = 'raw:54686973206973206D792076657279207365637265742070617373776F7264
 Note
 {: .label .label-red .ml-0 .mb-1 .mt-2 }
 Currently only the cipher schemes [sqleet: ChaCha20]({{ site.baseurl }}{% link docs/ciphers/cipher_chacha20.md %}) and [SQLCipher: AES 256 Bit]({{ site.baseurl }}{% link docs/ciphers/cipher_sqlcipher.md %}) support this method, requiring the literal syntax as given in the example.
+Starting with version [2.2.0](https://github.com/utelle/SQLite3MultipleCiphers/releases/tag/v2.2.0) the ciphers [Ascon128]({{ site.baseurl }}{% link docs/ciphers/cipher_ascon128.md %}) and [AEGIS]({{ site.baseurl }}{% link docs/ciphers/cipher_aegis.md %}) support this option, too.
+All named ciphers accept the raw key material in both forms shown in the example.
 
 ---
 
@@ -183,6 +187,23 @@ PRAGMA cipher = 'aes256cbc';
 
 ---
 
+### PRAGMA *cipher_salt*
+
+The `PRAGMA cipher_salt` allows to set or retrieve the _cipher salt_ used by the cipher scheme, and has the following syntax:
+
+```sql
+PRAGMA cipher_salt = { ciphersalt | 'ciphersalt' | "ciphersalt" };
+```
+
+where the value for `ciphersalt` has to be given as a string consisting of 32 hex digits representing the 16 bytes cipher salt.
+
+Note
+{: .label .label-red .ml-0 .mb-1 .mt-2 }
+- **Setting** the cipher salt is only possible, _before_ `PRAGMA key` is executed.
+- **Retrieving** the cipher salt is only possible, _after_ `PRAGMA key` was executed.
+
+---
+
 ### PRAGMA *hmac_check*
 
 The `PRAGMA hmac_check` sets a boolean flag whether the HMAC should be validated on read operations for encryption schemes using HMACs. It has the following syntax:

docs/configuration/config_uri.md

@@ -22,7 +22,7 @@ Notes
 - If either the URI query parameter `key` or `hexkey` is used and if it is not intended to use the default cipher, then the `cipher` query parameter and optionally further cipher configuration parameters have to be given in the URI query string as well. 
 - For security reasons it is not recommended to use the URI query parameter `key` or `hexkey`, because the passphrase is visible in memory for the whole duration of the database connection.
 - The URI query parameters `key` or `hexkey` are respected on **opening** a database, and on **attaching** a database. However, if the keyword `KEY` of the SQL command `ATTACH` is used on attaching a database, the value after the keyword `KEY` will take precedence over the URI parameters.
-- The `cipher` query parameter is always required, if further query parameters should be used to configure the encryption extension. If this parameter is missing or specifies an unknown cipher, all other cipher configuration parameters are silently ignored, and the default cipher as selected at compile time will be used.
+- If query parameters are used to configure the encryption extension, the `cipher` query parameter is mandatory for _all_ **non-default** ciphers; it is optional for the default cipher, but it is recommended to always specify the cipher. If this parameter specifies an unknown cipher, all other cipher configuration parameters are silently ignored, and the default cipher as selected at compile time will be used.
 - On **opening** a database all cipher configuration parameters given in the URI query string are used to set the **default** cipher configuration of the database connection. On **attaching** a database the cipher configuration parameters given in the URI query string will be used for the attached database, but will not change the defaults of the main database connection.
 
 <span class="label label-green">Example:</span> URI query string to select the _legacy_ SQLCipher Version 2 encryption scheme

docs/faq/faq_overview.md

@@ -58,3 +58,13 @@ Therefore the SQL configuration functions can't be used any longer for configuri
 Dynamically loading certain SQLite extensions may also fail, if done before`PRAGMA key` was executed. Namely FTS5 extensions (like [sqlite-better-trigram](https://github.com/streetwriters/sqlite-better-trigram) or [sqlite3-fts5-html](https://github.com/streetwriters/sqlite3-fts5-html)) are affected, because they retrieve the FTS5 API pointer via a `SELECT` statement (see [issue #208](https://github.com/utelle/SQLite3MultipleCiphers/issues/208)). Postpone dynamically loading affected extensions until `PRAGMA key` was executed.
 
 [Automatically loading statically linked extensions](https://sqlite.org/c3ref/auto_extension.html) will not work at all for extensions that depend on using `SELECT` statements while initializing the extension, because SQLite initializes extensions registered for automatic loading, before the cipher scheme is activated for the connection. For example, in case of extending the FTS5 extension, it would be necessary that the FTS5 extension provides access to the API pointer by other means than a `SELECT` statement.
+
+## Why my app is killed under **iOS** on suspension, when the _SQLite_ database is stored in a shared container for app groups?
+
+_iOS_ apps can't share an **encrypted** database with app extensions (e.g. share extensions) without being terminated every time they enter the background. _iOS_ won't let suspended apps retain a file lock on apps in the _"shared data container"_ used to share files between _iOS_ apps and their app extensions. This seems to affect all versions of iOS and all device models.
+
+To overcome this issue version 4 of _SQLCipher_ introduced a new parameter `plain_text_header_size`. 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.
+
+While _SQLite3 Multiple Ciphers_ supported the parameter `plain_text_header_size` right from the beginning, it did not for other cipher schemes. Starting with version [2.2.0](https://github.com/utelle/SQLite3MultipleCiphers/releases/tag/v2.2.0) the cipher schemes _chacha20_, _ascon128_, and _aegis_ support this parameter as well.
+
+In _SQLite3 Multiple Ciphers_ the cipher salt can be retrieved with the function [`sqlite3mc_codec_data`]({{ site.baseurl }}{% link docs/configuration/config_sql_functions/#function-sqlite3mc_codec_data %}) using parameter `cipher_salt`. Alternatively, it can be retrieved with `PRAGMA cipher_salt`. On opening a database the _cipher salt_ has to be supplied either via the database URI parameter `cipher_salt`, or via `PRAGMA cipher_salt='<hex bytes of cipher salt>'`, before `PRAGMA key` is executed.