SQLitePCLRaw.bundle_e_sqlite3mc 2.1.10-pre20240828193256

SQLite3 Multiple Ciphers NuGet Package

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

Table of Contents

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

Usage

Because the bindings are built using SQLitePCLRaw, you can use them with various .NET libraries.

⚠️ Warning! Don't use multiple SQLitePCLRaw bundles in the same project.

Microsoft.Data.Sqlite

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.

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

For accessing a database encrypted with the default cipher scheme specifying just the name of the database file as the Data Source and the passphrase as the Password in the connection string is sufficient:

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

However, for database files encrypted with a non-default cipher scheme the connection string looks a bit different. The following examples illustrate two common use cases.

How to open an existing database encrypted with SQLCipher

If you want to access a database created for example by bundle_e_sqlcipher (or any other tool supporting the original SQLCipher cipher scheme), it is necessary to configure the cipher scheme on establishing the database connection, because SQLCipher is not the default cipher scheme.

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 SQLCipher two configuration parameters are required:

1. cipher=sqlcipher - select the SQLCipher cipher scheme
2. legacy=4 - select the current SQLCipher version 4 (in use since November 2018)

The resulting connection string looks like this:

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!");

Acknowledgements

The following people have contributed to SQLite3 Multiple Ciphers NuGet:

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

See also

• SQLite3 Multiple Ciphers
• Microsoft.Data.Sqlite
• SQLite-net