Skip to content

Security upgrade #2

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
ankit-chaubey merged 4 commits into from
Feb 8, 2026
Merged

Security upgrade #2

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
2554f2d
Security upgrade
ankit-chaubey Feb 8, 2026
d6a4ea1
fix
ankit-chaubey Feb 8, 2026
bad12d3
Update ciph.c
ankit-chaubey Feb 8, 2026
271069c
security: harden chunk handling and bump version to v1.2.1
ankit-chaubey Feb 8, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
41 changes: 26 additions & 15 deletions CHANGELOG.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/) and follo

---

## [1.2.0] — Protocol Hardening & Security Finalization
## [1.2.1] — Protocol Hardening & Security Finalization

**Release date:** 2026-02-08

Expand All @@ -20,35 +20,40 @@ This version elevates CIPH from *strong encryption* to a **vault-grade, protocol
* Strict **key separation (domain separation)** between encryption keys and nonce-derivation keys
* Deterministic, secret-derived **per-chunk nonces**
* Explicit password API (raw bytes + explicit length)
* Formal **file format v2 (hardened)** documentation
* SECURITY.md describing threat model and guarantees
* Enforced cryptographic invariants by design (not convention)
* Formal **file format v2+ (hardened)** documentation
* SECURITY.md describing threat model, invariants, and guarantees
* Enforced cryptographic invariants by construction (not convention)
* Header ↔ payload binding guarantees documented and locked
* Deterministic EOF authentication semantics

### 🔒 Security

* Prevents metadata tampering (magic, version, cipher, filename, salt)
* Prevents metadata tampering (magic, version, cipher, chunk size, filename, salt)
* Prevents cipher downgrade attacks
* Prevents chunk replay, reordering, and cross-file transplantation
* Prevents chunk replay, reordering, duplication, and cross-file transplantation
* Prevents nonce reuse under the same key
* Stronger resistance to malformed or malicious encrypted inputs (DoS hardening)
* Explicit failure on truncation, corruption, or header manipulation
* No master keys, recovery paths, or hidden decrypt logic

### 🛠️ Changed

* File format header is now **fully authenticated** using AEAD AAD
* Python CLI updated to match hardened native API
* Password handling no longer relies on C-string semantics
* Cryptographic guarantees are enforced structurally, not by policy
* Python CLI bindings updated to match hardened native API semantics
* Password handling no longer relies on C-string assumptions
* Cryptographic guarantees are enforced structurally, not by policy or convention
* Documentation aligned exactly with the shipped C implementation

### ⚠️ Compatibility

* User workflow and CLI usage remain unchanged
* Existing encrypted files continue to decrypt correctly
* Re-encryption is **not required**, but recommended for maximum guarantees
* No breaking API or ABI changes

---

## [1.2.0] — Final Stable Release
## [1.2.1] — Final Stable Release

**Release date:** 2026-02-07

Expand Down Expand Up @@ -103,29 +108,35 @@ This release marks the first **production-ready**, **cryptographically stable**,

## [1.1.0] — Pre-Stable Beta

### Added
**Release date:** 2026-01 (approx.)

### ✨ Added

* Initial streaming encryption engine
* Python CLI wrapper
* Basic AES and ChaCha support
* Early file-format layout

### Known Limitations (resolved in 1.2.0)
### ⚠️ Known Limitations (resolved in 1.2.1)

* Fixed chunk size
* Weak error reporting
* No adaptive decryption
* Limited test coverage
* Partial header authentication

---

## Upgrade Notes

Upgrading from **1.1.0 → 1.2.0** is fully backward-compatible.
Upgrading from **1.2.0 → 1.2.1** is fully backward-compatible.

Encrypted files created with earlier versions **decrypt correctly** in 1.2.0.
Encrypted files created with earlier versions **decrypt correctly** in 1.2.1.

No action required.

For maximum long-term guarantees, re-encryption with ≥1.2.1 is recommended but not mandatory.

---

**CIPH 1.2.0 is protocol-hardened and audit-ready.**
**CIPH 1.2.1 is protocol-hardened, audit-ready, and designed for hostile storage environments.**
57 changes: 31 additions & 26 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -19,16 +19,22 @@

Most encryption tools load the entire file into memory before encrypting it. **ciph streams data in fixed-size chunks**, which means you can encrypt a **50 GB 4K video on a machine with only 2 GB of RAM**—smoothly and safely.

Unlike archive-based or buffer-based tools, ciph never needs random access to plaintext and never allocates memory proportional to file size. Memory usage is deterministic and bounded.

---

## ✨ Features

* 🔐 **Strong encryption** — AES‑256‑GCM or ChaCha20‑Poly1305
* 🔑 **Password protection** — Argon2id (memory‑hard key derivation)
* 🚀 **High performance** — streaming C core (1 MB chunks)
* 🚀 **High performance** — streaming C core with configurable chunk size
* 🧠 **Constant memory usage** — works with 10 GB+ files
* ⚙️ **Hardware‑aware** — AES‑NI when available, ChaCha fallback
* 🧪 **Integrity protected** — AEAD authentication on every chunk
* ☁️ **Cloud / Telegram safe** — encrypt before upload
* 🏷️ **Filename preserved** — original filename & extension are stored and restored on decryption
* 🧷 **Rename‑safe** — encrypted files may be freely renamed
* 🧯 **Fail‑closed design** — corruption always aborts decryption

---

