[RFC] Encryption at Rest for Multi-tenant Data Protection #379

qin-ctx · 2026-03-02T09:09:16Z

qin-ctx
Mar 2, 2026
Maintainer

This RFC is bilingual (English + Chinese). English version first, Chinese version below.
本 RFC 为双语版本（英文 + 中文）。英文版在前，中文版在后。

English Version / 英文版

🔍 Review Items

#	Review Item	Section	Decision Needed
1	AGFS Encryption Key Source	§2	Scheme A (client-provided key) or Scheme B (server Root Key derivation, ⭐ Recommended)?
2	Scheme A Async Task Handling	§2.1	If Scheme A: A-2a (in-memory key caching) or A-2b (persistent key caching)?
3	Scheme B Security Boundary	§2.4	If Scheme B: Accept that "server operators with Root Key access can decrypt all accounts"?

Already confirmed (no review needed): Algorithm selection (§1), API Key hashing (§4.4), VectorDB no-encryption strategy (§5).

Context

Currently all sensitive data in OpenViking's AGFS storage layer is stored in plaintext:

Data Type	Current Location	Status
User API Keys	`/{account_id}/_system/users.json` (AGFS)	Plaintext `secrets.token_hex(32)`
File Content (L0/L1/L2)	`/local/{account_id}/...` (AGFS local)	Plaintext UTF-8 text
Relation Data	`.relations.json` (AGFS)	Plaintext JSON
System Account Table	`/_system/accounts.json` (AGFS)	Plaintext JSON

Threat Model

OpenViking is a multi-tenant system where different customers (accounts) store data (resources, memories, skills) in the same server-side AGFS.

Core Threat: Anyone with server storage access (ops personnel, DBAs, or attackers who compromised the storage system) can directly read any customer's plaintext data.

Protection Goal: Even if an attacker obtains all files on the AGFS disk, without the corresponding account's encryption key, they cannot read any customer's file content.

Encryption Scope

Data	Encrypted	Method	Status
AGFS File Content	✅	AES-256-GCM symmetric encryption	🔍 Under Review (key source scheme in §2)
API Key	✅	Argon2id one-way hash	✅ Confirmed
VectorDB	❌	Handled by VectorDB backend	✅ Confirmed (see §5)
`ov.conf` Config	❌	Not encrypted	✅ Confirmed

1. Algorithm Selection

This scheme involves two confirmed cryptographic problems and one optional one depending on AGFS scheme choice:

Problem	Description	Selected Algorithm	Status
Symmetric Encryption	Encrypt AGFS file content	AES-256-GCM	✅ Confirmed (all schemes use it)
API Key Hash	Irreversible API Key storage, verification only	Argon2id	✅ Confirmed
Key Derivation	Derive per-account keys from Root Key	HKDF-SHA256	Depends on scheme (B needs it, A does not)

1.1 Symmetric Encryption Selection

Requirement: Encrypt AGFS file content (L0/L1/L2 text, JSON, etc.) with both confidentiality and integrity.

Candidate	Type	Pros	Cons	Verdict
AES-256-GCM	AEAD (encrypt+auth)	One-step encryption and tamper protection; CPU hardware acceleration (AES-NI); TLS 1.3 / AWS S3 / GCP standard	IV must not repeat under same key (mitigated by random IV + per-file key)	✅ Selected
AES-256-CBC + HMAC-SHA256	Encrypt + separate auth	Same security level	Two-step, more complex, error-prone (padding oracle)	❌ Legacy
ChaCha20-Poly1305	AEAD	Good software performance without AES hardware	Modern server CPUs all have AES-NI	❌ AES-GCM more universal
XChaCha20-Poly1305	AEAD, extended nonce	192-bit nonce, lower collision risk	Non-NIST; Python `cryptography` no direct support	❌ Non-standard
AES-256-SIV	Deterministic AEAD	IV misuse safe	Same plaintext → same ciphertext (leaks repetition); worse performance	❌ Per-file key mitigates IV reuse

Final Selection: AES-256-GCM (NIST SP 800-38D)

256-bit key, 96-bit IV (random), 128-bit authentication tag
Hardware acceleration: Intel AES-NI / ARM ARMv8-A, throughput >1 GB/s
Industry-proven: TLS 1.3 default cipher suite, AWS S3 SSE-S3, GCP CMEK

1.2 Key Derivation Function (Scheme B only)

Only needed for Scheme B. Purpose: derive independent per-account encryption keys from a single Root Key (see §2.5). Scheme A does not need key derivation.

Candidate	Design Goal	Pros/Cons	Verdict
HKDF-SHA256	Derive sub-keys from high-entropy key	Designed for this (RFC 5869); microsecond computation; deterministic	✅ Selected
PBKDF2-SHA256	Password → key (slow KDF)	Input is already 256-bit random; no need for slow stretching	❌
Argon2id	Password → key (slow KDF)	Same + 64MiB memory per derivation	❌
BLAKE3 derive_key	Key derivation	Non-NIST; weak Python ecosystem	❌

Final Selection: HKDF-SHA256 (RFC 5869) — info parameter binds account_id for per-account isolation, <1μs/call

1.3 API Key Hash Selection

Requirement: API Keys only need verification (one-way) after storage. Must resist brute-force.

Candidate	Anti-GPU/ASIC	Memory Hardness	Standard	Verdict
Argon2id	✅ Strong	✅ Configurable (64MiB+)	RFC 9106, 2015 PHC winner	✅ Selected
bcrypt	✅ Medium	❌ Fixed 4KB	De facto, no RFC	Fallback
scrypt	✅ Strong	✅ Configurable	RFC 7914	Complex tuning
PBKDF2-SHA256	❌ Weak (CPU only)	❌ None	NIST SP 800-132	❌ GPU-crackable
SHA-256 (direct)	❌ None	❌ None	—	❌ Near-zero brute-force cost

Final Selection: Argon2id (RFC 9106)

Hybrid: first half Argon2i (anti-side-channel), second half Argon2d (anti-GPU)
Parameters: memory=64MiB, iterations=3, parallelism=4
Single verification ~50ms

1.4 Summary & Referenced Standards

Domain	Algorithm	Standard/RFC	Status
File encryption	AES-256-GCM	NIST SP 800-38D	✅ Confirmed
Key derivation	HKDF-SHA256	RFC 5869	Depends on scheme
API Key hash	Argon2id	RFC 9106	✅ Confirmed

Standard	Purpose
NIST SP 800-57 Part 1	Key lifecycle management
Envelope Encryption (AWS/GCP/Azure)	Layered key architecture

2. AGFS File Encryption: Key Source Scheme 🔍 Under Review

Core question: Where does the encryption key come from, and who holds it? This determines the security boundary and system complexity.

2.1 Scheme A: Client-Provided Key

