Rose-Squared SDK

Privacy-preserving encrypted search SDK implementing the SWiSSSE protocol with forward/backward security and volume-hiding, compilable to WebAssembly.

Overview

Rose-Squared SDK enables developers to build applications with searchable encrypted data vaults. Store sensitive data on untrusted servers while maintaining the ability to search by keyword — without ever revealing what you're searching for, which documents match, or even how many results exist.

Built on state-of-the-art academic cryptographic protocols, this SDK handles all the complexity of encryption, key management, and private search protocols, allowing you to focus on your application's core functionality.

Key Features

🔒 Strong Security Guarantees

• Forward Security — Search tokens generated at time T cannot discover documents added after T
• Backward Security Type-II — Deleted documents are permanently unreachable via epoch rotation
• Volume Hiding — Every operation has exactly N_max entries (default 256); servers cannot distinguish result counts
• Tamper Detection — AES-256-GCM authentication tags detect server-side corruption or forgery
• Memory Safety — All secret keys derive ZeroizeOnDrop, automatically wiped from RAM on scope exit
• Zero Unsafe Code — #![forbid(unsafe_code)] enforced across the entire codebase

⚡ High Performance

• O(1) Server Complexity — Direct hash-map lookups, not scans or linked-list traversals
• Efficient Cryptographic Primitives — Argon2id + HKDF key derivation, AES-256-GCM encryption
• WASM-Optimized — Compiled to WebAssembly with LTO and size optimizations for browser use

🌐 WebAssembly Support

• Browser-Ready — Compile to WASM with wasm-pack build --target web --features wasm
• IndexedDB Integration — Persistent client-side state storage in the browser
• Async JavaScript API — Clean WasmVault class with Promise-based methods

🗄️ Pluggable Storage

• EncryptedStore Trait — Implement your own backend (IndexedDB, SQLite, Redis, S3, etc.)
• MockStore Included — HashMap-backed store for testing and development
• State Persistence — Encrypted index can be persisted locally or on remote servers

Architecture

rose-squared-sdk/
├── crypto/           # Primitives: KDF (Argon2id+HKDF), AEAD (AES-256-GCM)
├── client/           # KeywordState, TrapdoorEngine, UpdateEngine
├── server/           # EncryptedStore trait + MockStore
├── protocol/         # SearchProtocol, SWiSSSE volume padding
├── wasm/             # WASM bindings and IndexedDB store
├── vault.rs          # PrivacyVault: the public API
└── error.rs          # VaultError types

Cryptographic Protocols

This SDK implements the SWiSSSE (System-Wide Security for Searchable Symmetric Encryption) protocol, published in PoPETS 2024, with enhancements from the RO(SE)² framework for O(1) search complexity and forward/backward security.

Quick Start

Add to Your Project

[dependencies]
rose-squared-sdk = "0.1.0"

Basic Usage (Native Rust)

use rose_squared_sdk::{PrivacyVault, VolumeConfig};

// Initialize a new vault with a password
let password = "secure_password_here";
let config = VolumeConfig::default(); // N_max = 256
let vault = PrivacyVault::new(password, config)?;

// Add a document with keywords
vault.add_document(
    "doc_uuid_1",
    "My Secret Document",
    &["rust", "privacy", "encryption"]
)?;

// Search for documents
let results = vault.search("privacy")?;
println!("Found {} documents", results.len());

// Delete a document
vault.delete_document("doc_uuid_1", &["rust", "privacy", "encryption"])?;

WebAssembly Usage (Browser)

# Build for WASM
wasm-pack build --target web --features wasm

import { WasmVault } from 'rose-squared-sdk';

const vault = new WasmVault();
await vault.initialize('my_secure_password');

await vault.addDocument('doc_1', 'Secret Notes', ['rust', 'privacy']);
const results = await vault.search('privacy');
console.log(`Found ${results.length} documents`);

Cryptographic Flow

