Config interface: global parameter table about wxsqlite3 HOT 8 CLOSED

I have to admit that the documentation is not in sync with the implementation.

When I started to implement the feature to select the cipher at runtime, there was only a single global parameter table, but in a multi-threaded environment this could easily lead to problems in synchronizing the access to the global parameter table. Therefore I decided to use a copy of the global parameter table for each database connection.

Since the current interface for accessing and manipulating the parameter tables allows to manipulate only a single parameter per invocation, manipulating the global parameter table could still cause problems in a multi-threaded environment. Therefore the global parameter table is currently read-only.

If manipulating the global parameter table should be possible, then I think this will require a separate interface which allows to set all parameters of a cipher within one invocation, so that inconsistent states of the table are avoided. However, I'm not sure whether such an interface is so important that it is worth the effort.

from wxsqlite3.

However, I'm not sure whether such an interface is so important that it is worth the effort.

No, I don't think it's worth the effort, but I think the documentation should be updated. I can do this if you'd like.

Let me just clarify on this. Please correct me if any of the following is wrong:

1. Since the global parameter table is read-only, it's only purpose is to serve default values.
2. The default: parameter prefix denotes yet another default value which overrides the default value from the global parameter table.
3. If a "regular" parameter value has been set (that is, without the default: prefix), then the regular parameter value is only used once within the next sqlite3_key() or sqlite3_rekey() invocation. Subsequent sqlite3_key() or sqlite3_rekey() invocations will use a default value again.

from wxsqlite3.

... but I think the documentation should be updated. I can do this if you'd like.

Please feel free to update the documentation. I will review it, and I will comment if necessary. TIA.

1. Since the global parameter table is read-only, it's only purpose is to serve default values.

Yes. For each supported cipher the global parameter table holds reasonable default values. That is, usually it should be sufficient to just select the cipher to be used for a database connection without having to tweak its specific parameters.

The default values were chosen in that way that the cipher schemes conform to the restrictions imposed by the "official" SQLite Encryption Extension (SEE)) - mainly, leaving bytes 16 to 23 of the database header unencrypted. This has the advantage that the actual database page size is detected automatically. Otherwise it is usually necessary to explicitly set the page size.

The global parameter table can be adjusted at compile time. Legacy modes can be selected via preprocessor symbols (i.e. WXSQLITE3_USE_OLD_ENCRYPTION_SCHEME, WXSQLITE3_USE_SQLEET_LEGACY, WXSQLITE3_USE_SQLCIPHER_LEGACY). However, changing the specific cipher parameters would require to edit source file codec.c.

2. The default: parameter prefix denotes yet another default value which overrides the default value from the global parameter table.

Yes. This is for convenience. The parameter table holds 2 sets of parameters - the default set and the transient set. Some further explanations can be found in my posts for issue #34.

3. If a "regular" parameter value has been set (that is, without the default: prefix), then the regular parameter value is only used once within the next sqlite3_key() or sqlite3_rekey() invocation. Subsequent sqlite3_key() or sqlite3_rekey() invocations will use a default value again.

Yes, that is correct (although I prefer to call these parameter values transient).

from wxsqlite3.

OK thanks, I think I've got everything I need to update the docs :-)

If I may put in my two cents here: I think the interface would be cleaner if <no prefix> was used to refer to the default parameters and the prefix transient: was used to refer to the transient parameters. (I know this would be a breaking change, so I guess you'd probably don't want to modify this.)

However, the current interface seems a little counterintuitive to me, since the usual behavior / expectation of a setter function is that the value is stored persistently, and not transiently.

from wxsqlite3.

Well, indeed I don't intend to change the prefixes, at least not at the moment.

I like the default: prefix, because it makes clear that the default parameter values are set that are usually not meant to change again for the current database connection.

<no prefix> designates the current values which should be used for the next key setting operation. The parameters keep their current values until a key setting operation was actually performed; only then they are reverted to the default values.

I could have used a single set of parameters, but this would have required to always set the parameters before performing a key setting operation to be sure that the correct set of parameters is used.

I'm aware of that more detailed documentation would be useful. However, this will take some time.

from wxsqlite3.

I'm aware of that more detailed documentation would be useful. However, this will take some time.

I'm going to update the docs on this tomorrow.

from wxsqlite3.

There's no hurry! I really appreciate that you are going to improve the documentation.

from wxsqlite3.

Closed after documentation has been updated.

from wxsqlite3.