Components All New MacOS Windows Linux iOS
Examples Mac & Win Server Client Guides Statistic FMM Blog Deprecated Old

SQL.SQLite3.SetKey

Sets the encryption key to use.

Component Version macOS Windows Linux Server iOS SDK
SQL 5.3 ✅ Yes ✅ Yes ✅ Yes ✅ Yes ✅ Yes
MBS( "SQL.SQLite3.SetKey"; Connection; Key { ; Encoding } )   More

Parameters

Parameter Description Example Flags
Connection The connection reference number gained with SQL.NewConnection. $Connection
Key The new encryption key. "Hello World"
Encoding The text encoding for the key.
Default is UTF-8.
Possible encoding names: ANSI, ISO-8859-1, Latin1, Mac, Native, UTF-8, DOS, Hex, Base64 or Windows. More listed in the FAQ.
"UTF-8" Optional

Result

Returns OK or error.

Description

Sets the encryption key to use.
This key is applied to the database after connecting. In case of an error, the plugin raises an exception. An empty key can be used for having no encryption.

The amount of key material actually used by the encryption extension depends on which variant of SEE you are using. With RC4, the first 256 byte of key are used. With the AES128, the first 16 bytes of the key are used. With AES256, the first 32 bytes of key are used.

If you specify a key that is shorter than the maximum key length, then the key material is repeated as many times as necessary to complete the key. If you specify a key that is larger than the maximum key length, then the excess key material is silently ignored.

The key must begin with an ASCII prefix to specify which algorithm to use. The prefix must be one of "rc4:", "aes128:", or "aes256:". The prefix is not used as part of the key sent into the encryption algorithm. So the real key should begin on the first byte after the prefix. If no prefix is given, we default to AES 128. To be compatible to Xojo (Real Studio), you can use AES128.

Make sure you pass right text encoding (or none for UTF-8). e.g. using "Müller" as key in text encoding Windows ANSI will not open a database which used that key in UTF-8 encoding.

Examples

Use an encryption key:

MBS( "SQL.SQLite3.SetKey"; $Connection; "xxx" )

Clear encryption key:

MBS( "SQL.SQLite3.SetKey"; $Connection; "" )

Use an encryption key with UTF-8 and AES-256:

MBS( "SQL.SQLite3.SetKey"; $Connection; "aes256:" & $key; "UTF-8" )

See also

Blog Entries

This function is free to use.

Created 23th September 2015, last changed 12nd November 2015


SQL.SQLite3.ReKey - SQL.ServerVersion