How it works: Each account has its own encryption key held by the client. Every API request carries the key via Header (X-Encryption-Key). Server only holds the key during request processing — never persisted.

Security boundary: Server doesn't store keys. Even with disk + process access, operators cannot decrypt (key only exists briefly in request memory).

Pros:

Strongest security: server holds no key material; even full server compromise cannot decrypt historical data
No KMS / Root Key infrastructure needed; key management entirely on client side
Natural per-account key isolation

Cons:

Async tasks need extra engineering (see sub-schemes below)
Client must securely manage keys; loss = permanent data loss, unrecoverable
Key transmitted every request, increasing transmission surface risk (TLS mandatory)
High client API invasiveness: all requests must carry X-Encryption-Key Header

2.2 Scheme B: Server-side Root Key Derivation (Envelope Encryption) ⭐ Recommended

How it works: Server manages a "master key" (Root Key). Client needs no encryption knowledge. Encryption is fully transparent:

Server holds a Root Key (stored in KMS or local file, globally unique)
Each account's key is derived in real-time via HKDF: HKDF(Root Key, "acc_teamA") → teamA's dedicated key — called account key (industry term: KEK)
Each file write generates a one-time random key called file key (industry term: DEK). File key encrypts content, account key encrypts the file key
Written to disk: encrypted file key + encrypted content (Envelope Encryption)

Security boundary: All disk data is ciphertext. Direct storage access cannot read data. But server holds Root Key at runtime, so anyone with Root Key access can decrypt all accounts' data.

Pros:

Zero client API invasiveness — existing interfaces completely unchanged
Async tasks naturally compatible — server can derive account keys anytime
Lowest implementation complexity — keys derived from Root Key in real-time, no separate storage
Industry standard: AWS S3 SSE-KMS, GCP CMEK both use this architecture

Cons:

Server holds Root Key; privileged operators can decrypt all accounts (weaker boundary than Scheme A)
No per-account independent key rotation (Root Key rotation = full re-encryption)
Root Key is single point: losing Root Key = all data unrecoverable

Recommendation reason: Provides sufficient security under our threat model (protecting against storage-layer direct access) with minimal architectural impact. Root Key protection can be further strengthened via KMS (Vault / AWS KMS) — standard industry practice.

2.3 Scheme Comparison

Dimension	A: Client-Provided Key	B: Server Root Key ⭐ Recommended
Server can decrypt	❌ No	✅ Yes (holds Root Key)
Client API invasiveness	High (key per request)	None
Async task compatibility	Needs rework	Native
Key loss risk	Client loses = data lost	Root Key lost = all data lost
Implementation complexity	Medium	Low
Industry reference	Tresorit, ProtonMail	AWS S3 SSE-KMS, GCP CMEK

2.4 Review Decision Points

Which scheme? Recommend Scheme B (minimal architectural impact, industry standard); Scheme A has strongest security but impacts async architecture
If Scheme A, which async sub-scheme? A-2a (in-memory caching) or A-2b (persistent caching)?
If Scheme B, accept "server operators can decrypt" security boundary?

The following §2.5 ~ §3 are Scheme B's detailed design. To be adjusted after scheme confirmation.

2. Scheme Details: Flow Diagrams & Async Sub-schemes

Scheme A Flow Diagram

Client                           Server                          AGFS
  │  Request + X-Encryption-Key   │                               │
  │──────────────────────────────>│  encrypt(key, content)        │
  │                               │─────────────────────────────>│ Write ciphertext
  │  Request + X-Encryption-Key   │                               │
  │──────────────────────────────>│  decrypt(key, ciphertext)     │
  │<──────────────────────────────│<─────────────────────────────│ Read ciphertext
  │        Return plaintext       │    Key never persisted        │

Issues to solve:

⚠️ Async tasks: After add_resource() returns, background SemanticQueue generates L0/L1 and writes to AGFS — no client request context available

Async Sub-scheme	Approach	Trade-off
A-2a: In-memory caching	Key associated with queue task in memory, cleared after consumption	Key lives longer in memory; server restart loses unconsumed task keys
A-2b: Persistent caching	Key encrypted with server temp key, persisted with task, deleted after consumption	Solves restart; but server temp key degrades to Scheme B-like trust model

⚠️ Key loss unrecoverable: Client loses key → all account data permanently unreadable
⚠️ Transmission exposure: Key transmitted every request, TLS mandatory

Implementation plan (if chosen):

AES-256-GCM directly; per-file random file key encrypted with client key (two-layer Envelope)
No Root Key Provider / KMS infrastructure
API layer changes (new Header) + async queue rework
Key rotation managed by client; server provides batch re-encryption API

Scheme B Flow Diagram

Client                           Server                                     AGFS Disk
  │                                │                                           │
  │  Normal request (no keys)      │                                           │
  │──────────────────────────────>│                                           │
  │                                │  ① Derive account key:                   │
  │                                │    account_key = HKDF(Root Key, account_id)│
  │                                │  ② Generate per-file random key:          │
  │                                │    file_key = random 256-bit              │
  │                                │  ③ Encrypt content with file key          │
  │                                │  ④ Encrypt file key with account key      │
  │                                │────────────────────────────────────────>│ Write [encrypted file key + ciphertext]
  │                                │                                           │
  │  Read request                  │                                           │
  │──────────────────────────────>│<────────────────────────────────────────│ Read [encrypted file key + ciphertext]
  │                                │  ① account_key = HKDF(Root Key, account_id)│
  │                                │  ② Decrypt file key with account key      │
  │                                │  ③ Decrypt content with file key          │
  │<──────────────────────────────│  Return plaintext                         │

Implementation plan (if chosen):

Three-layer key architecture (see §2.5)
Root Key Provider: local file, HashiCorp Vault Transit, AWS KMS (see §3)
Key rotation: Root Key rotation = full re-encryption; file keys rotate naturally (see §6)
Zero client API changes, async tasks naturally compatible

2.5 Three-Layer Model & OpenViking Component Mapping (Scheme B Detailed Design)

Uses Envelope Encryption three-layer key model:

┌─────────────────────────────────────────────────────────────────┐
│  Layer 1: Root Key                                               │
│  Maps to: Entire OpenViking instance (globally unique)            │
│  Storage: KMS service / ~/.openviking/master.key                 │
│  Manager: System administrator (ROOT role)                        │
│  Role: Derives all account keys                                   │
└───────────────────────┬─────────────────────────────────────────┘
                        │ HKDF-SHA256(Root Key, account_id)
                        ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 2: Account Key (industry term: KEK)                       │
│  Maps to: One account (one workspace in APIKeyManager)           │
│  Quantity: One per account_id                                     │
│  Storage: Not stored; derived at runtime                          │
│  Isolation: teamA's key cannot decrypt teamB's files             │
│  Role: Encrypts all file keys under this account                 │
└───────────────────────┬─────────────────────────────────────────┘
                        │ AES-256-GCM(account key, file key)
                        ▼
