SQLCipher for .NET

SQLCipher for .NET encompases a set of packages that provide full database encryption for Microsoft .NET technologies, including Windows, Windows 10 UAP, Xamarin.iOS, Xamarin.Android, and WinRT 8.1. 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 2.x
  • Microsoft's ADO.NET implementation via Microsoft.Data.Sqlite.Core 2.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 »

Project Setup

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 NuGet references to sqlite-net or sqlite-net-pcl

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

SQLCipher Package Integration

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();

Client Library Integration

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.

sqlite-net

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(filename, true, password))

conn.ExecuteScalar(String.Format("PRAGMA cipher_license = '{0}';", licenseKey));

conn.CreateTable();

...

// use SQLiteConnection 

Microsoft Entity Framework Core

SQLCipher supports the use of Microsoft Entity Framework Core. To use this interface, add a NuGet dependency on Microsoft.EntityFrameworkCore.Sqlite.Core version 2.x or higher.

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 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 

Microsoft ADO.NET

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

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

Cross-platform Projects

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.

Additional Questions

If you have addition comments or questions please contact us.

Buy SQLCipher for .NET Packages Now »