From 957fbb8bb648239899d12415f92914c3776a67ca Mon Sep 17 00:00:00 2001 From: def Date: Thu, 20 Dec 2018 14:13:03 +0200 Subject: [PATCH] Add disclaimer about raw key interface --- README.md | 31 ++++++++++++++++++------------- 1 file changed, 18 insertions(+), 13 deletions(-) diff --git a/README.md b/README.md index 954a1ca..f6c1313 100644 --- a/README.md +++ b/README.md @@ -135,19 +135,24 @@ In addition, there are `sqlite3_key_v2()` and `sqlite3_rekey_v2()` functions that accept the target database name as the second parameter. By default, the main database is used. -The above functions pass the provided key string (password) to a key derivation -algorithm (i.e., PBKDF2-HMAC-SHA256 with a 16-byte salt and 12345 iterations). -Optionally, the user can bypass the key derivation by specifying a raw key in -format `raw:K` where `K` is a 32-byte binary string or a 64-digit hex-encoded -string. This is useful in programs that use sqleet as a library and want to -handle key derivation by themselves. Additionally, the raw key string can also -be followed by a 16-byte (or 32-hexdigit) salt which is stored in the beginning -of the database file (otherwise a random salt is generated). **Warning:** In -any way erroneous raw key (e.g., unsupported length or invalid hex-encoding) -results in the key being handled as a normal key including the `raw:` prefix. -Moreover, specifying a salt makes sense only when creating a new database or -re-encrypting an existing database, because otherwise the specified salt is -overridden by the salt stored in the database file. +#### Raw keys + +**Disclaimer**: The current interface is experimental and likely to change in +future versions (see issue #13 for discussion). Use at your own risk! + +The encryption functions pass the provided key string (password) to a key +derivation algorithm (i.e., PBKDF2-HMAC-SHA256 with a 16-byte salt and 12345 +iterations). Optionally, the user can bypass the key derivation by specifying a +raw key in format `raw:K` where `K` is a 32-byte binary string or a 64-digit +hex-encoded string. This is useful in programs that use sqleet as a library and +want to handle key derivation by themselves. Additionally, the raw key string +can also be followed by a 16-byte (or 32-hexdigit) salt which is stored in the +beginning of the database file (otherwise a random salt is generated). +**Warning:** In any way erroneous raw key (e.g., unsupported length or invalid +hex-encoding) results in the key being handled as a normal key including the +`raw:` prefix. Moreover, specifying a salt makes sense only when creating a new +database or re-encrypting an existing database, because otherwise the specified +salt is overridden by the salt stored in the database file. Android support