Topics   All   Mac OS X (Only)   Windows (Only)   Linux (Only, Not)   iOS (Only, Not)  
Components   Crossplatform Mac & Win   Server (Not)   Client   Old   Guides   Examples
New in version: 6.3   6.4   6.5   7.0   7.1   7.2   7.3   7.4   7.5   8.0    Statistic  

SQL.SQLite3.SetKey

Sets the encryption key to use.

Component Version macOS Windows Server FileMaker Cloud FileMaker iOS SDK
SQL 5.3 Yes Yes Yes Yes Yes

MBS( "SQL.SQLite3.SetKey"; Connection; Key { ; Encoding } )

Parameters

Parameter Description Example value
Connection The connection reference number gained with SQL.NewConnection. $Connection
Key The new encryption key. "Hello World"
Encoding Optional
The text encoding for the key.
Default is UTF-8.
Possible encoding names: ANSI, Arabic-Mac, Arabic-Win, Baltic-Win, CentralEurope-Mac, ChineseSimp-Mac, ChineseSimp-Win, ChineseTrad-Mac, ChineseTrad-Win, Cyrillic-Mac, Cyrillic-Win, EasternEurope-Win, Greek-Mac, Greek-Win, Hebrew-Mac, Hebrew-Win, ISO-8859-1, ISO-8859-2, ISO-8859-3, ISO-8859-4, ISO-8859-5, ISO-8859-6, ISO-8859-7, ISO-8859-8, ISO-8859-9, ISO-8859-15, Korean-Johab, Korean-Mac, Korean-Win, Latin1, Mac, Native, ShiftJIS-Mac, ShiftJIS-Win, Turkish-Mac, Turkish-Win, UTF-8, DOS or Windows. Pass native to use the native encoding of the current platform.
"UTF-8"

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


SQL.SQLite3.ReKey   -   SQL.ServerVersion

Feedback: Report problem or ask question.




Links
MBS Xojo PDF Plugins