michaelgiuliano/s3-crypt-vault

# S3 加密库    ## 项目概述 本项目实现了一个基于客户端加密和零知识原则的**安全存储系统**。 文件在使用 **AES-256-GCM** 进行本地加密，并采用信封加密模型处理后，再传输到 AWS S3。即使 S3 存储桶被入侵，在没有本地加密密钥的情况下，存储的数据仍然无法被读取。 云服务提供商始终无法访问明文数据，确保加解密操作始终在客户端进行。 系统提供两种接口：用于直接本地使用的 **CLI 工具**和用于程序化访问的 **REST API**。 ## 架构 系统由多个层次组成，每个层次都有明确的职责： - **CLI 层（Typer）** 处理用户交互和命令执行。 - **API 层（FastAPI）** 通过 HTTP 暴露加密存储操作。 - **加密库层（`CryptVault`）** 协调加解密和存储操作。接受依赖注入——与 CLI 和 API 关注点解耦。 - **加密层** 使用 AES-256-GCM 和信封加密实现客户端加密。 - **存储层（`S3Client`）** 处理与 AWS S3 的通信（开发环境中使用 LocalStack）。 - **错误处理层** 提供领域特定的异常，并一致地映射到 API 层的 HTTP 响应。 ### 数据流 ``` User Input (CLI or HTTP) ↓ CLI / API Layer ↓ Vault (orchestration) ↓ Encryption (client-side) ↓ S3 Client ↓ AWS S3 ``` 加密始终在本地进行，然后才会将任何数据传输到云端。 ## 安全模型 本项目遵循零知识架构： ### 防护范围 - S3 存储桶被入侵 - 未经授权访问存储的对象 - 云服务提供商数据泄露 ### 不防护范围 - 加密密钥丢失或被盗 - 本地机器被入侵 - 用户密钥管理不当 ### 密钥责任 用户全权负责安全存储加密密钥。 如果密钥丢失，数据将无法恢复。 ## 功能特性 - 使用 *AES-256-GCM* 进行**客户端加密**，结合信封加密和基于密码的密钥派生（`scrypt`）。 - **零知识设计**——加密密钥永远不会离开本地环境。 - **REST API**（FastAPI）用于程序化访问加密存储操作。 - 使用基于环境变量的凭证进行安全的 **AWS 集成**。 - 支持使用 **LocalStack** 进行本地开发。 - 可安装的 CLI 工具（**`s3vault`**）用于与加密存储交互。 - 使用 `pytest` 进行**集成测试**，包括通过 FastAPI `TestClient` 进行的完整 API 测试覆盖。 - 使用 GitHub Actions 的 **CI 流水线**。 ## 技术栈 - **语言**：Python 3.12+ - **云服务提供商**：AWS S3 - **API 框架**：FastAPI + Uvicorn - **基础设施模拟**：LocalStack + Docker Compose - **自动化**：GitHub Actions（CI） - **CLI 框架**：Typer - **测试**：Pytest ## 前置条件 在 AWS 上使用加密库之前，您必须具备： - 具有 S3 权限的 AWS 凭证 - 用于存储加密文件的 S3 存储桶 - 本地加密密钥文件（`master.key`） 生成密钥： ``` s3vault init-key ``` 创建存储桶： ``` s3vault create-bucket ``` ## 安装 克隆仓库： ``` git clone https://github.com/michaelgiuliano/s3-crypt-vault.git cd s3-crypt-vault ``` 以可编辑模式安装： ``` pip install -e . ``` 安装后，CLI 命令即可使用： ``` s3vault ``` ### 依赖管理 本项目使用 `pip-tools` 进行可重现的依赖管理。 更新依赖： ``` pip-compile requirements.in pip-compile dev-requirements.in ``` ## 环境配置 根据 `.env.example` 创建 `.env` 文件。 ``` AWS_ACCESS_KEY_ID=your_access_key_here AWS_SECRET_ACCESS_KEY=your_secret_key_here AWS_REGION=eu-north-1 S3_BUCKET_NAME=your-bucket-name-here KEY_PATH=master.key USE_LOCALSTACK=true ``` 当 `USE_LOCALSTACK=true` 时，CLI 和 API 都会连接到本地 S3 模拟器而非 AWS。 ## 本地开发（LocalStack） 启动本地 S3 环境： ``` docker-compose up -d ``` LocalStack 在本地模拟完整的 AWS S3 工作流程，无需创建真实的云资源。 ## CLI 使用方法 ### 设置 ``` # 生成新的加密密钥： s3vault init-key # 创建配置的 S3 存储桶： s3vault create-bucket # 列出可用的存储桶： s3vault list-buckets ``` ### 操作 ``` # 上传文件（在上传前在本地加密）： s3vault upload secret.txt # 列出存储在配置的存储桶中的加密文件： s3vault list-files # 下载并解密文件： s3vault download secret.txt.enc decrypted.txt ``` ## API 使用方法 启动 API 服务器： ``` uvicorn app.api.main:app --reload ``` 交互式文档可在 `http://localhost:8000/docs` 获取。 ### 端点 #### 健康检查 ``` curl http://localhost:8000/health ``` ``` {"status": "ok"} ``` #### 列出加密文件 ``` curl http://localhost:8000/files ``` ``` {"files": ["secret.txt.enc"]} ``` #### 上传文件 ``` curl -X POST http://localhost:8000/files \ -F "file=@secret.txt" \ -F "password=your-password" ``` ``` {"object_key": "secret.txt.enc"} ``` 如果文件已存在则返回 `409`。 #### 下载并解密文件 ``` curl -X POST http://localhost:8000/files/secret.txt.enc/download \ -H "Content-Type: application/json" \ -d '{"password": "your-password"}' \ --output decrypted.txt ``` 如果密码错误返回 `400`，文件不存在返回 `404`。 ## 加密架构 所有文件在上传到 S3 之前都会在**本地加密**。 本项目使用 **AES-256-GCM**，这是一种认证加密模式，确保： - **机密性**——没有密钥无法读取加密数据 - **完整性**——篡改密文会被检测到 - **真实性**——被修改的数据无法成功解密 ### v2 加密模型（信封加密） 从版本 0.2.0 开始，加密库采用信封加密方案： - 为每个文件生成一个**数据加密密钥（DEK）** - 使用 `scrypt` 从用户密码派生**主密钥** - 使用 DEK 对文件进行加密（AES-256-GCM） - 使用主密钥对 DEK 进行加密 这为每个文件提供了密钥隔离，并消除了磁盘上任何持久化的主密钥。 ### 加密流程 ``` File is read locally ↓ Random DEK generated per file ↓ AES-256-GCM encrypts the file using the DEK ↓ DEK is encrypted with the password-derived master key ↓ Structured binary blob (SCV2 format) uploaded to S3 ``` ### 篡改检测 *AES-GCM* 提供**内置身份验证**。即使密文只有一位被修改，解密也会因身份验证错误而失败。此行为由自动化测试 `test_tamper_detection()` 验证。 ## 测试 运行完整测试套件： ``` pytest tests/ ``` 测试覆盖： - 加解密正确性 - 篡改检测 - 使用 LocalStack 的 S3 集成 - 端到端加密库工作流 - 完整 API 集成测试（上载、下载、列表、错误情况） ## 持续集成 **GitHub Actions** 自动运行： - 代码检查（`flake8`） - 集成测试（`pytest`） - LocalStack 环境 在每次 `push` 和 `pull request` 时运行。 ## 项目结构 ``` s3-crypt-vault/ ├───.github/ │ └───workflows/ │ └───ci.yml ├───app/ │ ├───api/ │ │ ├───__init__.py │ │ ├───dependencies.py │ │ ├───exceptions.py │ │ ├───main.py │ │ ├───routes.py │ │ └───schemas.py │ ├───crypto/ │ │ ├───__init__.py │ │ ├───envelope.py │ │ └───kdf.py │ ├───__init__.py │ ├───cli.py │ ├───config.py │ ├───encryptor.py │ ├───exceptions.py │ ├───s3_client.py │ └───vault.py ├───tests/ │ ├───__init__.py │ ├───test_api.py │ ├───test_encryption.py │ ├───test_s3_client.py │ ├───test_s3_connection.py │ └───test_vault.py ├───.env.example ├───.gitignore ├───CHANGELOG.md ├───dev-requirements.in ├───dev-requirements.txt ├───docker-compose.yml ├───LICENSE ├───pyproject.toml ├───README.md ├───requirements.in └───requirements.txt ``` ## 许可证 本项目基于 MIT 许可证授权。 您可以自由使用、修改和分发本软件，但需注明出处。详见 LICENSE 文件中的完整许可证文本。

标签：AES-256-GCM, AV绕过, AWS S3, FastAPI, LocalStack, meg, Python, REST API, Typer, 云存储安全, 信封加密, 信息安全, 加密存储, 安全存储系统, 安全规则引擎, 客户端加密, 数据加密, 无后门, 端到端加密, 网络安全, 网络扫描, 网络测绘, 请求拦截, 隐私保护, 零知识架构