How ICEShare Works

A complete technical breakdown of ICEShare's emergency access system, from encryption to automatic deletion.

The Complete Process

Step 1: Share Creation

When you create a share, several cryptographic operations happen:

1.1 Data Encryption Key (DEK) Generation

dek = secrets.token_bytes(32)  # 256-bit key

Each share gets a unique 256-bit encryption key that's never reused.

1.2 Secret Encryption

Your secret is encrypted using XSalsa20-Poly1305 authenticated encryption:

box = nacl.secret.SecretBox(dek)
nonce = nacl.utils.random(24)
encrypted = box.encrypt(secret.encode(), nonce)

This ensures both confidentiality (can't be read) and authenticity (can't be tampered with).

1.3 Key Wrapping (Envelope Encryption)

The DEK is encrypted with a master Key Encryption Key (KEK) stored in HashiCorp Vault:

vault.secrets.transit.encrypt_data(
    name='iceshare-kek',
    plaintext=base64.b64encode(dek)
)

This "envelope encryption" means data is encrypted with a DEK, and the DEK is encrypted with a KEK.

1.4 Token Generation

Two cryptographically secure tokens are generated:

  • Redeem token: For the trustee to access the secret
  • Management token: For you to manage the share

Only SHA-256 hashes of these tokens are stored in the database for security.

Step 2: Email Notification

After encryption and storage:

  • Trustee receives email with one-time access link
  • Creator receives email with management link

Step 3: Access & Decryption

When the trustee clicks the redeem link:

  1. Security checks: Rate limiting, token validation, expiration check, IP blocking
  2. Audit logging: IP address, user agent, timestamp recorded
  3. Decryption:
    • DEK is unwrapped from Vault
    • Secret is decrypted using the DEK
    • Plaintext is shown to trustee

Step 4: Immediate Deletion

Permanent and Irreversible

After viewing, the encrypted data is immediately and permanently deleted:

  • Ciphertext cleared from database
  • Wrapped DEK destroyed
  • Nonce and authentication tag erased
  • Share marked as "USED"

There is no backup and no recovery mechanism.

System Architecture

User Browser (HTTPS)
    ↓
Nginx Reverse Proxy (TLS, Rate Limiting, Security Headers)
    ↓
Flask App (Encryption, Decryption, Management)
    ↓↓↓
PostgreSQL (Encrypted Data) | Vault (KEK) | Redis (Rate Limits)

Security Features

  • Envelope Encryption: Multiple layers of encryption protection
  • Zero-Knowledge: Server never sees plaintext except briefly during operations
  • Rate Limiting: Redis-backed protection against brute force
  • IP Blocking: Automatic blocking after suspicious activity
  • Database Locking: Prevents race conditions during redemption
  • Complete Audit Trail: Every action logged with IP, timestamp, and result

Technology Stack

Backend

  • Python 3.11 + Flask 3.0
  • Gunicorn WSGI server
  • SQLAlchemy 2.0 ORM
  • Celery task queue

Security

  • PyNaCl (XSalsa20-Poly1305)
  • HashiCorp Vault (Transit)
  • SHA-256 token hashing

Storage

  • PostgreSQL 15
  • Redis 7

Infrastructure

  • Nginx 1.24
  • Docker & Docker Compose
  • Prometheus & Grafana

Open Source Philosophy

ICEShare is built using open-source technologies and follows security best practices. The architecture is transparent and verifiable.

Ready to Create Your Emergency Access?

Now that you understand how it works, try it yourself!

Create Your First Share