SQLCipher for .NET

Commercial & Enterprise Edition Feature

SQLCipher for .NET encompasses a set of packages that provide full database encryption for Microsoft .NET Standard 2.x on platforms including Windows, Windows 10 UAP, Xamarin.iOS, Xamarin.Android, and macOS .NET. These libraries makes it quick and easy to integrate SQLCipher's AES-256 full database encryption into any application, and they are fully interoperable with other SQLCipher platform libraries. No special knowledge of cryptography is required, and the libraries support popular data access APIs including:

  • A sqlite-net compatible package based on the official praeclarum/sqlite-net library
  • Microsoft Entity Framework via Microsoft.EntityFrameworkCore.Sqlite.Core 3.x
  • Microsoft's ADO.NET implementation via Microsoft.Data.Sqlite.Core 3.x

SQLCipher takes care of data security behind the scenes with a small footprint and great performance that makes it well suited for protecting application databases on mobile platforms. SQLCipher .NET packages are only available through our Commercial Edition licensing via the link below, or through the SQLCipher Enterprise program.

Buy SQLCipher for .NET Packages Now »

SQLCipher for supported .NET platforms are delivered directly via NuGet packages that may be installed from a local NuGet project source.

🔥 Before using the package(s) be sure to remove any prior references in your project to:
  • Legacy SQLCipher .nupkg or .xam packages
  • Any previous SQLite-based NuGet or assembly references

There are several ways to setup local NuGet repositories, including file shares, global Visual Studio settings, and even running a NuGet web repository. However, one simple, flexible, and recommended approach is to store the SQLCipher NuGet packages alongside the project itself. This approach ensures that the dependencies are stored in version control alongisde the application, that the packages are instantly available to all developers and build tools, and that the dependencies can be fulfilled even offline. Note that this approach works both with Visual Studio for Windows or Mac, though the former is used here for demonstration purposes.

Start by copying the appropriate .nupkg filesinto a folder under the root of the application. It is even possible to place the package(s) in the top level folder of the application sources itself alongside the Solution (.sln) file. Next, create a simple nuget.config file in the same directory as the .sln and .nupkg files, that points a package source to the directory where the .nupkg file(s) are located.

nuget.config file and package in solution folder

In the following example, the the package source points to the current directory where the nuget.config and .sln file are located:

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <add key="Local" value="." />
  </packageSources>
</configuration>

Finally, in Visual Studio, add the nuget.config file at the solution level, save the solution, and restart the IDE.

add nuget.config file to solution

The nuget.config should now show up as a Solution Item.

nuget.config file as a solution item

Once the NuGet configuration is complete you will be able bring up the NuGet package manager and select the Local source to install the appropriate SQLCipher package at the project level. SQLCipher packages should be installed to the executable / Applicaiton project. For example, consider a multi-target Solution that includes a Xamarin.iOS application, a Xamarin.Android application, and a Windows 10 UAP application that use a shared data access project. In this case, the platform-specific SQLCipher packages zetetic-sqlcipher-ios, zetetic-sqlcipher-android, and zetetic-sqlcipher-windows-uap should be each be installed to the respective project.

add nuget package to project

To ensure that the SQLCipher package appropriate for you platform is used, add the following early in your application's startup lifecycle code:

SQLitePCL.Batteries_V2.Init();

For Xamarin.iOS you will also need to call one additional method, SQLitePCL.lib.embedded.Init(), to instruct the Xamarin linker to properly bundle SQLCipher, i.e.

SQLitePCL.lib.embedded.Init(); /* required on iOS to link SQLCipher library */
SQLitePCL.Batteries_V2.Init();

For Windows UWP projects, the SQLitePCLRaw 2.x version used in recent releases no longer calls sqlite3_win32_set_directory() automatically. Thus you may need to add the following to your application initialization

            var rc = SQLitePCL.raw.sqlite3_win32_set_directory(
                1, // data
                Windows.Storage.ApplicationData.Current.LocalFolder.Path
                );

            rc = SQLitePCL.raw.sqlite3_win32_set_directory(
                2, // temp
                Windows.Storage.ApplicationData.Current.TemporaryFolder.Path
                );

Microsoft AppCenter provides a popular set of tools that enable crash reporting, application analytics, and other features for integrating applications. Due to the design of AppCenter, it brings in several transitive NuGet dependencies that include assets that conflict with SQLCipher packages. As such, we recommend including the following explicit PackageReference statements in any project file that includes AppCenter.

<PackageReference Include="sqlite-net-pcl">
  <Version>*</Version>
  <ExcludeAssets>All</ExcludeAssets>
</PackageReference>
<PackageReference Include="SQLitePCLRaw.bundle_green">
  <Version>*</Version>
  <ExcludeAssets>All</ExcludeAssets>
</PackageReference>

