Cryptography

Sentinel includes a comprehensive cryptography module that provides hashing, digital signatures, encryption, and key derivation. This guide explains the available algorithms, how to configure them, and when to use each one.

Overview

The Sentinel crypto module (sentinel-crypto) provides four categories of cryptographic operations:

1. Hashing: Compute content hashes for integrity verification
2. Signing: Create and verify digital signatures for tamper evidence
3. Encryption: Encrypt and decrypt sensitive data with multiple algorithm options
4. Key Derivation: Derive encryption keys from passphrases

Each category has multiple algorithm choices, allowing you to balance security, performance, and compatibility for your use case.

Global Configuration

Cryptographic algorithms are configured globally using CryptoConfig:

use sentinel_dbms::{
    CryptoConfig,
    HashAlgorithmChoice,
    SignatureAlgorithmChoice,
    EncryptionAlgorithmChoice,
    KeyDerivationAlgorithmChoice,
    set_global_crypto_config,
};

fn main() {
    let config = CryptoConfig {
        hash_algorithm: HashAlgorithmChoice::Blake3,
        signature_algorithm: SignatureAlgorithmChoice::Ed25519,
        encryption_algorithm: EncryptionAlgorithmChoice::XChaCha20Poly1305,
        key_derivation_algorithm: KeyDerivationAlgorithmChoice::Argon2id,
    };

    // Must be called before any crypto operations
    set_global_crypto_config(config).expect("Config must be set once");
}

The configuration can only be set once per process. Attempting to set it again will emit a warning and the original configuration will remain in effect.

Default Configuration

If you don’t set a configuration, Sentinel uses secure defaults:

These defaults provide excellent security and performance for most use cases.

Hashing

Sentinel uses hashing to create content fingerprints for integrity verification.

BLAKE3 (Default and Only Option)

BLAKE3 is a modern, high-performance cryptographic hash function:

use sentinel_dbms::hash_data;
use serde_json::json;

let data = json!({"key": "value", "number": 42});
let hash = hash_data(&data)?;

println!("Hash: {}", hash);  // 64-character hex string

BLAKE3 provides several advantages over older hash functions:

• Security: 256-bit security with protection against length-extension attacks
• Performance: Significantly faster than SHA-256 while maintaining equivalent security
• Parallelism: Supports parallel computation for large inputs
• Deterministic: Same input always produces same output

All documents in Sentinel automatically include a BLAKE3 hash of their data field, enabling you to verify integrity at any time.

Digital Signatures

Signatures provide tamper-evident storage by cryptographically binding documents to a signing key.

Ed25519 (Default and Only Option)

Ed25519 is a modern elliptic curve signature scheme:

use sentinel_dbms::{sign_hash, verify_signature, SigningKeyManager};

// Generate a signing key
let key = SigningKeyManager::generate_key();

// Sign a hash
let hash = "a1b2c3d4...";
let signature = sign_hash(hash, &key)?;

// Verify the signature
let public_key = key.verifying_key();
let is_valid = verify_signature(hash, &signature, &public_key)?;

assert!(is_valid);

Ed25519 provides several benefits:

• Security: 128-bit security level
• Performance: Fast signing and verification operations
• Compactness: Signatures are 64 bytes, private keys are 32 bytes
• Deterministic: Same message and key always produce same signature
• Batch Verification: Efficient for verifying multiple signatures at once

When you create a Store with a passphrase, Sentinel generates an Ed25519 signing key and uses it to sign all documents automatically.

Encryption

Sentinel supports three authenticated encryption algorithms for protecting sensitive data. Each algorithm provides different trade-offs between security, performance, and hardware acceleration.

XChaCha20-Poly1305 (Default)

The default encryption algorithm provides excellent security with nonce misuse resistance:

use sentinel_dbms::{encrypt_data, decrypt_data, EncryptionKeyManager};

let key = EncryptionKeyManager::generate_key();
let plaintext = b"sensitive data";

// Encrypt
let ciphertext = encrypt_data(plaintext, &key)?;

// Decrypt
let decrypted = decrypt_data(&ciphertext, &key)?;

assert_eq!(plaintext, decrypted.as_slice());

Characteristics:

• Nonce Size: 24 bytes (extended nonce for random nonce generation)
• Security: 256-bit security
• Performance: Fast on all platforms
• Hardware: No special acceleration needed
• Nonce Safety: Extended nonce makes accidental reuse extremely unlikely

XChaCha20-Poly1305 is recommended for general use due to its excellent security profile and good performance across all platforms.

AES-256-GCM-SIV

An alternative with hardware acceleration on supporting CPUs:

use sentinel_dbms::{
    CryptoConfig,
    EncryptionAlgorithmChoice,
    set_global_crypto_config,
};

let config = CryptoConfig {
    encryption_algorithm: EncryptionAlgorithmChoice::Aes256GcmSiv,
    ..Default::default()
};

set_global_crypto_config(config).expect("Config set once");

Characteristics:

• Nonce Size: 12 bytes (standard GCM nonce)
• Security: 256-bit security with nonce misuse resistance
• Performance: Very fast with hardware AES acceleration (AES-NI)
• Hardware: Benefits from AES-NI instruction set
• Nonce Safety: SIV mode provides nonce misuse resistance

AES-256-GCM-SIV is a good choice when hardware AES acceleration is available and performance is critical.

Ascon-128

A lightweight cipher suitable for constrained environments:

use sentinel_dbms::{
    CryptoConfig,
    EncryptionAlgorithmChoice,
    set_global_crypto_config,
};

let config = CryptoConfig {
    encryption_algorithm: EncryptionAlgorithmChoice::Ascon128,
    ..Default::default()
};

set_global_crypto_config(config).expect("Config set once");

