SQLCipher for Linux FIPS

Introduction

This document describes the steps that differ from the standard SQLCipher for Linux integration instructions when using the FIPS package. Follow the base documentation for compiler flags, linking, and general API usage, and apply the changes below.

SQLCipher for Linux FIPS uses an embedded FIPS validated cryptographic module on applicable platforms per FIPS Implementation Guidance. Only dynamic linking is supported for FIPS use; the FIPS module is distributed as a shared library and configuration file that must be co-located with the SQLCipher library at runtime.

Package Contents

Extract the sqlcipher-linux-fips-4.16.0.zip package. Unlike the standard Linux package, each architecture directory under libs/ contains three files that must be deployed together:

  • libsqlcipher.so: SQLCipher dynamic library
  • fips.so: FIPS cryptographic module
  • fips.cnf: FIPS configuration file

Architectures provided: arm, arm64, x86, x86_64. Static libraries (libsqlcipher.a, libcrypto.a) are not included; FIPS operation requires the dynamic linking path only.

Library Installation

Important: All three files (libsqlcipher.so, fips.so, and fips.cnf) must be present in the same directory and accessible to your application at runtime. The FIPS module cannot load if any component is missing. Ensure the runtime path is set so the loader finds them, either via LD_LIBRARY_PATH or, preferably, an rpath baked into the application:

-Wl,-rpath,'$ORIGIN/path/to/architecture/specific/library'

Compilation and linking flags are identical to the standard integration; see the Dynamic Linking section of the base documentation.

Apply License Code

License code application is identical to the non-FIPS integration. Apply PRAGMA cipher_license before any other database operation:

rc = sqlite3_prepare(db, "PRAGMA cipher_license = 'YOUR_LICENSE_KEY';", -1, &stmt, NULL);
rc = sqlite3_step(stmt);
sqlite3_finalize(stmt);

If the license code is not properly applied your application will receive not authorized or SQLITE_AUTH (23) errors.

Check FIPS Mode

Applications using a FIPS validated cryptographic module should, as a matter of practice, check that the library is operating in FIPS mode early in the application lifecycle. This ensures that the FIPS-enabled library has been integrated, loaded properly at runtime, that all Power On Self Tests have completed successfully, and that the library is running in FIPS mode.

rc = sqlite3_prepare(db, "PRAGMA cipher_fips_status;", -1, &stmt, NULL);
rc = sqlite3_step(stmt);
if(rc == SQLITE_ROW && strcmp(sqlite3_column_text(stmt, 0), "1") == 0) {
  // operating in FIPS mode
} else {
  // not operating in FIPS mode - throw error
}
sqlite3_finalize(stmt);

Reference Application

A complete reference application is available under examples/sqlcipher-c/ in the sqlcipher-linux-fips-4.16.0.zip package. It includes:

  • demo.c: sample application demonstrating database operations and FIPS verification
  • Makefile: build configuration that auto-detects the host architecture and copies the required FIPS files into the build output

Troubleshooting

  1. Shared Library Not Found: errors like error while loading shared libraries: libsqlcipher.so: cannot open shared object file indicate the runtime library path is not set correctly.
  2. FIPS Mode Validation Failure: if the application fails to validate FIPS mode, ensure all three required files (libsqlcipher.so, fips.so, and fips.cnf) are in the same directory and accessible. The FIPS module cannot operate without all components present.
  3. Not Authorized / SQLITE_AUTH (23): the License Code was not supplied, is not valid, or has expired. Check that the application is applying PRAGMA cipher_license before any other database operations.
  4. Architecture Mismatch: ensure you are using the libraries from the correct platform subdirectory (arm, arm64, x86, or x86_64).
  5. Power On Self Test Failures: if FIPS validation fails during initialization, check stderr for FIPS module errors, which may indicate integrity check failures.

Please contact support@zetetic.net with any questions or to receive private support.