Skip to content

Self-evolving Context Database for AI Agents. Unify Agent Memory, Knowledge RAG and Skills.

feat(encryption): support inline local root key (#6678)

Jiahui Zhou3901724ac4e4
diff --git a/docs/en/guides/01-configuration.md b/docs/en/guides/01-configuration.md
index 08eeafb3d..e1d0f6847 100644
--- a/docs/en/guides/01-configuration.md
+++ b/docs/en/guides/01-configuration.md
@@ -2284,7 +2284,7 @@ At-rest encryption protects newly written files with account-specific keys throu
| `provider` | str | Key provider: `"local"`, `"vault"`, or `"volcengine_kms"` | - |
| `api_key_hashing.enabled` | bool | File-provider only: whether to apply Argon2id one-way hashing to API key values (independent of file-level `enabled`); see [Encryption Guide](./08-encryption.md) | `false` |
-### Local (File)
+### Local
Suitable for development environments and single-node deployments:
@@ -2303,6 +2303,11 @@ Suitable for development environments and single-node deployments:
| Parameter | Type | Description | Default |
|-----------|------|-------------|---------|
| `local.key_file` | str | Root key file path | `~/.openviking/master.key` |
+| `local.root_key` | str | Inline 32-byte root key encoded as exactly 64 hexadecimal characters | - |
+
+Do not configure `local.key_file` and `local.root_key` together. If both are omitted,
+`local.key_file` defaults to `~/.openviking/master.key`. See the [Encryption Guide](./08-encryption.md)
+for inline-key handling and security requirements.
### Vault (HashiCorp Vault)
diff --git a/docs/en/guides/08-encryption.md b/docs/en/guides/08-encryption.md
index 9f3a28ba1..c1ef340b0 100644
--- a/docs/en/guides/08-encryption.md
+++ b/docs/en/guides/08-encryption.md
@@ -146,7 +146,7 @@ Enable Argon2id one-way hashing to stop storing recoverable API key values:
| Provider | Use Case | Pros | Cons |
|----------|----------|------|------|
-| **Local** | Dev environments, single-node | Simple, no external services | Requires local file permissions and separate key backups |
+| **Local** | Dev environments, single-node | Simple, no external services | Requires local secret permissions and separate key backups |
| **Vault** | Production, multi-cloud | Enterprise-grade KMS, version control | Requires deploying and maintaining Vault |
| **Volcengine KMS** | Volcengine cloud | Cloud-native KMS service | Volcengine-only |
@@ -191,6 +191,35 @@ ov system crypto init-key -f ~/.openviking/master.key
}
```
+### Inline Root Key
+
+For simple, controlled deployments, the Local provider can read the same 32-byte root key
+directly from `ov.conf` instead of a separate file:
+
+```json
+{
+ "encryption": {
+ "enabled": true,
+ "provider": "local",
+ "local": {
+ "root_key": "<64-character hexadecimal root key>"
+ }
+ }
+}
+```
+
+The value is 32 bytes encoded as exactly 64 hexadecimal characters. You can generate one with
+`openssl rand -hex 32`, or reuse the contents of an existing `master.key` when moving between the
+two Local configurations.
+
+- Do not configure `root_key` and `key_file` together. If both are omitted, the Local provider
+ continues to use `~/.openviking/master.key`.
+- An inline key is never generated automatically. Losing or changing it makes existing encrypted
+ data unreadable.
+- Treat `ov.conf` as a key file: restrict it to the service user, back it up securely, and never
+ commit it to version control.
+- Prefer Vault or KMS when production deployments need centralized secret management.
+
---
## Vault Mode Detailed Guide
diff --git a/docs/zh/guides/01-configuration.md b/docs/zh/guides/01-configuration.md
index 082b15657..926720ad5 100644
--- a/docs/zh/guides/01-configuration.md
+++ b/docs/zh/guides/01-configuration.md
@@ -2199,7 +2199,7 @@ Redis 连接和命令超时通过 `cache.params.connect_timeout_ms` 和
| `provider` | str | 密钥提供程序:`"local"`、`"vault"` 或 `"volcengine_kms"` | - |
| `api_key_hashing.enabled` | bool | 仅 File Provider:是否对 API key 字段启用 Argon2id 单向哈希(与文件级 `enabled` 独立控制),详见 [加密指南](./08-encryption.md) | `false` |
-### Local(本地文件)
+### Local
适合开发环境和单节点部署:
@@ -2218,6 +2218,10 @@ Redis 连接和命令超时通过 `cache.params.connect_timeout_ms` 和
| 参数 | 类型 | 说明 | 默认值 |
|------|------|------|--------|
| `local.key_file` | str | 根密钥文件路径 | `~/.openviking/master.key` |
+| `local.root_key` | str | 直接配置的 32 字节根密钥,必须编码为恰好 64 个十六进制字符 | - |
+
+不要同时配置 `local.key_file` 和 `local.root_key`。如果两者都省略,`local.key_file` 默认使用
+`~/.openviking/master.key`。内联密钥的管理和安全要求详见[加密指南](./08-encryption.md)。
### Vault(HashiCorp Vault)
diff --git a/docs/zh/guides/08-encryption.md b/docs/zh/guides/08-encryption.md
index 6c47a83df..0ceadef03 100644
--- a/docs/zh/guides/08-encryption.md
+++ b/docs/zh/guides/08-encryption.md
@@ -146,7 +146,7 @@ test()
| 提供程序 | 适用场景 | 优点 | 缺点 |
|---------|---------|------|------|
-| **Local** | 开发环境、单节点部署 | 简单,无需外部服务 | 需要管理本地文件权限和独立密钥备份 |
+| **Local** | 开发环境、单节点部署 | 简单,无需外部服务 | 需要管理本地密钥权限和独立密钥备份 |
| **Vault** | 生产环境、多云部署 | 企业级密钥管理,支持版本控制 | 需要部署和维护 Vault |
| **Volcengine KMS** | 火山引擎云部署 | 云原生密钥管理服务 | 仅限火山引擎环境 |
@@ -191,6 +191,33 @@ ov system crypto init-key -f ~/.openviking/master.key
}
```
+### 在配置中直接提供根密钥
+
+对于简单、受控的部署,Local provider 可以直接从 `ov.conf` 读取同一个 32 字节根密钥,
+不再使用单独的密钥文件:
+
+```json
+{
+ "encryption": {
+ "enabled": true,
+ "provider": "local",
+ "local": {
+ "root_key": "<64 个十六进制字符的根密钥>"
+ }
+ }
+}
+```
+
+配置值是 32 字节密钥的十六进制表示,因此必须恰好包含 64 个十六进制字符。可以使用
+`openssl rand -hex 32` 生成,也可以在两种 Local 配置之间迁移时直接复用已有
+`master.key` 的内容。
+
+- 不要同时配置 `root_key` 和 `key_file`;如果两者都省略,Local provider 仍使用
+ `~/.openviking/master.key`。
+- 内联密钥不会自动生成;密钥丢失或改变后,已有加密数据将无法读取。
+- 此时必须把 `ov.conf` 当作密钥文件管理:只允许服务用户读取、安全备份,并且禁止提交到版本控制。
+- 生产环境需要集中式密钥管理时,仍建议使用 Vault 或 KMS。
+
---
## Vault 模式详细指南
diff --git a/openviking/crypto/config.py b/openviking/crypto/config.py
index 1824c8345..04f3580ed 100644
--- a/openviking/crypto/config.py
+++ b/openviking/crypto/config.py
@@ -12,7 +12,7 @@ from typing import Any, Dict, List, Optional, Tuple
from openviking.crypto.encryptor import FileEncryptor
from openviking.crypto.exceptions import ConfigError
-from openviking.crypto.providers import create_root_key_provider
+from openviking.crypto.providers import create_root_key_provider, decode_inline_root_key
from openviking_cli.utils.logger import get_logger
logger = get_logger(__name__)
@@ -60,8 +60,22 @@ def _validate_local_provider_config(config: Dict[str, Any]) -> List[str]:
"""Validate Local Provider configuration."""
errors = []
local_config = config.get("local", {})
- key_file_path = local_config.get("key_file", "~/.openviking/master.key")
+ key_file_path = local_config.get("key_file")
+ root_key = local_config.get("root_key")
+ if key_file_path is not None and root_key is not None:
+ errors.append(
+ "encryption.local.root_key and encryption.local.key_file are mutually exclusive"
+ )
+ return errors
+ if root_key is not None:
+ try:
+ decode_inline_root_key(root_key)
+ except ConfigError as exc:
+ errors.append(str(exc))
+ return errors
+ if key_file_path is None:
+ key_file_path = "~/.openviking/master.key"
if not key_file_path:
errors.append("encryption.local.key_file is required")
return errors
diff --git a/openviking/crypto/providers.py b/openviking/crypto/providers.py
index cbeb50c10..59e612876 100644
--- a/openviking/crypto/providers.py
+++ b/openviking/crypto/providers.py
@@ -53,6 +53,20 @@ PROVIDER_VAULT = 0x02
PROVIDER_VOLCENGINE = 0x03
+def decode_inline_root_key(root_key: object) -> bytes:
+ """Decode a 32-byte root key without exposing it in validation errors."""
+ error = "encryption.local.root_key must be a 64-character hexadecimal string"
+ if not isinstance(root_key, str) or len(root_key) != 64:
+ raise ConfigError(error)
+ try:
+ decoded = bytes.fromhex(root_key)
+ except ValueError as exc:
+ raise ConfigError(error) from exc
+ if len(decoded) != 32:
+ raise ConfigError(error)
+ return decoded
+
+
class RootKeyProvider(ABC):
"""Root Key Provider abstract base class."""
@@ -179,17 +193,20 @@ class BaseProvider(RootKeyProvider):
class LocalFileProvider(BaseProvider):
- """Local file Root Key Provider."""
+ """Local Root Key Provider backed by a file or inline configuration."""
- def __init__(self, key_file: str):
+ def __init__(self, key_file: Optional[str] = None, root_key: Optional[str] = None):
"""
Initialize LocalFileProvider.
Args:
- key_file: Root Key file path
+ key_file: Root Key file path.
+ root_key: 32-byte Root Key encoded as 64 hexadecimal characters.
"""
- self.key_file = Path(key_file).expanduser()
- self._root_key: Optional[bytes] = None
+ if (key_file is None) == (root_key is None):
+ raise ConfigError("exactly one of key_file or root_key must be configured")
+ self.key_file = Path(key_file).expanduser() if key_file is not None else None
+ self._root_key = decode_inline_root_key(root_key) if root_key is not None else None
async def get_root_key(self) -> bytes:
"""Get Root Key."""
@@ -224,6 +241,7 @@ class LocalFileProvider(BaseProvider):
async def _load_or_create_root_key(self) -> bytes:
"""Load or create Root Key."""
+ assert self.key_file is not None
if self.key_file.exists():
# Read existing key
with open(self.key_file, "r") as f:
@@ -820,8 +838,17 @@ def create_root_key_provider(
"""
if provider_type == "local":
local_config = config.get("local", {})
- key_file_path = local_config.get("key_file", "~/.openviking/master.key")
+ key_file_path = local_config.get("key_file")
+ root_key = local_config.get("root_key")
+ if key_file_path is not None and root_key is not None:
+ raise ConfigError(
+ "encryption.local.root_key and encryption.local.key_file are mutually exclusive"
+ )
+ if root_key is not None:
+ return LocalFileProvider(root_key=root_key)
+ if key_file_path is None:
+ key_file_path = "~/.openviking/master.key"
if not key_file_path:
raise ConfigError("encryption.local.key_file is required")
return LocalFileProvider(key_file_path)
diff --git a/openviking_cli/utils/config/encryption_config.py b/openviking_cli/utils/config/encryption_config.py
index 377468df5..d7fb244fc 100644
--- a/openviking_cli/utils/config/encryption_config.py
+++ b/openviking_cli/utils/config/encryption_config.py
@@ -2,19 +2,31 @@
# SPDX-License-Identifier: AGPL-3.0
from typing import Any, Dict, Optional
-from pydantic import BaseModel, Field
+from pydantic import BaseModel, Field, model_validator
class LocalEncryptionProviderConfig(BaseModel):
- """Local file encryption provider configuration.
+ """Local encryption provider configuration.
- Uses a local file to store the Root Key.
+ Reads the Root Key from a local file or directly from configuration.
Suitable for single-user or development environments.
"""
- key_file: str = Field(
- default="~/.openviking/master.key", description="Path to local root key file"
+ key_file: Optional[str] = Field(
+ default="~/.openviking/master.key",
+ description="Path to local root key file",
)
+ root_key: Optional[str] = Field(
+ default=None,
+ repr=False,
+ description="32-byte root key encoded as 64 hexadecimal characters",
+ )
+
+ @model_validator(mode="after")
+ def use_inline_key_without_implicit_file(self) -> "LocalEncryptionProviderConfig":
+ if self.root_key is not None and "key_file" not in self.model_fields_set:
+ self.key_file = None
+ return self
class VaultEncryptionProviderConfig(BaseModel):
diff --git a/tests/unit/crypto/test_config.py b/tests/unit/crypto/test_config.py
index b77660219..36a9dc006 100644
--- a/tests/unit/crypto/test_config.py
+++ b/tests/unit/crypto/test_config.py
@@ -6,7 +6,11 @@ Unit tests for crypto configuration.
import pytest
-from openviking.crypto.config import bootstrap_encryption
+from openviking.crypto.config import bootstrap_encryption, validate_encryption_config
+from openviking_cli.utils.config.encryption_config import (
+ EncryptionConfig,
+ LocalEncryptionProviderConfig,
+)
@pytest.mark.asyncio
@@ -43,6 +47,78 @@ async def test_bootstrap_encryption_local_file(tmp_path):
assert encryptor is not None
+async def test_bootstrap_encryption_inline_local_root_key(tmp_path, monkeypatch):
+ """The local provider can use the existing 32-byte key directly from config."""
+ monkeypatch.setenv("HOME", str(tmp_path))
+ root_key = bytes(range(32))
+ encryption = EncryptionConfig(
+ enabled=True,
+ provider="local",
+ local={"root_key": root_key.hex()},
+ )
+
+ encryptor = await bootstrap_encryption({"encryption": encryption.model_dump()})
+
+ assert encryptor is not None
+ assert await encryptor.provider.get_root_key() == root_key
+
+
+def test_local_root_key_and_key_file_are_mutually_exclusive(tmp_path):
+ config = {
+ "encryption": {
+ "enabled": True,
+ "provider": "local",
+ "local": {
+ "key_file": str(tmp_path / "master.key"),
+ "root_key": "00" * 32,
+ },
+ }
+ }
+
+ is_valid, errors = validate_encryption_config(config)
+
+ assert not is_valid
+ assert errors == [
+ "encryption.local.root_key and encryption.local.key_file are mutually exclusive"
+ ]
+
+
[email protected]("root_key", ["00" * 31, "zz" * 32, 123])
+def test_local_root_key_must_be_32_byte_hex(root_key):
+ config = {
+ "encryption": {
+ "enabled": True,
+ "provider": "local",
+ "local": {"root_key": root_key},
+ }
+ }
+
+ is_valid, errors = validate_encryption_config(config)
+
+ assert not is_valid
+ assert errors == [
+ "encryption.local.root_key must be a 64-character hexadecimal string"
+ ]
+ assert str(root_key) not in errors[0]
+
+
+def test_local_encryption_config_hides_inline_root_key_from_repr():
+ root_key = "ab" * 32
+
+ config = LocalEncryptionProviderConfig(root_key=root_key)
+
+ assert config.root_key == root_key
+ assert config.key_file is None
+ assert root_key not in repr(config)
+
+
+def test_local_encryption_config_preserves_default_key_file():
+ config = LocalEncryptionProviderConfig()
+
+ assert config.key_file == "~/.openviking/master.key"
+
+
@pytest.mark.asyncio
async def test_bootstrap_encryption_invalid_provider():
"""Test bootstrap_encryption with invalid provider."""
diff --git a/tests/unit/crypto/test_local_provider.py b/tests/unit/crypto/test_local_provider.py
index d599e538c..fcbca091c 100644
--- a/tests/unit/crypto/test_local_provider.py
+++ b/tests/unit/crypto/test_local_provider.py
@@ -9,6 +9,7 @@ import tempfile
import pytest
+from openviking.crypto.encryptor import PROVIDER_LOCAL, FileEncryptor
from openviking.crypto.providers import LocalFileProvider
@@ -68,3 +69,30 @@ async def test_local_file_provider_different_accounts(local_file_provider):
decrypted2 = await local_file_provider.decrypt_file_key(encrypted_key2, iv2, account2)
assert decrypted2 == plaintext_key
+
+
+async def test_local_provider_accepts_inline_root_key_with_local_envelope_type():
+ root_key = bytes(range(32))
+
+ provider = LocalFileProvider(root_key=root_key.hex())
+
+ assert await provider.get_root_key() == root_key
+ assert FileEncryptor(provider).provider_type == PROVIDER_LOCAL
+
+
+async def test_inline_and_file_local_providers_are_ciphertext_compatible(tmp_path):
+ root_key = bytes(range(32))
+ key_file = tmp_path / "master.key"
+ key_file.write_text(root_key.hex())
+ file_encryptor = FileEncryptor(LocalFileProvider(key_file=str(key_file)))
+ inline_encryptor = FileEncryptor(LocalFileProvider(root_key=root_key.hex()))
+ account_id = "test_account"
+ plaintext = b"compatible local provider ciphertext"
+
+ file_ciphertext = await file_encryptor.encrypt(account_id, plaintext)
+ inline_ciphertext = await inline_encryptor.encrypt(account_id, plaintext)
+
+ assert await inline_encryptor.decrypt(account_id, file_ciphertext) == plaintext
+ assert await file_encryptor.decrypt(account_id, inline_ciphertext) == plaintext