1. Initialization — Password + salt → Argon2id (64 MiB, 3 iterations) → 256-bit root key → HKDF-SHA256 fans out into 4 sub-keys (K_tag, K_val, K_state, K_srch)

2. Add Document — For each keyword: increment total_writes, derive HMAC-based tag, encrypt payload with AES-256-GCM, pad to N_max with decoy entries, write to server

3. Search — Look up live indices, generate (tag, key) pairs, pad with dummy entries, Fisher-Yates shuffle, send to server, decrypt matching results

4. Delete Document — Collect old-epoch tags, evict from live indices, bump epoch, re-encrypt survivors under new epoch, atomic update on server

Use Cases

• 📔 Secure Journaling — Store journal entries encrypted, search by keyword without the provider reading them
• 📝 Private Note-Taking — Ideas and sensitive information in a searchable private vault
• 🔑 Password Managers — Store and search passwords by website/service name securely
• 🏥 Healthcare Records — HIPAA-compliant patient record search
• ⚖️ Legal Documents — GDPR-compliant document management with cryptographic "Right to be Forgotten"
• 💬 Secure Messaging — Private message history search in chat applications

Configuration

VolumeConfig

Control the volume-hiding behavior:

use rose_squared_sdk::VolumeConfig;

let config = VolumeConfig {
    n_max: 256,  // Pad all operations to 256 entries
};

• Larger N_max = better privacy, more bandwidth/storage overhead
• Smaller N_max = faster operations, weaker volume hiding
• Default: 256 (recommended for most use cases)

Building from Source

Prerequisites

• Rust 1.70+ (Edition 2021)
• For WASM: wasm-pack (cargo install wasm-pack)

Native Build

# Clone the repository
git clone https://github.com/adithya-adee/rose-squared-sdk.git
cd rose-squared-sdk

# Run tests
cargo test

# Build
cargo build --release

WASM Build

# Install wasm-pack if not already installed
cargo install wasm-pack

# Build for web
wasm-pack build --target web --features wasm

# Output in pkg/ directory, ready for npm or direct browser use

Run Examples

# SQLite example (requires rusqlite)
cargo run --example sqlite_store

Testing

# Run all tests
cargo test

# Run with verbose output
cargo test -- --nocapture

# Run specific test module
cargo test crypto::

Security Considerations

What the Server Cannot Learn

• 🔍 Search queries — Keywords being searched are hidden via trapdoor tokens
• 📄 Document contents — All data encrypted with AES-256-GCM
• 🔗 Access patterns — Forward/backward security prevents linking operations
• 📊 Result counts — Volume hiding pads all operations to constant size

What You Must Protect

• 🔑 Client-side password — Compromise reveals all data
• 💾 ClientStateTable — If lost without backup, data becomes unrecoverable
• ⚠️ Search token reuse — Using same token enables server-side query linking

Limitations

• Not designed for multi-writer scenarios (single user per vault)
• Client state must be maintained for forward/backward security
• Volume padding introduces bandwidth overhead (N_max entries per operation)

API Documentation

• API Reference (docs.rs)
• Academic Paper (PDF)

Roadmap

✅ Completed (v0.1.0)

• RO(SE)² protocol implementation
• SWiSSSE volume hiding
• Forward and backward security
• WASM bindings
• IndexedDB integration
• Crash recovery mechanism

🚧 Planned

• SQLite backend for native apps
• Redis backend for distributed systems
• S3-compatible object storage backend
• Adaptive N_max based on dataset analysis
• Multi-keyword boolean queries (AND/OR)
• Fuzzy search support

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License — see the LICENSE file for details.

Author

Adithya — GitHub

Acknowledgments

This SDK is based on the following academic papers:

• RO(SE)²: "A Robust, Secure, and Efficient Searchable Encryption Scheme" — IEEE Transactions on Computers, January 2025
• SWiSSSE: "System-Wide Security for Searchable Symmetric Encryption" — PoPETS 2024