Security & Encryption

ICEShare takes security seriously. This page explains the cryptographic algorithms, security mechanisms, and threat models that protect your sensitive information.

Encryption Algorithms

XSalsa20-Poly1305 (Content Encryption)

Algorithm: XSalsa20 stream cipher with Poly1305 authenticator

Key Size: 256 bits (32 bytes)

Nonce Size: 192 bits (24 bytes)

Authentication Tag: 128 bits (16 bytes)

XSalsa20-Poly1305 is a modern authenticated encryption algorithm that provides both confidentiality and authenticity. It's used by Signal, WireGuard, and other security-focused applications. The algorithm is:

Fast: Optimized for modern CPUs
Secure: No known practical attacks
Authenticated: Detects tampering automatically
Nonce-misuse resistant: Extended nonce space (2^192)

AES-256-GCM96 (Key Wrapping)

Algorithm: AES in Galois/Counter Mode

Key Size: 256 bits

Nonce Size: 96 bits

HashiCorp Vault's Transit engine uses AES-256-GCM to wrap Data Encryption Keys (DEKs). This provides an additional layer of encryption for keys, ensuring that even if the database is compromised, DEKs remain protected by the master Key Encryption Key (KEK) in Vault.

SHA-256 (Token Hashing)

Algorithm: SHA-256 cryptographic hash

Output Size: 256 bits

Access tokens and management tokens are hashed with SHA-256 before storage. This means the database only contains hashes, not the original tokens. An attacker with database access cannot use the hashes to access shares.

Envelope Encryption Architecture

ICEShare uses envelope encryption, a security best practice where data is encrypted with one key (DEK), and that key is encrypted with another key (KEK).

Why Envelope Encryption?

Performance: Encrypting large data with Vault is slow. We encrypt locally with NaCl, then only wrap the small DEK with Vault.
Key Rotation: The KEK in Vault can be rotated without re-encrypting all data.
Defense in Depth: Two independent systems must be compromised (database + Vault) to decrypt secrets.
Scalability: Vault doesn't need to process every encryption operation.

Zero-Knowledge Architecture

ICEShare is designed so that server operators cannot access your plaintext secrets:

No logging of secrets: Plaintext secrets are never written to logs
Memory-only DEKs: DEKs exist in memory for milliseconds during encryption/decryption
Immediate deletion: After one-time access, all encrypted data is permanently erased
No backups contain secrets: Even database backups only contain encrypted ciphertexts

Rate Limiting & Abuse Prevention

Multiple layers of rate limiting protect against abuse:

Endpoint	Limit	Burst	Purpose
`/create`	2 req/s	5	Prevent spam share creation
`/redeem`	5 req/s	10	Prevent brute force attacks
General	10 req/s	20	Overall traffic protection

IP Blocking

Automatic IP blocking protects against repeated abuse:

3 email bounces → 24-hour IP block
5 email bounces → Permanent IP block
Manual blocking → Admins can block/unblock IPs

Database Security

What's stored in the database:

✅ Encrypted ciphertext (useless without DEK)
✅ Wrapped DEK (useless without Vault KEK)
✅ Nonce and authentication tag (public values)
✅ SHA-256 token hashes (irreversible)
✅ Email addresses (for notifications)
✅ Audit logs (IP, timestamp, user agent)
❌ Plaintext secrets (NEVER stored)
❌ Unwrapped DEKs (only exist in memory)
❌ Original tokens (only hashes stored)

Threat Model

ICEShare is designed to protect against these threats:

✓ Protected Against

Database compromise (data encrypted at rest)
Network eavesdropping (TLS 1.3)
Brute force attacks (rate limiting)
Replay attacks (one-time tokens)
Token theft from database (only hashes stored)
Insider threats (zero-knowledge design)
Spam and abuse (email bounce detection, IP blocking)

⚠ Partial Protection

Memory dumps during active encryption/decryption (DEKs briefly in RAM)
Client-side compromise (if user's browser is hacked)
Email interception (trustee email contains access link)

✗ Not Protected Against

Complete system compromise (database + Vault + application)
Physical access to running server with root privileges
Trustee sharing the secret with others
Social engineering (phishing for tokens)

Best Practices for Users

To maximize security when using ICEShare:

Choose trustees carefully: Only share with people you absolutely trust
Use strong passwords: If sharing passwords, make them long and random
Don't share the same secret twice: Each share should be unique
Revoke if circumstances change: Use the management link to revoke access if needed
Monitor your email: You'll be notified when access occurs
Keep management links secure: Don't share your management link with anyone

Security Auditing

While ICEShare hasn't undergone a formal third-party security audit, the codebase follows security best practices:

Use of well-established cryptographic libraries (NaCl, Vault)
No custom cryptography implementations
Defense in depth architecture
Complete audit logging
Regular dependency updates
Input validation and sanitization

Note: This is a personal project provided "as-is" without warranties. While every effort has been made to ensure security, users should evaluate the risk based on their specific use case.

Responsible Disclosure

If you discover a security vulnerability in ICEShare, please report it to:

Email: security@iceshare.peebee.com.au

We take security reports seriously and will respond within 48 hours.

Open Source Security

ICEShare's security is enhanced by transparency. The architecture is documented, the algorithms are well-known and peer-reviewed, and the system can be independently verified and audited.