shield-core

EXPTIME-secure encryption library for Rust - symmetric cryptography with proven exponential-time security.

Why Shield?

Shield uses only symmetric primitives with EXPTIME-hard security guarantees. Breaking requires 2^256 operations - no shortcut exists:

• PBKDF2-SHA256 for key derivation (100,000 iterations)
• SHA256-based stream cipher (AES-256-CTR equivalent)
• HMAC-SHA256 for authentication

Installation

[dependencies]
shield-core = "2.2"

For WebAssembly:

[dependencies]
shield-core = { version = "2.2", features = ["wasm"] }

For Confidential Computing (TEE attestation):

[dependencies]
shield-core = { version = "2.2", features = ["confidential"] }

Quick Start

Basic Encryption

use shield_core::Shield;

// Password-based encryption
let shield = Shield::new("my_password", "github.com");
let encrypted = shield.encrypt(b"secret data")?;
let decrypted = shield.decrypt(&encrypted)?;

Pre-shared Key

use shield_core::{quick_encrypt, quick_decrypt};

let key = [0u8; 32]; // Your 32-byte key
let encrypted = quick_encrypt(&key, b"data")?;
let decrypted = quick_decrypt(&key, &encrypted)?;

Large File Encryption

use shield_core::StreamCipher;

let cipher = StreamCipher::from_password("password", b"salt");
let data = vec![0u8; 1024 * 1024]; // 1MB
let encrypted = cipher.encrypt(&data)?;
let decrypted = cipher.decrypt(&encrypted)?;

Forward Secrecy (Ratchet)

use shield_core::RatchetSession;

let root_key = [0u8; 32]; // Exchanged via secure channel

let mut alice = RatchetSession::new(&root_key, true);
let mut bob = RatchetSession::new(&root_key, false);

// Each message uses a new key
let encrypted = alice.encrypt(b"Hello Bob!")?;
let decrypted = bob.decrypt(&encrypted)?;

Features

• std (default): Standard library support
• cli (default): Command-line interface (shield binary)
• wasm: WebAssembly support via wasm-bindgen
• async: Async runtime support (Tokio)
• confidential: Confidential Computing with TEE attestation
• openapi: OpenAPI/Swagger schema generation for APIs

CLI Tool

# Install
cargo install shield-core

# Encrypt/decrypt files
shield encrypt secret.txt -o secret.enc
shield decrypt secret.enc -o secret.txt

# Check password strength
shield check "MyP@ssw0rd123"

# Encrypt text directly
shield text encrypt "hello" -p password -s service

# Generate random key
shield keygen

# Show info
shield info

Password Strength

use shield_core::password::{check_password, StrengthLevel};

let result = check_password("MyP@ssw0rd123");
println!("Entropy: {:.1} bits", result.entropy);
println!("Level: {:?}", result.level);  // Strong
println!("Crack time: {}", result.crack_time_display());

if !result.is_acceptable() {
    for suggestion in &result.suggestions {
        println!("Suggestion: {}", suggestion);
    }
}

Confidential Computing

Hardware-based attestation for Trusted Execution Environments (requires confidential feature).

Supported Platforms

Usage

use shield_core::confidential::{
    AttestationProvider, NitroAttestationProvider,
    TEEKeyManager, KeyReleasePolicy,
};
use std::sync::Arc;

// Create provider for your platform
let provider = Arc::new(NitroAttestationProvider::new()
    .with_expected_pcr(0, "expected_pcr0_hash")
    .with_max_age(300));

// Key manager with attestation gating
let key_manager = TEEKeyManager::new(
    "master_password",
    "my-service",
    provider,
);

// Get keys only after attestation verification
let key = key_manager.derive_key(&attestation_evidence).await?;

SGX Sealed Storage

use shield_core::confidential::{SealedStorage, SGXSealPolicy};

let storage = SealedStorage::new(SGXSealPolicy::MRENCLAVE);
storage.store("my_key", &secret_data).await?;
let data = storage.load("my_key").await?;

API Reference

Shield

Main encryption struct with password-derived keys.

impl Shield {
    fn new(password: &str, service: &str) -> Self;
    fn with_key(key: &[u8; 32]) -> Self;
    fn encrypt(&self, plaintext: &[u8]) -> Result<Vec<u8>>;
    fn decrypt(&self, ciphertext: &[u8]) -> Result<Vec<u8>>;
}

StreamCipher

Streaming encryption for large files.

impl StreamCipher {
    fn new(key: &[u8; 32]) -> Self;
    fn from_password(password: &str, salt: &[u8]) -> Self;
    fn encrypt(&self, data: &[u8]) -> Result<Vec<u8>>;
    fn decrypt(&self, encrypted: &[u8]) -> Result<Vec<u8>>;
}

RatchetSession

Forward secrecy with key ratcheting.

impl RatchetSession {
    fn new(root_key: &[u8; 32], is_initiator: bool) -> Self;
    fn encrypt(&mut self, plaintext: &[u8]) -> Result<Vec<u8>>;
    fn decrypt(&mut self, ciphertext: &[u8]) -> Result<Vec<u8>>;
}

PasswordStrength

Password strength analysis.

impl PasswordStrength {
    fn length: usize;           // Password length
    fn entropy: f64;            // Bits of entropy
    fn level: StrengthLevel;    // Critical/Weak/Fair/Strong/VeryStrong
    fn crack_time_seconds: f64; // Estimated crack time
    fn suggestions: Vec<String>;// Improvement suggestions
    fn is_acceptable(&self) -> bool;
    fn is_recommended(&self) -> bool;
    fn crack_time_display(&self) -> String;
}

Interoperability

Shield produces byte-identical output across all implementations:

• Python: pip install shield-crypto
• Rust: cargo add shield-core
• JavaScript: npm install @dikestra/shield

Security Model

Shield uses only symmetric primitives with unconditional security:

• Symmetric encryption (AES-256 equivalent)
• Hash functions (SHA-256)
• HMAC authentication (all MAC verifications use subtle::ConstantTimeEq)
• Key derivation (PBKDF2 + HMAC-SHA256 domain separation for enc_key/mac_key)
• Memory safety (Zeroize/ZeroizeOnDrop on all key-holding structs)

Breaking requires 2^256 operations - no shortcut exists.

v2.1 Security Hardening

Comprehensive hardening based on 189-finding security assessment:

• Key separation via HMAC-SHA256 domain labels (shield-encrypt / shield-authenticate)
• HMAC-SHA256 in all 13 internal modules (ratchet, rotation, group, identity, exchange, signatures)
• Counter overflow guards in all 8 keystream generators
• Timing-safe authentication preventing user enumeration
• 121 tests (106 unit + 7 interop + 8 doc-tests), clippy clean with -D warnings

Safety

This crate uses #![forbid(unsafe_code)] and relies on audited cryptographic libraries:

• ring for PBKDF2, HMAC-SHA256, and random number generation
• subtle for constant-time operations

License

MIT License - Use freely.

See Also

• Shield Python Package
• Shield npm Package
• GitHub Repository
• BENCHMARKS.md - Performance comparison vs AES-GCM
• MIGRATION.md - Migration from Fernet, NaCl, etc.