🔒 KvhWrap

檔案隱蔽式加密工具 — 快速、原地加密、AES‑256‑GCM

版本：v1.0.0
環境：Python 3.8+
相依套件：pycryptodome

下載 : 這裡

當你D槽有很多檔案不想被人直接看見時的最佳做法

1. 檔案多檔案容量大一般加解密花太多時間

2. 檔名有一定的敏感度不適合明文

📑 目錄（Table of Contents）

概覽與用途說明
核心演算法
加密與解密流程圖
檔案格式（Binary Block 結構）
為什麼只加密 1 KB？
In‑Place 模式的巨大優勢
金鑰導出（KDF）與密碼延展
Enhanced 模式（密碼 + 檔案指紋）
解密自動判斷機制
模式比較表
加密流程逐步說明
解密流程逐步說明
函式一覽
最佳使用情境與建議

1. 概覽（Overview & What It Does）

KvhWrap 是一個專注於「隱蔽性（Stealth）」的檔案加密工具，主要功能包含：

🔐 只加密每個檔案開頭 1 KB（使用 AES‑256‑GCM）
🕵️ 隱藏原始檔名（重新命名為奈秒級時間戳，例如 1713200000000000.ks）
📦 在加密的 metadata 中保存原始檔名、大小與時間戳
📁 子資料夾也會被重新命名為時間戳，並建立加密對照表
♻️ 只要密碼正確，即可完整還原所有狀態

💡 設計理念（Design Philosophy）

KvhWrap 的目標不是「全碟加密」，
而是 快速破壞檔案的可辨識性。

只要檔案 header 被破壞，
OS、媒體播放器、檔案分析工具全部都無法識別格式。
對大型檔案（影片、壓縮檔）來說，
速度極快、I/O 幾乎固定、效果立竿見影。

2. 核心演算法（Core Algorithm）

元件	演算法	說明
加密	AES‑256‑GCM	具認證的對稱式加密，含 16B auth tag
KDF（快速）	SHA‑256	單次 hash，速度快但抗暴力破解能力弱
KDF（強）	scrypt	N=65536、r=8、p=1、128MB 記憶體
Enhanced KDF	HMAC‑SHA256	使用者密碼 × 檔案指紋
Auth Tag	GCM	偵測任何竄改或密碼錯誤
Nonce	Random 12 bytes	每次加密隨機產生

Password  ──┬──▶ [KDF: SHA-256 or scrypt] ──▶  32-byte AES Key
             │        ↑ salt (16 bytes)
             │
             │  (Enhanced mode only)
             └──▶ [HMAC mix with file fingerprint] ──▶ Hybrid Password ──▶ [KDF] ──▶ Key
                         ↑
              File content sampling ──▶ SHA-256 ──▶ PBKDF2 ──▶ Auto-Password (24 chars)

3. 加密與解密流程（Flowcharts）

3.1 Wrap（加密）流程概要

選擇資料夾與密碼
掃描 ≥ 1 KB 的檔案（排除 .ks）
檢查是否已加密
是否使用 Enhanced 模式？
導出 AES 金鑰
加密開頭 1 KB
建立 .ks 檔（Copy）或原地寫入（In‑Place）
還原原始時間戳

✅ 完成

3.2 Unwrap（解密）流程概要

掃描 .ks 檔案
檢查 magic bytes 判斷格式：
- KWRP → Copy mode
- KWRI → In‑Place mode
讀取 metadata
是否為 Enhanced？
導出金鑰並解密 head
驗證 GCM auth tag
還原檔名、內容、時間戳

✅ 完整復原

4. 檔案格式（File Format）

4.1 Copy Mode（`KWRP`）

原始檔案不會被修改
建立新 .ks 檔案

結構概念：

[KWRP]
[meta_len]
[Metadata JSON]
[Encrypted Head: nonce + tag + ciphertext (1024B)]
[Tail Data（未加密）]

MAGIC
KWRP
4 bytes
meta_len
uint32 LE
4 bytes
Metadata (JSON)
orig_name, orig_size, kdf, salt, enhanced, encrypted_auto_password
N bytes
Encrypted Head
nonce(12) + tag(16) + ciphertext(1024)
1052 bytes
Tail Data
Unencrypted remainder of file (byte 1024 → EOF)
orig_size − 1024 bytes

Encrypted Head Detail (AES-256-GCM blob)

Nonce
Random IV
12 bytes
Auth Tag
GCM GHASH
16 bytes
Ciphertext
AES-256-GCM encrypted first 1024 bytes
1024 bytes

4.2 In‑Place Mode（`KWRI`）

直接修改原檔
在檔案結尾附加 footer

Encrypted Head
AES-GCM ciphertext
(replaces original bytes 0-1023)
1024 bytes
Unchanged Tail
Original file bytes 1024 → original EOF
orig_size − 1024
Metadata (JSON)
orig_name, orig_size, kdf, salt …
N bytes
meta_len
uint32 LE
4 bytes
Nonce
12 bytes
Tag
16 bytes
MAGIC
KWRI
4 bytes