┌─────────────────────────────────────────────────────────────────┐
│  Layer 3: File Key (industry term: DEK)                          │
│  Maps to: Single file in AGFS (L0/L1/L2, relations, users.json) │
│  Quantity: New one per VikingFS.write() call                     │
│  Storage: Encrypted in file header (envelope)                    │
│  Role: Encrypts actual file content                              │
└─────────────────────────────────────────────────────────────────┘

Walkthrough: acc_teamA uploads `viking://resources/utils.py`

Write flow (VikingFS.write()):

1. URI → AGFS path: viking://resources/utils.py → /local/acc_teamA/resources/utils.py
2. Derive account key: HKDF-SHA256(Root Key, info="openviking:kek:v1:acc_teamA")
3. Generate file key: os.urandom(32)
4. Encrypt content: AES-256-GCM(file_key, "def helper(): ...")
5. Encrypt file key: AES-256-GCM(account_key, file_key)
6. Write: [OVE1 header | encrypted_file_key | encrypted_content]

Then semantic queue generates L0/L1, also encrypted:

.abstract.md → [OVE1 | file_key2 | "Python utility file"]
.overview.md → [OVE1 | file_key3 | "Contains helper()..."]

Read flow (VikingFS.read()):

1. Read raw bytes → check b"OVE1" → encrypted
2. Derive account_key = HKDF(Root Key, "acc_teamA")
3. Decrypt file key with account key
4. Decrypt content with file key → return plaintext

Cross-account isolation: teamB's derived key ≠ teamA's → cannot decrypt → InvalidTag

Why Three Layers

Scheme	Problem
Single: Root Key encrypts all	Leak = all exposed; no isolation; IV collision
Two: account key encrypts directly	Rotation = re-encrypt all content (GBs); IV collision
Three: Root Key → account key → file key	✅ Rotation only re-encrypts 32-byte keys; zero IV collision; file-level isolation

Account Key Derivation

from cryptography.hazmat.primitives.kdf.hkdf import HKDF
from cryptography.hazmat.primitives import hashes

def derive_account_key(root_key: bytes, account_id: str) -> bytes:
    hkdf = HKDF(
        algorithm=hashes.SHA256(), length=32,
        salt=b"openviking-kek-salt-v1",
        info=f"openviking:kek:v1:{account_id}".encode(),
    )
    return hkdf.derive(root_key)

Fixed salt (Root Key already high-entropy); info binds account_id; v1 for future upgrades; deterministic output

File Key & Envelope

def encrypt_file(account_key: bytes, plaintext: bytes) -> bytes:
    file_key = os.urandom(32)
    data_iv = os.urandom(12)
    encrypted_content = AESGCM(file_key).encrypt(data_iv, plaintext, None)
    key_iv = os.urandom(12)
    encrypted_file_key = AESGCM(account_key).encrypt(key_iv, file_key, None)
    return b"OVE1" + encrypted_file_key + key_iv + data_iv + encrypted_content

3. Root Key Provider Detailed Design (Scheme B)

Scheme B's core: server holds a Root Key. Where does it live? Provider abstracts this.

Three implementations for different environments:

3.1 Abstract Interface

class RootKeyProvider(ABC):
    async def get_root_key(self) -> bytes: ...
    async def encrypt_file_key(self, plaintext_key: bytes) -> bytes: ...
    async def decrypt_file_key(self, encrypted_key: bytes) -> bytes: ...

3.2 Local File Provider (Dev / Single-node)

32-byte random key in ~/.openviking/master.key (hex-encoded, chmod 0600)
Config: {"encryption": {"enabled": true, "provider": "local", "local": {"key_file": "~/.openviking/master.key"}}}
Init: read → verify permissions → parse hex → verify 32 bytes → cache
Generate: openviking-cli crypto init-key --output ~/.openviking/master.key

3.3 HashiCorp Vault Provider (Production)

Vault Transit Engine: "Encryption as a Service", Root Key never leaves Vault
Uses context parameter for per-account derivation (Vault does HKDF internally)
Auth: token / approle / kubernetes
Protocol: POST /v1/transit/encrypt|decrypt/openviking-root with context=base64(account_id)
Rotation: POST /v1/transit/keys/openviking-root/rotate — old versions retained

class VaultProvider(RootKeyProvider):
    async def encrypt_file_key(self, plaintext_key, account_id):
        return self.client.secrets.transit.encrypt_data(
            name=self.key_name, plaintext=b64encode(plaintext_key),
            context=b64encode(account_id), mount_point=self.mount)

Dependency: hvac

3.4 AWS KMS Provider (AWS Cloud)

CMK in AWS HSM, never exportable
GenerateDataKey returns both plaintext + encrypted file key
EncryptionContext={"account_id": "xxx"} as AAD, must match on decrypt
Auto-rotation: aws kms enable-key-rotation; all calls logged to CloudTrail

class AWSKMSProvider(RootKeyProvider):
    async def generate_file_key(self, account_id):
        return self.kms.generate_data_key(
            KeyId=self.key_id, KeySpec="AES_256",
            EncryptionContext={"account_id": account_id, "service": "openviking"})

Dependency: boto3

3.5 Provider Comparison

Feature	Local File	HashiCorp Vault	AWS KMS
Root Key storage	Local file	Vault HSM/software	AWS HSM (FIPS 140-2 L2)
Exportable	Yes	No (Transit)	No (CMK)
Auth	File permissions	Token/AppRole/K8s	IAM/AccessKey
Audit log	None	Vault Audit	CloudTrail
Auto rotation	Manual	API-triggered	Annual
Multi-node	Manual distribution	Native	Native
Use case	Dev/single-node	Production/multi-cloud	AWS deployment

4. Data Encryption Detailed Design

4.1 Envelope Format v1

Offset  Size    Field                   Description
0x00    4       magic                   b"OVE1"
0x04    1       provider_type           0x01=local, 0x02=vault, 0x03=aws_kms
0x05    2       encrypted_key_length    Big-endian (Local:48, Vault/AWS:variable)
0x07    var     encrypted_file_key
var     12      key_iv                  Local mode only
var     12      data_iv
var     var     encrypted_content       With 16-byte GCM auth tag

Magic bytes OVE1 → decrypt path; otherwise → plaintext (gradual migration).

4.2 AGFS Encryption Scope

File Type	Path Example	Encrypted	Reason
L0 abstract	`.abstract.md`	✅	Semantic summary
L1 overview	`.overview.md`	✅	Structured overview
L2 content	`file.py`	✅	Original content
Relations	`.relations.json`	✅	Resource relationships
Users	`_system/users.json`	✅	User identity
Accounts	`_system/accounts.json`	✅	Account info
Directories	Dir/file names	❌	Traversal needed
Collection meta	`collection_meta.json`	❌	VectorDB metadata

