Improve documentation

Clarify how to use the plaintext header feature together with specifying raw key and salt material

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-2025 Ulrich Telle. Distributed under an <a href=\"https://github.com/utelle/SQLite3MultipleCiphers/tree/master/LICENSE\">MIT license.</a>"
+footer_content: "Copyright &copy; 2020-2026 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_dynamic.md

@@ -2,7 +2,7 @@
 layout: default
 title: Dynamic cipher schemes
 parent: Supported Ciphers
-nav_order: 9
+nav_order: 10
 ---
 ## <a name="legacy" /> Dynamic cipher schemes
 

docs/ciphers/cipher_plaintext_header.md

@@ -0,0 +1,18 @@
+---
+layout: default
+title: Plaintext header
+parent: Supported Ciphers
+nav_order: 9
+---
+## <a name="plaintext_header" /> Plaintext database header
+
+On **iOS** there exists an issue with encrypted databases, if they are stored in a shared container. **iOS** identifies SQLite database files by inspecting certain bytes in the database header. However, several cipher schemes, namely [ChaCha20]({{ site.baseurl }}{% link docs/ciphers/cipher_chacha20.md %}), [SQLCipher]({{ site.baseurl }}{% link docs/ciphers/cipher_sqlcipher.md %}), [Ascon]({{ site.baseurl }}{% link docs/ciphers/cipher_ascon.md %}), and [AEGIS]({{ site.baseurl }}{% link docs/ciphers/cipher_aegis.md %}), save a cipher salt value used in the key derivation process in the first 16 bytes of the database header, and usually encrypt the database header, too. This prevents **iOS** from identifying, and therefore **iOS** will kill the application process when it tries to maintain a file lock on the database  while it is in the background.
+
+To avoid problems on **iOS** it is necessary to leave the database header unencrypted - at least partially. For this purpose the parameter `plaintext_header_size` was introduced to exclude a specified number of bytes of the database header unencrypted.
+
+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`. Alternatively, the SQL command `PRAGMA cipher_salt` can be used for that purpose.
+
+**Note**
+{: .label .label-red .ml-0 .mb-1 .mt-2 }
+Some developers prefer to use raw key and salt material under **iOS**. In this case, an application would provide the key and salt material via a specially formatted key value via `PRAGMA key`.
+While specifying raw key **and** salt material is required for the cipher scheme _SQLCipher_, it is sufficient to specify just the key material for the cipher schemes _ChaCha20_, _Ascon_, and _AEGIS_, because they use the salt only for the key derivation process (which doesn't take place, when raw key material is provided). Thus, for the latter cipher schemes retrieving and specifying the cipher salt isn't required at all, when using raw key material. 

docs/configuration/config_sql_pragmas.md

@@ -108,11 +108,12 @@ PRAGMA key = "x'54686973206973206D792076657279207365637265742070617373776F72642E
 PRAGMA key = 'raw:54686973206973206D792076657279207365637265742070617373776F72642E2E73616C7479206B65792073616C742E';
 ```
 
-Note
+Notes
 {: .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_ascon.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.
+- 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_ascon.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.
+- When using the _plaintext header_ option together with raw key and salt material, the cipher scheme [SQLCipher: AES 256 Bit]({{ site.baseurl }}{% link docs/ciphers/cipher_sqlcipher.md %}) requires to specify raw _key_ **and** _salt_ material. All other cipher schemes only need the raw key material, because the salt is not used in this case.
 
 ---