SQLCipher for iOS .NET FIPS

Introduction

This document describes the steps that differ from the standard SQLCipher for .NET integration instructions when using the FIPS package for iOS. Follow the base documentation for nuget.config setup, SQLitePCLRaw providers, runtime activation, iOS Specific Integration linker settings, and client library integration (sqlite-net / EF Core / ADO.NET), and apply the changes below.

SQLCipher for iOS .NET FIPS uses an embedded FIPS validated cryptographic module per FIPS Implementation Guidance.

Package Contents

Extract the sqlcipher-ios-net-fips-4.16.0.zip package. It contains:

  • sqlcipher-ios-fips.4.16.0.nupkg: FIPS-enabled native SQLCipher library package for iOS. This package also embeds the SQLitePCL.SQLite3Provider_sqlcipher provider class (via SQLitePCL.SQLite3Provider_sqlcipher_ios.dll), so the standalone SQLitePCLRaw.provider.sqlcipher package is not required on iOS.
  • sqlcipher-sqlite-net-base.4.16.0.nupkg: SQLite-net base library (only needed if using the sqlite-net data access API)
  • examples/SQLCipher.Example/: reference solution with sample projects demonstrating sqlite-net, Entity Framework Core, ADO.NET, and MAUI integration

The FIPS nupkg bundles SQLCipher.xcframework, fips.xcframework, and openssl.xcframework and references them as native frameworks through MSBuild targets; they are automatically linked and embedded when the package is installed into an iOS target.

Package Integration

Copy both .nupkg files into the local NuGet package source directory configured in your nuget.config (as described in the base Project Setup).

When installing SQLCipher at the Application project level, substitute the FIPS package name:

  • Use sqlcipher-ios-fips in place of sqlcipher-ios

All other steps from the base .NET documentation apply, with one important difference in provider configuration. Unlike the non-FIPS iOS package, which uses the internal provider, the iOS FIPS package uses the SQLite3Provider_sqlcipher provider, and supplies that class directly through the sqlcipher-ios-fips nupkg. As a result:

  • Do NOT add SQLitePCLRaw.provider.sqlcipher as a package reference for iOS targets; the provider class is already supplied by sqlcipher-ios-fips. If your project multi-targets platforms that do require SQLitePCLRaw.provider.sqlcipher (for example Android FIPS), make that PackageReference conditional so it is excluded for iOS target frameworks.
  • Call SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_sqlcipher()) early in application startup; the class resolves from the sqlcipher-ios-fips package on iOS.
  • Apply the license code via PRAGMA cipher_license.
  • Configure iOS linker behavior to avoid stripping SQLCipher assemblies (see iOS Specific Integration).

For projects that target both FIPS and non-FIPS iOS packages, the SQLCIPHER_IOS_FIPS preprocessor symbol is defined automatically by the FIPS package’s build targets. This can be used to select the correct provider at compile time:

#if IOS && !SQLCIPHER_IOS_FIPS
    /* Non-FIPS iOS uses the internal provider */
    SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_internal());
#else
    /* iOS FIPS and all other platforms use the standard SQLCipher provider */
    SQLitePCL.raw.SetProvider(new SQLitePCL.SQLite3Provider_sqlcipher());
#endif

Check FIPS Mode

Applications using a FIPS 140 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.

After opening the database, keying, and applying the license code, query PRAGMA cipher_fips_status. A result of 1 indicates FIPS mode:

using (var command = connection.CreateCommand())
{
  command.CommandText = "PRAGMA cipher_fips_status;";
  var status = command.ExecuteScalar() as string;
  if (status != "1")
  {
    throw new InvalidOperationException("SQLCipher is not operating in FIPS mode");
  }
}

Reference Application

A complete reference solution is available under examples/SQLCipher.Example/ in the sqlcipher-ios-net-fips-4.16.0.zip package. It includes MAUI, Console, and WinUI projects that demonstrate multiple data access APIs (sqlite-net, Entity Framework Core, ADO.NET) with the FIPS status check in place.

Troubleshooting

  1. Not Authorized / SQLITE_AUTH (23): the License Code was not supplied, is not valid, or has expired. Check that PRAGMA cipher_license is applied before any other database operations.
  2. FIPS Mode Validation Failure: a cipher_fips_status result other than 1 indicates the FIPS module did not load or the Power On Self Test did not pass. Confirm the sqlcipher-ios-fips package is referenced by the Application project (not a shared class library), that SQLitePCLRaw.provider.sqlcipher is not also referenced for the iOS target (it conflicts with the provider embedded in sqlcipher-ios-fips), and that no conflicting SQLitePCLRaw bundles such as SQLitePCLRaw.bundle_e_sqlcipher are present.
  3. Linker Stripping SQLCipher Assemblies: if SQLCipher fails to load at runtime on iOS, set Linker Behavior to Link SDK assemblies only or Don't Link, or provide a linker description file that excludes SQLCipher assemblies. See iOS Specific Integration in the base documentation.
  4. Conflicting SQLite Packages: see NuGet Package Conflicts in the base documentation to exclude transitive SQLite dependencies that can mask the FIPS native library.

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