SQLcrypt™ C API

SQLcrypt™ is based on SQLite. SQLcrypt™ adds to SQLite two C API functions and several result codes specific to it; otherwise SQLcrypt™ is exactly like SQLite version 3.

Function

  int sqlcrypt3_passphrase(sqlite3 *, const char *, int, char **);

This function invokes SQLcrypt™'s cryptographic functionality. It must be called after the call to sqlite3_open() or sqlite3_open16() and before callls to any other SQLite function. The first parameter is the pointer to the sqlite3 structure returned from one of these calls. The second parameter is a NULL-terminated string containing the user-supplied passphrase.

The third parameter indicates the cryptographic operation: 0 for decryption and 1 for encryption.

The fourth parameter follows SQLite's error messaging convention: If it is not NULL, it is made to point to memory obtained from malloc() when an error occurs; SQLcrypt™ then writes an appropriate error message into this memory. The calling function must free the memory subsequently by calling sqlite3_free(). If this parameter is NULL, no error message is written.

The return value is SQLITE_OK if there is no error; otherwise it is either one of the result codes described below, or one of SQLite's result codes if the error is not SQLcrypt™-specific.

If the passphrase supplied is wrong, then, when SQLcrypt™ uses the passphrase-derived cipher key to decrypt data in the database, invoked via sqlite3_exec(), say, the decrypted data will appear to be gibberish and sqlite3_exec() will return SQLITE_CORRUPT or SQLITE_NOTADB, depending on context.

Function

  int sqlcrypt3_license_key(const char *);

This function informs SQLcrypt™ of an appropriate license key string. It is mandatory in the binary-licensed version of SQLcrypt™ and must be invoked before the call to sqlcrypt3_passphrase(). This function is neither necessary nor available in the source-licensed version of SQLcrypt™.

The return value is SQLITE_OK if there is no error and SQLCRYPT3_BADLIC otherwise.

Result Codes

  SQLCRYPT3_TOOSHORT

This result code is returned from sqlcrypt3_passphrase() if the passphrase is too short. A passphrase must be between 8 and 128 characters long. In the trial version of SQLcrypt™, a passphrase must be exactly 8 characters long.

  SQLCRYPT3_TOOLONG

This result code is returned from sqlcrypt3_passphrase() if the passphrase is too long. A passphrase must be between 8 and 128 characters long. In the trial version of SQLcrypt™, a passphrase must be exactly 8 characters long.

  SQLCRYPT3_BADLIC

This result code is returned from sqlcrypt3_license_key() if the license key string supplied is rejected.