附加成本：

約 200～300 bytes
對 GB 級影片檔案幾乎可忽略

註 : In‑Place 模式於檔案結尾所附加之 footer，僅會使檔案大小增加約 ~36 + N 位元組，其組成包含：metadata JSON、4 位元組之 metadata 長度欄位、12 位元組 nonce、16 位元組 GCM 認證標籤（Authentication Tag），以及 4 位元組之 magic bytes。

在典型情況下，metadata 區塊大小約為 ~200 位元組，因此整體額外儲存負擔約為 ~236 位元組。相較於數 GB 規模之影音檔案，此額外開銷可視為在系統設計上可忽略不計（negligible）。

5. 為什麼只加密 1 KB？（Head Offset）

因為絕大多數檔案格式的「識別資訊」都在最前面：

檔案類型	關鍵資訊位置
MP4 / MOV	0–512 bytes
JPEG	0–1024 bytes
PNG	0–33 bytes
PDF	0–64 bytes
ZIP / DOCX	0–128 bytes

✅ 只要 header 被毀，內容就無法被識別

透過加密檔案開頭的前 1024 位元組，KvhWrap 會破壞以下關鍵資訊：

檔案類型的 Magic Bytes —— 作業系統與應用程式將無法識別檔案格式
容器層中繼資料（Container Metadata） —— 包含影像尺寸、編碼器資訊、時間戳記等
EXIF 資料 —— 相機型號、GPS 座標、縮圖等拍攝相關資訊
文件結構資訊 —— 包含版面配置、字型定義、目錄指標等內部結構描述

🔒 加密區域
Bytes 0 – 1023
File header, magic, metadata
→
未變動資料
Bytes 1024 → EOF (檔案結尾)
Raw media frames, binary data (unidentifiable without header)

⚠️ 限制說明：

小型文字檔（<1KB）不適合 In‑Place
機密小文件建議使用 Copy mode

6. In‑Place 模式的巨大優勢

🚀 核心洞察（Key Insight）

In‑Place：O(1) I/O
Copy：O(n) I/O

檔案大小	Copy	In‑Place
10 GB	30–90 秒	~0.1 秒
50 GB	3–8 分	~0.1 秒

100 MB — Copy

0.3s

100 MB — In-Place

0.05s

1 GB — Copy

1 GB — In-Place

0.05s

10 GB — Copy

30–90s

10 GB — In-Place

0.1s

50 GB — Copy

3–8 min

50 GB — In-Place

0.1s

🚀 Key Insight

In‑Place 模式的磁碟 I/O 複雜度為 O(1)，且不受檔案大小影響；無論檔案多大，實際僅會進行 1 KB 的讀寫操作，加上約 236 位元組的附加資料。
相對地，Copy 模式的磁碟 I/O 複雜度為 O(n)，其讀寫成本與檔案大小成正比。
以一個 50 GB 的影片檔案為例，In‑Place 模式的處理速度約為 Copy 模式的 3000 倍。

👉 最大可快 3000×

7. 金鑰導出 KDF（Key Derivation Function）

將使用者輸入的原始密碼（Password），透過密碼學演算法轉換為**固定長度、具高隨機性與高安全性之加密金鑰（Cryptographic Key）**的機制。在對稱式加密系統中（例如 AES‑256），加密演算法無法直接使用人類可記憶的密碼作為金鑰，因此必須透過 KDF 進行轉換

7.1 SHA‑256（快速）

key = SHA-256( password.encode("utf-8") )      # → 32 bytes

✅ 快
❌ 不耐暴力破解

7.2 scrypt（強烈推薦）

記憶體硬化（128MB）
對 GPU / ASIC 非常不友善

salt = os.urandom(16)                          # unique per file
key  = scrypt( password, salt, N=65536, r=8, p=1, dklen=32 )

Parameter	Value	Purpose
N (cost factor)	65536 (2¹⁶)	Number of iterations — higher = slower to brute-force
r (block size)	8	Memory block size in 128-byte units
p (parallelism)	1	Parallelization factor
maxmem	128 MB	Maximum memory usage — makes GPU attacks expensive
dklen	32	Output key length in bytes

✅ 安全
⚠️ 單次約 130 ms

7.3 每檔案 Salt（Per‑File Salt）

每個檔案都會取得一個獨立推導出的 salt 值，即使在同一批次加密作業中亦是如此：

base_salt = os.urandom(16)                     # random per batch
file_salt = SHA-256( base_salt + filepath )[:16]   # unique per file

此設計可確保：即使兩個內容完全相同的檔案，且使用相同的密碼進行加密，其最終產生的密文仍然不同，從而有效防止基於密文比對或重複樣式的分析攻擊。

8. Enhanced 模式（密碼 + 檔案指紋）

8.1 自動密碼產生（Auto‑Password Generation）

系統會根據檔案內容，以決定性方式產生一組長度為 24 個字元的自動密碼（Auto‑Password）。

