ESP32 WebAssembly 小应用权限模型：Manifest、API 检查与资源配额

摘要在 ESP32 上运行可独立安装的 WebAssembly 小应用时只把display、touch、storage写进 Manifest并不能自动形成安全边界。权限声明必须由应用包签名保护并在安装校验、WASM 加载、事件分发和每一次系统 API 调用中真正执行。本文介绍 ESP Mini App Platform 当前权限模型的实现思路包括导入限制、显示与触摸权限检查、应用独立 NVS 数据空间、指令和绘图配额以及这套原型目前仍然存在的边界。1. 为什么 ESP32 小应用也需要权限权限并不只是为了防范恶意程序。在微控制器上更常见的风险是普通代码错误坐标计算错误绘图越过应用画布错误的内存偏移被传给原生函数死循环或过长计算持续占用 CPU高频写入不断消耗 Flash 擦写寿命一个应用访问了另一个应用的数据。当系统首页、触摸驱动、网络、存储和多个应用共用同一颗 MCU 时一个应用失控就可能拖累整台设备。因此这个平台把限制分成两类权限决定应用能否使用某项能力。配额决定它最多能消耗多少资源。可以把核心判断概括为权限回答“能不能做”配额回答“最多能做多少”。2. Manifest 是权限申请表不是执行器当前应用包可以声明三种权限{permissions:[display,touch,storage]}display使用清屏、矩形和文字绘制 APItouch接收平台分发的触摸释放事件storage访问该应用自己的键值数据空间。Manifest 会与 WASM 一起打进.appManifest 本身由 P-256 ECDSA 私钥签名。权限列表因此也属于签名内容包生成以后不能在不破坏签名的情况下增加权限。设备安装时还会检查权限数组未知权限、重复权限和不支持的字段都会被拒绝。不过这一步只证明“申请表有效”。真正的执行仍然要落在平台代码中。3. 权限模型的整体结构当前链路可以表示为签名 .app ↓ 验证 Manifest 与 permissions ↓ 检查 WASM 导入、内存和入口约束 ↓ 启动 WAMR 实例 ↓ 事件分发与每一次系统 API 调用再次检查权限 ↓ 检查参数、地址、坐标和资源配额权限不是集中在一个函数里完成的而是贯穿应用包、加载器、Runtime、系统 API 和存储后端。4. 第一层限制只公开最小系统 API普通 ESP-IDF 程序可以直接调用 GPIO、I²C、SPI、文件系统和网络接口。当前 WASM ABI v1 不把这些原生能力直接交给应用。应用只能导入平台注册的函数clear rect text millis kv_get kv_set平台不开放 WASI、线程、原生 GPIO、LVGL 对象、驱动句柄和原生地址。WASM 模块的 Import Section 目前只允许函数导入导入内存、表、全局变量或未知函数都会在加载阶段失败。这种做法的重点不是接口少而是让所有硬件交互都经过可检查的入口。5. 第二层限制每一次调用都检查权限5.1 显示权限绘图 API 调用前先检查PERM_DISPLAY同时统计本次入口已经使用的绘图次数staticboolallowed(wasm_exec_env_tenv){if(!(permissionsPERM_DISPLAY)||draw_calls96){wasm_runtime_set_exception(wasm_runtime_get_module_inst(env),display permission/quota exceeded);returnfalse;}returntrue;}即使拥有显示权限参数也必须继续校验rect的坐标和尺寸不能越过 480×400 应用画布text最多接收 160 字节文本偏移和长度必须落在当前 WASM 实例的线性内存中检查通过后平台才把文本复制到受控缓冲区。5.2 触摸权限应用不能直接读取触摸控制器。触摸先由系统读取再由 Runtime 决定是否分发事件if(state!APP_RUNNING||(event2!(permissionsPERM_TOUCH))){return;}其中事件2表示触摸释放。没有touch权限时坐标不会进入应用的app_event()。5.3 存储权限只有声明storage的应用启动时才会打开自己的 NVS 句柄。kv_get和kv_set的入口也会再次检查权限if(!(permissionsPERM_STORAGE)||!data_handle){wasm_runtime_set_exception(instance,storage permission denied);return-1;}每个应用的数据空间由应用 ID 映射为独立 NVS namespace并额外保存原始 ID 校验归属。如果发生命名空间映射冲突平台会拒绝打开而不会交出另一个应用的数据。存储接口不接受任意文件路径只接受受限键名和位于 WASM 线性内存中的缓冲区。6. 资源配额有权限也不能无限使用当前版本设置了以下边界资源当前限制目的WASM 指令每次app_init()或app_event()最多 50000 条避免单次回调长期占用 CPU绘图调用每次入口最多 96 次避免无限提交绘制请求线性内存最多 4 页即 256 KiB限制单应用内存占用文本参数最多 160 字节限制原生缓冲区使用单个存储值最多 128 字节限制数据规模键数量每个应用最多 8 个防止耗尽 NVS 条目写入频率整个 Runtime 每秒最多 4 次有效写入控制 Flash 写入压力相同内容的重复写入不会真正落盘。NVS 剩余条目少于安全阈值时平台也会拒绝应用继续写入为系统数据保留空间。如果 WASM 超过指令预算WAMR 会终止执行如果出现越界地址、未授权调用或无效参数平台会设置异常并停止当前应用随后释放模块实例、执行环境和数据句柄。7. Snake 应用中的实际调用链Snake 同时声明了display、touch和storage可以覆盖完整链路启动时通过显示 API 绘制蛇身、食物和分数平台检查显示权限、坐标和绘图次数用户触摸后系统读取坐标并确认触摸权限Runtime 把触摸释放事件交给app_event()最高分变化时Snake 调用kv_set(best, ...)平台检查存储权限、键名、地址、长度、键数量和写入额度数据写入 Snake 自己的 NVS namespace。如果从 Manifest 中移除storage但程序仍然调用kv_set设备会产生storage permission denied异常。函数被编译进 WASM并不代表应用能够绕过权限声明。8. WASM 隔离与系统 API 边界的关系WASM 线性内存让应用不能像原生 C 程序那样随意构造地址访问系统内存WAMR 提供模块加载、实例化和异常机制。但 WASM 本身不知道画布尺寸也不知道 Flash 的写入寿命。宿主一旦开放某项能力它的具体边界仍由系统 API 决定。WASM / WAMR隔离代码与线性内存 系统 API检查权限、参数、资源配额和硬件访问两层需要同时存在。只使用 WASM 而没有受限宿主 API仍可能把危险能力直接暴露给应用只有 API 检查而没有内存隔离又很难安全接收应用传来的地址。9. 当前实现边界这套权限模型仍处于工程原型阶段当前只有display、touch和storage网络、GPIO、I²C、SPI、音频和传感器没有直接开放给应用权限在构建阶段写入 Manifest设备暂时没有首次调用弹窗、动态授权和单项撤销当前机制依赖签名包、WAMR、加载策略、API 检查和配额共同工作它不能简单等同于桌面或手机操作系统的进程沙箱。当前思路是先把每一种能力的入口和限制做清楚再根据真实应用需求扩展权限而不是先列出大量没有实际执行逻辑的权限名称。10. 总结一个可执行的权限模型至少需要四个部分权限声明被应用包签名保护加载阶段只允许受控导入和内存结构每次 API 调用和事件分发都检查权限对指令、绘图、内存和存储继续设置配额。Manifest 负责描述平台负责执行。只有两者连起来permissions才不是一段展示文字。下一篇将继续讨论独立存储多个应用共用一块 Flash 时如何使用应用 ID、NVS namespace、键数量和写入额度避免数据互相覆盖。标签ESP32WebAssemblyWAMR嵌入式开发权限模型系统APIManifestNVS软件架构物联网