4.3 VikingFS Integration

class VikingFS:
    def __init__(self, ..., encryptor: Optional[FileEncryptor] = None):
        self._encryptor = encryptor

    async def write(self, uri, content, ctx):
        raw = content.encode("utf-8")
        if self._encryptor:
            raw = await self._encryptor.encrypt(ctx.account_id, raw)
        await self._agfs.write(path, raw)

    async def read(self, uri, ctx):
        raw = await self._agfs.read(path)
        if self._encryptor and raw[:4] == b"OVE1":
            raw = await self._encryptor.decrypt(ctx.account_id, raw)
        return raw.decode("utf-8")

Dependency injection; magic bytes auto-detect; unencrypted files still readable

4.4 API Key Hash ✅ Confirmed

Argon2id (RFC 9106), one-way hash:

ph = PasswordHasher(time_cost=3, memory_cost=65536, parallelism=4)
key_hash = ph.hash(key_plaintext)  # Store hash + prefix(first 8 chars)
ph.verify(stored_hash, incoming_key)  # Verify

Prefix-based lookup: {prefix → [(identity, hash)]} → O(1) + single Argon2id verify (~50ms)

Method	Current	Change
`_load_account_keys()`	Plaintext → dict	(prefix, hash) → index
`resolve()`	`key_index[key]` O(1)	Prefix + Argon2id verify
`register_user()`	Store plaintext	Store hash + prefix

5. VectorDB Strategy ✅ No Encryption

Encrypted vectors cannot perform ANN search — VectorDB's core function
Managed services (Volcengine VikingDB): HTTPS + SignerV4 + server-side encryption
Local backend: dev environment, lower requirements
Metadata has encrypted copies in AGFS; VectorDB is index/cache

Backend	Transport	Storage	Auth	Note
`local`	N/A	❌	N/A	Dev; OS permissions
`http`	Need HTTPS	Depends	None	Must TLS
`volcengine`	✅ HTTPS	✅	✅ SignerV4	Meets requirements
`vikingdb`	Depends	Depends	Header	Recommend TLS

Future options: encrypt text metadata fields; or homomorphic encryption (academic stage).

6. Key Rotation

Not implemented this phase. Documentation only.

Periodically replacing keys to limit breach impact.

Layer	Method	Cost	Notes
File Key	New per `write()`	Zero	Natural rotation
Root Key (Local)	Decrypt all → re-encrypt with new	High	Recommend ≥1 year
Root Key (Vault)	Vault API; old versions retained	Low	Rewrap on demand
Root Key (AWS KMS)	Auto annual rotation	Zero	Fully automatic

Scheme A rotation managed by client.

7. Implementation Summary

Changes

Change	Description
New `openviking/crypto/`	Providers + KeyManager + FileEncryptor + Envelope
`viking_fs.py`	Transparent encrypt/decrypt in read/write
`api_keys.py`	Argon2id hash + prefix index
`openviking_service.py`	Init encryption from config
Migration script	Encrypt existing files + hash API Keys

Dependencies

Library	Purpose	Required
`cryptography`	AES-256-GCM, HKDF	Required
`argon2-cffi`	Argon2id	Required
`hvac`	Vault client	Optional
`boto3`	AWS KMS	Optional

Verification

Correctness: Round-trip; HKDF determinism; cross-account isolation; hash verify
Security: Tampered data → InvalidTag; permission checks
Integration: E2E add_resource() → find(), add_message() → commit()
Performance: AES >1 GB/s; Argon2id ~50ms; KMS latency OK

中文版 / Chinese Version

🔍 待评审事项

#	评审项	所在章节	需要决策的问题
1	AGFS 加密密钥来源	§2	选方案 A（client 传入密钥）还是方案 B（server Root Key 派生，⭐ 推荐）？
2	方案 A 异步任务处理	§2.1	若选 A，异步任务用 A-2a（内存暂存）/ A-2b（持久化暂存）？
3	方案 B 安全边界	§2.4	若选 B，是否接受 "持有 Root Key 的 server 运维可解密所有 account" 这一安全边界？

以下内容已确认，无需评审：算法选型（§1）、API Key 哈希方案（§4.4）、VectorDB 不加密策略（§5）。

Context

当前 OpenViking 所有 AGFS 存储层的敏感数据均以明文存储：

数据类型	当前存储位置	当前状态
用户 API Key	`/{account_id}/_system/users.json` (AGFS)	明文 `secrets.token_hex(32)`
文件内容 (L0/L1/L2)	`/local/{account_id}/...` (AGFS 本地)	明文 UTF-8 文本
关系数据	`.relations.json` (AGFS)	明文 JSON
系统账户表	`/_system/accounts.json` (AGFS)	明文 JSON

威胁模型

OpenViking 是多租户系统，不同客户（account）的数据（资源文件、记忆、技能）都存储在同一套服务端 AGFS 中。

核心威胁: 有服务端存储访问权限的人（运维人员、DBA、或存储系统被入侵时的攻击者）可以直接读取任意客户的明文数据。

防护目标: 即使攻击者拿到了 AGFS 磁盘上的全部文件，在没有对应 account 的加密密钥的情况下，无法读取任何客户的文件内容。

加密范围与状态

数据	是否加密	方式	状态
AGFS 文件内容	✅	AES-256-GCM 对称加密	🔍 待评审（密钥来源方案见第 2 节）
API Key	✅	Argon2id 单向哈希	✅ 已确认
VectorDB	❌	由 VectorDB 后端自身负责	✅ 已确认（详见第 5 节）
`ov.conf` 配置文件	❌	不加密	✅ 已确认

1. 算法选型

本方案涉及两个已确认的密码学问题，以及一个取决于 AGFS 方案选择的可选问题：

问题	描述	选定算法	状态
对称加密	加密 AGFS 中的文件内容	AES-256-GCM	✅ 已确认（三个 AGFS 方案均使用）
API Key 哈希	用户 API Key 不可逆存储，只做验证	Argon2id	✅ 已确认
密钥派生	从一个 Root Key 为每个 account 计算出各自独立的加密密钥	HKDF-SHA256	取决于 AGFS 方案（方案 B 需要，方案 A 不需要）

1.1 对称加密算法选型

需求: 加密 AGFS 文件内容（L0/L1/L2 文本、JSON 等），需要同时保证机密性和完整性。