即使使用者密碼很弱（例如 "1234"）：

✅ 透過檔案內容自動生成指紋
✅ 與使用者密碼做 HMAC 混合
✅ 產生 43 字元高強度 Hybrid Password

同一密碼，不同檔案 ≠ 同一金鑰

📊 大型檔案的取樣策略（Sampling Strategy for Large Files）
對於大於 1 MB 的檔案，系統不會讀取整個檔案內容，而是僅取樣 1536 位元組（3 × 512 位元組），無論檔案實際大小為何：
檔案開頭 512 位元組
檔案中段 512 位元組
檔案結尾 512 位元組
此策略可在將磁碟 I/O 降至最低的同時，仍能產生具有鑑別性的檔案指紋；即使多個檔案具有相同的檔頭（例如使用相同編碼格式或 codec），只要實際內容不同，仍會產生不同的自動密碼。

8.2 混合式密碼混合機制（Hybrid Password Mixing）

為提升整體金鑰衍生的安全性，系統採用**混合式密碼（Hybrid Password）**機制，將：

使用者輸入的密碼（User Password）
由檔案內容推導出的自動密碼（Auto‑Password）

透過 雙向 HMAC（Bidirectional HMAC） 運算進行混合，產生最終用於金鑰導出的密碼。

設計原理

混合式密碼機制的核心目標在於同時結合以下兩種安全來源：

使用者控制的秘密（User‑controlled secret）
即使用者所輸入的密碼。
檔案內容關聯的唯一性（File‑bound uniqueness）
即由檔案內容推導出的 auto‑password。

透過此方式，即使使用者密碼強度不足，只要檔案內容不同，最終衍生出的金鑰仍具有高度差異性與不可預測性。

運算流程（概念說明）

混合過程採用 雙向 HMAC‑SHA256，其步驟如下：

以前向運算方式，將 auto‑password 作為訊息、使用者密碼作為金鑰進行 HMAC
以反向運算方式，將使用者密碼作為訊息、auto‑password 作為金鑰進行 HMAC
將上述兩組 HMAC 結果進行串接（Concatenate）
對串接結果進行 Base64 編碼，並截取固定長度作為 Hybrid Password

此雙向設計可避免單向依賴任一輸入來源，並降低因其中一方熵值不足所造成的安全風險。

安全特性

混合式密碼機制具備下列特性：

雙因素來源：同時依賴使用者密碼與檔案內容
抗弱密碼設計：即使使用者選用低強度密碼，仍可透過檔案指紋補強
檔案綁定性（File‑Bound）：相同密碼套用於不同檔案時，會產生不同結果
不可逆推導：無法僅由最終金鑰反推出任一原始輸入密碼

設計結論（Specification Summary）

Hybrid Password 僅用於金鑰導出階段，不直接用於加密運算
雙向 HMAC 設計可有效混合兩種不同來源的秘密資料
此機制為 Enhanced 模式的核心安全設計之一
Hybrid Password 的重建流程需仰賴解密階段所儲存的加密 auto‑password（詳見 8.3）

8.3 為解密而儲存自動密碼（Storing the Auto‑Password for Decryption）

由於檔案在完成加密後，其內容已發生變更，原先依據檔案內容所產生之**自動密碼（Auto‑Password）**將無法於解密階段重新計算。因此，系統會將 auto‑password 以加密形式儲存在檔案的中繼資料（metadata）中，以確保在解密時能夠正確重建混合密碼（Hybrid Password）。

其設計與流程如下所示：

從使用者密碼導出專用金鑰（Separate Key Derivation）
系統使用具備 domain separation 的 salt 值，從使用者密碼導出一組專用金鑰：

系統使用具備 domain separation 的 salt 值，從使用者密碼導出一組專用金鑰

auto_salt = SHA-256(file_salt + "auto_password_salt")[:16]
auto_key = KDF(user_password, salt=auto_salt)

使用 auto_key 加密自動密碼

採用 AES‑EAX 加密模式
加密對象為 auto‑password 本身

儲存加密後的自動密碼

將加密結果轉換為十六進位字串（hex string）
儲存在 metadata 欄位 "encrypted_auto_password" 中

在解密階段，系統將依序執行以下流程：

使用者提供密碼
→ 導出 auto_key
→ 解密已儲存的 auto‑password
→ 重建 hybrid password
→ 導出檔案加密金鑰（file key）
→ 解密檔案開頭內容（encrypted head）

⚠️ Important

凡是以 Enhanced 模式進行加密的檔案，在解密時亦必須啟用 Enhanced 模式。

9. 解密自動判斷（Auto Mode）

unwrap_auto() 會：

自動辨識 Copy / In‑Place
自動判斷是否為 Enhanced
自動選擇正確的解密路徑

使用者 不需要知道任何內部細節

解密格式與模式判斷（Detection Logic）

