OutWit.Database.Core.BouncyCastle 1.0.0

OutWit.Database.Core.BouncyCastle

ChaCha20-Poly1305 encryption provider for WitDatabase using BouncyCastle.

This package provides an alternative encryption algorithm when AES-NI hardware acceleration is not available.

Installation

<PackageReference Include="OutWit.Database.Core.BouncyCastle" Version="1.0.0" />

Quick Start

Password-Based Encryption

using OutWit.Database.Core.Builder;
using OutWit.Database.Core.BouncyCastle;

var db = new WitDatabaseBuilder()
    .WithFilePath("encrypted.db")
    .WithBouncyCastleEncryption("my-secure-password")
    .WithBTree()
    .Build();

User + Password Encryption

var db = new WitDatabaseBuilder()
    .WithFilePath("encrypted.db")
    .WithBouncyCastleEncryption("username", "password")
    .WithBTree()
    .Build();

Raw Key Encryption

byte[] key = new byte[32]; // 256-bit key
RandomNumberGenerator.Fill(key);

var db = new WitDatabaseBuilder()
    .WithFilePath("encrypted.db")
    .WithBouncyCastleEncryption(key)
    .WithBTree()
    .Build();

Why ChaCha20-Poly1305?

Use ChaCha20-Poly1305 when:

• Running on hardware without AES-NI (older CPUs, some ARM devices)
• Running in Blazor WebAssembly (no hardware acceleration)
• Consistent performance across all platforms is important

Use AES-GCM (default) when:

• Running on modern x86/x64 CPUs with AES-NI
• Maximum performance is required

API Reference

WitDatabaseBuilder Extensions

// Password-based encryption (PBKDF2 key derivation)
builder.WithBouncyCastleEncryption(string password)

// User + password encryption
builder.WithBouncyCastleEncryption(string user, string password)

// Raw 256-bit key
builder.WithBouncyCastleEncryption(byte[] key)

// Raw key with custom salt
builder.WithBouncyCastleEncryption(byte[] key, byte[] salt)

BouncyCastleCryptoProvider

// Create provider with raw key
var provider = new BouncyCastleCryptoProvider(key);

// Create provider from password
var provider = BouncyCastleCryptoProvider.FromPassword(
    password: "secret",
    salt: saltBytes,
    iterations: 100_000
);

// Properties
provider.NonceSize   // 12 bytes
provider.TagSize     // 16 bytes
provider.ProviderKey // "chacha20-poly1305"

Security Details

Key Derivation

• Algorithm: PBKDF2-SHA256
• Iterations: 100,000 (default)
• Key size: 256 bits
• Salt size: 16 bytes (derived from password or user)

Encryption

• Algorithm: ChaCha20-Poly1305
• Key size: 256 bits
• Nonce size: 96 bits (12 bytes)
• Authentication tag: 128 bits (16 bytes)

Memory Safety

• Uses ArrayPool<T> for temporary buffers (reduced GC pressure)
• Sensitive data is zeroed after use via CryptographicOperations.ZeroMemory
• Key material is securely cleared on Dispose()

Blazor WebAssembly Support

ChaCha20-Poly1305 works well in Blazor WebAssembly where hardware AES acceleration is not available:

var db = new WitDatabaseBuilder()
    .WithIndexedDbStorage("MyDatabase", JSRuntime)
    .WithBouncyCastleEncryption("password")
    .WithBTree()
    .Build();

Dependencies

Related Projects

License

Licensed under the Apache License, Version 2.0. See LICENSE.

Attribution (optional)

If you use OutWit.Database.Core.BouncyCastle in a product, a mention is appreciated (but not required), for example: "Powered by WitDatabase https://witdatabase.io/".

Trademark / Project name

"WitDatabase" and the WitDatabase logo are used to identify the official project by Dmitry Ratner.

You may:

• refer to the project name in a factual way (e.g., "built with WitDatabase");
• use the name to indicate compatibility (e.g., "WitDatabase-compatible").

You may not:

• use "WitDatabase" as the name of a fork or a derived product in a way that implies it is the official project;
• use the WitDatabase logo to promote forks or derived products without permission.

See Also

• OutWit.Database.Core - Core database library
• OutWit.Database.Core.IndexedDb - Blazor WASM support
• BouncyCastle - Cryptography library
• ROADMAP.md - Version 2.0 planned features
• ROADMAP.md - Main project roadmap