候选	类型	优势	劣势	结论
AES-256-GCM	AEAD (加密+认证一体)	一步完成加密和防篡改；CPU 硬件加速 (AES-NI)；TLS 1.3 / AWS S3 / GCP 标准	单个 key 下 IV 不可重复（用 random IV + per-file 文件密钥规避）	✅ 选用
AES-256-CBC + HMAC-SHA256	加密 + 独立认证	同等安全性	需要两步操作，实现更复杂，容易出错（如 padding oracle 攻击）	❌ 淘汰：历史方案
ChaCha20-Poly1305	AEAD	软件实现性能好（无 AES 硬件时）	现代服务器 CPU 都有 AES-NI	❌ 淘汰：服务端 AES-GCM 更通用
XChaCha20-Poly1305	AEAD，扩展 nonce	192-bit nonce，碰撞风险更低	非 NIST 标准；Python `cryptography` 库不直接支持	❌ 淘汰：非标准，生态弱
AES-256-SIV	确定性 AEAD	IV misuse 安全	相同明文产生相同密文（泄露重复模式）；性能差	❌ 淘汰：per-file 文件密钥已规避 IV 重复

最终选择: AES-256-GCM (NIST SP 800-38D)

256-bit 密钥，96-bit IV（随机生成），128-bit authentication tag
硬件加速：Intel AES-NI / ARM ARMv8-A 原生支持，吞吐量 >1 GB/s
行业验证：TLS 1.3 默认 cipher suite、AWS S3 SSE-S3、GCP CMEK

1.2 密钥派生函数 (KDF) 选型（AGFS 方案 B 适用）

仅方案 B 需要。用途：从一个 Root Key 为每个 account 派生出独立的加密密钥（详见 §2.5）。方案 A 不需要密钥派生。

候选	设计目标	优劣	结论
HKDF-SHA256	从高熵密钥派生子密钥	专为此场景设计（RFC 5869）；微秒级计算；确定性输出	✅ 选用
PBKDF2-SHA256	口令→密钥（慢速 KDF）	输入已是 256-bit 随机密钥，不需要慢速"拉伸"	❌ 淘汰
Argon2id	口令→密钥（慢速 KDF）	同上，且每次派生消耗 64MiB 内存	❌ 淘汰
BLAKE3 derive_key	密钥派生	非 NIST 标准；Python 生态弱	❌ 淘汰

最终选择: HKDF-SHA256 (RFC 5869) — info 参数绑定 account_id 确保 per-account 隔离，计算开销 <1μs/次

1.3 API Key 哈希算法选型

需求: 用户 API Key 存储后只需验证（单向），不需要还原原文。需要抗暴力破解。

候选	抗 GPU/ASIC	内存硬度	标准化	结论
Argon2id	✅ 强	✅ 可配置（64MiB+）	RFC 9106, 2015 PHC 冠军	✅ 选用
bcrypt	✅ 中等	❌ 固定 4KB	事实标准，无 RFC	备选
scrypt	✅ 强	✅ 可配置	RFC 7914	参数调优复杂
PBKDF2-SHA256	❌ 弱（纯 CPU）	❌ 无	NIST SP 800-132	❌ 淘汰：GPU 可暴力破解
SHA-256 (直接)	❌ 无	❌ 无	—	❌ 淘汰：几乎无暴力破解成本

最终选择: Argon2id (RFC 9106)

混合变体：前半段 Argon2i（抗侧信道），后半段 Argon2d（抗 GPU）
参数: memory=64MiB, iterations=3, parallelism=4
单次验证 ~50ms

1.4 算法总览与引用标准

问题领域	算法	标准/RFC	状态
文件内容加密	AES-256-GCM	NIST SP 800-38D	✅ 已确认
密钥派生	HKDF-SHA256	RFC 5869	取决于方案
API Key 哈希	Argon2id	RFC 9106	✅ 已确认

标准	用途
NIST SP 800-57 Part 1	密钥生命周期管理
Envelope Encryption (AWS/GCP/Azure)	分层密钥架构

2. AGFS 文件加密：密钥来源方案 🔍 待评审

AGFS 加密的核心问题是：加密密钥从哪来、谁持有。这决定了安全边界和系统复杂度。

2.1 方案 A：Client 传入密钥

工作方式: 每个 account 有自己的加密密钥，由 client 持有。每次 API 请求通过 Header（X-Encryption-Key）携带密钥。Server 只在请求处理期间持有密钥，不落盘、不存储。

安全边界: server 不存储密钥，运维人员即使有磁盘 + 进程访问权限，也无法解密（密钥不在 config 里，只在请求内存中短暂存在）。

优点:

安全性最强：server 不持有任何密钥材料，即使 server 被完全入侵也无法解密历史数据
无需 KMS / Root Key 等基础设施，密钥管理完全由 client 负责
天然支持 per-account 密钥隔离

缺点:

异步任务需要额外改造（见下方子方案）
client 必须自行安全保管密钥，丢失则数据永久不可恢复
每次请求都要传输密钥，增加传输面风险（必须 TLS）
client API 侵入性高，所有请求都要带 X-Encryption-Key Header

2.2 方案 B：Server 端 Root Key 派生（Envelope Encryption） ⭐ 推荐

工作方式: Server 自己管理一把"总钥匙"（Root Key），client 不需要知道任何加密细节。加密过程完全由 server 透明完成：

Server 持有一把 Root Key，存在 KMS 或本地文件中（全局唯一，管理员配置）
每个 account 的加密密钥不是单独存储的，而是用 HKDF 从 Root Key 实时算出来的：HKDF(Root Key, "acc_teamA") → teamA 专用密钥。这把派生密钥叫 account 密钥（行业术语 KEK）
每次写文件时，再生成一把一次性随机密钥叫 文件密钥（行业术语 DEK），用文件密钥加密文件内容，再用 account 密钥加密文件密钥本身
最终写入磁盘的是：加密后的文件密钥 + 加密后的文件内容（这种"钥匙和锁一起存，但钥匙本身也是锁着的"模式叫 Envelope Encryption）

安全边界: 磁盘上全是密文，直接访问存储无法读取。但 server 运行时持有 Root Key，因此有 Root Key 访问权限的人可以解密所有 account 的数据。

优点:

client API 零侵入，现有接口完全不变
异步任务天然兼容，server 随时可派生 account 密钥加解密
实现复杂度最低，密钥不需要额外存储（从 Root Key 实时算出）
行业标准模式：AWS S3 SSE-KMS、GCP CMEK 均采用此架构

缺点:

server 持有 Root Key，有权限的运维可解密所有 account（安全边界弱于方案 A）
不支持单个 account 独立密钥轮换（Root Key 轮换 = 全量重加密）
Root Key 是单点：丢失 Root Key = 全部数据不可恢复

推荐理由: 在威胁模型（防存储层直接访问）下提供了足够的安全保障，同时对现有架构冲击最小。Root Key 的保护可通过 KMS（Vault / AWS KMS）进一步加强，这是云厂商和行业的标准做法。

2.3 方案对比

维度	A: Client 传入密钥	B: Server Root Key 派生 ⭐ 推荐
server 能否解密	❌ 不能	✅ 能（持有 Root Key）
client API 侵入性	高（每次请求带 key）	无
异步任务兼容	需改造	天然兼容
密钥丢失风险	client 丢 = 数据丢失	丢 Root Key = 全部丢失
实现复杂度	中	低
行业参考	Tresorit、ProtonMail	AWS S3 SSE-KMS、GCP CMEK

