TianShanOS 安全实现进度表

本文档跟踪 TianShanOS 安全特性的实现状态，包括开发阶段和生产阶段的安全措施。

安全等级定义

等级	说明	适用场景
L1	软件防护	开发阶段、内部测试
L2	NVS 加密	预生产、受控环境
L3	Flash 加密 + Secure Boot	生产环境
L4	完整硬件安全	高安全性生产环境

〇、WebUI 认证系统 ✅ 新增

0.1 用户体系

特性	状态	等级	说明
双用户（admin/root）	✅ 已实现	L1	不同权限级别
SHA256+Salt 密码哈希	✅ 已实现	L1	16 字节随机 Salt
登录失败锁定	✅ 已实现	L1	5 次失败锁定 5 分钟
恒定时间哈希比较	✅ 已实现	L1	防止时序攻击
密码内存清零	✅ 已实现	L1	验证后立即清除

0.2 权限级别

用户	级别	权限范围	默认密码
admin	TS_PERM_ADMIN (3)	系统、网络、文件、安全页面	rm01
root	TS_PERM_ROOT (4)	所有页面（含终端、自动化、指令）	rm01

0.3 会话管理

特性	状态	说明
Token 有效期	✅ 24 小时	`CONFIG_TS_SECURITY_TOKEN_EXPIRE_SEC=86400`
最大并发会话	✅ 8 个	防止资源耗尽
版本控制重置	✅ 已实现	`AUTH_CONFIG_VERSION` 变化时强制重置密码
首次登录提醒	✅ 已实现	提示用户修改默认密码

0.4 API 端点

API	方法	认证	说明
auth.login	POST	否	用户登录
auth.logout	POST	Token	用户登出
auth.status	POST	Token	检查认证状态
auth.change_password	POST	Token	修改密码

0.5 前端权限控制

<!-- 导航栏权限标记 -->
<a href="#/terminal" class="nav-link" data-requires-root>终端</a>
<a href="#/automation" class="nav-link" data-requires-root>自动化</a>
<a href="#/commands" class="nav-link" data-requires-root>指令</a>

// router.js - 权限检查
checkAccess(path) {
    if (!api.isLoggedIn()) return { allowed: false, reason: 'not_logged_in' };
    if (this.rootOnlyPages.includes(path) && !api.isRoot()) {
        return { allowed: false, reason: 'root_required' };
    }
    return { allowed: true };
}

一、密钥存储安全

1.1 私钥保护

特性	状态	等级	说明
NVS 存储私钥	✅ 已实现	L1	私钥存储在 NVS 命名空间 `ts_keystore`
禁止私钥导出 API	✅ 已实现	L1	`ts_keystore_export_to_file()` 已改为仅导出公钥
可导出密钥标记	✅ 已实现	L1	`--exportable` 标记，仅明确允许的密钥可导出私钥
隐藏密钥 ID	✅ 已实现	L1	`hidden` 标记 + 别名系统，防止低权限用户知道敏感密钥 ID
CLI 仅导出公钥	✅ 已实现	L1	`key --export` 只输出公钥
私钥内存清零	✅ 已实现	L1	`secure_free_key()` 带边界检查的安全清零
NVS 加密	⏳ 待配置	L2	需要 `CONFIG_NVS_ENCRYPTION=y`
Flash 加密	⏳ 待配置	L3	需要 `CONFIG_FLASH_ENCRYPTION_ENABLED=y`

1.2 存储容量

配置项	当前值	目标值	说明
NVS 分区大小	0x6000 (24KB)	0xC000 (48KB)	支持 8 个 RSA-4096 密钥
最大密钥数	8	8	`TS_KEYSTORE_MAX_KEYS`
单个私钥最大	4096 字节	4096 字节	RSA-4096 PEM ~3.3KB

1.3 密钥容量估算

密钥类型	私钥大小	公钥大小	元数据	单个合计	8 个合计
RSA-2048	~1.7KB	~400B	~150B	~2.3KB	~18KB
RSA-4096	~3.3KB	~750B	~150B	~4.2KB	~34KB
ECDSA P-256	~230B	~200B	~150B	~580B	~4.6KB
ECDSA P-384	~300B	~250B	~150B	~700B	~5.6KB

