RakkaEvandra06/QuanSphere

# QuanSphere — 强化加密工具包 **ZeroTrace** 是一个生产级、强化的加密工具包和 CLI，专为在 Python 中进行安全数据操作而设计。它涵盖了日常加密需求的方方面面：对称和非对称加密、混合密钥交换、数字签名、多算法哈希、基于密码的加密、分块文件加密以及加密安全的随机数生成——所有这些都通过一个统一的 `crypto-toolkit` 命令来完成。 ## 目录 - [关于本项目](#about-the-project) - [架构](#architecture) - [安装](#installation) - [验证安装](#verify-installation) - [用法](#usage) - [开发](#development) - [贡献](#contributing) - [许可证](#license) - [免责声明](#disclaimer) ## 💡 关于本项目 QuanSphere 的设计围绕着这样一个原则：**正确的密码学应该是最容易、最自然的路径**。工具包中的每一个决策都体现了这一点： - **深度防御封装格式** 每个 ciphertext token 都包含一个带版本的 magic header、算法标签、nonce 和 GCM 身份验证标签。在任何明文字节被释放之前，就能检测到篡改行为。 - **混合加密** ECC (SECP256R1 / ECDH) 和 X25519 混合路径将临时的 Diffie-Hellman 与 AES-256-GCM 和 HKDF-SHA-256 结合在一起，因此接收者的长期私钥永远不会被用来直接加密数据。 - **默认使用 Argon2id** 基于密码的加密和文件加密开箱即用地使用 Argon2id（时间成本 3，内存 64 MiB，并行度 4）来派生密钥。PBKDF2-HMAC 可作为备选方案，其迭代次数符合 OWASP 2023 标准。 - **解密时的 DoS 防护** 所有 PBE 和文件加密路径都会限制从不受信任的信封中读取的 KDF 参数，防止攻击者触发过度的 CPU 或内存使用。 - **密钥材料清零** 共享密钥和派生密钥在使用后会立即使用 `ctypes.memset` (CPython) 进行覆盖。 - **无明文泄漏** 原始密码和敏感参数永远不会被记录、打印或存储。当密码出现在 shell 历史记录中时，CLI 标志会发出明显的警告，并始终推荐使用 `--prompt-password`。 - **分块文件流式传输** 任意大小的文件都会被分成 64 KiB 的块进行加密，每个块的 AAD 会将该块与其位置和文件头绑定，从而检测出 bit-flip 攻击和截断攻击。 ## 🏗️ 架构 ``` QuanSphere/ ├── assets/ # Banner images and static assets ├── crypto_toolkit/ │ ├── cli/ │ │ ├── __init__.py # CLI package version │ │ ├── main.py # Typer app all CLI commands │ │ └── output.py # Rich-powered terminal output helpers │ └── core/ │ ├── asymmetric.py # RSA-4096, ECC P-256, X25519 keygen, OAEP, hybrid ECDH │ ├── constants.py # Shared algorithm parameters and envelope magic bytes │ ├── exceptions.py # Typed exception hierarchy (8 exception classes) │ ├── file_crypto.py # Chunked AES-256-GCM file encryption/decryption │ ├── hashing.py # SHA-256/512, SHA3-256/512, BLAKE2b/s data, stream, file │ ├── kdf.py # Argon2id and PBKDF2-HMAC key derivation │ ├── pbe.py # Password-based encryption (Argon2id or PBKDF2 + AES-GCM) │ ├── random_gen.py # Cryptographically secure key, token, and password generation │ ├── signatures.py # Ed25519 and RSA-PSS sign/verify + PEM serialisation │ └── symmetric.py # AES-256-GCM and ChaCha20-Poly1305 authenticated encryption ├── tests/ │ ├── integration/ │ │ ├── __init__.py │ │ └── test_cli.py # End-to-end CLI integration tests │ └── unit/ │ ├── __init__.py │ ├── conftest.py # Shared fixtures │ ├── test_asymmetric.py │ ├── test_file_crypto.py │ ├── test_hashing.py │ ├── test_kdf.py │ ├── test_pbe.py │ ├── test_random_gen.py │ ├── test_signatures.py │ └── test_symmetric.py ├── LICENSE.txt ├── pyproject.toml └── README.md ``` ## ⚙️ 安装 **要求：** Python ≥ 3.10 ``` # 1. Clone 仓库 git clone https://github.com/RakkaEvandra06/QuanSphere.git cd QuanSphere # 2. 创建并激活虚拟环境（推荐） python -m venv .venv source .venv/bin/activate # Windows: .venv\Scripts\activate # 3. 安装所有开发依赖 pip install -e ".[dev]" ``` **仅安装运行时（不包含开发工具）：** ``` pip install -e . ``` ### 验证安装 ``` crypto-toolkit --help ``` ## 🚀 用法 ### 对称加密 ``` # 生成 256 位 AES 密钥 crypto-toolkit generate-key --type symmetric # → Symmetric Key (hex): a1b2c3... # 使用密钥加密 (AES-256-GCM) crypto-toolkit encrypt "my secret message" --key # 解密 crypto-toolkit decrypt --key # 使用 ChaCha20-Poly1305 替代 AES-GCM crypto-toolkit encrypt "data" --key --algo chacha20 # 使用密码加密 (Argon2id KDF — 无需密钥管理) crypto-toolkit encrypt "my secret" --password "strongpassword" crypto-toolkit decrypt --password "strongpassword" # 交互式密码提示 — 永远不会存储在 shell 历史记录中 crypto-toolkit encrypt "data" --prompt-password # 从 stdin 或文件读取明文 echo "secret" | crypto-toolkit encrypt --stdin --key crypto-toolkit encrypt --input-file document.txt --key --output document.enc ``` ### 哈希 ``` # SHA-256 (默认) crypto-toolkit hash "hello world" # 其他算法 crypto-toolkit hash "hello world" --algo sha512 crypto-toolkit hash "hello world" --algo sha3_256 crypto-toolkit hash "hello world" --algo blake2b # 对文件进行 Hash crypto-toolkit hash --file /path/to/document.pdf # 从 stdin 进行 Hash echo -n "pipe this" | crypto-toolkit hash --stdin # 支持: sha256, sha512, sha3_256, sha3_512, blake2b, blake2s ``` ### 密钥生成 ``` # 对称 AES-256 密钥 (hex) crypto-toolkit generate-key --type symmetric # Ed25519 签名密钥对 → ed25519_private.pem + ed25519_public.pem crypto-toolkit generate-key --type ed25519 --out ./keys/ # ECC P-256 密钥对 (用于混合加密) crypto-toolkit generate-key --type ecc --out ./keys/ # X25519 密钥对 (用于 Diffie-Hellman 混合加密) crypto-toolkit generate-key --type x25519 --out ./keys/ # RSA-4096 密钥对 crypto-toolkit generate-key --type rsa --out ./keys/ # 使用密码短语加密私钥 crypto-toolkit generate-key --type rsa --out ./keys/ --key-password "keypass" # URL 安全的随机 token (32 字节熵) crypto-toolkit generate-key --type token # 安全的随机密码 (默认 20 个字符，大写字母 + 数字 + 符号) crypto-toolkit generate-key --type password crypto-toolkit generate-key --type password --size 32 ``` ### 数字签名 ``` # 生成 Ed25519 密钥对 crypto-toolkit generate-key --type ed25519 --out ./keys/ # 签名数据 crypto-toolkit sign "important document" --key ./keys/ed25519_private.pem # → Signature (ed25519, base64): # 对文件进行签名 crypto-toolkit sign --input-file contract.pdf --key ./keys/ed25519_private.pem # 验证签名 crypto-toolkit verify "important document" \ --sig \ --key ./keys/ed25519_public.pem # → ✓ Signature (ed25519) 有效。 (exit 0) # → ✗ Signature (ed25519) 无效。 (exit 1) # RSA-PSS (SHA-256) 替代方案 crypto-toolkit sign "data" --key ./keys/rsa_private.pem --algo rsa-pss crypto-toolkit verify "data" --sig --key ./keys/rsa_public.pem --algo rsa-pss # 受密码短语保护的私钥 crypto-toolkit sign "data" --key ./keys/rsa_private.pem --key-password "keypass" ``` ### RSA 加密 ``` # 生成 RSA-4096 密钥对 crypto-toolkit generate-key --type rsa --out ./keys/ # 使用 RSA-OAEP / SHA-256 加密 (适用于小型 payload，例如 session key) crypto-toolkit rsa-encrypt "secret session key" --key ./keys/rsa_public.pem # 解密 crypto-toolkit rsa-decrypt --key ./keys/rsa_private.pem # 受密码短语保护的私钥 crypto-toolkit rsa-decrypt \ --key ./keys/rsa_private.pem \ --key-password "keypass" ``` ### 文件加密 ``` # 生成密钥 crypto-toolkit generate-key --type symmetric # → a1b2c3... # 加密文件 (原始密钥) crypto-toolkit encrypt-file secret.pdf secret.pdf.enc --key # 解密 crypto-toolkit decrypt-file secret.pdf.enc recovered.pdf --key # 使用 Argon2id 派生的密钥加密 (KDF salt 嵌入在输出文件中) crypto-toolkit encrypt-file data.zip data.zip.enc --password "vaultpassword" crypto-toolkit decrypt-file data.zip.enc data.zip --password "vaultpassword" # 使用 PBKDF2 替代 Argon2id crypto-toolkit encrypt-file data.zip data.zip.enc --pbkdf2 --password "vaultpassword" # 交互式提示 (推荐用于敏感文件) crypto-toolkit encrypt-file sensitive.db sensitive.db.enc --prompt-password crypto-toolkit decrypt-file sensitive.db.enc sensitive.db --prompt-password ``` ### 密钥派生 ``` # 使用 Argon2id 派生密钥 (默认) crypto-toolkit derive-key --password "mypassword" # → Derived Key (Argon2id): # → Salt (保存此项以便重新派生): # 使用已保存的 salt 重新派生 (生成相同的密钥) crypto-toolkit derive-key --password "mypassword" --salt # PBKDF2-HMAC-SHA256 (OWASP 2023: 600,000 次迭代) crypto-toolkit derive-key --password "mypassword" --pbkdf2 # PBKDF2-HMAC-SHA512 (OWASP 2023: 210,000 次迭代) crypto-toolkit derive-key --password "mypassword" --pbkdf2 --hash-algo sha512 # 交互式提示 (推荐) crypto-toolkit derive-key --prompt-password ``` ### 安全随机数生成 ``` # URL 安全的随机 token (默认, 32 字节熵) crypto-toolkit random # Hex 编码的随机字节 crypto-toolkit random --kind hex --bytes 64 # Base64 编码的随机字节 crypto-toolkit random --kind base64 --bytes 32 # 安全的随机密码 (20 个字符，保证包含大写字母 + 数字 + 符号) crypto-toolkit random --kind password --length 24 # 将输出写入文件 crypto-toolkit random --kind token --output ./secrets/token.txt ``` ## 🛠️ 开发 ### 运行测试 ``` # 运行所有测试并带有覆盖率 (推荐) pytest # 详细输出 pytest -v # 仅运行单元测试 pytest tests/unit/ # 仅运行集成测试 pytest tests/integration/ # 生成 HTML 覆盖率报告 pytest --cov=crypto_toolkit --cov-report=html # → 在浏览器中打开 htmlcov/index.html ``` ### Lint 与类型检查 ``` # 安装 lint 扩展 pip install -e ".[lint]" # 使用 ruff 进行 lint 并自动修复 ruff check . ruff check . --fix # 使用 mypy 进行静态类型检查 mypy crypto_toolkit/ ``` ### 构建和发布 ``` # 安装构建工具 pip install build twine # 构建源分发和 wheel python -m build # 验证分发包 twine check dist/* # 上传到 PyPI twine upload dist/* ``` ## 📜 许可证 基于 **MIT License** 分发。完整文本请参见 [`LICENSE.txt`](LICENSE.txt)。 ## ⚠️ 免责声明 QuanSphere 的开发仅用于**教育和研究目的**。虽然它应用了完善的加密原语并遵循当前的最佳实践参数建议，但在将其部署到生产或安全关键环境之前，任何工具包都无法替代正式的安全审计。请务必与合格的专业人员一起根据您的具体威胁模型审查加密选择。

标签：CVE, Python, 加密, 密码学, 手动系统调用, 数字签名, 文件保护, 无后门, 漏洞扫描器, 逆向工具