2.4 待评审决策点

选哪个方案？ 推荐方案 B（架构冲击最小、行业标准）；方案 A 安全性最强但对异步架构有冲击
如果选方案 A，异步任务选 A-2a（内存暂存）/ A-2b（持久化暂存）？
如果选方案 B，是否接受 "server 运维可解密" 这个安全边界？

以下第 2.5 ~ 第 3 节为方案 B 的详细设计。方案确认后按需调整。

2. 方案详细流程图与异步子方案

方案 A 流程图

Client                           Server                          AGFS
  │  请求 + X-Encryption-Key       │                               │
  │───────────────────────────────>│  encrypt(key, content)        │
  │                                │──────────────────────────────>│ 写入密文
  │  请求 + X-Encryption-Key       │                               │
  │───────────────────────────────>│  decrypt(key, ciphertext)     │
  │<───────────────────────────────│<──────────────────────────────│ 读取密文
  │         返回明文                │    密钥不落盘                  │

需要解决的问题:

⚠️ 异步任务: add_resource() 返回后，后台 SemanticQueue 异步生成 L0/L1 并写入 AGFS，此时没有 client 请求上下文

异步解决子方案	做法	代价
A-2a: 内存暂存	密钥关联到 queue task 暂存内存，消费后清除	密钥在内存中存活更久；server 重启丢失未消费 task 的密钥（数据生成丢失）
A-2b: 持久化暂存	密钥用 server 临时密钥加密后随 task 持久化到队列存储，消费后删除	解决重启丢失问题；但 server 临时密钥本身需要安全管理（退化为类似方案 B 的信任模型）

⚠️ 密钥丢失不可恢复: client 丢了密钥，该 account 全部数据永久不可读
⚠️ 传输面暴露: 每次请求传输密钥，必须 TLS 保护

后续实施规划（如选此方案）:

加密层直接用 AES-256-GCM，每个文件一个随机文件密钥，文件密钥用 client 传入的 key 加密（两层 Envelope）
无需 Root Key Provider / KMS 基础设施
需改造 API 层（新增 Header）、异步队列流程
密钥轮换由 client 自行管理，server 提供批量重加密 API

方案 B 流程图

Client                           Server                                     AGFS 磁盘
  │                                │                                           │
  │  正常请求（不带任何密钥）         │                                           │
  │───────────────────────────────>│                                           │
  │                                │  ① 算出 account 密钥:                     │
  │                                │    account密钥 = HKDF(Root Key, account_id)│
  │                                │  ② 生成本次文件专用随机密钥:                 │
  │                                │    文件密钥 = random 256-bit               │
  │                                │  ③ 用文件密钥加密文件内容                    │
  │                                │  ④ 用 account 密钥加密文件密钥               │
  │                                │─────────────────────────────────────────>│ 写入 [加密的文件密钥 + 密文]
  │                                │                                           │
  │  读取请求                       │                                           │
  │───────────────────────────────>│<─────────────────────────────────────────│ 读取 [加密的文件密钥 + 密文]
  │                                │  ① account密钥 = HKDF(Root Key, account_id)│
  │                                │  ② 用 account 密钥解密文件密钥               │
  │                                │  ③ 用文件密钥解密文件内容                    │
  │<───────────────────────────────│  返回明文                                  │

后续实施规划（如选此方案）:

三层密钥架构（详见下方 2.5 节详细设计）
Root Key Provider 支持三种模式：本地文件、HashiCorp Vault Transit、AWS KMS（详见第 3 节）
密钥轮换：Root Key 轮换需全量重加密；文件密钥随文件更新自然轮换（详见第 6 节）
对 client API 零侵入，异步任务天然兼容

2.5 三层模型与 OpenViking 组件映射（方案 B 详细设计）

本方案采用 Envelope Encryption（信封加密）三层密钥模型：

┌─────────────────────────────────────────────────────────────────┐
│  第 1 层: Root Key（根密钥）                                      │
│  对应: 整个 OpenViking 实例（全局唯一）                             │
│  存储: KMS 服务内 / ~/.openviking/master.key                      │
│  管理者: 系统管理员（ROOT 角色）                                    │
│  职责: 派生出所有 account 密钥                                     │
└───────────────────────┬─────────────────────────────────────────┘
                        │ HKDF-SHA256(Root Key, account_id) 派生
                        ▼
┌─────────────────────────────────────────────────────────────────┐
│  第 2 层: account 密钥（行业术语 KEK）                              │
│  对应: 一个 account（即 APIKeyManager 中的一个 workspace）          │
│  数量: 每个 account_id 一把                                        │
│  存储: 不存储，运行时从 Root Key + account_id 实时派生              │
│  隔离: acc_teamA 的 account 密钥无法解密 acc_teamB 的任何文件       │
│  职责: 加密该 account 下所有文件的文件密钥                          │
└───────────────────────┬─────────────────────────────────────────┘
                        │ AES-256-GCM(account 密钥, 文件密钥) 加密
                        ▼
┌─────────────────────────────────────────────────────────────────┐
│  第 3 层: 文件密钥（行业术语 DEK）                                  │
│  对应: AGFS 中的单个文件（L0/L1/L2、relations、users.json 等）      │
│  数量: 每次 VikingFS.write() 调用生成一把新的                       │
│  存储: 加密后嵌入文件头部（envelope），与密文在一起                   │
│  职责: 加密该文件的实际内容                                         │
└─────────────────────────────────────────────────────────────────┘

用实际例子走一遍：acc_teamA 上传 `viking://resources/utils.py`

写入流程 (VikingFS.write()):

1. URI → AGFS 路径: viking://resources/utils.py → /local/acc_teamA/resources/utils.py
2. 派生 account 密钥: HKDF-SHA256(Root Key, info="openviking:kek:v1:acc_teamA")
3. 生成随机文件密钥: os.urandom(32)
4. 用文件密钥加密文件内容: AES-256-GCM(文件密钥, "def helper(): ...")
5. 用 account 密钥加密文件密钥: AES-256-GCM(account密钥, 文件密钥)
6. 写入: [OVE1 头 | 加密后文件密钥 | 加密后内容]

随后语义队列生成 L0/L1 摘要，同样加密存储：

.abstract.md → [OVE1 | 文件密钥2 加密 | "Python 工具函数文件"]
.overview.md → [OVE1 | 文件密钥3 加密 | "包含 helper() 函数..."]

读取流程 (VikingFS.read()):

1. 从 AGFS 读取原始字节 → 检查 b"OVE1" → 是加密文件
2. 派生 account密钥 = HKDF(Root Key, "acc_teamA")
3. 用 account 密钥解密文件密钥
4. 用文件密钥解密文件内容 → 返回明文