结论：48KB NVS 可支持 8 个 RSA-4096 + 系统配置。

二、SSH 连接安全

2.1 认证安全

特性	状态	等级	说明
密码认证	✅ 已实现	L1	`--password` 参数
公钥认证（文件）	✅ 已实现	L1	`--key` 参数
公钥认证（安全存储）	✅ 已实现	L1	`--keyid` 参数，私钥不离开安全存储
密钥部署	✅ 已实现	L1	`--copyid` 追加公钥到 authorized_keys
公钥作废	✅ 已实现	L1	`--revoke` 从远程删除公钥

2.2 主机验证

特性	状态	等级	说明
Known hosts 存储	✅ 已实现	L1	`ts_known_hosts.c` 存储在 NVS
主机指纹验证	✅ 已实现	L1	所有 SSH 连接自动验证
首次连接确认	✅ 已实现	L1	TOFU 策略，提示用户确认指纹
指纹变化警告	✅ 已实现	L1	醒目警告框，检测 MITM 攻击
`hosts` 命令	✅ 已实现	L1	管理 known hosts（list/info/remove/clear）
已部署主机管理	✅ 已实现	L1	`hosts --deployed` 管理公钥部署记录
WebUI 主机管理	✅ 已实现	L1	安全页面可管理指纹和已部署主机

三、硬件安全（生产环境）

3.1 ESP32-S3 安全特性

特性	状态	配置项	说明
Secure Boot v2	⏳ 待启用	`CONFIG_SECURE_BOOT=y`	防止恶意固件
Flash 加密	⏳ 待启用	`CONFIG_FLASH_ENCRYPTION_ENABLED=y`	整盘加密
JTAG 禁用	⏳ 待启用	`CONFIG_SECURE_BOOT_DISABLE_JTAG=y`	防止调试攻击
eFuse 保护	⏳ 待配置	烧录后不可更改	永久性安全配置

3.2 NVS 加密方案

方案	安全性	复杂度	适用等级	说明
HMAC 密钥派生 ⭐	高	低	L2	eFuse HMAC 派生密钥，无需 Flash 加密
nvs_keys 分区	中	低	L3	需要 Flash 加密保护 nvs_keys 分区
Flash 加密 + NVS	最高	高	L3/L4	完整 Flash 加密支持

L2 推荐方案：HMAC 密钥派生

sdkconfig.defaults 配置：
CONFIG_NVS_ENCRYPTION=y
CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME=1
CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC=y
CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID=4      # 使用 eFuse BLOCK4

工作原理：

nvs_flash_init() 检查 eFuse BLOCK4 是否有 HMAC 密钥
如果没有，自动生成 256-bit 随机密钥并烧录到 eFuse
使用 HMAC 密钥派生 XTS-AES 加密密钥
所有 NVS 读写自动加密/解密

四、攻击向量与防御

4.1 物理攻击

攻击方式	L1 防护	L2 防护	L3 防护	L4 防护
JTAG 读取	❌	❌	✅ 禁用	✅ eFuse
Flash 读取	❌	⚠️ NVS 加密	✅ 全盘加密	✅
UART 泄露	⚠️ 软件限制	⚠️	✅	✅

4.2 软件攻击

攻击方式	防护措施	状态
API 私钥泄露	移除导出 API	✅ 已实现
内存 dump	使用后清零	✅ 已实现
恶意固件	Secure Boot	⏳ 待启用

五、分区表配置

5.1 当前配置

# Name,   Type, SubType, Offset,  Size,   Flags
nvs,      data, nvs,     0x9000,  0xC000,        # 48KB - 已扩大
nvs_keys, data, nvs_keys,0x15000, 0x1000,        # 4KB - 已添加
phy_init, data, phy,     0x16000, 0x1000,
factory,  app,  factory, 0x20000, 0x2F0000,      # 3008KB
storage,  data, spiffs,  0x310000,0xA0000,
www,      data, spiffs,  0x3B0000,0x40000,
fatfs,    data, fat,     0x3F0000,0x10000,