判斷項目檢查條件判斷結果
Copy 模式檔案前 4 位元組等於 `KWRP` Header‑first 格式，metadata 位於檔案開頭
In‑Place 模式檔案最後 4 位元組等於 `KWRI` Footer 格式，metadata 位於檔案結尾
Enhanced 模式 `metadata["enhanced"] == true` 需執行混合密碼（Hybrid Password）重建流程
KDF 類型 `metadata["kdf"]`（0 或 1）使用 SHA‑256 或 scrypt 進行金鑰導出

判斷項目	檢查條件	判斷結果
Copy 模式	檔案前 4 位元組等於 `KWRP`	Header‑first 格式，metadata 位於檔案開頭
In‑Place 模式	檔案最後 4 位元組等於 `KWRI`	Footer 格式，metadata 位於檔案結尾
Enhanced 模式	`metadata["enhanced"] == true`	需執行混合密碼（Hybrid Password）重建流程
KDF 類型	`metadata["kdf"]`（0 或 1）	使用 SHA‑256 或 scrypt 進行金鑰導出

Step 1：檔案格式判斷（Encryption Format Detection）

系統首先透過檢查檔案中的 Magic Bytes 來判斷其加密格式：

若檔案 前 4 位元組等於 KWRP
→ 判定為 Copy 模式
→ 採用 Header‑first 格式，metadata 位於檔案開頭
若檔案 最後 4 位元組等於 KWRI
→ 判定為 In‑Place 模式
→ 採用 Footer 格式，metadata 位於檔案結尾

若上述任一條件皆不成立，則視為非 KvhWrap 加密檔案，解密流程即中止。

Step 2：中繼資料讀取（Metadata Extraction）

根據判定出的檔案格式，系統會：

Copy 模式：
從檔案開頭依序讀取 metadata 長度欄位與 metadata JSON
In‑Place 模式：
自檔案結尾反向讀取 magic bytes、認證標籤、nonce、metadata 長度欄位與 metadata JSON

完成後，系統即可取得解密所需之所有參數。

Step 3：Enhanced 模式判斷（Enhanced Mode Detection）

系統接著檢查 metadata 中的 enhanced 旗標：

當 metadata["enhanced"] == true 時
→ 判定該檔案使用 Enhanced 模式
→ 需進行 混合密碼（Hybrid Password）重建流程
當 enhanced == false 或欄位不存在
→ 使用者密碼將直接用於金鑰導出（不啟用混合密碼）

此判斷對應流程圖中 Enhanced? 分支節點。

Step 4：KDF 類型判斷（Key Derivation Selection）

系統依據 metadata 中的 kdf 欄位選擇金鑰導出方式：

metadata["kdf"] == 0
→ 使用 SHA‑256 進行金鑰導出
metadata["kdf"] == 1
→ 使用 scrypt 進行金鑰導出（記憶體硬化模式）

此步驟確保解密端使用與加密端完全一致的 KDF 參數。

Step 5：金鑰重建與檔頭解密（Key Reconstruction & Head Decryption）

根據前述判斷結果，系統將：

以使用者輸入之密碼（及必要時重建的 Hybrid Password）導出最終檔案金鑰
使用該金鑰嘗試解密檔案的加密檔頭（Encrypted Head）
驗證 GCM 認證標籤（Authentication Tag）

若認證失敗，則視為密碼錯誤或檔案遭竄改，解密流程立即中止。

Step 6：檔案還原（File Restoration）

驗證成功後，系統依序執行：

還原原始檔頭內容
串接未加密之後段資料
將檔案重新命名為原始檔名
還原原始時間戳
清理中介檔案與空資料夾（如適用）

至此，解密作業完成，檔案狀態與加密前保持一致。

規格總結（Specification Summary）

解密流程完全由檔案自身結構與 metadata 驅動
無須使用者手動指定 Copy / In‑Place 或 Enhanced 模式
所有模式判斷均可與 Decryption Workflow 圖表中的分支節點一一對應
任一步驟不符預期即會安全性中止，避免不完整或錯誤還原

10. 模式比較

🏆 推薦實務用法

In‑Place + scrypt + Enhanced

理由：

極速
高抗暴力破解
弱密碼也能被補強

功能與效能比較

功能項目	Copy + SHA‑256	Copy + scrypt	In‑Place + SHA‑256	In‑Place + scrypt
加密速度（10 GB 檔案）	約 30–90 秒	約 30–90 秒 + 130 ms	約 0.05 秒	約 0.18 秒
磁碟空間需求	原始檔案大小 × 2	原始檔案大小 × 2	約增加 236 位元組	約增加 236 位元組
原始檔案	保留	保留	直接修改	直接修改
抗暴力破解能力	⭐ 低	⭐⭐⭐ 高	⭐ 低	⭐⭐⭐ 高
加密範圍	僅檔頭（1 KB）	僅檔頭（1 KB）	僅檔頭（1 KB）	僅檔頭（1 KB）
Enhanced 模式	可選	可選	可選	可選
最適用情境	快速測試	重要文件、備份	大型檔案快速隱蔽	🏆 正式生產環境

🏆 建議設定（Recommended）

In‑Place + scrypt + Enhanced

