Shield

Misuse-resistant authenticated encryption on a standard AEAD core (AES-256-GCM / ChaCha20-Poly1305), byte-identical across 12 language bindings, with an optional post-quantum hybrid key exchange (X25519 + ML-KEM-768, FIPS 203). The symmetric core uses no RSA/ECC, so it is unaffected by attacks on asymmetric crypto; 256-bit keys give ~128-bit post-quantum security.

pip install shield-crypto    # Python
npm install @dikestra/shield   # JavaScript
go get github.com/Dikestra-ai/shield  # Go

The 30-Second Version

from shield import Shield

# Encrypt
s = Shield("your-password", "your-app.com")
encrypted = s.encrypt(b"secret data")

# Decrypt
decrypted = s.decrypt(encrypted)

That's it. No keys to manage. No certificates. No configuration.

---

Why Shield?

Current encryption will break. Not "might" - will.

Threat	RSA/ECDSA	Shield
P=NP proven	Broken	Not directly helped (no asymmetric structure to exploit)
Quantum computer	Broken	~128-bit post-quantum (Grover halves the key)
2^128 brute force	Broken	Infeasible
2^256 brute force	Broken	Infeasible

Shield uses only symmetric cryptography with 256-bit keys. P=NP would break RSA/ECDSA, but brute-forcing a random 256-bit symmetric key has no structure for a polynomial algorithm to exploit, so a P=NP result would not directly help. Brute force requires 2^256 operations — note this is a claim that rests on standard assumptions about SHA-256/HMAC, not a mathematical proof.

---

Quick Start

Python

pip install shield-crypto

from shield import Shield, TOTP, RatchetSession

# Basic encryption
s = Shield("password", "myapp.com")
encrypted = s.encrypt(b"Hello, World!")
decrypted = s.decrypt(encrypted)

# Two-factor authentication
totp = TOTP(TOTP.generate_secret())
code = totp.generate()  # "847293"
totp.verify(code)       # True

# Forward secrecy (messaging)
alice = RatchetSession(shared_key, is_initiator=True)
bob = RatchetSession(shared_key, is_initiator=False)
encrypted = alice.encrypt(b"Hi Bob!")
decrypted = bob.decrypt(encrypted)

JavaScript

npm install @dikestra/shield

const { Shield, TOTP, RatchetSession } = require('@dikestra/shield');

// Basic encryption
const s = new Shield('password', 'myapp.com');
const encrypted = s.encrypt(Buffer.from('Hello, World!'));
const decrypted = s.decrypt(encrypted);

// Two-factor authentication
const totp = new TOTP(TOTP.generateSecret());
const code = totp.generate();  // "847293"
totp.verify(code);             // true

Go

go get github.com/Dikestra-ai/shield

import "github.com/Dikestra-ai/shield/shield"

// Basic encryption
s := shield.New("password", "myapp.com", nil)
encrypted, _ := s.Encrypt([]byte("Hello, World!"))
decrypted, _ := s.Decrypt(encrypted)

// Two-factor authentication
secret := shield.GenerateTOTPSecret()
totp := shield.NewTOTP(secret)
code := totp.Generate(time.Now().Unix())

All Languages

Language	Install	Docs
Python	pip install shield-crypto	python/
JavaScript	npm install @dikestra/shield	javascript/
Go	go get github.com/Dikestra-ai/shield	go/
C	make in c/	c/
Java	Gradle: ai.dikestra:shield	java/
C#	NuGet: Dikestra.Shield	csharp/
Swift	Swift Package	swift/
Kotlin	Gradle: ai.dikestra:shield	kotlin/
WebAssembly	wasm-pack build	wasm/
Browser	npm install @dikestra/shield-browser	browser/
Android	Gradle: ai.dikestra:shield-android	android/
iOS	CocoaPods / SPM	ios/

---

Features