5.2 分区说明

分区	大小	用途
nvs	48KB	系统配置 + 密钥存储（8个RSA-4096）
nvs_keys	4KB	NVS加密密钥（启用加密时使用）
factory	3008KB	应用程序
storage	640KB	SPIFFS 用户数据
www	256KB	WebUI 静态文件
fatfs	64KB	FAT 文件系统

六、实施计划

阶段一：软件加固 (L1) - ✅ 已完成

任务	状态	日期
移除 `ts_keystore_export_to_file()` 私钥导出	✅	2026-01-18
添加私钥内存清零	✅	2026-01-18
限制私钥 API 调用范围	✅	2026-01-18
创建安全进度文档	✅	2026-01-18
添加 `exportable` 密钥标记	✅	2026-01-19
增强 `secure_free_key()` 边界检查	✅	2026-01-19
SSH 主机密钥验证	✅	2026-01-19
首次连接 TOFU 确认	✅	2026-01-19
指纹变化警告	✅	2026-01-19
添加 `hosts` 命令	✅	2026-01-19
添加 `ssh --revoke`	✅	2026-01-19
WebUI 主机指纹更新功能	✅	2026-01-23
隐藏密钥 ID + 别名系统	✅	2026-01-23

阶段二：NVS 加密 (L2) - ⏸️ 待功能开发完成

任务	状态	优先级
扩大 NVS 分区到 48KB	✅	P0
添加 nvs_keys 分区	✅	P0
配置 HMAC 方案选项	✅	P0
验证 `nvs_flash_init()` 兼容性	✅	P0
启用 `CONFIG_NVS_ENCRYPTION=y`	⏸️ 待功能完成	P1
测试密钥存储功能	⏸️ 待功能完成	P1

注意：L2 配置已就绪，待所有功能性开发完成后再启用测试。

原因：

开发阶段保持 L1 模式便于调试

避免 eFuse 写入对开发板的永久影响

统一在预生产阶段进行安全测试

L2 启用步骤

备份重要数据（启用加密后 NVS 数据会丢失）

修改 sdkconfig.defaults：

# 取消注释以下行
CONFIG_NVS_ENCRYPTION=y
CONFIG_NVS_SEC_KEY_PROTECTION_SCHEME=1
CONFIG_NVS_SEC_KEY_PROTECT_USING_HMAC=y
CONFIG_NVS_SEC_HMAC_EFUSE_KEY_ID=4

# 注释掉这行
#CONFIG_NVS_ENCRYPTION=n

清理并重新配置：
```
rm sdkconfig
idf.py reconfigure
```
擦除 Flash 并烧录：
```
idf.py erase-flash flash monitor
```
首次启动：
- ESP32 会自动在 eFuse BLOCK4 生成 HMAC 密钥
- 使用 HMAC 派生 NVS 加密密钥
- 后续所有 NVS 数据自动加密

⚠️ 注意：HMAC 密钥烧录到 eFuse 后不可更改！

阶段三：SSH 安全增强 (L1) - ✅ 已完成

任务	状态	完成日期
启用主机指纹验证	✅	2026-01-19
添加 `hosts` 命令	✅	2026-01-19
添加 `ssh --revoke`	✅	2026-01-19

阶段四：生产安全 (L3/L4) - 📋 计划中

任务	状态	优先级
启用 Secure Boot v2	📋	P1
启用 Flash 加密	📋	P1
禁用 JTAG	📋	P1
eFuse 配置文档	📋	P2

七、配置检查清单

开发阶段

CONFIG_NVS_ENCRYPTION=n（便于调试）
JTAG 可用
串口控制台可用
测试密钥管理功能

预生产阶段

CONFIG_NVS_ENCRYPTION=y
测试 NVS 加密功能
验证密钥存储容量

生产阶段

八、HTTPS/mTLS 证书管理

8.1 ts_cert 组件

