SQLCipher License Codes - How to avoid SQLITE_AUTH (23) not authorized errors

Commercial & Enterprise Edition Feature

SQLCipher Commercial and Enterprise packages require the use of a License Code to enable encryption functionality in the product. Failure to provide a license code, or the use of an expired trial code, will result in one of the following errors (depending on the data access API in use):

  • SQLITE_AUTH
  • Result Code 23
  • not authorized

To resolve this issue, provide the license code via the PRAGMA cipher_license API. The general syntax follows:

PRAGMA cipher_license = 'OmNpZDowMDFHMDA...';

This PRAGMA may be invoked either prior to or after keying, but must be run before using any encryption features.

In addition to setting the license code by PRAGMA, it is also possible to provide the license code without modifying the application code. Starting in SQLCipher 4.10.0, the license code value may also be set in:

  • The environmental variable CIPHER_LICENSE
  • A file named cipher_license in the same directory as the SQLCipher library
  • A file named cipher_license in the same directory as the current executable
  • A file named cipher_license in the same directory as the current working directory
  • A file named cipher_license in the Resources directory directory next to the main library in a macOS bundle
  • An arbitrary file path set using the CIPHER_LICENSE_FILE environmental variable

Trial license codes may be requested prior to purchase and are valid for 15 days of testing.

Permanent license codes are delivered electronically after purchase. If you have an active Commercial or Enterprise license you can request your license codes on the Customer Downloads site.

License Codes and Encryption Keys

The License Code is distinct from the database encryption Key and the two values are unrelated. The License Code is provided to PRAGMA cipher_license and is used solely to enable encryption functionality in Commercial and Enterprise builds. Current license codes start with a value like OmNpZDowMDFHMDA.... The encryption Key is the secret material used to encrypt and decrypt database content, supplied via PRAGMA key, sqlite3_key, or the platform-specific key parameter. License codes are not used in key derivation, encryption, or any other security operation.

Distributing License Codes in Applications

It is acceptable to embed the License Code directly in an application, including hardcoded source values, application resources, preferences, or registry entries. Obfuscation is not required.

Current license codes contain an opaque identifier used for internal tracking and do not include directly identifiable customer information. License codes are signed, which prevents modification and ties each code to specific library versions, so a code cannot be altered or used to unlock newer libraries than the one it was issued for. The expire:never tag on permanent codes only disables the trial shutoff timer and does not grant additional capability.

If a License Code is extracted from an application, the only tangible impact is that it could be used with older SQLCipher libraries in a separate, unlicensed application. An extracted License Code cannot be used to compromise the security of the application or its encrypted databases.