A similar technique can be used to resolve conflicts with any other package that include a dependency on sqlite-net-pcl or any non-Zetetic SQLitePCLRaw bundles.

Once the appropriate project-specific packages are installed you can choose the desired client libraries for accessing databases. SQLCipher supports multiple APIs for accessing data: sqlite-net, Entity Framework, and ADO.NET. Details on each integration approach are included here.

SQLCipher ships with a sqlite-net compatible package based on the official praeclarum/sqlite-net library. To use this interface, make sure that zetetic-sqlite-net-base-X.X.X.nupkg is present in the local NuGet repository and install it to the project.

Example

The following example provides an abbreviated code sample for using SQLCipher via the sqlite-net API, where the key material is passed to the constructor. Note that a fully functional referece application is included with each SQLCipher package to demonstrate library usage.

using SQLite;

...

public class Model
{
  [PrimaryKey,AutoIncrement]
  public int Id { get; set; }
  public string Content { get; set; }
}

...

var conn = new SQLiteConnection(new SQLiteConnectionString(filename, true, password));
conn.ExecuteScalar<int>(String.Format("PRAGMA cipher_license = '{0}';", licenseKey));
conn.CreateTable<Model>();

...

// use SQLiteConnection

SQLCipher supports the use of Microsoft Entity Framework Core version 3.

NuGet Package Requirements

To integrate Microsoft.EntityFrameworkCore.Sqlite.Core 3, configure the following Nuget packages:

  1. Microsoft.EntityFrameworkCore.Sqlite.Core version 3.x
  2. SQLitePCLRaw.bundle_zetetic version 2.x
  3. platform-specific SQLCipher packages
  4. ensure that there are no references to zetetic-sqlite-net-base package

Example

The following example provides an abbreviated code sample for using Microsoft Entity Framework Core where the key material is passed to via PRAGMA. Note that a fully functional referece application is included with each SQLCipher package to demonstrate library usage.

using Microsoft.EntityFrameworkCore;

...

public class Model
{
  [PrimaryKey,AutoIncrement]
  public int Id { get; set; }
  public string Content { get; set; }
}

...


public class SQLCipherDbContext : DbContext
{
    public string Filename {get; set;}
    public DbSet<Model> Records { get; set; }

    public SQLCipherDbContext(string filename)
    {
        Filename = filename;
    }

    protected override void OnConfiguring(DbContextOptionsBuilder optionsBuilder)
    {
        optionsBuilder.UseSqlite($"Filename={Filename}");
    }
}

...

context = new SQLCipherDbContext(filename);

var connection = context.Database.GetDbConnection();
connection.Open();
using (var command = connection.CreateCommand())
{
    command.CommandText = $"PRAGMA key = '{password}';";
    command.ExecuteNonQuery();
}

using (var command = connection.CreateCommand())
{
    command.CommandText = $"PRAGMA cipher_license = '{license}';";
    command.ExecuteNonQuery();
}

context.Database.EnsureCreated();

...

// use context

SQLCipher supports ADO.NET via the Microsoft.Data.Sqlite.Core version 3 library. To use this interface, add a NuGet dependency on Microsoft.Data.Sqlite.Core version 3.x or higher.

NuGet Package Requirements

To integrate Microsoft.EntityFrameworkCore.Sqlite.Core 3, configure the following Nuget packages:

  1. Microsoft.Data.Sqlite.Core version 3.x
  2. SQLitePCLRaw.bundle_zetetic version 2.x
  3. platform-specific SQLCipher packages
  4. ensure that there are no references to zetetic-sqlite-net-base package

Example

The following example provides an abbreviated code sample for using the ADO.NET Adapter where the key material is passed to via PRAGMA. Note that a fully functional referece application is included with each SQLCipher package to demonstrate library usage.

using Microsoft.Data.Sqlite;
using System.Data;

...

connection = (IDbConnection)new SqliteConnection($"Data Source={filename}");
connection.Open();

using (var command = _connection.CreateCommand())
{
    command.CommandText = $"PRAGMA key = '{password}';";
    command.ExecuteNonQuery();
}

using (var command = _connection.CreateCommand())
{
    command.CommandText = $"PRAGMA cipher_license = '{license}';";
    command.ExecuteNonQuery();
}

using (var command = _connection.CreateCommand())
{
    command.CommandText = "CREATE TABLE IF NOT EXISTS Model(id, a,b);";
    command.ExecuteNonQuery();
}

...

// use connection

Applications that are simultaneously targeting multiple platforms (e.g. Xamarin.iOS and Xamarin.Android, Windows 10 UAP, etc.), should place their shared data access code in a separate project that depends on the appropriate data access library. Then install the SQLCipher platform NuGet package(s) and the data access library at the platform-specific project level.

If you have addition comments or questions please contact us.

Buy SQLCipher for .NET Packages Now »