特性	状态	等级	说明
ECDSA P-256 密钥生成	✅ 已实现	L1	PSRAM 分配，安全清零
X.509 CSR 生成	✅ 已实现	L1	RFC 2986 标准
证书链验证	✅ 已实现	L1	Root → Intermediate → Device
NVS 持久化	✅ 已实现	L1	namespace: ts_cert
私钥禁止导出	✅ 已实现	L1	仅支持 CSR 流程

8.2 证书管理 API

API 端点	功能	状态
`cert.status`	获取证书状态	✅
`cert.generate_key`	生成 ECDSA 密钥对	✅
`cert.generate_csr`	生成 CSR	✅
`cert.get_csr`	获取已生成的 CSR	✅
`cert.install`	安装签发的证书	✅
`cert.install_ca`	安装 CA 链	✅
`cert.delete`	删除证书和密钥	✅

8.3 WebUI 集成

功能	状态	说明
统一密钥管理表格	✅	SSH + HTTPS 密钥整合显示
HTTPS 证书状态卡片	✅	有效期/CN/签发者/序列号
CSR 生成模态框	✅	输入 CN → 生成 PEM
证书安装模态框	✅	粘贴 PEM → 安装
CA 链安装	✅	支持完整证书链

九、相关文件

文件	说明
`components/ts_security/src/ts_keystore.c`	SSH 密钥存储实现
`components/ts_security/include/ts_keystore.h`	SSH 密钥存储 API
`components/ts_security/src/ts_cert.c`	HTTPS 证书管理实现
`components/ts_security/include/ts_cert.h`	HTTPS 证书管理 API
`components/ts_security/src/ts_known_hosts.c`	Known hosts 实现
`components/ts_api/src/ts_api_cert.c`	证书管理 REST API
`components/ts_console/commands/ts_cmd_key.c`	key 命令实现
`components/ts_console/commands/ts_cmd_ssh.c`	ssh 命令实现
`components/ts_console/commands/ts_cmd_hosts.c`	hosts 命令实现
`partitions.csv`	分区表配置
`sdkconfig.defaults`	SDK 默认配置

版本历史

版本	日期	说明
1.0	2026-01-18	初始版本，完成 L1 软件加固基础
1.1	2026-01-19	添加 exportable 密钥标记、增强内存安全
1.2	2026-01-19	完成 SSH 安全增强：主机验证、hosts 命令、revoke 功能
1.3	2026-01-19	L2 准备：配置 HMAC 方案 NVS 加密选项，添加启用指南
1.4	2026-01-19	L2 测试推迟至功能开发完成后进行
1.5	2026-01-27	完成 HTTPS/mTLS 证书管理：ts_cert 组件、7 个 API 端点、WebUI 集成

Uh oh!

FilesExpand file tree

SECURITY_IMPLEMENTATION.md

Latest commit

History

SECURITY_IMPLEMENTATION.md

File metadata and controls

TianShanOS 安全实现进度表

安全等级定义

〇、WebUI 认证系统 ✅ 新增

0.1 用户体系

0.2 权限级别

0.3 会话管理

0.4 API 端点

0.5 前端权限控制

一、密钥存储安全

1.1 私钥保护

1.2 存储容量

1.3 密钥容量估算

二、SSH 连接安全

2.1 认证安全

2.2 主机验证

三、硬件安全（生产环境）

3.1 ESP32-S3 安全特性

3.2 NVS 加密方案

四、攻击向量与防御

4.1 物理攻击

4.2 软件攻击

五、分区表配置

5.1 当前配置

5.2 分区说明

六、实施计划

阶段一：软件加固 (L1) - ✅ 已完成

阶段二：NVS 加密 (L2) - ⏸️ 待功能开发完成

L2 启用步骤

阶段三：SSH 安全增强 (L1) - ✅ 已完成

阶段四：生产安全 (L3/L4) - 📋 计划中

七、配置检查清单

开发阶段

预生产阶段

生产阶段

八、HTTPS/mTLS 证书管理

8.1 ts_cert 组件

8.2 证书管理 API

8.3 WebUI 集成

九、相关文件

版本历史