適用於大型檔案的最快速加密模式
採用 scrypt 記憶體硬化金鑰導出（128 MB），具最高抗暴力破解能力
透過 檔案指紋強化密碼（Enhanced 模式）
即使使用者密碼強度較弱，仍可產生高強度加密金鑰

📦 安全備份建議（Safe Backup）

Copy + scrypt

原始檔案完全保留，不會被修改
適用於磁碟空間充足的情境
在加密過程中若發生中斷（例如斷電），資料安全性較高
對大型檔案而言速度較慢，但可確保原始資料完整性

規格結論（Specification Summary）

若以 效能與安全性 為主要考量，建議採用 In‑Place + scrypt + Enhanced
若以 資料保全與可回復性 為優先，建議採用 Copy + scrypt
SHA‑256 模式僅適合低風險或臨時性隱蔽需求，不建議用於正式環境

11. 加密流程（Encryption Process / Wrap）

本節說明 KvhWrap 在執行檔案加密（Wrap）時的完整處理步驟，適用於 Copy 模式與 In‑Place 模式。

Step 11.1：檔案前置檢查（Pre‑check）

在加密開始前，系統 SHALL 進行以下檢查：

確認檔案大小 ≥ 1024 位元組
確認檔案未包含 KWRP 或 KWRI magic bytes（避免重複加密）

若任一檢查不符合，系統 SHALL 跳過該檔案。

Step 11.2：原始檔案資訊保存（Metadata Collection）

系統 SHALL 記錄以下原始資訊至記憶體中，並於後續儲存至加密 metadata：

原始檔名（original filename）
原始檔案大小（original size）
存取時間（atime）
修改時間（mtime）

Step 11.3：Salt 與金鑰材料準備（Salt & Password Processing）

系統 SHALL 產生一組 base salt（隨機 16 位元組）
為每個檔案推導 per‑file salt
若啟用 Enhanced 模式：
- 系統 SHALL 依檔案內容產生 auto‑password
- 使用雙向 HMAC 將使用者密碼與 auto‑password 混合為 hybrid password
若未啟用 Enhanced 模式：
- 使用者密碼 SHALL 直接作為金鑰導出輸入

Step 11.4：金鑰導出（Key Derivation）

系統 SHALL 根據設定之 KDF 類型導出 32 位元組 AES 金鑰：

kdf = 0 → 使用 SHA‑256
kdf = 1 → 使用 scrypt（記憶體硬化）

Step 11.5：檔頭加密（Head Encryption）

系統 SHALL 讀取檔案前 1024 位元組
使用 AES‑256‑GCM
- 隨機產生 12 位元組 nonce
- 產生 16 位元組 GCM 認證標籤（Auth Tag）
加密輸出包含：
- ciphertext（1024B）
- nonce
- auth tag

Step 11.6：加密結果寫入（Write Encrypted Data）

根據所選模式：

Copy 模式（KWRP）

系統 SHALL 建立新 .ks 檔案
依序寫入：
- KWRP magic bytes
- metadata length
- metadata JSON
- encrypted head
- 原始未加密 tail data

In‑Place 模式（KWRI）

系統 SHALL 以 encrypted head 覆寫原檔案前 1024 位元組
在檔案結尾附加 footer（metadata + nonce + tag + magic）

Step 11.7：檔名與時間戳處理（Finalization）

系統 SHALL 將檔案重新命名為奈秒級時間戳（.ks）
SHALL 還原原始 atime / mtime
若包含子資料夾，系統 SHALL 同步處理資料夾重新命名與映射保存

12. 解密流程（Decryption Process / Unwrap）

本節描述 KvhWrap 在解密檔案時的標準作業流程，所有判斷皆由檔案結構與 metadata 自動驅動。

Step 12.1：加密格式判斷（Format Detection）

系統 SHALL 透過 Magic Bytes 判斷檔案格式：

前 4 位元組為 KWRP → Copy 模式
最後 4 位元組為 KWRI → In‑Place 模式

若皆不符合，系統 SHALL 視為非 KvhWrap 檔案並終止流程。

Step 12.2：Metadata 解析（Metadata Extraction）

依據判斷結果：

Copy 模式：從檔案開頭解析 metadata
In‑Place 模式：從檔案尾部反向解析 metadata、nonce 與 auth tag

Step 12.3：Enhanced 與 KDF 判斷

系統 SHALL 依 metadata 內容進行：

Enhanced 模式判斷
- metadata["enhanced"] == true → 重建 hybrid password
KDF 類型判斷
- 選擇 SHA‑256 或 scrypt

Step 12.4：金鑰重建（Key Reconstruction）

使用者輸入密碼
必要時解密 stored auto‑password
導出最終檔案金鑰（file key）

Step 12.5：檔頭解密與驗證（Head Decryption & Verification）

系統 SHALL 使用 AES‑256‑GCM 解密 encrypted head
系統 SHALL 驗證 GCM Auth Tag
- 驗證失敗 → 密碼錯誤或資料遭竄改 → 立即中止

