Introduction

This document provides installation and configuration guidelines for the SQLCipher for Linux FIPS package.

SQLCipher for Linux FIPS uses an embedded FIPS validated cryptographic module on applicable platforms per FIPS Implementation Guidance.

Package Contents

Extract the sqlcipher-linux-fips-X.X.X.zip package. The package contains:

  • /libs - Architecture-specific libraries for arm, arm64, x86, and x86_64
  • /include - Header files (sqlite3.h, sqlite3ext.h, sqlite3session.h)
  • /examples - Reference implementation and sample code
  • LICENSE.txt - License information

For each architecture, the following files are provided:

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

    Library Installation

  1. Extract the sqlcipher-linux-fips-X.X.X.zip package to your desired location.
  2. Ensure the appropriate architecture-specific libraries are accessible to your application. The package includes libraries for:
    • arm
    • arm64
    • x86
    • x86_64

Important: All three files (libsqlcipher.so, fips.so, and fips.cnf) must be present in the same directory and accessible to your application at compile time and runtime for proper FIPS operation.

Building with SQLCipher for Linux FIPS

Using the Dynamic Library

Include the SQLCipher headers in your application:

#include "sqlite3.h"

Add the appropriate compiler flags:

CFLAGS=-DSQLITE_HAS_CODEC

Link against the libsqlcipher library and set the correct library path:

LDFLAGS=-lsqlcipher -L/path/to/architecture/specific/library

Ensure the runtime library path is set to locate the shared libraries:

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

Ensure that when packaging the application libsqlcipher.so, fips.so, and fips.cnf are present in the same directory and loadable by your application (i.e. in the LD_LIBRARY_PATH, or RPATH for the application).

Apply License Code

Retrieve the license code from the SQLCipher fulfillment site:

https://license.zetetic.net/request-account/

The license code must be provided when opening a connection to the database. The license can be set using the PRAGMA cipher_license command before performing any other operations on the database.

// Apply license before any other database operations
rc = sqlite3_prepare(db, "PRAGMA cipher_license = 'YOUR_LICENSE_KEY';", -1, &stmt, NULL);
rc = sqlite3_step(stmt);
sqlite3_finalize(stmt);

Note that 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 important step ensures that the FIPS-enabled library has been integrated into the application, that it has been loaded properly at runtime, that all Power On Self Tests have completed successfully, and that the library is running in FIPS mode.

// Check FIPS status
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 in the examples/sqlcipher-fips-shared folder of the sqlcipher-linux-fips-X.X.X.zip package. This reference application incorporates all of the required configurations and can be used for testing or comparison purposes.

The example includes:

  • demo.c - Sample application showing database operations with FIPS verification
  • Makefile.linux - Linux build configuration
  • Architecture-specific libraries in subdirectories (arm, arm64, x86, x86_64)

Troubleshooting

The following outline possible error conditions and resolutions.

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

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