openaliro

一个 Aliro 数字钥匙锁：iPhone 或 Apple Watch 在靠近时（超宽带测距）或轻触时（NFC）即可解锁。

目标 · 快速开始 · 硬件 · 工作原理 · 状态 · 文档 · 许可证

_{硬件上的真实解锁：iPhone 靠近解锁。}

openaliro 实现了 [Aliro](https://csa-iot.org/all-solutions/aliro/) 数字钥匙的锁端。手机通过 Bluetooth LE 进行身份验证，并利用超宽带技术测量距离：当手机靠近时门会自动解锁，离开时则会重新上锁。普通的 NFC 轻触也能解锁。无需应用，无需按键。 ## 功能 - **免手动解锁**：靠近时解锁，离开时重新上锁。 - **轻触解锁**：将 iPhone 或 Apple Watch 贴近读卡器（快捷模式，无需 Face ID）。 - **与凭证绑定的测距**：距离测量与钥匙绑定，因此录制的信号无法重放进行解锁。 - **无需 UWB 协处理器**：整个安全测距栈在裸机 Qorvo DW3110 上的固件中运行。 - **双 SoC**：相同的测距引擎可运行在 Nordic 和 Espressif 的芯片上。

_{Key setup · Approach Direction · provisioning · lock and unlock states, all against live hardware}

## 目标 两个目标平台均能在 iPhone 靠近时实现解锁，并且都已在硬件上完成验证。它们共享位于 `modules/woz_uwb` 中的 UWB 引擎，且代码逐字节完全一致。 | 目标 | 它是什么 | 位置 | |---|---|---| | **nRF5340 DK** | 主要构建版本。在 Nordic 门锁附加组件的基础上，实现了靠近解锁以及 NFC 轻触解锁路径。 | [`ports/nrf5340dk/`](ports/nrf5340dk/) (从仓库根目录构建：`make build`) | | **ESP32-S3** | 一款基于从零编写的读卡器栈构建的 Matter 门锁：包含 BLE 传输、凭证身份验证和测距密钥派生。仅支持靠近解锁，不支持 NFC 轻触。 | [`ports/esp32/`](ports/esp32/) | ESP32 的移植版本并非简单的重新编译。参考设计将凭证身份验证和测距密钥派生委托给了一个仅以 ARM 二进制文件提供的闭源供应商库，因此在 Xtensa 架构上没有任何组件可以链接它。整个这一层都在此重新实现了。 ## 快速开始 **nRF5340 DK:** ``` nrfutil sdk-manager toolchain install --ncs-version v3.3.0 # once per machine make bootstrap # fetch NCS v3.3.0 + the Nordic add-on (~6.5 GB) into ./workspace make build # → ./build/merged.hex make flash-erase # first flash of a net-core image make flash # every flash after that ``` 其他可用命令：`make test`（主机测试套件，无需工具链或硬件）、`make coverage`、`make selftest`（启动自检，无需 iPhone）、`make rebuild`、`make term` 和 `make clean`。仅运行 `make` 可查看完整的分组列表。选项可作为变量传入：`make build PRETTY=1 CHIP=dw3720`（也包括 `PRISTINE=1`、`SELFTEST=1`）。 `HA=1` 会构建一个可选的 Home Assistant 变体，通过 Matter 公开锁操作和 UWB 距离感知。它必须在两个步骤中都进行设置（`make bootstrap HA=1 && make build HA=1`），并且未经硬件验证；默认构建不受影响。详见 [`integration/homeassistant/`](integration/homeassistant/README.md)，该文档还记录了一个完全无需更改固件的控制台到 MQTT 桥接。 **ESP32-S3** (需要机器上安装有 ESP-IDF 和 esp-matter): ``` cd ports/esp32/apps/matter-lock make set-target # once per checkout make go # build + flash + monitor ``` **无硬件** (仅限笔记本电脑 — 运行完整的主机端门禁): ``` make test # 578-assertion KAT suite, plain cc, sub-second make test-port # ESP32 port suite (crypto KATs, codec, provisioning) make verify # everything: test + sanitizers + fuzz + CBMC ``` 关于端口索引，请参见 [`ports/README.md`](ports/README.md)；关于无线电模块的接线说明，请参见 [`docs/esp32-bringup.md`](docs/esp32-bringup.md)。 ## 仓库结构 ``` Makefile every entry point (build, flash, test, docs); run `make` for the list scripts/ the machinery behind it (bootstrap, build, docs, workspace seeding) modules/ woz_port/ THE PORTING SEAM: woz_port.h + woz_log.h, the whole platform contract woz_uwb/ UWB engine: driver, FiRa MAC, CCC STS, M1-M4 codec (shared, all targets) woz_aliro/ Aliro credential auth: key schedule, secure channels, wire codec, reader woz_aliro_ecp/ NFC ECP emitter for Express Mode tap (Nordic-licensed) ports/ nrf5340dk/ primary target: patches + overlays laid over the fetched Nordic add-on esp32/ ESP32-S3: shared components + two apps (matter-lock, bench reader) + tests deps/dw3000/ vendored Qorvo/Decawave DW3000 driver, compiled unchanged by every target integration/ Home Assistant MQTT bridge (no firmware change needed) tests/ host KAT suite, sanitizers, fuzzing, CBMC proofs, tooling tests docs/ guides (protocol research, bring-up, porting) + generated reference ``` ## 硬件 **nRF5340 DK:** | 部件 | 作用 | |---|---| | nRF5340 DK | 主机 SoC：BLE + Matter 以及测距引擎 | | DWM3000EVB (DW3110) | UWB 无线电模块，连接在 Arduino 接口上 (SPIM4) | | X-NUCLEO-NFC12A1 (ST25R300) | 用于轻触解锁的 NFC 读卡器前端 (SPIM2) | 引脚分配位于 [`ports/nrf5340dk/overlays/dw3000-nfc.overlay`](ports/nrf5340dk/overlays/dw3000-nfc.overlay)。 **ESP32-S3:** | 部件 | 作用 | |---|---| | ESP32-S3 开发板 | 主机 SoC：通过 Wi-Fi 运行的 BLE + Matter 以及测距引擎 | | DWM3000EVB (DW3110) | 连接在 SPI2 上的 UWB 无线电模块，需十一根跳线 | 引脚分配位于 [`ports/esp32/components/woz_uwb/port/board_pins.h`](ports/esp32/components/woz_uwb/port/board_pins.h)； 接线表位于 [`docs/esp32-bringup.md`](docs/esp32-bringup.md)。 ## 工作原理 整个交互过程依托于 BLE 进行；UWB 不传输应用数据，仅用于距离测量。通信双方独立从身份验证信息中派生出测距密钥，因此测距过程无法通过嗅探到的 BLE 流量进行重放。当设备进入配置的距离阈值内时锁会打开，并在超过滞后裕度时重新上锁。 ``` flowchart LR phone(["iPhone / Apple Watch"]) phone -- "BLE: auth + key agreement" --> soc phone -- "UWB: secure ranging" --> uwb phone -- "NFC: ECP tap" --> nfc subgraph lock ["Lock · nRF5340 DK or ESP32-S3"] soc["Host SoC
BLE · Matter · reader"] uwb["DW3110
MAC · PHY · STS in firmware"] nfc["ST25R300
NFC reader (nRF only)"] soc --> uwb soc --> nfc end ``` ## 状态 | 功能 | nRF5340 DK | ESP32-S3 | |---|---|---| | Matter 调试 + 密钥预配置到 Wallet | 可用 | 可用 | | BLE 身份验证 + 测距密钥协商 | 可用（通过附加组件的供应商库） | 可用（重新实现） | | 空中测距设置 (M1-M4) | 可用 | 可用 | | 安全 UWB 测距（距离） | 可用 | 可用 | | 基于距离的门控解锁 / 重新上锁 | 可用 | 可用 | | NFC ECP 轻触解锁 | 可用 | 未实现 | 这两个目标平台都已针对真实的 iPhone 完成了端到端测试：在靠近时会播放 Wallet 解锁动画，离开时会重新上锁。版本的发布取决于手动的[硬件验证清单](docs/hardware-validation.md)。 ## 文档 - [`docs/protocol-research.md`](docs/protocol-research.md)：关于 BLE + UWB 靠近解锁协议的逆向工程报告。 - [`docs/protocol-notes.md`](docs/protocol-notes.md)：在真实硬件上观察到的固件时间同步和凭证有效性行为。 - [`docs/troubleshooting.md`](docs/troubleshooting.md)：两个目标平台常见的构建、烧录、解锁和接线问题。 - [`ports/README.md`](ports/README.md)：ESP32-S3 移植版，以及 [`docs/esp32-gotchas.md`](docs/esp32-gotchas.md)，这是一份详细记录了启动过程中遇到的所有隐蔽陷阱的日志，包含故障现象和修复方法。如果您正在构建自己的读卡器，这是这里最有用的资料。 - [`docs/porting-esp32.md`](docs/porting-esp32.md)：关于该移植是如何规划的，以及实际进展如何。 - [`docs/README.md`](docs/README.md)：仓库生成的代码结构图，其中包含位于 [`docs/architecture/`](docs/architecture/) 的各模块 API 参考，以及说明各组件如何协同工作的 [`docs/ARCHITECTURE.md`](docs/ARCHITECTURE.md)。 项目实践：[`CONTRIBUTING.md`](CONTRIBUTING.md) · [`SECURITY.md`](SECURITY.md) · [`CHANGELOG.md`](CHANGELOG.md) · [`docs/RELEASING.md`](docs/RELEASING.md)

底层原理（为什么这很困难，以及它是如何构建的）

### 困难之处 大多数 UWB 项目依赖于交钥匙测距模块，将无线电隐藏在友好的 API 背后。但本项目并非如此。它在没有 UWB 协处理器的裸机 Qorvo DW3110（DWM3000EVB）上运行，因此整个安全测距栈、MAC、PHY 帧以及 STS（加扰时间戳序列）都是在主机 SoC 的固件中实现的，直接基于 [`deps/dw3000`](deps/dw3000) 驱动运行。要让手机信任它测量到的距离，意味着必须正确处理每一个字节。 在 ESP32 上还有第二个难点。参考设计将凭证身份验证和测距密钥派生交给了闭源的供应商库，因此在 Xtensa 架构上，这一层必须重新实现：包括密钥调度、两个安全通道、通信编解码器以及读卡器身份。此外，DS-TWR 响应器必须在一个拥有比 nRF 更慢的 SPI 和更不稳定的回调调度的目标上，在 2 毫秒的时隙内为每一帧做好准备，这本身就是另一场艰难的挑战。 ### 架构 一个分层的栈；每一层都是可选的，并且仅依赖于其下面的一层： - **`modules/woz_port/`**：平台契约 —— `woz_port.h`（八个函数 + 一个 mutex）和 `woz_log.h`。其他所有层都是基于这两个头文件编写的，这正是引擎具有可移植性的原因；参见 [`docs/porting.md`](docs/porting.md)。 - **`modules/woz_uwb/`**：UWB 引擎（`src/`，分为 `driver/ fira/ ccc/ aliro/ facade/ shell/`）：包含 CCC 密钥阶梯、MAC、STS 和 DS-TWR 响应器，直接驱动 `deps/dw3000`。M1-M4 测距设置编解码器位于 `src/aliro/` 中，调用方通过 `facade/woz_uwb_facade.c` 接入。 - **`modules/woz_aliro/`**：Aliro 凭证身份认证读卡器 —— 密钥调度、安全通道、通信编解码器、配置分发 —— 是目标平台之间共享的源码。 - **`modules/woz_aliro_ecp/`**：用于快捷模式（无需 Face ID）轻触的 NFC ECP 发射器。 - **`deps/dw3000/`**：Bruno Randolf 的 DW3000 decadriver (ISC)。 - **`ports/`**：每个目标平台一个目录。`nrf5340dk/` 是针对 Nordic 附加组件的补丁 + 覆盖层；`esp32/` 原封不动地编译上述模块，添加了一个 ESP-IDF DW3000 后端，并提供了自己的读卡器栈以替代 Nordic 附加组件。 在 nRF 上，Nordic 附加组件掌管着 BLE 和 Matter，并向引擎提供明文的测距密钥；而在 ESP32 上，移植版自己的读卡器会派生出该密钥，并在相同的接入点将其传递过去。集成到获取的附加组件上是分层的，并且从不进行原地编辑：补丁位于 `ports/nrf5340dk/patches/`，配置位于 `ports/nrf5340dk/overlays/`，模块位于 `modules/` + `deps/`。

## 许可证 本项目自有的代码（`modules/woz_uwb/`、`ports/`、除下文注明外的 `modules/woz_aliro_ecp/`、构建脚本、文档）采用 ISC 许可证；参见 [`LICENSE`](LICENSE)。整个代码树是混合许可证的，并非全部都是 ISC： - [`deps/dw3000/`](deps/dw3000) 是基于 `LicenseRef-QORVO-2` 许可的 Qorvo/Decawave 驱动程序（仅可用于 Qorvo IC，不可进行逆向工程）。 - `modules/woz_aliro_ecp/src/nfc_prop_ecp.cpp` 基于 `LicenseRef-Nordic-5-Clause` 许可（归 Nordic Semiconductor 所有）。 每个文件上的 `SPDX-License-Identifier` 头文件是真实的凭据。由于这些供应商条款，本仓库整体上是“源码可用”的，而不是 OSI 意义上的开源。

_{独立的个人项目。不隶属于任何供应商或标准机构，也未获得其认可。
按“原样”提供，不提供任何保证。请勿依赖它来保护任何有价值的物品。}

标签：Aliro, NFC, nRF5340, UWB, 客户端加密, 嵌入式固件, 智能门锁, 物联网