Feature	What it does	Use case
Shield	Password-based encryption	Storing secrets
quickEncrypt	Key-based encryption	Pre-shared keys
StreamCipher	Large file encryption	Gigabyte files
RatchetSession	Forward secrecy	Messaging apps
TOTP	Time-based 2FA codes	Login security
RecoveryCodes	Backup 2FA codes	Account recovery
SymmetricSignature	HMAC signatures	API authentication
LamportSignature	Quantum-safe signatures	Long-term documents
Post-quantum hybrid KEX	X25519 + ML-KEM-768 (FIPS 203) key agreement	Post-quantum key exchange
KeyRotationManager	Key versioning	Zero-downtime rotation
GroupEncryption	Multi-recipient	Team messaging
IdentityProvider	Token-based auth	SSO systems
check_password	Password strength	Prevent weak passwords
Secure Transport (Rust)
ShieldChannel	TLS-like secure channel	Encrypted TCP/streams
AsyncShieldChannel	Async secure channel	Tokio-based networking
Web Integrations (Python)
ShieldMiddleware	FastAPI encryption	API response encryption
ShieldFlask	Flask extension	Flask app encryption
RateLimiter	Rate limiting	API protection
EncryptedCookie	Secure cookies	Session management
BrowserBridge	Browser key exchange	Client-side decryption
Browser SDK
ShieldBrowser	Auto-decrypt fetch()	Transparent browser encryption
Shield Proxy (Rust)
shield-proxy	Transparent encryption proxy	Network-layer Shield appliance
DNS Forwarder	Multi-upstream DNS failover	Resilient DNS resolution
Hot Redundancy	Active/standby heartbeat	Zero-downtime failover

---

Feature Matrix

Not all features are available in all languages. Here's what's supported:

Core Features (All Languages)

Feature	Rust	Python	JS	Go	Java	C#	Swift	Kotlin	C	Android	iOS
Shield	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
quickEncrypt	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
RatchetSession	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
TOTP	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
RecoveryCodes	✅	✅	✅	✅	✅	✅	✅	✅	-	✅	✅
SymmetricSignature	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅
LamportSignature	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅	✅

Advanced Features

Feature	Rust	Python	JS	Go	Java	C#	Swift	Kotlin	C
StreamCipher	✅	✅	✅	✅	-	-	-	-	-
GroupEncryption	✅	✅	✅	✅	-	-	-	-	-
KeyRotationManager	✅	✅	✅	✅	-	-	-	-	-
IdentityProvider	✅	✅	✅	✅	-	-	-	-	-
PAKEExchange¹	✅	✅	✅	✅	-	-	-	-	-
QRExchange	✅	✅	✅	✅	-	-	-	-	-
KeySplitter	✅	✅	✅	✅	-	-	-	-	-
check_password	✅	✅	✅	✅	-	-	-	-	-

¹ PAKEExchange / ShieldChannel is a pre-shared-key handshake, not a true PAKE despite the name. It sends a deterministic, password-derived contribution on the wire, so a recorded handshake permits an offline dictionary attack against a low-entropy secret. Use it only with a high-entropy shared secret. For password-based or forward-secret key establishment, use the X25519 + ML-KEM-768 hybrid KEX (pq feature). See PROTOCOL.md §3.2.

Platform-Specific Features

Feature	Platform	Description
ShieldChannel	Rust	TLS-like secure transport
AsyncShieldChannel	Rust	Tokio-based async transport
SecureKeyStore	Android	Hardware-backed key storage (TEE/StrongBox)
SecureKeychain	iOS	Keychain + Face ID/Touch ID
ShieldMiddleware	Python	FastAPI integration
ShieldFlask	Python	Flask extension
ShieldBrowser	Browser	Auto-decrypt fetch() responses

Language Tiers

• Tier 1 (Full Features): Rust, Python, JavaScript, Go
• Tier 2 (Core Features): Java, C#, Swift, Kotlin, C
• Tier 3 (Platform-Optimized): Android, iOS, Browser, WASM

---

The Note Test

"Give your friend a note with these instructions. Will they know what to do?"

Encrypt a file

shield encrypt secret.txt -o secret.enc
# Enter password when prompted

Decrypt a file

shield decrypt secret.enc -o secret.txt
# Enter same password

Check password strength

shield check "MyP@ssw0rd123"
# Output: STRONG - 72.3 bits entropy

Encrypt text directly

shield text encrypt "secret message" -p password -s myapp
# Output: hex-encoded ciphertext

Generate a secure key

shield keygen
# Output: 32 random bytes in hex

---

Interoperability

All implementations produce byte-identical output across 13 platforms.

Encrypt in Python:

encrypted = Shield("pw", "app").encrypt(b"secret")
open("data.enc", "wb").write(encrypted)

Decrypt in Go:

encrypted, _ := os.ReadFile("data.enc")
decrypted, _ := shield.New("pw", "app", nil).Decrypt(encrypted)
// decrypted = "secret"

Decrypt in JavaScript:

const encrypted = fs.readFileSync('data.enc');
const decrypted = new Shield('pw', 'app').decrypt(encrypted);
// decrypted = Buffer<secret>

---

Security Parameters