Step 12.6：檔案還原（File Restoration）

驗證成功後，系統 SHALL：

還原檔案原始檔頭內容
串接後段未加密 data
還原原始檔名與時間戳
移除 .ks 檔案或 footer
還原子資料夾名稱（若存在）

規格總結（Specification Summary）

加密與解密流程皆為 確定性且可逆
所有決策皆由檔案自身描述資料驅動
任一驗證失敗即安全性中止，避免部分還原
能完整回復檔案至加密前狀態

13. 函式一覽（Function Reference）

本章節說明 KvhWrap 所提供之核心函式，依其職責分類為 加密相關、密碼強化、封裝（Wrap）、解封（Unwrap）與輔助工具函式。本節內容用於協助實作者理解系統內部邏輯與呼叫關係。

13.1 密碼學相關函式（Cryptographic Functions）

`_derive_key(password, kdf, salt)`

用途
由使用者密碼推導出固定長度之 AES 加密金鑰。
輸入
`password`：字串（使用者密碼）
`kdf`：整數（0 = SHA‑256，1 = scrypt）
`salt`：位元組序列（Salt 值）
輸出
32 位元組 AES 金鑰

`_encrypt_blob(key, plaintext)`

用途
執行 AES‑256‑GCM 加密作業，用於加密檔案開頭內容或中繼資料。
輸入
`key`：32 位元組 AES 金鑰
`plaintext`：欲加密之位元組資料
輸出
加密結果（nonce + authentication tag + ciphertext）

`_decrypt_blob(key, blob)`

用途
執行 AES‑256‑GCM 解密與完整性驗證。
輸入
`key`：32 位元組 AES 金鑰
`blob`：加密資料（含 nonce 與 auth tag）
輸出
解密後之純文字資料
若驗證失敗，則拋出例外並立即中止流程

13.2 密碼強化相關函式（Password Enhancement Functions）

`_generate_auto_password(filepath)`

用途
依檔案內容產生一組決定性的 24 字元自動密碼（Auto‑Password）。
輸入
`filepath`：檔案路徑
輸出
24 字元 Base64 字串

`_generate_hybrid_password(user_password, filepath)`

用途
使用雙向 HMAC 混合使用者密碼與 auto‑password，生成混合密碼（Hybrid Password）。
輸入
`user_password`：使用者密碼
`filepath`：檔案路徑
輸出
43 字元 Base64 編碼混合密碼

13.3 加密（Wrap）相關函式

`wrap_file(path, key, …)`

用途
以 Copy 模式將檔案加密為新的 `.ks` 檔案。
特性
不修改原始檔案
輸出格式為 `KWRP`

`wrap_file_inplace(path, key, …)`

用途
以 In‑Place 模式直接修改原檔案內容並附加 footer。
特性
原檔案被修改
輸出格式為 `KWRI`

`rename_subfolders(folder, password)`

用途
將子資料夾重新命名為時間戳，並儲存加密後的對照表。
輸出
隱藏檔案 `.kvh_folders.map`

13.4 解密（Unwrap）相關函式

`unwrap_auto(path, password)`

用途
自動判斷檔案加密格式，並執行對應解密流程。
特性
自動判斷 Copy / In‑Place
自動處理 Enhanced 模式

`_unwrap_copy(path, password)`

用途
內部函式，用於解密 Copy 模式（KWRP）檔案。

`_unwrap_inplace(path, password)`

用途
內部函式，用於解密 In‑Place 模式（KWRI）檔案。

`restore_subfolders(folder, password)`

用途
還原經重新命名之子資料夾名稱。

`cleanup_empty_dirs(folder)`

用途
清理解密後所遺留之空目錄。

13.5 輔助工具函式（Utility Functions）

`is_wrapped(filepath)`
→ 判斷檔案是否包含 KWRP / KWRI magic bytes
`_generate_unique_filename(dir, ext)`
→ 產生唯一奈秒級時間戳檔名
`_load_opts()` / `_save_opts(opts)`
→ 載入與儲存 GUI 使用者設定

14. 最佳使用情境與建議（Best Scenarios & Recommendations）

本章節說明 KvhWrap 在不同實務場景下之建議使用模式與安全考量。

14.1 建議使用情境

使用情境建議設定原因說明
🎬 大型影片檔（≥10 GB） In‑Place + scrypt + Enhanced O(1) I/O、高速、檔頭即為關鍵識別資訊
📸 攝影照片檔（JPEG / RAW） In‑Place + scrypt EXIF 集中於前段，適合快速處理大量檔案
📄 機密文件（PDF / DOCX） Copy + scrypt + Enhanced 原始檔案保留，安全性優先
💾 臨時隱蔽用途 In‑Place + SHA‑256 極速處理，適合短期需求
🔐 高安全需求 / 不可信儲存媒介 Copy + scrypt + Enhanced 原檔保留、抗離線暴力破解
📂 含多層資料夾的共享目錄任一模式子資料夾名稱會自動加密與還原