Expand All @@ -40,9 +46,9 @@ Most encryption tools load the entire file into memory before encrypting it. **c
2. Your password is hardened using **Argon2id**.
3. The data key is encrypted using the derived password key.
4. Every chunk is authenticated to detect tampering.
5. The **original filename (without path)** is stored as encrypted metadata and automatically restored on decryption.
5. The **original filename (without path)** is stored as authenticated metadata and automatically restored on decryption.

No custom crypto. No weak primitives.
No custom crypto. No weak primitives. No silent failure modes.

---

Expand Down Expand Up @@ -71,19 +77,19 @@ Starting from **v1.2.0**, ciph introduces a **protocol‑level security hardenin

### What changed internally

* 🔒 **Full metadata authentication (AAD binding)**
All file header fields (magic, version, cipher, salt, filename, encrypted key) are cryptographically bound to the encrypted content. Any modification causes decryption to fail.
* 🔒 **Full metadata authentication (AAD binding)**
All file header fields (magic, version, cipher, chunk size, salt, nonce key, filename, encrypted key) are cryptographically bound to the encrypted content. Any modification causes decryption to fail.

* 🔑 **Strict key separation**
* 🔑 **Strict key separation**
Encryption keys and nonce‑derivation keys are derived independently using domain separation. Keys are never reused across purposes.

* 🔁 **Chunk replay & reordering protection**
* 🔁 **Chunk replay & reordering protection**
Each encrypted chunk uses a nonce derived from a secret key and the chunk index. Chunks cannot be reordered, duplicated, or transplanted between files.

* 🧼 **Explicit password handling**
* 🧼 **Explicit password handling**
Passwords are treated as raw byte buffers with explicit length. No implicit string handling, truncation, or hidden transformations.

* 🛡️ **DoS‑safe streaming**
* 🛡️ **DoS‑safe streaming**
Encrypted chunk sizes are validated before allocation to prevent memory exhaustion attacks.

### What is now cryptographically impossible
Expand All @@ -95,8 +101,6 @@ Starting from **v1.2.0**, ciph introduces a **protocol‑level security hardenin
* ❌ Reusing nonces under the same key
* ❌ Injecting malformed headers that decrypt silently

This update moves ciph from *"strong encryption"* to **"protocol‑hardened encryption"**, suitable for long‑term archival and hostile storage environments.

---

## 🚀 Quick Start (Build from Source)
Expand All @@ -108,6 +112,8 @@ make
pip install .
```

---

## 📦 Installation

### Requirements
Expand Down Expand Up @@ -166,38 +172,37 @@ ciph decrypt movie.mkv.ciph

## 📝 File Format

> **Updated & Hardened (v1.2.0)** — This section extends the original format without removing any fields. All existing fields remain valid; new guarantees and clarifications are added.
> **Extended without removing any fields**. All original fields remain present; guarantees are clarified and enforced.

### Header Layout (Authenticated as AAD)

| Offset | Size | Description |
| ------ | ---- | ------------------------------------------------------ |
| 0 | 4 | Magic bytes (`CIPH`) |
| 4 | 1 | Format version (`0x02`) |
| 4 | 1 | Format version |
| 5 | 1 | Cipher mode (1 = AES‑256‑GCM, 2 = ChaCha20‑Poly1305) |
| 6 | 16 | Argon2id salt (random per file) |
| 22 | 12 | Nonce‑derivation key (random per file) |
| 34 | 1 | Filename length (N) |
| 35 | N | Original filename (UTF‑8, no path, not NUL‑terminated) |
| 35+N | 2 | Encrypted data‑key length (big‑endian) |
| 37+N | L | Encrypted data key (AEAD‑protected) |
| 6 | 4 | Chunk size in MB (big‑endian) |
| 10 | 16 | Argon2id salt (random per file) |
| 26 | 12 | Nonce‑derivation key (random per file) |
| 38 | 1 | Filename length (N) |
| 39 | N | Original filename (UTF‑8, no path, not NUL‑terminated) |
| 39+N | 2 | Encrypted data‑key length (big‑endian) |
| 41+N | L | Encrypted data key (AEAD‑protected) |

> **All header fields above are cryptographically authenticated (AAD)**. Any modification results in decryption failure.

### Encrypted Payload Layout (Streaming)

The payload is a sequence of independently authenticated chunks:

| Field | Size | Description |
| --------- | ---- | -------------------------------------------- |
| ChunkLen | 4 | Length of encrypted chunk (ciphertext + tag) |
| ChunkData | M | AEAD‑encrypted chunk data |

This pair repeats until end‑of‑file.
This pair repeats until end‑of‑file. A final authenticated zero‑length chunk acts as an EOF marker.

### Cryptographic Binding Guarantees (v1.2.0)
### Cryptographic Binding Guarantees (v1.2.0+)

The following properties are now **cryptographically enforced**, not policy‑based:
The following properties are **cryptographically enforced**, not policy‑based:

* Header ↔ payload binding (no metadata tampering)
* Cipher mode binding (no downgrade attacks)
Expand All @@ -209,7 +214,7 @@ The following properties are now **cryptographically enforced**, not policy‑ba

## 📊 Performance

* Processes data in **(4-1024) MB chunks**
* Processes data in **(1–1024) MB chunks**
* Cryptography handled in **C (libsodium)**
* Python used only for CLI orchestration
* Typical throughput: **hundreds of MB/s** (CPU‑bound)
Expand Down Expand Up @@ -243,7 +248,7 @@ The project focuses on building **secure, efficient, and practical cryptographic

Apache License 2.0

Copyright © 2026 Ankit Chaubey
Copyright © 2026–present Ankit Chaubey

Licensed under the Apache License, Version 2.0 (the "License"); you may not use this file except in compliance with the License.
You may obtain a copy of the License at:
Expand Down
Loading