umbra

README

Umbra

Umbra is a command-line tool that securely splits, encrypts, and redundantly stores files across multiple cloud providers using a zero-knowledge architecture.

Overview

Umbra reimagines file storage by fragmenting files into encrypted chunks and distributing redundant copies across multiple storage backends. This approach provides privacy, redundancy, and vendor independence — no single provider has complete information about your data.

Key Features

• File Fragmentation: Split files into configurable chunks for distributed storage
• Strong Encryption: XChaCha20-Poly1305 authenticated encryption with Argon2id key derivation
• Redundant Storage: Configure multiple copies per chunk across different providers
• Zero-Knowledge Manifest: Encrypted metadata reveals nothing without the password
• Provider Agnostic: Pluggable architecture supports multiple storage backends
• Integrity Verification: SHA-256 hashing ensures data integrity at chunk and file level
• Fail-Safe Design: Abort on any integrity mismatch to prevent data corruption

Installation

From Source

git clone https://github.com/henomis/umbra.git
cd umbra
make build

The binary will be created in bin/umbra.

Install to GOPATH

make install

Usage

Upload a File

Split and encrypt a file, then distribute chunks across providers:

umbra upload \
  --file ./secret.tar.gz \
  --password "your-secure-password" \
  --manifest ./secret.umbra \
  --chunks 3 \
  --copies 2 \
  --providers termbin,clbin

Options:

• --file, -f: File to upload (required)
• --password, -p: Encryption password (required)
• --manifest, -m: Path to save the manifest file (required)
• --chunk-size, -s: Chunk size in bytes (mutually exclusive with --chunks)
• --chunks, -c: Number of chunks to create (default: 3, mutually exclusive with --chunk-size)
• --copies, -n: Number of redundant copies per chunk (default: 1)
• --providers, -P: Comma-separated list of providers (defaults to all available)
• --option, -o: Provider-specific options as key=value (repeatable)
• --quiet, -q: Suppress progress output

Download a File

Reconstruct a file from its manifest:

umbra download \
  --manifest ./secret.umbra \
  --password "your-secure-password" \
  --file ./secret-restored.tar.gz

Options:

• --manifest, -m: Path to the manifest file (required)
• --password, -p: Decryption password (required)
• --file, -f: Output file path (required)
• --option, -o: Provider-specific options as key=value (repeatable)
• --quiet, -q: Suppress progress output

Display Manifest Information

View metadata about an encrypted manifest:

umbra info \
  --manifest ./secret.umbra \
  --password "your-secure-password"

Options:

• --manifest, -m: Path to the manifest file (required)
• --password, -p: Password to decrypt manifest (required)

How It Works

1. File Fragmentation

Umbra divides your file into chunks using either:

• Explicit chunk size: Specify exact bytes per chunk (e.g., --chunk-size 1048576 for 1MB chunks)
• Chunk count: Let Umbra calculate size based on number of chunks (e.g., --chunks 5)

Each chunk is independently hashed using SHA-256 for integrity verification.

2. Encryption

Before any data leaves your machine:

• Key Derivation: Password → encryption key via Argon2id (4 iterations, 64 MiB memory, parallelism of 4)
• Authenticated Encryption: XChaCha20-Poly1305 provides confidentiality and authenticity
• Random Nonces: Each manifest uses unique salt and nonce values

Storage providers only receive encrypted blobs — they never see your plaintext data.

3. Redundant Distribution

Chunks are uploaded to multiple providers based on your --copies setting:

• Resilience: File survives provider downtime or data loss
• No Vendor Lock-in: Distribute across heterogeneous backends
• Failure Recovery: Download succeeds if any redundant copy is available

4. Zero-Knowledge Manifest

The manifest file contains all reconstruction information:

• Public Header: Magic bytes, version, cryptographic parameters (KDF, cipher, salt, nonce)
• Encrypted Payload: Chunk hashes, provider identifiers, provider metadata

Without the password, the manifest reveals nothing about file contents, structure, or storage locations.

5. Reconstruction

Download process:

1. Decrypt manifest using password
2. Fetch chunks from providers (trying redundant copies on failure)
3. Verify each chunk hash
4. Reassemble chunks in order
5. Verify final file hash

Any integrity mismatch causes immediate abort — corrupted data is never delivered.

Supported Providers

Built-in Providers

• termbin: TCP-based paste service (termbin.com)
• clbin: HTTP paste service (clbin.com)
• pipfi: Pipe-based file transfer service
• pastecnetorg: paste.c-net.org integration
• dummy: Local filesystem provider (testing only)

Provider Constraints

Each provider has limits:

• Maximum chunk size (typically 10MB for paste services)
• Expiration duration (varies by service)

Umbra validates chunk size against provider limits before upload.

Default Providers

If --providers is omitted, Umbra uses: termbin,clbin,pipfi,pastecnetorg

Architecture

Design Principles

• Security by Design: Encryption before data transmission
• Fail Loudly: Abort on integrity failures rather than deliver corrupted data
• Modularity: Clean separation between crypto, content, and provider layers
• Extensibility: Simple provider interface for adding new backends
• Type Safety: Strong typing catches configuration errors early

Security Considerations

Cryptographic Guarantees

• Argon2id KDF: Memory-hard password hashing resistant to GPU/ASIC attacks
• XChaCha20-Poly1305 AEAD: Modern authenticated encryption (confidentiality + integrity)
• Random Nonces: Each manifest uses cryptographically random salt and nonce
• Hash Verification: SHA-256 checksums prevent undetected corruption

Threat Model

Protected Against:

• Passive provider surveillance (data encrypted at rest)
• Provider data breaches (providers store only ciphertext)
• Data corruption (cryptographic verification)
• Single provider failure (redundancy)

NOT Protected Against:

• Weak passwords (use strong, unique passwords)
• Compromised endpoints (malware on your machine)
• Manifest + password exposure (keep password separate from manifest)
• Traffic analysis (timing/size metadata visible to providers)

Best Practices

1. Strong Passwords: Use long, random passwords (consider a password manager)
2. Separate Storage: Store manifest and password in different locations
3. Additional Backups: Umbra is experimental — maintain traditional backups
4. Secure Deletion: Securely delete source files after upload if needed
5. Verify Downloads: Always check that downloaded files match expectations

License

See LICENSE file for details.

Disclaimer

⚠️ Umbra is experimental software.

• Not recommended as the sole backup solution for critical data
• Cryptographic implementation should be independently audited before production use
• Provider availability and data persistence are not guaranteed
• Always maintain additional backups of important files

Use at your own risk.

Acknowledgments

Umbra — Secure, fragmented, redundant storage for the privacy-conscious.