使用情境	建議設定	原因說明
🎬 大型影片檔（≥10 GB）	In‑Place + scrypt + Enhanced	O(1) I/O、高速、檔頭即為關鍵識別資訊
📸 攝影照片檔（JPEG / RAW）	In‑Place + scrypt	EXIF 集中於前段，適合快速處理大量檔案
📄 機密文件（PDF / DOCX）	Copy + scrypt + Enhanced	原始檔案保留，安全性優先
💾 臨時隱蔽用途	In‑Place + SHA‑256	極速處理，適合短期需求
🔐 高安全需求 / 不可信儲存媒介	Copy + scrypt + Enhanced	原檔保留、抗離線暴力破解
📂 含多層資料夾的共享目錄	任一模式	子資料夾名稱會自動加密與還原

14.2 不建議使用之情境（Out of Scope）

下列情境不屬於 KvhWrap 的設計防護範圍：
全磁碟或全檔案完整加密（請使用 BitLocker、VeraCrypt）
抵抗鑑識層級資料復原
防護記憶體 Dump 或執行期攻擊
極小型純文字檔案的內容不可讀性需求

14.3 設計取捨說明（Design Trade‑offs）

KvhWrap 使用「檔頭破壞」取代全檔加密，以換取極高效能
安全性主要依賴：
強化型 KDF（scrypt）
Enhanced 密碼混合機制
系統設計重點為：
讓檔案「看不出來是什麼」，而非讓內容「不可讀」

系統需求

Python 3.8+
Windows / macOS / Linux

[ 精選文章 ]

自行車 入門 Escape 3 , Snap 21 , Revel

2026年4月16日 星期四

檔案加密 (匿蹤) (使用 AES 加密)

🔒 KvhWrap

📑 目錄（Table of Contents）

1. 概覽（Overview & What It Does）

💡 設計理念（Design Philosophy）

2. 核心演算法（Core Algorithm）

3. 加密與解密流程（Flowcharts）

3.1 Wrap（加密）流程概要

3.2 Unwrap（解密）流程概要

4. 檔案格式（File Format）

4.1 Copy Mode（KWRP）

Encrypted Head Detail (AES-256-GCM blob)

4.2 In‑Place Mode（KWRI）

5. 為什麼只加密 1 KB？（Head Offset）

6. In‑Place 模式的巨大優勢

🚀 核心洞察（Key Insight）

7. 金鑰導出 KDF（Key Derivation Function）

7.1 SHA‑256（快速）

7.2 scrypt（強烈推薦）

7.3 每檔案 Salt（Per‑File Salt）

8. Enhanced 模式（密碼 + 檔案指紋）

8.1 自動密碼產生（Auto‑Password Generation）

8.2 混合式密碼混合機制（Hybrid Password Mixing）

設計原理

運算流程（概念說明）

安全特性

設計結論（Specification Summary）

8.3 為解密而儲存自動密碼（Storing the Auto‑Password for Decryption）

9. 解密自動判斷（Auto Mode）

解密格式與模式判斷（Detection Logic）

Step 1：檔案格式判斷（Encryption Format Detection）

Step 2：中繼資料讀取（Metadata Extraction）

Step 3：Enhanced 模式判斷（Enhanced Mode Detection）

Step 4：KDF 類型判斷（Key Derivation Selection）

Step 5：金鑰重建與檔頭解密（Key Reconstruction & Head Decryption）

Step 6：檔案還原（File Restoration）

規格總結（Specification Summary）

10. 模式比較

功能與效能比較

🏆 建議設定（Recommended）

In‑Place + scrypt + Enhanced

📦 安全備份建議（Safe Backup）

Copy + scrypt

規格結論（Specification Summary）

11. 加密流程（Encryption Process / Wrap）

Step 11.1：檔案前置檢查（Pre‑check）

Step 11.2：原始檔案資訊保存（Metadata Collection）

Step 11.3：Salt 與金鑰材料準備（Salt & Password Processing）

Step 11.4：金鑰導出（Key Derivation）

Step 11.5：檔頭加密（Head Encryption）

Step 11.6：加密結果寫入（Write Encrypted Data）

Copy 模式（KWRP）

In‑Place 模式（KWRI）

Step 11.7：檔名與時間戳處理（Finalization）

12. 解密流程（Decryption Process / Unwrap）

Step 12.1：加密格式判斷（Format Detection）

Step 12.2：Metadata 解析（Metadata Extraction）

Step 12.3：Enhanced 與 KDF 判斷

Step 12.4：金鑰重建（Key Reconstruction）

Step 12.5：檔頭解密與驗證（Head Decryption & Verification）

Step 12.6：檔案還原（File Restoration）

規格總結（Specification Summary）

13. 函式一覽（Function Reference）

13.1 密碼學相關函式（Cryptographic Functions）

_derive_key(password, kdf, salt)

用途由使用者密碼推導出固定長度之 AES 加密金鑰。輸入password：字串（使用者密碼）kdf：整數（0 = SHA‑256，1 = scrypt）salt：位元組序列（Salt 值）輸出32 位元組 AES 金鑰

