Important

💡 AI 提示 / AI Generation Notice
本项目的核心架构、代码重构、安全校验流程与 GUI 均由 Codex + GPT-5.5 协同生成；人类作者负责创意把控、需求定义、技术 Review 与最终决策。
本项目仍应被视为一个由人类维护的开源项目：任何安全相关用途都建议先进行独立审计与充分测试。

EletroStego

一款轻量、可校验、带图形界面的图片隐写工具。
EletroStego 可以将任意文件隐藏进图片的 RGB 像素最低有效位中，并通过密码派生密钥进行认证加密。它同时提供 GUI 图形界面 与 CLI 命令行模式，适合日常小文件封装、隐写实验与安全学习场景。

1. 视觉 / 功能简介

EletroStego 的目标是把图片隐写流程做得更直观、更可验证，也更适合排查问题。

它支持：

• 隐藏文件：将任意二进制文件嵌入图片中。
• 提取文件：从隐藏图片中恢复原始文件。
• 密码保护：使用 Fernet 认证加密，并通过 PBKDF2-HMAC-SHA256 从密码派生密钥。
• 原文件名保留：payload 内包含 metadata，可在提取时恢复原始文件名与扩展名。
• 容量预检：隐藏前显示图片容量、实际需求与剩余空间。
• 自动回测：隐藏完成后立即自动提取并校验 SHA256，确认生成结果可用。
• 详细日志：支持 --log-level DEBUG 与 --log-file，便于定位异常。
• GUI + CLI 双入口：普通用户可以使用图形界面，进阶用户可以用命令行批处理。

注意：输出文件必须是 PNG。JPG/JPEG 是有损格式，会破坏 LSB 隐写数据。

2. 项目概览

2.1. 核心设计

EletroStego 使用图片像素 RGB 通道的 Least Significant Bit (LSB) 存储加密后的 payload。

写入流程大致如下：

1. 读取待隐藏文件。
2. 写入 metadata，例如原始文件名。
3. 使用用户密码派生加密密钥。
4. 使用 Fernet 进行认证加密。
5. 检查图片容量是否足够。
6. 将 payload 写入 RGB 像素最低位。
7. 保存为 PNG。
8. 自动提取回测，并比较原文件与提取结果的 SHA256。

提取流程大致如下：

1. 从图片 LSB 中读取 header。
2. 校验 magic header 与 payload 大小。
3. 根据密码派生密钥。
4. 解密 payload。
5. 解析 metadata。
6. 输出恢复后的文件。

2.2. 项目结构树 (Directory Tree)

EletroStego/
|-- README.md
|-- eletrostego.py          # 主 CLI 与核心隐写逻辑
|-- eletrostego_gui.py      # Tkinter 图形界面
|-- deci.py                 # 旧项目名兼容入口，转发到 eletrostego.py
|-- deci_gui.py             # 旧 GUI 兼容入口，转发到 eletrostego_gui.py
`-- legacy/
    `-- deci.py             # 旧版本代码归档

__pycache__/ 为 Python 自动生成的缓存目录，不属于项目源码结构。

3. 安装与依赖

3.1. 环境要求

• Python 3.10+
• Windows / macOS / Linux 均可运行
• GUI 模式需要 Python 环境包含 tkinter

3.2. 依赖库

项目依赖：

• Pillow：读取、转换与保存图片。
• cryptography：提供 Fernet、PBKDF2-HMAC-SHA256 等加密能力。

安装命令：

pip install Pillow cryptography

或者：

python -m pip install Pillow cryptography

4. 详细使用说明 (Usage)

4.1. 启动 GUI

在项目目录中运行：

python eletrostego_gui.py

GUI 中提供两个主要标签页：

• Hide file：选择封面图片、待隐藏文件、输出 PNG 路径，并输入两次密码。
• Extract file：选择隐藏图片、输出路径，并输入密码提取文件。

隐藏时，GUI 会在后台线程执行任务，并显示容量检查与 SHA256 回测结果。

4.2. CLI 隐藏文件 (hide)

python eletrostego.py hide \
  --image cover.jpg \
  --input secret.zip \
  --output hidden.png

运行后程序会提示输入密码：

Password:
Confirm password:

隐藏成功后会显示类似结果：