Characteristics:

• Nonce Size: 16 bytes
• Security: 128-bit security
• Performance: Moderate speed
• Hardware: No special acceleration needed
• Size: Optimized for resource-constrained environments

Ascon was selected as the winner of the NIST Lightweight Cryptography competition. It’s designed for resource-constrained environments like embedded systems and IoT devices, while still providing strong security.

Encryption Algorithm Comparison

*With hardware AES support

Key Derivation

Key derivation functions convert passphrases into cryptographic keys suitable for encryption.

Argon2id (Default)

The default and recommended key derivation function:

use sentinel_dbms::{derive_key_from_passphrase, derive_key_from_passphrase_with_salt};

// Derive a key with a new random salt
let (salt, key) = derive_key_from_passphrase("my-secret-passphrase")?;

// Re-derive with same salt
let same_key = derive_key_from_passphrase_with_salt("my-secret-passphrase", &salt)?;

assert_eq!(key, same_key);

Characteristics:

• Security: Excellent protection against GPU-based and side-channel attacks
• Memory Hard: Expensive to attack with specialized hardware
• Configurable: Memory and parallelism can be tuned
• Standard: Won the Password Hashing Competition

Argon2id is the recommended choice for security-critical applications.

PBKDF2

A widely-supported alternative for compatibility:

use sentinel_dbms::{
    CryptoConfig,
    KeyDerivationAlgorithmChoice,
    set_global_crypto_config,
};

let config = CryptoConfig {
    key_derivation_algorithm: KeyDerivationAlgorithmChoice::Pbkdf2,
    ..Default::default()
};

set_global_crypto_config(config).expect("Config set once");

Characteristics:

• Security: Good protection against brute-force attacks
• Memory: Low memory usage
• Performance: Fast computation
• Compatibility: Supported in nearly every cryptographic library

PBKDF2 is suitable when you need interoperability with other systems. However, it’s less resistant to hardware-accelerated attacks than Argon2id.

Key Derivation Comparison

Using Cryptography with Stores

When you create a store with a passphrase, Sentinel uses the configured key derivation and encryption algorithms automatically:

use sentinel_dbms::Store;

#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error>> {
    // Sentinel will:
    // 1. Use Argon2id to derive key from passphrase (default)
    // 2. Use XChaCha20-Poly1305 to encrypt the signing key (default)
    // 3. Use Ed25519 for signing documents (default)
    let store = Store::new("./secure-data", Some("my-passphrase")).await?;

    Ok(())
}

You can customize these algorithms by setting the global crypto configuration before creating the store.

Manual Cryptographic Operations

You can also use cryptographic operations directly without going through Store:

use sentinel_dbms::{
    hash_data,
    sign_hash,
    verify_signature,
    encrypt_data,
    decrypt_data,
    derive_key_from_passphrase,
    SigningKeyManager,
    EncryptionKeyManager,
};
use serde_json::json;

// Hash data
let data = json!({"sensitive": "information"});
let hash = hash_data(&data)?;

// Sign with a key
let signing_key = SigningKeyManager::generate_key();
let signature = sign_hash(&hash, &signing_key)?;

// Verify the signature
let public_key = signing_key.verifying_key();
let is_valid = verify_signature(&hash, &signature, &public_key)?;

// Encrypt data
let encryption_key = EncryptionKeyManager::generate_key();
let plaintext = b"secret message";
let ciphertext = encrypt_data(plaintext, &encryption_key)?;

// Decrypt data
let decrypted = decrypt_data(&ciphertext, &encryption_key)?;

assert_eq!(plaintext, decrypted.as_slice());

Security Considerations

When using Sentinel’s cryptography module, keep these security principles in mind:

• Never hardcode passphrases. Load them from environment variables, secret managers, or secure configuration files.

• Use defaults unless you have specific requirements. The default algorithms provide excellent security for most use cases.

• Understand trade-offs. Stronger algorithms may be slower. Choose based on your security requirements and performance constraints.

• Protect your signing keys. The passphrase-derived key stored in .keys/ is encrypted, but the passphrase itself must remain secret.

• Verify signatures when consuming data. If documents should be signed, verify signatures before trusting the data.

• Secure key storage. Use environment variables or secret managers to pass passphrases to your application, not command-line arguments or config files.

• Rotate keys periodically. Consider key rotation policies for long-running systems.

• Use appropriate algorithms for your environment. Choose Ascon for embedded systems, AES-256-GCM-SIV for systems with hardware acceleration, and XChaCha20-Poly1305 for general use.

Algorithm Selection Guide

Use this guide to choose the right algorithms for your use case:

For General Applications

Use the defaults (BLAKE3, Ed25519, XChaCha20-Poly1305, Argon2id):

• Web applications
• Desktop applications
• Server-side services
• Most use cases

For High-Performance Environments

Use AES-256-GCM-SIV for encryption:

• Systems with AES-NI support
• High-throughput data processing
• Real-time systems
• Cloud instances with CPU acceleration

For Embedded Systems

Use Ascon-128 for encryption:

• IoT devices
• Embedded controllers
• Resource-constrained environments
• Battery-powered devices

For Interoperability

Use PBKDF2 for key derivation:

• Systems needing compatibility with other cryptographic libraries
• Legacy integration
• Cross-platform consistency requirements

For Maximum Security

Use Argon2id for key derivation and configure it with high memory and time parameters:

• High-value data protection
• Regulatory compliance
• Security-critical infrastructure

Next Steps

Now that you understand Sentinel’s cryptography options, explore:

• Store: How signing integrates with stores
• Document: How hashing and signatures protect documents
• Error Handling: Handling cryptographic errors
• Verification Options: Configuring verification behavior