跨 account 隔离: teamB 的派生密钥 ≠ teamA → 无法解密 → InvalidTag 异常

为什么需要三层

方案	问题
单层：Root Key 直接加密	泄露 = 全部暴露；无隔离；IV 碰撞
两层：account 密钥直接加密	轮换 = 重加密全部内容（GB 级）；IV 碰撞
三层：Root Key → account 密钥 → 文件密钥	✅ 轮换只需重加密 32 字节密钥；零 IV 碰撞；文件级隔离

account 密钥派生算法

from cryptography.hazmat.primitives.kdf.hkdf import HKDF
from cryptography.hazmat.primitives import hashes

def derive_account_key(root_key: bytes, account_id: str) -> bytes:
    hkdf = HKDF(
        algorithm=hashes.SHA256(), length=32,
        salt=b"openviking-kek-salt-v1",
        info=f"openviking:kek:v1:{account_id}".encode(),
    )
    return hkdf.derive(root_key)

固定 salt（Root Key 已是高熵）；info 绑定 account_id；v1 预留升级；确定性输出

文件密钥生成与 Envelope

def encrypt_file(account_key: bytes, plaintext: bytes) -> bytes:
    file_key = os.urandom(32)
    data_iv = os.urandom(12)
    encrypted_content = AESGCM(file_key).encrypt(data_iv, plaintext, None)
    key_iv = os.urandom(12)
    encrypted_file_key = AESGCM(account_key).encrypt(key_iv, file_key, None)
    return b"OVE1" + encrypted_file_key + key_iv + data_iv + encrypted_content

3. Root Key Provider 详细设计（方案 B 适用）

方案 B 的核心：server 持有 Root Key。Root Key 本身存在哪里？ Provider 对此抽象。

三种实现适配不同环境：

3.1 抽象接口

class RootKeyProvider(ABC):
    async def get_root_key(self) -> bytes: ...
    async def encrypt_file_key(self, plaintext_key: bytes) -> bytes: ...
    async def decrypt_file_key(self, encrypted_key: bytes) -> bytes: ...

3.2 Local File Provider（开发/单机）

32 字节随机密钥存在 ~/.openviking/master.key（hex 编码，chmod 0600）
配置: {"encryption": {"enabled": true, "provider": "local", "local": {"key_file": "~/.openviking/master.key"}}}
初始化: 读取 → 验证权限 → 解析 hex → 验证 32 字节 → 缓存
生成: openviking-cli crypto init-key --output ~/.openviking/master.key

3.3 HashiCorp Vault Provider（生产推荐）

Vault Transit Engine: "加密即服务"，Root Key 永远不离开 Vault
用 context 参数实现 per-account 密钥派生（Vault 内部做 HKDF）
认证: token / approle / kubernetes
协议: POST /v1/transit/encrypt|decrypt/openviking-root + context=base64(account_id)
轮换: POST /v1/transit/keys/openviking-root/rotate — 旧版本自动保留

class VaultProvider(RootKeyProvider):
    async def encrypt_file_key(self, plaintext_key, account_id):
        return self.client.secrets.transit.encrypt_data(
            name=self.key_name, plaintext=b64encode(plaintext_key),
            context=b64encode(account_id), mount_point=self.mount)

依赖: hvac

3.4 AWS KMS Provider（AWS 云部署）

CMK 存在 AWS HSM，不可导出
GenerateDataKey 同时返回明文和加密后的文件密钥
EncryptionContext={"account_id": "xxx"} 作为 AAD，解密时必须匹配
自动轮换: aws kms enable-key-rotation；所有调用记录到 CloudTrail

class AWSKMSProvider(RootKeyProvider):
    async def generate_file_key(self, account_id):
        return self.kms.generate_data_key(
            KeyId=self.key_id, KeySpec="AES_256",
            EncryptionContext={"account_id": account_id, "service": "openviking"})

依赖: boto3

3.5 Provider 对比

特性	Local File	HashiCorp Vault	AWS KMS
Root Key 存储	本地文件	Vault HSM/软件	AWS HSM (FIPS 140-2 L2)
是否可导出	是	否 (Transit)	否 (CMK)
认证方式	文件权限	Token/AppRole/K8s	IAM/AccessKey
审计日志	无	Vault Audit	CloudTrail
自动轮换	手动	API 触发	自动年度
多节点	手动分发	原生	原生
适用	开发/单机	生产/多云	AWS 部署

4. 数据加密方案详细设计

4.1 加密文件二进制格式 (Envelope Format v1)

Offset  Size    Field                   Description
0x00    4       magic                   b"OVE1"
0x04    1       provider_type           0x01=local, 0x02=vault, 0x03=aws_kms
0x05    2       encrypted_key_length    大端序 (Local:48, Vault/AWS:变长)
0x07    var     encrypted_file_key
var     12      key_iv                  仅 Local 模式
var     12      data_iv
var     var     encrypted_content       含 16-byte GCM auth tag

Magic OVE1 → 解密路径；否则 → 明文（支持渐进式迁移）。

4.2 AGFS 文件加密范围

文件类型	路径示例	是否加密	理由
L0 摘要	`.abstract.md`	✅	含语义摘要
L1 概览	`.overview.md`	✅	含结构化概览
L2 完整内容	`file.py`	✅	原始内容
关系数据	`.relations.json`	✅	资源关联
用户注册表	`_system/users.json`	✅	用户身份
账户列表	`_system/accounts.json`	✅	账户信息
目录结构	目录名、文件名	❌	需要遍历
集合元数据	`collection_meta.json`	❌	VectorDB 元数据

4.3 VikingFS 集成

class VikingFS:
    def __init__(self, ..., encryptor: Optional[FileEncryptor] = None):
        self._encryptor = encryptor

    async def write(self, uri, content, ctx):
        raw = content.encode("utf-8")
        if self._encryptor:
            raw = await self._encryptor.encrypt(ctx.account_id, raw)
        await self._agfs.write(path, raw)

    async def read(self, uri, ctx):
        raw = await self._agfs.read(path)
        if self._encryptor and raw[:4] == b"OVE1":
            raw = await self._encryptor.decrypt(ctx.account_id, raw)
        return raw.decode("utf-8")

依赖注入；magic bytes 自动检测；明文文件仍可读（渐进式迁移）

4.4 API Key 哈希存储 ✅ 已确认

Argon2id (RFC 9106)，单向哈希：

ph = PasswordHasher(time_cost=3, memory_cost=65536, parallelism=4)
key_hash = ph.hash(key_plaintext)  # 存储 hash + prefix(前 8 字符)
ph.verify(stored_hash, incoming_key)  # 验证

Prefix 索引: {prefix → [(identity, hash)]} → O(1) + 单次 Argon2id (~50ms)

