SQLite3 Multiple Ciphers NuGet

This library provides C#/.NET bindings for SQLite3 Multiple Ciphers. It leverages SQLitePCLRaw to create the bindings.

In teamwork with Brice Lambson and Eric Sink this library has been made a part of the main SQLitePCLRaw project and is released as NuGet package SQLitePCLRaw.bundle_e_sqlite3mc.

Table of Contents

• Version
• Installation
• Usage
• Passphrase based database encryption support
• Examples for cipher configuration
• License
• Acknowledgements
• See also

Version

Installation

The latest version is available on NuGet.

dotnet add package SQLitePCLRaw.bundle_sqlite3mc

:warning: Warning! Don't use multiple SQLitePCLRaw bundles in the same project. See the instructions below for details.

Usage

For Microsoft.Data.Sqlite, be sure to use the Microsoft.Data.Sqlite.Core package instead of the main one to avoid using multiple bundles.

using Microsoft.Data.Sqlite;

using var connection = new SqliteConnection("Data Source=example.db;Password=Password12!");
connection.Open();

var command = connection.CreateCommand();
command.CommandText = "select sqlite3mc_version()";
var version = (string)command.ExecuteScalar()!;

Console.WriteLine(version);

Dapper

Use Dapper with Microsoft.Data.Sqlite by following the same instructions detailed above.

using Dapper;
using Microsoft.Data.Sqlite;

using var connection = new SqliteConnection("Data Source=example.db;Password=Password12!");
var version = connection.ExecuteScalar<string>("select sqlite3mc_version()");
Console.WriteLine(version);

EF Core

EF Core is built on top of Microsoft.Data.Sqlite. Be sure to use the Microsoft.EntityFrameworkCore.Sqlite.Core package instead of the main one to avoid using multiple bundles.

options.UseSqlite("Data Source=example.db;Password=Password12!");

SQLite-net

With SQLite-net, be sure to use the sqlite-net-base package instead of the main one to avoid using multiple bundles.

using SQLite;

SQLitePCL.Batteries_V2.Init();

var connection = new SQLiteConnection(new("example.db", storeDateTimeAsTicks: true, key: "Password12!"));
var version = connection.ExecuteScalar<string>("select sqlite3mc_version()");
Console.WriteLine(version);

Low-level bindings

If you really want to use the low-level bindings directly, you can. But these are primarly intended to be used by libraries like Microsoft.Data.Sqlite and SQLite-net.

using static SQLitePCL.raw;

SQLitePCL.Batteries_V2.Init();

var rc = sqlite3_open("example.db", out var db);
if (rc != SQLITE_OK) return;
using (db)
{
    rc = sqlite3_key(db, "Password12!"u8);
    if (rc != SQLITE_OK) return;

    rc = sqlite3_prepare_v2(db, "select sqlite3mc_version()", out var stmt);
    if (rc != SQLITE_OK) return;
    using (stmt)
    {
        rc = sqlite3_step(stmt);
        if (rc != SQLITE_ROW) return;

        var version = sqlite3_column_text(stmt, 0).utf8_to_string();
        Console.WriteLine(version);
    }
}

Passphrase based database encryption support

This NuGet package supports access to encrypted SQLite databases from .NET applications. It is based on the project SQLite3 Multiple Ciphers.

SQLite3 Multiple Ciphers is an extension to the public domain version of SQLite that allows applications to read and write encrypted database files. Currently 5 different encryption cipher schemes are supported:

• wxSQLite3: AES 128 Bit CBC - No HMAC
• wxSQLite3: AES 256 Bit CBC - No HMAC
  Use of the wxSQLite3 ciphers is not recommended for new projects.
• sqleet: ChaCha20 - Poly1305 HMAC
  This cipher scheme is currently the default cipher scheme.
• SQLCipher: AES 256 Bit CBC - SHA1/SHA256/SHA512 HMAC
  All SQLCipher variants (from version 1 up to version 4) can be accessed.
• System.Data.SQLite: RC4
  Supported for compatibility with earlier System.Data.SQLite versions only. Don't use it in new projects. Since early 2020 the official System.Data.SQLite distribution no longer includes the RC4 encryption extension.
• Ascon: Ascon-128 v1.2
  Ascon has been selected as new standard for lightweight cryptography in the NIST Lightweight Cryptography competition (2019–2023).

In addition to reading and writing encrypted database files it is also possible to read and write plain unencrypted database files.

SQLite3 Multiple Ciphers transparently encrypts the entire database file, so that an encrypted SQLite database file appears to be white noise to an outside observer. Not only the database files themselves, but also journal files are encrypted.

For a detailed documentation of the currently supported cipher schemes, their configuration options, and the SQL interface please consult the SQLite3MultipleCiphers website.

Examples for cipher configuration

using var connection = new SqliteConnection("Data Source=example.db;Password=Password12!");

using var connection = new SqliteConnection("Data Source=file:example.db?cipher=sqlcipher&legacy=4;Password=Password12!");

Note:
For prior SQLCipher versions use the matching version number as the value of the legacy parameter. For non-default SQLCipher encryption variants you may need to specify additional parameters. For a detailed list of parameters see the SQLite3 Multiple Ciphers documentation.

How to open an existing database that was encrypted with System.Data.SQLite

If you want to access a database created for example by System.Data.SQLite, it is again necessary to configure the cipher scheme on establishing the database connection.

The easiest approach to accomplish this is to specify the data source in the connection string as a Uniform Resource Identifier (URI) including the required configuration parameters as URI parameters. In case of System.Data.SQLITE RC4 one or two configuration parameters are required:

1. cipher=rc4 - select the System.Data.SQLITE RC4 cipher scheme
2. legacy_page_size=<page size in bytes> - optional, if the database uses the default SQLite page size (currently 4096 bytes); required, if a non-default page size is used.

The resulting connection string looks like this:

using var connection = new SqliteConnection("Data Source=file:example.db?cipher=rc4;Password=Password12!");

License

SQLite3 Multiple Ciphers NuGet is free software and is licensed under the MIT license.

Acknowledgements

• Brice Lambson
• Josh Menzel
• Eric Sink
• Ulrich Telle

See also

• SQLite3 Multiple Ciphers
• Microsoft.Data.Sqlite
• SQLite-net
• More SQLite Encryption in .NET