From 51e129f8a2ece1a112461d4a6bd81edabe55d6a8 Mon Sep 17 00:00:00 2001 From: godvmxi Date: Wed, 11 Feb 2026 01:09:59 -0800 Subject: [PATCH] fix directory and add en/cn readme --- README.md | 83 ++++++++++++++------------------- cn/README.md | 61 ++++++++++++++++++++++++ data_flow.md => cn/data_flow.md | 0 en/README.md | 61 ++++++++++++++++++++++++ en/data_flow.md | 49 +++++++++++++++++++ test_core.py | 79 +++++++++++++++++++++++++++++++ 6 files changed, 284 insertions(+), 49 deletions(-) create mode 100644 cn/README.md rename data_flow.md => cn/data_flow.md (100%) create mode 100644 en/README.md create mode 100644 en/data_flow.md create mode 100644 test_core.py diff --git a/README.md b/README.md index f8f2c9d..e4d7490 100644 --- a/README.md +++ b/README.md @@ -1,61 +1,46 @@ -# Sentinel Crypt Core +# Sentinel Protocol Demo -Sentinel 是一个用于数字资产继承（Digital Inheritance）的加密原型系统。它结合了 Shamir 秘密共享（SSS）、AES 对称加密和 RSA 非对称加密技术，旨在解决数字遗产的安全存储与条件触发传承问题。 +This project demonstrates the core concepts of the **Sentinel Protocol**, a key management and secure data storage solution. It showcases advanced cryptographic techniques for key sharding, data encryption, and restoration under various scenarios (e.g., standard access, inheritance). -## 核心功能 +## Key Features -1. **密钥分片 (Trust Sharding)**: - * 使用 Shamir's Secret Sharing (3-of-2) 算法将用户主密钥（BIP-39 助记词）拆分为三个分片： - * **Device Share**: 存储于用户设备。 - * **Cloud Share**: 托管于 Sentinel 云端。 - * **Physical Share**: 物理传承卡，交由继承人保管。 - * 任意两个分片组合即可恢复原始密钥，单一分片无法获取任何信息。 +Based on the `main_demo.py` workflow: -2. **零知识金库 (Vault Layer)**: - * 使用从助记词派生的 AES-256 密钥对用户隐私数据进行加密。 - * 采用 AES-GCM 模式，确保数据的机密性和完整性。 - * 系统在未获得足够分片前无法解密用户数据（零知识特性）。 +1. **Key Sharding (Initialization)** + - Generation of mnemonic phrases (BIP-39). + - Splitting secrets using Shamir's Secret Sharing (SSS) into multiple shares (Device, Cloud, Physical). -3. **系统网关 (Gateway Layer)**: - * 使用 RSA-4096 系统公钥对用户密文进行二次加密（加壳）。 - * 实现“被动验证”机制：只有在满足特定触发条件（如确认死亡或订阅失效）后，系统才使用私钥剥离外层加密，允许继承人尝试恢复。 +2. **Vault Layer (User Encryption)** + - Derives AES keys from the master secret. + - Encrypts user privacy data securely. -## 环境依赖 +3. **Gateway Layer (System Wrapping)** + - Adds a layer of system-level encryption using RSA. + - Simulates "double wrapping" for enhanced security and access control. -本项目基于 Python 3 开发，依赖以下加密库： +4. **Trigger/Unlock Mechanism** + - Demonstrates how system-level triggers (e.g., death confirmation, subscription lapse) can decrypt the outer layer. -* `pycryptodome`: 用于 AES 加密和 PBKDF2 密钥派生。 -* `cryptography`: 用于 RSA 加密和密钥序列化。 -* `mnemonic`: 用于 BIP-39 助记词生成与处理。 +5. **Restoration Scenarios** + - **Life Access**: Recovering data using Device + Cloud shares. + - **Inheritance**: Recovering data using Cloud + Physical shares (simulating beneficiary access). + - **Verification**: Recovering data using Device + Physical shares. -### 安装依赖 +## Documentation + +For detailed documentation, please refer to the language-specific guides: + +- **中文文档 (Chinese Documentation)**: [cn/README.md](cn/README.md) +- **English Documentation**: [en/README.md](en/README.md) + +## protocol_whitepaper + +- **Protocol Whitepaper**: [doc/protocol_whitepaper.md](doc/protocol_whitepaper.md) + +## Quick Start + +Run the main demo script to see the full data flow in action: ```bash -pip install pycryptodome cryptography mnemonic +python3 main_demo.py ``` - -## 快速开始 - -运行主演示脚本，查看完整的数字遗产传承流程模拟： - -```bash -python main_demo.py -``` - -该脚本将演示以下全流程： -1. **初始化**: 生成密钥并进行 SSS 分片。 -2. **加密**: 用户加密数据，系统进行二次加壳。 -3. **触发**: 模拟系统判定触发条件，剥离外层加密。 -4. **恢复**: 演示三种不同的分片组合（如“云端+传承卡”）恢复数据的场景。 - -## 项目结构 - -* `core/`: 核心加密模块 - * `sp_trust_sharding.py`: 密钥生成与 Shamir 分片算法实现（基于有限域 $GF(2^{521}-1)$）。 - * `sp_vault_aes.py`: 用户侧 AES-256-GCM 加密金库实现。 - * `sp_gateway_rsa.py`: 系统侧 RSA-4096 加密网关实现。 -* `main_demo.py`: 全流程演示脚本。 -* `data_flow.md`: 数据流与协议设计的详细文档。 - ---- -*注意：本项目为原型验证代码（PoC），生产环境使用需进一步进行安全审计和密钥管理强化。* diff --git a/cn/README.md b/cn/README.md new file mode 100644 index 0000000..29eb516 --- /dev/null +++ b/cn/README.md @@ -0,0 +1,61 @@ +# Sentinel Crypt Core + +Sentinel 是一个用于数字资产继承（Digital Inheritance）的加密原型系统。它结合了 Shamir 秘密共享（SSS）、AES 对称加密和 RSA 非对称加密技术，旨在解决数字遗产的安全存储与条件触发传承问题。 + +## 核心功能 + +1. **密钥分片 (Trust Sharding)**: + * 使用 Shamir's Secret Sharing (3-of-2) 算法将用户主密钥（BIP-39 助记词）拆分为三个分片： + * **Device Share**: 存储于用户设备。 + * **Cloud Share**: 托管于 Sentinel 云端。 + * **Physical Share**: 物理传承卡，交由继承人保管。 + * 任意两个分片组合即可恢复原始密钥，单一分片无法获取任何信息。 + +2. **零知识金库 (Vault Layer)**: + * 使用从助记词派生的 AES-256 密钥对用户隐私数据进行加密。 + * 采用 AES-GCM 模式，确保数据的机密性和完整性。 + * 系统在未获得足够分片前无法解密用户数据（零知识特性）。 + +3. **系统网关 (Gateway Layer)**: + * 使用 RSA-4096 系统公钥对用户密文进行二次加密（加壳）。 + * 实现“被动验证”机制：只有在满足特定触发条件（如确认死亡或订阅失效）后，系统才使用私钥剥离外层加密，允许继承人尝试恢复。 + +## 环境依赖 + +本项目基于 Python 3 开发，依赖以下加密库： + +* `pycryptodome`: 用于 AES 加密和 PBKDF2 密钥派生。 +* `cryptography`: 用于 RSA 加密和密钥序列化。 +* `mnemonic`: 用于 BIP-39 助记词生成与处理。 + +### 安装依赖 + +```bash +pip install pycryptodome cryptography mnemonic +``` + +## 快速开始 + +运行主演示脚本，查看完整的数字遗产传承流程模拟： + +```bash +python main_demo.py +``` + +该脚本将演示以下全流程： +1. **初始化**: 生成密钥并进行 SSS 分片。 +2. **加密**: 用户加密数据，系统进行二次加壳。 +3. **触发**: 模拟系统判定触发条件，剥离外层加密。 +4. **恢复**: 演示三种不同的分片组合（如“云端+传承卡”）恢复数据的场景。 + +## 项目结构 + +* `core/`: 核心加密模块 + * `sp_trust_sharding.py`: 密钥生成与 Shamir 分片算法实现（基于有限域 $GF(2^{521}-1)$）。 + * `sp_vault_aes.py`: 用户侧 AES-256-GCM 加密金库实现。 + * `sp_gateway_rsa.py`: 系统侧 RSA-4096 加密网关实现。 +* `main_demo.py`: 全流程演示脚本。 +* `data_flow.md`: 数据流与协议设计的详细文档。 + +--- +*注意：本项目为原型验证代码（PoC），生产环境使用需进一步进行安全审计和密钥管理强化。* \ No newline at end of file diff --git a/data_flow.md b/cn/data_flow.md similarity index 100% rename from data_flow.md rename to cn/data_flow.md diff --git a/en/README.md b/en/README.md new file mode 100644 index 0000000..58a2caf --- /dev/null +++ b/en/README.md @@ -0,0 +1,61 @@ +# Sentinel Crypt Core + +Sentinel is a cryptographic prototype system for Digital Inheritance. It combines Shamir's Secret Sharing (SSS), AES symmetric encryption, and RSA asymmetric encryption technologies, aiming to solve the problems of secure storage and conditional triggered inheritance of digital assets. + +## Core Features + +1. **Trust Sharding**: + * Uses Shamir's Secret Sharing (3-of-2) algorithm to split the user master key (BIP-39 mnemonic) into three shares: + * **Device Share**: Stored on the user's device. + * **Cloud Share**: Hosted on the Sentinel cloud. + * **Physical Share**: Physical inheritance card, kept by the heir. + * Any combination of two shares can recover the original key; a single share cannot retrieve any information. + +2. **Vault Layer (Zero-Knowledge)**: + * Uses an AES-256 key derived from the mnemonic to encrypt user private data. + * Adopts AES-GCM mode to ensure data confidentiality and integrity. + * The system cannot decrypt user data without obtaining enough shares (Zero-Knowledge property). + +3. **Gateway Layer**: + * Uses an RSA-4096 system public key to re-encrypt (wrap) the user ciphertext. + * Implements a "Passive Verification" mechanism: The system uses the private key to strip the outer encryption only after specific trigger conditions are met (e.g., confirmed death or subscription expiration), allowing the heir to attempt recovery. + +## Environment Dependencies + +This project is developed based on Python 3 and depends on the following cryptographic libraries: + +* `pycryptodome`: For AES encryption and PBKDF2 key derivation. +* `cryptography`: For RSA encryption and key serialization. +* `mnemonic`: For BIP-39 mnemonic generation and processing. + +### Install Dependencies + +```bash +pip install pycryptodome cryptography mnemonic +``` + +## 快速开始 + +运行主演示脚本，查看完整的数字遗产传承流程模拟： + +```bash +python main_demo.py +``` + +该脚本将演示以下全流程： +1. **初始化**: 生成密钥并进行 SSS 分片。 +2. **加密**: 用户加密数据，系统进行二次加壳。 +3. **触发**: 模拟系统判定触发条件，剥离外层加密。 +4. **恢复**: 演示三种不同的分片组合（如“云端+传承卡”）恢复数据的场景。 + +## 项目结构 + +* `core/`: 核心加密模块 + * `sp_trust_sharding.py`: 密钥生成与 Shamir 分片算法实现（基于有限域 $GF(2^{521}-1)$）。 + * `sp_vault_aes.py`: 用户侧 AES-256-GCM 加密金库实现。 + * `sp_gateway_rsa.py`: 系统侧 RSA-4096 加密网关实现。 +* `main_demo.py`: 全流程演示脚本。 +* `data_flow.md`: 数据流与协议设计的详细文档。 + +--- +*注意：本项目为原型验证代码（PoC），生产环境使用需进一步进行安全审计和密钥管理强化。* \ No newline at end of file diff --git a/en/data_flow.md b/en/data_flow.md new file mode 100644 index 0000000..8c8e0ab --- /dev/null +++ b/en/data_flow.md @@ -0,0 +1,49 @@ +# Sentinel Protocol Demo Data Flow Overview +## 1. Key Sharding Flow: Fragmentation of Identity (Initialization) +This is the starting point of the system. Through the SSS (3,2) threshold algorithm, the user's absolute control is transformed into distributed trust. +- Input: System randomly generates 12 BIP-39 standard mnemonic words. +- Action: Split the Entropy corresponding to the mnemonic words into 3 independent mathematical shares: + - Share A (Device): Presumed to be stored in the user's mobile phone security chip. + - Share B (Cloud): Presumed to be stored on the Sentinel server. + - Share C (Physical): Presumed to be printed on a physical inheritance card and given to the heir. +- Verification Point: Demonstrate that the original 12 mnemonic words can be reconstructed through any of the three combinations (A+B), (B+C), (A+C). + +## 2. User Inner Encryption Flow: Establishing a Private Vault (Vault Layer) +This is client-side encryption, ensuring "Zero-Knowledge" storage, meaning the system cannot perceive the data content without the shares. +- Input: User private data (plaintext) + Mnemonic words recovered in Step 1. +- Action: + - Derive a symmetric encryption key (AES-256-GCM) from the mnemonic words. + - Use this key to encrypt the data, generating Ciphertext 1. +- Feature: This step simulates completion on the user's local device; Ciphertext 1 is the primary protection form of user assets. + +## 3. System Outer Wrapping Flow: Double Encapsulation (Gateway Layer) +This is the company/platform layer encryption, used to implement "Passive Verification" and "Permission Locking". +- Input: Ciphertext 1 + Company generated independent RSA Public Key. +- Action: + - The system generates a set of RSA public/private key pairs (Company Keys) unrelated to the user. + - Use the RSA Public Key to re-encrypt Ciphertext 1, generating Ciphertext 2. + +- Logical Value: The generated Ciphertext 2 now has double security—even if the mnemonic is leaked, it cannot be opened without the company private key; even if the company private key is leaked, it cannot be opened without the mnemonic shares. + +## 4. Decision Trigger Flow: Stripping the System Shell (Trigger/Unlock Layer) + +This is the turning point of the Demo, simulating the system releasing the first layer of lock when "subscription fails" or during "normal access while alive". +- Input: Ciphertext 2 + Company RSA Private Key. +- Action: Use the private key to decrypt Ciphertext 2, restoring it to Ciphertext 1. +- Business Mapping: + - Alive Mode: User is active, system private key cooperates in real-time, allowing data to flow to the user. + - Inheritance Mode: After death is confirmed, the system permanently releases this private key permission to the data packet. + +## 5. Multi-Scenario Restoration Flow: Final Extraction (Restoration Scenarios) +This is the end of the Demo, showing how data eventually returns to human hands in different social scenarios. +- Input: Ciphertext 1 restored in Step 4 + Different combinations of shares. +- Scenario Simulation: + - Scenario 1: Normal access while alive + - Combination: Share A (Phone) + Share B (Cloud) --> Recover Mnemonic --> Decrypt Ciphertext 1. + - Significance: Proves that the user can view data without the inheritance card while alive. + - Scenario 2: Standard inheritance after death + - Combination: Share B (Cloud) + Share C (Physical Card) ---> Recover Mnemonic ---> Decrypt Ciphertext 1. + - Significance: Simulates the user passing away, and the heir completing the handover relying on the card and the share released by the server. + - Scenario 3: Pure testing verification, since the user holds all 12 mnemonic words + - Combination: Share A (Phone) + Share C (Physical Card) --> Recover Mnemonic --> Decrypt Ciphertext 1. + - Significance: Testing purposes. \ No newline at end of file diff --git a/test_core.py b/test_core.py new file mode 100644 index 0000000..9110855 --- /dev/null +++ b/test_core.py @@ -0,0 +1,79 @@ +import unittest +import sys +import os + +# 确保可以导入上级目录的 core 包 +sys.path.append(os.path.dirname(os.path.dirname(os.path.abspath(__file__)))) + +from core.sp_trust_sharding import SentinelKeyEngine +from core.sp_vault_aes import SentinelVault +from core.sp_gateway_rsa import SentinelSystemProvider + +class TestSentinelCore(unittest.TestCase): + + def setUp(self): + self.key_engine = SentinelKeyEngine() + self.vault = SentinelVault() + self.sys_provider = SentinelSystemProvider() + + def test_01_sharding_recovery(self): + """测试 SSS 密钥分片与恢复 (3选2)""" + print("\n[Test] Running Sharding & Recovery...") + + # 1. 生成 + words, entropy = self.key_engine.generate_vault_keys() + self.assertEqual(len(words.split()), 12, "助记词应为12个单词") + + # 2. 分片 + shares = self.key_engine.split_to_shares(entropy) + self.assertEqual(len(shares), 3, "应生成3个分片") + + # 3. 验证所有组合 (3选2) + # 组合 A+B + rec_ab = self.key_engine.recover_from_shares(shares[0], shares[1]) + self.assertEqual(rec_ab, words, "分片 A+B 恢复失败") + + # 组合 B+C + rec_bc = self.key_engine.recover_from_shares(shares[1], shares[2]) + self.assertEqual(rec_bc, words, "分片 B+C 恢复失败") + + # 组合 A+C + rec_ac = self.key_engine.recover_from_shares(shares[0], shares[2]) + self.assertEqual(rec_ac, words, "分片 A+C 恢复失败") + + def test_02_vault_encryption(self): + """测试 AES 金库加密与解密""" + print("[Test] Running AES Vault...") + words = "abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about" + key = self.vault.derive_key(words) + data = "Sentinel Top Secret Data" + + # 加密 + encrypted = self.vault.encrypt_data(key, data) + self.assertNotEqual(encrypted, data.encode(), "密文不应与明文相同") + + # 解密 + decrypted = self.vault.decrypt_data(key, encrypted) + self.assertEqual(decrypted, data, "解密后数据应与原始数据一致") + + # 错误密钥测试 + wrong_key = self.vault.derive_key("zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo zoo") + result = self.vault.decrypt_data(wrong_key, encrypted) + self.assertIn("解密失败", result, "使用错误密钥应返回失败信息") + + def test_03_gateway_rsa(self): + """测试 RSA 系统网关加壳流程""" + print("[Test] Running RSA Gateway...") + priv_pem, pub_pem = self.sys_provider.generate_system_keys() + payload = b"User Encrypted Blob Data" + + # 加密 + cipher = self.sys_provider.encrypt_with_system_public(pub_pem, payload) + self.assertNotEqual(cipher, payload) + + # 解密 + restored = self.sys_provider.decrypt_with_system_private(priv_pem, cipher) + self.assertEqual(restored, payload, "RSA 解密还原失败") + +if __name__ == '__main__': + unittest.main() \ No newline at end of file