RIOT OS 集成 Microchip CryptoAuth 库ATECC608A 安全芯片配置、多设备扩展与 PSA Crypto 后端实战指南【免费下载链接】RIOTRIOT - The friendly OS for IoT项目地址: https://gitcode.com/GitHub_Trending/riot/RIOT导读本文围绕 RIOT 操作系统中cryptoauthlib软件包展开系统讲解如何将 Microchip CryptoAuth 系列安全芯片ATECC508A / ATECC608A接入 RIOT 应用从 Makefile 引入、Shell 辅助命令的使用、I2C 通信 HAL 的实现细节到多设备参数定制、将 cryptoauthlib 作为 PSA Crypto 安全元素后端以及关键区config / data / otp zone锁定的注意事项。读完本文你将掌握在 RIOT 中初始化、配置、锁定并调用 CryptoAuth 设备完成 SHA-256、ECDSA 签名、AES 加密等硬件加速密码学操作的完整流程。1. 软件包概览与引入方式cryptoauthlib是 RIOT 中以pkg形式引入的第三方软件包对应 Microchip 官方 CryptoAuth 库用于驱动 ATECC508A、ATECC608A 等通过 I2C 连接的硬件安全芯片。RIOT 侧对该包的封装位于 pkg/cryptoauthlib包含以下关键组成文件/目录作用include/atca_params.h设备默认配置参数I2C 总线、地址、设备类型等include/atca.h默认 I2C 地址与设备描述符contrib/atca.c面向 RIOT 的 HAL 层实现I2C 收发、延时、唤醒psa_atca_driver/psa_atca_se_driver.cPSA Crypto 安全元素驱动胶水代码sys/shell/cmds/cryptoauthlib.cRIOT Shell 辅助命令在应用的 Makefile 中通过USEPKG引入USEPKG cryptoauthlib根据 pkg/cryptoauthlib/Makefile.dep引入该包会自动拉取以下依赖ztimer与ztimer_usec供 HAL 层atca_delay_us/atca_delay_ms使用periph_i2cFEATURES_REQUIRED设备通信依赖 I2C 外设periph_i2c_reconfigureFEATURES_OPTIONAL用于唤醒时临时将 SDA 引脚切换为 GPIO 输出以产生唤醒脉冲auto_init_securityDEFAULT_MODULE设备在启动阶段自动初始化cryptoauthlib_contrib编译 contrib/atca.c 提供的 HAL 实现。构建时Makefile 通过 CMake 交叉编译 Microchip 上游源码并统一以-DATCA_HAL_I2C启用 I2C 模式最终产出libcryptoauth.a归档加入链接。2. Shell 辅助命令配置与锁定设备为了便于设备配置RIOT 在 Shell 中提供了一组atca命令。只要应用同时引入了cryptoauthlib与 shell例如examples/basic/default该命令即可用。完整命令清单与语义如下对应 sys/shell/cmds/cryptoauthlib.c 中_atca的实现命令功能备注atca show_dev列出可用设备及 ID显示当前选中设备、设备类型与 I2C 地址atca set_dev number切换到指定设备默认 ID 0多设备场景下切换操作对象atca read读取并格式化打印 config zone逐项解读设备信息、Slot 配置、锁定状态等atca read_bin读取 config zone 并按二进制原始格式输出便于对照数据手册逐字节核对atca write写入配置到 config zone写入前会自动备份当前配置atca restore恢复 config zone 到上次备份状态依赖write前保存的config_backupatca lock_c永久锁定config zone不可撤销atca lock_d永久锁定data zone不可撤销atca check_lc检查 config zone 是否已锁定调用calib_is_lockedatca check_ld检查 data zone 是否已锁定调用calib_is_lockedatca read输出非常详尽从源码看其解析逻辑会打印序列号、版本号、AES/I2C 使能状态、I2C 地址或单线 GPIO 模式、Counter Match/OTP 模式、ChipMode看门狗 1.3s/10s、TTL 电平、时钟分频等、16 个 Slot 的 Config 与 Key Config十六进制 二进制、锁定状态X表示已锁定-表示未锁定、Chip Options、X509 格式限制、SecureBoot 配置等。atca write使用的默认配置模板位于 pkg/cryptoauthlib/include/atecc608a_config.h实际项目应基于自身密钥管理策略替换。重要警告锁定操作是永久性的无法撤销。部分库函数只有在设备的 data、config 与 otp zone 均被锁定后才能真正启用详见下文实现状态一节。在确认配置完全正确之前不要执行lock_c/lock_d。更详细的行为请参考芯片数据手册。3. 轮询模式与无轮询模式No poll modeCryptoAuth 设备处理一条命令需要一定执行时间。默认情况下RIOT 侧的通信流程是发送命令后轮询设备状态一旦就绪便立即读取响应从而获得更快的响应速度。如果需要简化时序、减少总线占用可以通过 CFLAGS 启用ATCA_NO_POLLCFLAGS -DATCA_NO_POLL启用后驱动不再轮询而是直接等待命令的最大执行时间再读取响应。这在实时性要求不高、希望代码路径更简单的场景下是合理取舍。4. HAL 层实现与当前实现状态RIOT 将 Microchip 官方库所需的 HAL 函数实现在 pkg/cryptoauthlib/contrib/atca.c 中核心要点如下延时函数atca_delay_us、atca_delay_10us、atca_delay_ms均基于ztimer_sleep(ZTIMER_USEC, ...)实现。I2C 收发hal_i2c_send/hal_i2c_receive在每次读写前后分别i2c_acquire/i2c_release总线读操作按cfg-rx_retries默认 20 次重试设备地址统一右移 1 位8 位地址转 7 位。唤醒机制hal_i2c_wake有两种实现——若板卡支持periph_i2c_reconfigure则将 SDA 引脚临时切换为 GPIO 输出拉低 100µst_WOL产生唤醒脉冲后重新初始化 I2C否则通过向ATCA_WAKE_ADDR写字节0x00唤醒此方式要求 I2C 时钟最高 100kHz。唤醒后读取 4 字节状态并用hal_check_wake校验。电源管理hal_i2c_idle/hal_i2c_sleep分别向0x02/0x01字地址写控制字节。当前实现状态与文档一致可由源码确认未实现hal_i2c_release源码中仅返回ATCA_SUCCESS因为每次读写都已独立 acquire/release 总线、hal_i2c_discover_devices、hal_i2c_discover_buses返回ATCA_UNIMPLEMENTED见 contrib/atca.c。hal_i2c_post_init为空实现直接返回成功。该实现已在 ATECC508A 与 ATECC608A 设备上做过部分测试。5. 测试内部单元测试与 SHA-256 对比测试cryptoauthlib附带两方面的测试1库自带单元测试。RIOT 测试目录中的tests/pkg/cryptoauthlib_internal-tests会运行官方库的部分单元测试在 main.c 中通过atca_test_config_set_ifacecfg将接口配置指向atca_params[0]再根据ATCA_DEVTYPE选择ecc508/ecc608并运行basic测试。该测试的 Makefile 默认板卡为nucleo-f767zi通过USEMODULE cryptoauthlib_test引入全部子测试模块jwt、tng、atcacert、api_atcab、api_calib、api_crypto、vectors 等见 pkg/cryptoauthlib/Makefile.dep。需要特别说明的是部分官方测试仅在 config、data 和/或 otp zone 已锁定时才能运行个别测试会自动锁定 zone。由于锁定永久不可逆RIOT 有意跳过了这些用例——这一点在运行测试前必须知晓避免在未配置好的设备上被测试程序意外锁死。2SHA-256 软硬件对比测试。还存在一项用于对比 RIOT 软件实现与 CryptoAuth 硬件实现计算 SHA-256 哈希耗时的测试用于量化硬件加速的实际收益。6. 单设备默认参数与多设备扩展ATECCX08A 设备的参数集中在 pkg/cryptoauthlib/include/atca_params.h 中配置。RIOT 默认定义了一台设备#define ATCA_PARAM_I2C (I2C_DEV(0)) #define ATCA_PARAM_ADDR (ATCA_I2C_ADDR) /* 默认 0xC0见 atca.h */ #define ATCA_RX_RETRIES (20) #define ATCA_DEVTYPE (ATECC608A) #define ATCA_PARAMS { .iface_type ATCA_I2C_IFACE, \ .devtype ATCA_DEVTYPE, \ .atcai2c.address ATCA_PARAM_ADDR, \ .atcai2c.bus ATCA_PARAM_I2C, \ .atcai2c.baud -1, \ .wake_delay 1500, \ .rx_retries ATCA_RX_RETRIES }其中ATCAIfaceCfg中的bus字段在 RIOT 中存放的是I2C_DEV(n)baud字段被置为-1RIOT 无运行时改波特率 API实际速率由板级 I2C 配置决定wake_delay 1500单位是微秒。atca_params数组由该宏展开ATCA_NUMOF自动等于数组元素个数设备指针统一存放于atca_devs_ptr[]由 sys/auto_init/security/auto_init_atca.c 填充并随auto_init完成初始化。当需要挂接多台设备时有两种接线方案不同 I2C 地址的设备共挂一条总线或相同地址的设备分挂不同总线。官方推荐的做法是在应用目录下新建custom_atca_params.h可参考 examples/advanced/psa_crypto/custom_atca_params.h为每台设备定义独立的ATCA_PARAM_*宏并展开进ATCA_PARAMS#define ATCA_PARAM_I2C_DEV0 (I2C_DEV(0)) #define ATCA_PARAM_ADDR_DEV0 (ATCA_I2C_ADDR_DEV0) #define ATCA_RX_RETRIES_DEV0 (20) #define ATCA_DEVTYPE_DEV0 (ATECC608A) #define ATCA_PARAM_I2C_DEV1 (I2C_DEV(0)) #define ATCA_PARAM_ADDR_DEV1 (ATCA_I2C_ADDR_DEV1) #define ATCA_RX_RETRIES_DEV1 (20) #define ATCA_DEVTYPE_DEV1 (ATECC608A) #define ATCA_PARAMS { .iface_type ATCA_I2C_IFACE, \ .devtype ATCA_DEVTYPE_DEV0, \ .atcai2c.address ATCA_PARAM_ADDR_DEV0, \ .atcai2c.bus ATCA_PARAM_I2C_DEV0, \ .atcai2c.baud -1, \ .wake_delay 1500, \ .rx_retries ATCA_RX_RETRIES }, \ { .iface_type ATCA_I2C_IFACE, \ .devtype ATCA_DEVTYPE_DEV1, \ .atcai2c.address ATCA_PARAM_ADDR_DEV1, \ .atcai2c.bus ATCA_PARAM_I2C_DEV1, \ .atcai2c.baud -1, \ .wake_delay 1500, \ .rx_retries ATCA_RX_RETRIES }随后在 Makefile 中让自定义头文件参与编译CFLAGS -DCUSTOM_ATCA_PARAMS INCLUDES -I$(APPDIR)atca_params.h检测到CUSTOM_ATCA_PARAMS宏后会优先包含应用目录下的自定义文件include/atca_params.h之后auto_init会逐一初始化全部设备。多设备场景下应使用 cryptoauth 库的calib-API它允许显式传入设备句柄通过atca_devs_ptr数组按索引取用设备#include atca_params.h ATCADevice dev atca_devs_ptr[0]; calib_sha_start(dev);7. 将 cryptoauthlib 作为 PSA Crypto 后端RIOT 的 PSA Crypto 子系统sys/psa_crypto/doc.md支持以安全元素Secure ElementSE方式接入外部密码硬件。cryptoauthlib 通过 psa_atca_driver/psa_atca_se_driver.c 提供 PSA 驱动胶水层将 PSA 的密钥管理与密码运算调用翻译为 cryptoauth 的calib_*调用。7.1 设备参数中增加 location用作 PSA 后端时每个设备需要在ATCA_PARAMS中额外携带一个atca_loc字段类型为psa_key_location_t。首台设备使用PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT其余设备必须在PSA_KEY_LOCATION_SE_MIN与PSA_KEY_LOCATION_SE_MAX之间取值这两个宏定义于 sys/include/psa_crypto/psa/key/lifetime.h具体数值以该头文件为准#define PSA_ATCA_LOCATION (PSA_KEY_LOCATION_PRIMARY_SECURE_ELEMENT) #define ATCA_PARAM_I2C (I2C_DEV(0)) #define ATCA_PARAM_ADDR (ATCA_I2C_ADDR) #define ATCA_DEVTYPE (ATECC608A) #define ATCA_RX_RETRIES (20) #define ATCA_PARAMS { .atca_loc PSA_ATCA_LOCATION,\ .cfg {\ .iface_type ATCA_I2C_IFACE, \ .devtype ATCA_DEVTYPE, \ .atcai2c.address ATCA_PARAM_ADDR, \ .atcai2c.bus ATCA_PARAM_I2C, \ .atcai2c.baud -1, \ .wake_delay 1500, \ .rx_retries ATCA_RX_RETRIES } \ }多设备时照搬多设备扩展一节的做法为每个设备定义独立的 location 并加入ATCA_PARAMS。初始化阶段sys/auto_init/security/auto_init_atca.c 会调用psa_register_secure_element将每个设备与其 location、atca_methods驱动及槽位配置列表注册进 PSA。7.2 支持的密码学操作从 psa_atca_se_driver.c 的ALG_IS_SUPPORTED与驱动方法表可以看出当前后端支持非对称ECDSA SHA-256 签名/验签calib_sign/calib_verify_stored、ECC P-256 密钥生成calib_genkey与公钥导出calib_get_pubkey对称仅 ATECC608 支持 AES提供 AES-CBCatcab_aes_cbc_encrypt_block与 AES-ECB 加密calib_aes_encrypt密钥固定为 128 位、块大小 16 字节MACHMAC-SHA256calib_sha_hmac密钥导入ECC 公钥写入calib_write_pubkey、AES/HMAC 密钥写入 data zone 槽位calib_write_bytes_zone写入缓冲固定 32 字节。驱动还实现了 ATCA 状态码到 PSA 错误码的映射如ATCA_NOT_LOCKED映射为PSA_ERROR_BAD_STATE、通信类错误映射为PSA_ERROR_COMMUNICATION_FAILURE并在 sys/shell/cmds/cryptoauthlib.c 中提供了atca_status_to_humanly_readable的字符串化辅助定义于 PSA 驱动文件内供调试打印使用。8. 槽位配置Slot Configurations与 PSA 对接ATECCX08A 设备拥有独立的密钥管理通过在 config 与 data zone 中设置标志位完成槽位策略配置配置组合非常多无法全部映射到 PSA 模型。因此文档与实现都假定用户熟悉数据手册并已将设备配置为可用状态。对接 PSA 有几个硬性前提PSA 目前无法使用设备上预存的密钥因此所有密钥槽位必须在锁定 config/data zone 之后仍然可写ECC 槽位配置必须至少允许使用gen_key命令AES 与 HMAC 密钥槽位必须允许明文写入clear write。安全警告AES / HMAC 密钥允许明文写入意味着密钥材料可被篡改可能引入安全风险请务必结合威胁模型评估。为了让 PSA 知道每个槽位允许存放什么类型的密钥需要为每个槽位初始化一个psa_atca_slot_config_t结构该结构定义于 include/atca.h字段含义见注释typedef struct { psa_key_type_t key_type_allowed; // Declare the key type allowed in this slot uint8_t key_persistent; // Ignore for now, PSA does not yet support persistent keys uint8_t slot_occupied; // Set to 0, PSA will set this to one after writing a key } psa_atca_slot_config_t;在custom_atca_params.h中按 16 个槽位声明每台设备的配置列表以下仅为示例请按实际需求修改#define ATCA_SLOTS_DEV0 { { PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1), 0, 0 }, \ { PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1), 0, 0 }, \ { PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1), 0, 0 }, \ { PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1), 0, 0 }, \ { PSA_KEY_TYPE_AES, 0, 0 }, \ { PSA_KEY_TYPE_HMAC, 0, 0 }, \ { PSA_KEY_TYPE_ECC_KEY_PAIR(PSA_ECC_FAMILY_SECP_R1), 0, 0 }, \ { 0, 1, 1 }, \ { 0, 0, 0 }, \ { PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_SECP_R1), 0, 0 }, \ { PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_SECP_R1), 0, 0 }, \ { PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_SECP_R1), 0, 0 }, \ { PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_SECP_R1), 0, 0 }, \ { PSA_KEY_TYPE_ECC_PUBLIC_KEY(PSA_ECC_FAMILY_SECP_R1), 0, 0 }, \ { 0, 0, 0 }, \ { 0, 0, 0 }} #define ATCA_CONFIG_LIST { ATCA_SLOTS_DEV0 }多个设备时依次定义ATCA_SLOTS_DEV0~ATCA_SLOTS_DEVX并全部加入配置列表#define ATCA_CONFIG_LIST { ATCA_SLOTS_DEV0 }, \ { ATCA_SLOTS_DEV1 }, \ ... \ { ATCA_SLOTS_DEVX }atca_allocate见 psa_atca_se_driver.c在 PSA 分配密钥时遍历该列表找到key_type_allowed匹配且未被持久占用的槽位后分配{ 0, 1, 1 }表示该槽位被标记为持久占用、应被驱动跳过。完整的可运行示例参见 examples/advanced/psa_crypto其中MULTIPLE_SE宏控制单/双 SE 场景双设备时第二台地址示例为0xCClocation 使用PSA_KEY_LOCATION_SE_MIN。9. 故障排查9.1 设备初始化失败如果auto_init阶段设备初始化失败例如 auto_init_atca.c 打印error initializing cryptoauth device优先检查 I2C 总线速度CryptoAuth 设备需要将总线速度设置为I2C_SPEED_NORMAL。请确认板级配置中对应I2C_DEV(n)的速率满足要求同时核对ATCA_PARAM_ADDR是否与设备实际 I2C 地址一致8 位地址默认0xC0见 include/atca.h。9.2 唤醒与通信异常若设备无响应可结合 HAL 层行为定位启用periph_i2c_reconfigure的板卡依赖 SDA 引脚可切换为 GPIO 输出产生唤醒脉冲未启用时唤醒依赖写0x00字节此时 I2C 时钟必须不高于 100kHz。此外ATCA_RX_RETRIES默认 20 次读重试若总线干扰严重可适当增大。9.3 锁定相关操作失败check_lc/check_ld可用于确认当前锁定状态对已锁定的 zone 再次执行lock_c/lock_d会直接报错拒绝。请牢记config 与 data zone 的锁定永久不可逆锁定前务必通过atca read全面核对配置。10. 结语cryptoauthlib软件包为 RIOT 应用提供了开箱即用的 Microchip CryptoAuth 硬件安全能力借助 Shell 命令可以完成设备配置与锁定通过calib-API 可驱动单台或多台 ATECCX08A 设备更进一步可将其注册为 PSA Crypto 的安全元素后端使应用以标准 PSA 接口获得硬件加速的 ECDSA、AES 与 HMAC 能力。正确理解 I2C 参数、zone 锁定语义与槽位配置是安全、可靠地使用这套方案的关键前提。【免费下载链接】RIOTRIOT - The friendly OS for IoT项目地址: https://gitcode.com/GitHub_Trending/riot/RIOT创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考