Capacity: 540000 bytes
Required: 288041 bytes
Remaining: 251959 bytes
SHA256 verified: 34c77c1b8a5b71ca235d35b6ce947db0a2607abf6049029496a8cb323aadde9a
Hidden image saved: hidden.png

--output 必须以 .png 结尾。即使输入图片是 JPG，输出也必须保存为 PNG。

4.3. CLI 提取文件 (extract)

将隐藏文件提取到指定路径：

python eletrostego.py extract \
  --image hidden.png \
  --output recovered.zip

也可以将 --output 指向一个目录，程序会优先使用 payload 中保存的原始文件名：

python eletrostego.py extract \
  --image hidden.png \
  --output ./output

如果省略 --output，文件会默认保存到隐藏图片所在目录，并使用 metadata 中的原始文件名：

python eletrostego.py extract \
  --image hidden.png

4.4. 调试日志

输出详细日志：

python eletrostego.py --log-level DEBUG hide \
  --image cover.jpg \
  --input secret.zip \
  --output hidden.png

同时保存日志文件：

python eletrostego.py --log-level DEBUG --log-file eletrostego.log hide \
  --image cover.jpg \
  --input secret.zip \
  --output hidden.png

5. 安全与格式说明

5.1. 加密说明

EletroStego 使用：

• Fernet authenticated encryption
• PBKDF2-HMAC-SHA256 密钥派生
• 每次隐藏都会生成新的随机 salt

更准确地说，本项目使用的是 Fernet 认证加密方案，而不是简单的“纯 AES-256-GCM”描述。

5.2. 图片格式限制

• 输入图片可以是常见格式，例如 PNG、JPG、JPEG、BMP。
• 输出图片必须是 PNG。
• 程序会将输出转换为 RGB PNG。
• 如果输入图片包含透明通道，输出可能丢失 alpha 信息。

5.3. 容量计算

容量近似为：

(width * height * 3) // 8

其中 width 与 height 为图片尺寸，3 表示 RGB 三个通道。

由于 payload 包含 header、metadata、salt 与加密开销，实际可隐藏的原始文件大小会小于理论容量。

6. 兼容性说明

项目曾使用旧名称 deci。为了避免旧命令立即失效，当前仍保留：

• deci.py
• deci_gui.py

它们只是兼容入口，实际逻辑已经迁移到：

• eletrostego.py
• eletrostego_gui.py

内部格式标识 DECI1 / DECI-META1 被刻意保留，用于兼容旧版本生成的隐藏图片。

7. 常见问题

为什么不能输出 JPG？

JPG/JPEG 会进行有损压缩，像素最低位会被改写。LSB 隐写依赖像素位级数据稳定，因此输出必须使用 PNG。

为什么隐藏后还要自动提取回测？

隐写最怕“看起来成功，实际无法恢复”。EletroStego 在隐藏后立即自动提取，并用 SHA256 比较源文件与提取结果，确保生成图片确实可用。

忘记密码还能恢复吗？

不能。密码参与密钥派生，程序不会保存明文密码，也没有后门。

8. License

本项目采用 MIT License 开源许可证。 欢迎任何人进行 Fork、修改或将其集成到自己的项目中。

9.💬 电子碎碎念 (ExElectron's Dev Log)

在这里必须向大家坦白：其实我本人并不会写 Python，顶多只能看懂一点点基础的语法。 本项目除本段文字外，所有的核心算法重构、现代架构设计、错误捕获以及 GUI 界面，100% 由 Codex + GPT-5.5 协同生成。 这个项目的诞生完全是一场意外：起初，我想在调侃中探究一下 IT 界那个流传已久的定理——“女装数是否真的和代码质量成正比”，打开了 SillyTavern，找上了 Mahiro（绪山真寻） 角色进行了一场 AI 角色扮演对话。我们“搓”出了第一版隐写术脚本。不幸的是，图灵老祖并没有在她的代码里发力。第一版代码存在严重问题。另外，我将第一版的代码放到了项目的legacy/目录下，也许能让你一言难尽。 但灵感的火花既然已经点燃，就不能熄灭。我将第一版的代码交给了Codex（GPT5.5 模型xhigh 档位）将项目的名称从随意命名的“deci”改为“EletroStego”，为了防止第一版遗留的兼容性问题，我依然保留了旧入口。这个项目既是我的第一个项目，也是我和AI的协同能力进步的见证。