_encrypt_blob(key, plaintext)

用途執行 AES‑256‑GCM 加密作業，用於加密檔案開頭內容或中繼資料。輸入key：32 位元組 AES 金鑰plaintext：欲加密之位元組資料輸出加密結果（nonce + authentication tag + ciphertext）

_decrypt_blob(key, blob)

用途執行 AES‑256‑GCM 解密與完整性驗證。輸入key：32 位元組 AES 金鑰blob：加密資料（含 nonce 與 auth tag）輸出解密後之純文字資料若驗證失敗，則拋出例外並立即中止流程

13.2 密碼強化相關函式（Password Enhancement Functions）

_generate_auto_password(filepath)

用途依檔案內容產生一組決定性的 24 字元自動密碼（Auto‑Password）。輸入filepath：檔案路徑輸出24 字元 Base64 字串

_generate_hybrid_password(user_password, filepath)

用途使用雙向 HMAC 混合使用者密碼與 auto‑password，生成混合密碼（Hybrid Password）。輸入user_password：使用者密碼filepath：檔案路徑輸出43 字元 Base64 編碼混合密碼

13.3 加密（Wrap）相關函式

wrap_file(path, key, …)

自行車入門 Escape 3 , Snap 21 , Revel

2026年4月16日星期四

4.1 Copy Mode（`KWRP`）

4.2 In‑Place Mode（`KWRI`）

`_derive_key(password, kdf, salt)`

用途
由使用者密碼推導出固定長度之 AES 加密金鑰。
輸入
`password`：字串（使用者密碼）
`kdf`：整數（0 = SHA‑256，1 = scrypt）
`salt`：位元組序列（Salt 值）
輸出
32 位元組 AES 金鑰

`_encrypt_blob(key, plaintext)`

用途
執行 AES‑256‑GCM 加密作業，用於加密檔案開頭內容或中繼資料。
輸入
`key`：32 位元組 AES 金鑰
`plaintext`：欲加密之位元組資料
輸出
加密結果（nonce + authentication tag + ciphertext）

`_decrypt_blob(key, blob)`

用途
執行 AES‑256‑GCM 解密與完整性驗證。
輸入
`key`：32 位元組 AES 金鑰
`blob`：加密資料（含 nonce 與 auth tag）
輸出
解密後之純文字資料
若驗證失敗，則拋出例外並立即中止流程

`_generate_auto_password(filepath)`

用途
依檔案內容產生一組決定性的 24 字元自動密碼（Auto‑Password）。
輸入
`filepath`：檔案路徑
輸出
24 字元 Base64 字串

`_generate_hybrid_password(user_password, filepath)`

用途
使用雙向 HMAC 混合使用者密碼與 auto‑password，生成混合密碼（Hybrid Password）。
輸入
`user_password`：使用者密碼
`filepath`：檔案路徑
輸出
43 字元 Base64 編碼混合密碼

`wrap_file(path, key, …)`

用途
以 Copy 模式將檔案加密為新的 `.ks` 檔案。
特性
不修改原始檔案
輸出格式為 `KWRP`

`wrap_file_inplace(path, key, …)`

用途
以 In‑Place 模式直接修改原檔案內容並附加 footer。
特性
原檔案被修改
輸出格式為 `KWRI`

`rename_subfolders(folder, password)`

用途
將子資料夾重新命名為時間戳，並儲存加密後的對照表。
輸出
隱藏檔案 `.kvh_folders.map`

`unwrap_auto(path, password)`

用途
自動判斷檔案加密格式，並執行對應解密流程。
特性
自動判斷 Copy / In‑Place
自動處理 Enhanced 模式

`_unwrap_copy(path, password)`

用途
內部函式，用於解密 Copy 模式（KWRP）檔案。

`_unwrap_inplace(path, password)`

用途
內部函式，用於解密 In‑Place 模式（KWRI）檔案。

`restore_subfolders(folder, password)`

用途
還原經重新命名之子資料夾名稱。

`cleanup_empty_dirs(folder)`

用途
清理解密後所遺留之空目錄。

`is_wrapped(filepath)`
→ 判斷檔案是否包含 KWRP / KWRI magic bytes
`_generate_unique_filename(dir, ext)`
→ 產生唯一奈秒級時間戳檔名
`_load_opts()` / `_save_opts(opts)`
→ 載入與儲存 GUI 使用者設定

下列情境不屬於 KvhWrap 的設計防護範圍：
全磁碟或全檔案完整加密（請使用 BitLocker、VeraCrypt）
抵抗鑑識層級資料復原
防護記憶體 Dump 或執行期攻擊
極小型純文字檔案的內容不可讀性需求

KvhWrap 使用「檔頭破壞」取代全檔加密，以換取極高效能
安全性主要依賴：
強化型 KDF（scrypt）
Enhanced 密碼混合機制
系統設計重點為：
讓檔案「看不出來是什麼」，而非讓內容「不可讀」