方法	当前	改动
`_load_account_keys()`	明文 → dict	(prefix, hash) → 索引
`resolve()`	`key_index[key]` O(1)	prefix + Argon2id verify
`register_user()`	存储明文	存储 hash + prefix

5. VectorDB 加密策略 ✅ 不加密

加密后的向量无法进行 ANN 相似性搜索——VectorDB 的核心功能
托管服务（Volcengine VikingDB）：HTTPS + SignerV4 + 服务端加密
Local 后端：开发环境，安全要求较低
元数据在 AGFS 中已有加密副本；VectorDB 本质是索引/缓存

后端	传输	存储加密	认证	建议
`local`	N/A	❌	N/A	开发；OS 权限
`http`	需 HTTPS	取决于	无	必须 TLS
`volcengine`	✅ HTTPS	✅	✅ SignerV4	已满足
`vikingdb`	取决于	取决于	Header	建议 TLS

未来可选：加密文本元数据字段；或同态加密（学术阶段）。

6. 密钥轮换

本期不实现，仅做方案说明。

定期换新密钥，限制泄露影响范围。

层级	方式	代价	说明
文件密钥	每次 `write()` 新生成	零	天然轮换
Root Key (Local)	全量解密 → 重加密	高	建议 ≥1 年
Root Key (Vault)	Vault API；旧版本保留	低	按需 rewrap
Root Key (AWS KMS)	自动年度轮换	零	全自动

方案 A 密钥轮换由 client 管理。

7. 实施概要

主要改动

改动	说明
新增 `openviking/crypto/`	Provider + KeyManager + FileEncryptor + Envelope
`viking_fs.py`	read/write 透明加解密
`api_keys.py`	Argon2id hash + prefix 索引
`openviking_service.py`	根据 config 初始化加密链路
迁移脚本	存量文件加密 + API Key 哈希转换

依赖库

库	用途	必须/可选
`cryptography`	AES-256-GCM, HKDF	必须
`argon2-cffi`	Argon2id	必须
`hvac`	Vault 客户端	可选
`boto3`	AWS KMS	可选

验证要点

正确性: round-trip；HKDF 确定性；跨 account 隔离；hash verify
安全性: 篡改 → InvalidTag；权限校验
集成: add_resource() → find()、add_message() → commit() 端到端
性能: AES >1 GB/s；Argon2id ~50ms；KMS 延迟可接受

chuanbao666 · 2026-03-03T04:42:46Z

chuanbao666
Mar 3, 2026
Maintainer

倾向选择方案B

方案A可能更适合个人/团队client + 基于共享、不受信的存储（server+agfs）。这种情况下，推荐独立部署ov server，用方案B也能满足（成本上ov server部署成本也比较低）。
方案B在企业环境更合适（统一管理、不允许单点风险），而且方便对接现有的加密设施
加密考虑做成可插拔的方式，不侵入核心流程？

1 reply

qin-ctx Mar 3, 2026
Maintainer Author

是指加密是可选功能吗？不强制开启

baojun-zhang · 2026-03-03T06:57:21Z

baojun-zhang
Mar 3, 2026
Maintainer

倾向选择方案B

方案A 中密钥丢失代表着数据丢失，从数据可用性和产品易用性的角度来看感觉不太行？不可恢复对于一个系统来讲是很难接受的吧

PS:
方案中是否还应该考虑密钥泄漏的 case ，同时支持变更密钥的能力

1 reply

qin-ctx Mar 3, 2026
Maintainer Author

应该是密钥轮转吧，需要重新对现有的文件重新做加密。上面第6点有提到

[RFC] Encryption at Rest for Multi-tenant Data Protection #379

Uh oh!

Uh oh!

qin-ctx Mar 2, 2026 Maintainer

English Version / 英文版

🔍 Review Items

Context

Threat Model

Encryption Scope

1.1 Symmetric Encryption Selection

1.2 Key Derivation Function (Scheme B only)

1.3 API Key Hash Selection

1.4 Summary & Referenced Standards

2. AGFS File Encryption: Key Source Scheme 🔍 Under Review

2.1 Scheme A: Client-Provided Key

2.2 Scheme B: Server-side Root Key Derivation (Envelope Encryption) ⭐ Recommended

2.3 Scheme Comparison

2.4 Review Decision Points

Scheme A Flow Diagram

Scheme B Flow Diagram

Walkthrough: acc_teamA uploads viking://resources/utils.py

Why Three Layers

Account Key Derivation

File Key & Envelope

3.1 Abstract Interface

3.2 Local File Provider (Dev / Single-node)

3.3 HashiCorp Vault Provider (Production)

3.4 AWS KMS Provider (AWS Cloud)

3.5 Provider Comparison

4.1 Envelope Format v1

4.2 AGFS Encryption Scope

4.3 VikingFS Integration

4.4 API Key Hash ✅ Confirmed

Changes

Dependencies

Verification

中文版 / Chinese Version

🔍 待评审事项

Context

威胁模型

加密范围与状态

1.1 对称加密算法选型

1.2 密钥派生函数 (KDF) 选型（AGFS 方案 B 适用）

1.3 API Key 哈希算法选型

1.4 算法总览与引用标准

2. AGFS 文件加密：密钥来源方案 🔍 待评审

2.1 方案 A：Client 传入密钥

2.2 方案 B：Server 端 Root Key 派生（Envelope Encryption） ⭐ 推荐

2.3 方案对比

2.4 待评审决策点

方案 A 流程图

方案 B 流程图

用实际例子走一遍：acc_teamA 上传 viking://resources/utils.py

为什么需要三层

account 密钥派生算法

文件密钥生成与 Envelope

3.1 抽象接口

3.2 Local File Provider（开发/单机）

3.3 HashiCorp Vault Provider（生产推荐）

3.4 AWS KMS Provider（AWS 云部署）

3.5 Provider 对比

4.1 加密文件二进制格式 (Envelope Format v1)

4.2 AGFS 文件加密范围

4.3 VikingFS 集成

4.4 API Key 哈希存储 ✅ 已确认

主要改动

依赖库

验证要点

Replies: 2 comments · 2 replies

Uh oh!

chuanbao666 Mar 3, 2026 Maintainer

Uh oh!

qin-ctx Mar 3, 2026 Maintainer Author

Uh oh!

baojun-zhang Mar 3, 2026 Maintainer

Uh oh!

qin-ctx Mar 3, 2026 Maintainer Author

qin-ctx
Mar 2, 2026
Maintainer

Walkthrough: acc_teamA uploads `viking://resources/utils.py`

用实际例子走一遍：acc_teamA 上传 `viking://resources/utils.py`

Replies: 2 comments 2 replies

chuanbao666
Mar 3, 2026
Maintainer

qin-ctx Mar 3, 2026
Maintainer Author

baojun-zhang
Mar 3, 2026
Maintainer

qin-ctx Mar 3, 2026
Maintainer Author