Parameter	Value	Why
Key derivation	PBKDF2-HMAC-SHA256	Proven, NIST-approved
Iterations	600,000	OWASP 2023 floor (~107–290ms depending on language)
Key size	256 bits	2^256 brute-force resistance
AEAD cipher	AES-256-GCM (default) or ChaCha20-Poly1305	Standard, audited, hardware-accelerated (wire format v4)
Nonce	96 bits random	Per-message, standard AEAD nonce size
Auth tag	128-bit AEAD tag	Tamper detection (built into the AEAD)
Key separation	HKDF-SHA256-Expand	Derives the AEAD key from the master key (domain separation)
Freshness window	Timestamp-based	Rejects messages older than the window (60s default); NOT full replay protection — the base API does not track seen nonces, so identical ciphertext can be replayed within the window. Use RatchetSession for per-message counters
Length obfuscation	Random padding (32-128 bytes)	Hides message size

---

What Shield Protects Against

• Brute force - 600,000 PBKDF2 iterations slow attackers
• Tampering - the AEAD authentication tag (AES-GCM / ChaCha20-Poly1305) detects any modification
• Replay attacks - Use RatchetSession (per-message counters); the base API only enforces a timestamp freshness window
• Quantum computers - 256-bit symmetric = ~128-bit post-quantum; plus an optional hybrid X25519 + ML-KEM-768 key exchange for post-quantum key agreement
• P=NP proofs - No asymmetric crypto in the symmetric core to break

What Shield Does NOT Protect Against

• Weak passwords - Use check_password() to enforce strength
• Compromised devices - If attacker has your device, game over
• Stolen keys - Protect your keys like passwords
• Side channels - Use constant-time comparison (we do)

---

Project Structure

Shield/
├── shield-core/     # Rust core library + CLI (single source of truth)
├── browser/         # Browser SDK (auto-decrypt fetch)
├── android/         # Android SDK (Keystore integration)
├── ios/             # iOS SDK (Keychain + Face ID/Touch ID)
├── python/          # pip install shield-crypto
├── javascript/      # npm install @dikestra/shield
├── go/              # go get github.com/Dikestra-ai/shield
├── c/               # libshield.a
├── java/            # Gradle project
├── csharp/          # .NET project
├── swift/           # Swift Package
├── kotlin/          # Kotlin/JVM
├── wasm/            # WebAssembly (re-exports shield-core)
├── shield-proxy/    # Transparent encryption proxy (DNS failover, hot redundancy)
├── examples/        # Integration examples
├── tests/           # Cross-language integration tests
├── CHEATSHEET.md    # Quick reference for all languages
├── BENCHMARKS.md    # Performance benchmarks vs AES-GCM
├── MIGRATION.md     # Migration from Fernet, NaCl, etc.
├── INSTALL.md       # Detailed installation guide
├── SECURITY.md      # Threat model and best practices
└── CONTRIBUTING.md  # How to contribute

---

Performance

Operation	Speed	Notes
Key derivation	~107ms (Rust)	PBKDF2 600k, intentional (anti-brute-force); one-time per instance
Encryption	~1.2 GB/s (1MB, Rust)	AES-256-GCM (see BENCHMARKS.md)
Decryption	~1.6 GB/s (1MB, Rust)	AES-256-GCM
TOTP generation	<1ms
Lamport signing	~10ms	8KB signature

Shield v4 encrypts with a standard, hardware-accelerated AEAD (AES-256-GCM by default, ChaCha20-Poly1305 optional), so throughput tracks the underlying AEAD plus a small constant framing overhead. See BENCHMARKS.md for the full per-language tables and methodology.

---

Tests

All 12 language bindings build and pass their test suites on hosted CI (Linux, Windows, and real Apple-hardware macOS runners). The GitHub Actions matrix is the authoritative, always-current source of truth — see the Actions tab / CI badge above.

# Rust core (97 lib tests + interop + doc-tests; clippy clean)
cd shield-core && cargo test && cargo clippy --all-targets

# Python (209 tests)
cd python && python -m pytest

# JavaScript (119 tests)
cd javascript && node --test test/

# Go
cd go && go test ./...

# C (34 tests; + post-quantum vectors on Linux via c/scripts/build_and_test_pq.sh)
cd c && make test

# Java / Kotlin / C# / Android — gradle test / dotnet test
# WebAssembly — wasm-pack build (re-exports shield-core)

Cross-language conformance (byte-identical output) is enforced by shared vector files (tests/v4_test_vectors.json, tests/pq_kex_vectors.json) that every binding must reproduce.

---

Contributing

See CONTRIBUTING.md.

1. Fork the repository
2. Create a feature branch
3. Run tests in your language
4. Submit a pull request

---

License

MIT License - See LICENSE.

Use freely. No attribution required (but appreciated).

---

Shield - Because 2^256 is enough for anyone.

Built by Dikestra.ai