鸿蒙 PC tiny-AES-c 三方库适配实践

项目信息

说明：文档文件名含历史命名 xmpp_sasl_plain，实际适配库为 tiny-AES-c（包名 AES）。

概述

tiny-AES-c 是 kokke 维护的轻量级 AES-128 实现，支持 ECB / CBC / CTR 三种模式，接口为纯 C（aes.h / aes.c），无外部库依赖，适合嵌入式与 OpenHarmony 交叉编译。

本适配在 lycium 体系下提供 HPKBUILD / HPKCHECK、SHA512SUM、README_zh.md、README.OpenSource 等标准产物；在 prepare 中重写 CMakeLists.txt，修正上游错误的头文件搜索路径，并编出静态库 **libtiny-aes.a**、上游自测程序 **tiny_aes_test**，通过 CTest 与设备端运行验证算法正确性。

适配过程

1. 搭建 lycium 环境

参考社区指引搭建工程，例如：

• https://gitcode.com/OpenHarmonyPCDeveloper/lycium_plusplus

需满足：

• 已安装 OpenHarmony SDK，并设置环境变量 **OHOS_SDK**（指向 SDK 根目录，内含 native/build-tools/cmake、native/build/cmake/ohos.toolchain.cmake 等）。
• 在 lycium_plusplus/lycium 目录执行构建；三方库位于 **lycium_plusplus/thirdparty/AES**（或你本机对应路径），目录名需与 HPKBUILD 中 pkgname=AES 一致。

可选：将 lycium/script/build_hpk.sh、envset.sh 以符号链接方式放到 thirdparty/AES（由 ./build.sh AES 流程自动处理）。

2. 源码获取与校验

• HPKBUILD 中 source 使用 codeload 地址，避免在 macOS 上 wget 拉取 github.com/.../archive/refs/tags/... 失败：

  https://codeload.github.com/kokke/tiny-AES-c/tar.gz/v${pkgver}

• **packagename：tiny-AES-c-${pkgver}.tar.gz；builddir**：tiny-AES-c-${pkgver}。

• 同目录放置 **SHA512SUM**，与上述 tarball 一致，便于 build_hpk.sh 自动校验。

3. prepare()：行尾与 CMake

进入解压后的 $builddir 后：

1. 对 aes.c、aes.h、test.c 做 **sed 's/\r$//'**，避免 CRLF 导致 shell/编译异常。
2. **整文件重写 CMakeLists.txt**，原因包括：
• 上游将 target_include_directories 指到不存在的 tiny-AES-c/ 子目录，交叉编译会找不到头文件。
• 需显式生成 静态库 **tiny-aes**（产物名 **libtiny-aes.a**），并链接上游 test.c 为 **tiny_aes_test**。
• 开启 enable_testing()，add_test 注册 **tiny_aes_upstream_tests**，供 HPKCHECK 中 ctest 调用。

4. build()：CMake + OHOS 架构

• 在 $builddir 下执行 **cmake "$@" -B"$ARCH-build" -S.**，其中 "$@" 由 build_hpk.sh 注入 -DCMAKE_TOOLCHAIN_FILE=.../ohos.toolchain.cmake、-DOHOS_ARCH=$ARCH、-DCMAKE_INSTALL_PREFIX=... 等。
• $MAKE -C "$ARCH-build" 完成编译；日志写入 **$buildlog**（由 lycium 设置）。
• archs 配置 armeabi-v7a、arm64-v8a 时，会对每个架构各执行一轮 prepare → build → package → archive（若定义）。

5. package()：安装布局

将产物拷贝到 $LYCIUM_ROOT/usr/AES/$ARCH/ 下标准布局：

应用集成时：**-I.../include、-L.../lib、-ltiny-aes**。

6. archive()（可选）：打包与 HNP

若 HPKBUILD 中定义了 **archive()**（本仓库已定义）：

1. 将 thirdparty/AES/hnp.json 复制到 **$LYCIUM_ROOT/usr/AES/$ARCH/**（使用 **${PWD}/hnp.json**，勿用错误的 **../hnp.json**）。
2. 在 usr/AES/$ARCH 内打 tar.gz 到 **$LYCIUM_ROOT/output/$ARCH/**。
3. 若存在可执行的 hnpcli（$HNP_TOOL 或 **$OHOS_SDK/toolchains/hnpcli**），再执行 pack；armeabi-v7a 场景下若未导出 **HNP_TOOL**，脚本会跳过 pack 并写日志，避免整库编译失败。

鸿蒙 PC 验证用的目录压缩包，也可在产物目录下手动执行（示例）：

tar -zcvf arm64-v8a.tar.gz arm64-v8a

6.1 hnp.json（HNP 打包配置）

本库在 thirdparty/AES/hnp.json 中提供 HNP（HarmonyOS 包格式相关） 的配置描述，与 HPKBUILD 里的 archive() 配合使用：在 package() 完成后，**archive()** 会先把 hnp.json 复制到 $LYCIUM_ROOT/usr/AES/$ARCH/ 根目录，再对该目录打 **tar.gz**；若本机存在可执行的 **hnpcli**，还会执行 **hnpcli pack -i <安装目录> -o <output>**，生成平台所需的 HNP 侧产物。

当前文件内容示例：

{"type": "hnp-config","name": "tiny-AES-c","version": "1.0.0","install": {}}

注意：

• hnp.json 必须与 HPKBUILD 同目录；**archive()** 内应使用 "${PWD}/hnp.json" 复制，避免相对路径写成 ../hnp.json 导致找不到文件。
• 仅交叉编译出 lib/include/bin 而不跑 archive() 时，可以不关心 **hnp.json**；一旦需要 HNP 打包或提交带 hnp.json 的产物目录，请保证 version、name 与发布说明一致。

7. HPKCHECK 与设备测试

HPKCHECK 的作用、**logfile** 路径、**openharmonycheck** 逐步说明及全文对照，见下文 「HPKCHECK 详解」。在鸿蒙 PC 上也可直接运行打包产物中的 **bin/tiny_aes_test**（输出见 「测试验证」）。

8. 六类产物清单（对照社区规范）

可选：**AES_oh_pkg.patch、hnp.json**（说明见上文 6.1 节）、根目录 LICENSE（MIT） 等按仓库策略维护。

HPKBUILD / HPKCHECK 的变量表、**build_hpk.sh** 调用顺序、各函数逐步说明与脚本对照，见 「常见问题速查」 之后的 「HPKBUILD 详解」、「HPKCHECK 详解」。

9. 常见问题速查

HPKBUILD 详解

HPKBUILD 是 lycium 三方库的构建描述文件，由 lycium/script/build_hpk.shsource 加载。典型调用方式为在 lycium 目录执行 **./build.sh AES**：脚本进入 **thirdparty/AES**，链接 build_hpk.sh 后执行，内部依次 **cleanhpk → 下载/校验/解压 → prepare → build → package →（若存在）archive → check**，并对 archs 中每个架构循环一遍。

元变量与下载相关

lycium 注入的环境变量（与本库相关）

prepare()

1. cd "$builddir"：进入解压后的源码树（builddir 含版本号，路径请加引号）。
2. CRLF 处理：对 aes.c、aes.h、test.c 执行 **sed 's/\r$//'**，避免 Windows 行尾导致编译或 shell 异常。
3. **重写 CMakeLists.txt**（heredoc）：
• add_library(tiny-aes STATIC aes.c) → **libtiny-aes.a**；
• target_include_directories(... PUBLIC ${CMAKE_CURRENT_SOURCE_DIR}) 修正上游错误子目录；
• add_executable(tiny_aes_test test.c) + **target_link_libraries(... tiny-aes)**；
• enable_testing() + add_test(NAME tiny_aes_upstream_tests COMMAND tiny_aes_test) 供 CTest / HPKCHECK；
• install(...) 定义标准安装布局（本库 package() 仍用手动 **cp**，与 install 规则语义一致）。
4. cd "$OLDPWD" 回到库目录。

build()

1. **cd "$builddir"**。
2. ${OHOS_SDK}/native/build-tools/cmake/bin/cmake "$@" -B"$ARCH-build" -S.
• "$@" 含 -DCMAKE_TOOLCHAIN_FILE=.../ohos.toolchain.cmake、-DOHOS_ARCH=$ARCH、-DCMAKE_INSTALL_PREFIX=$LYCIUM_ROOT/usr/AES/$ARCH/ 等（由 build_hpk.sh 生成）。
• 构建树目录为 **tiny-AES-c-1.0.0/$ARCH-build**（例如 **arm64-v8a-build**）。
3. 若 cmake 失败则 **return**，否则 **$MAKE -C "$ARCH-build"**；标准输出与错误均追加到 **"$buildlog"**。
4. cd "$OLDPWD" 并返回 make 的退出码。

package()

在 $builddir 下创建 $LYCIUM_ROOT/usr/AES/$ARCH/ 下的 **lib、include、bin**，并拷贝：

• $ARCH-build/libtiny-aes.a → lib/
• aes.h → include/
• 若存在 $ARCH-build/tiny_aes_test → bin/

本库未使用 **cmake --install**，便于与固定目录结构及 archive() 一致。

archive()

1. **mkdir -p "${LYCIUM_ROOT}/output/$ARCH"**。
2. 若存在 "${PWD}/hnp.json"（PWD 为 **thirdparty/AES**），复制到 **${LYCIUM_ROOT}/usr/AES/$ARCH/**。
3. pushd 到 **usr/AES/$ARCH**，将目录内全部文件打成 **${LYCIUM_ROOT}/output/$ARCH/${pkgname}_${pkgver}.tar.gz**（即 **AES_1.0.0.tar.gz**）。
4. **hnpcli**：优先 **$HNP_TOOL**，否则 **$OHOS_SDK/toolchains/hnpcli**；可执行则 **pack -i .../usr/AES/$ARCH -o .../output/$ARCH/**，否则仅写日志、不失败。

check() 与 cleanbuild()

• **check()**：仅打印提示，说明测试需在 OpenHarmony 设备/模拟器上执行（真正自动化入口在 HPKCHECK + **lycium/test.sh**）。
• **cleanbuild()**：删除 "${PWD}/$builddir" 与 **"${PWD}/$packagename"**，供 build_hpk.sh 每次构建前清理。

HPKBUILD 关键片段索引（便于对照仓库）

pkgname=AESpkgver=1.0.0source="https://codeload.github.com/kokke/tiny-AES-c/tar.gz/v${pkgver}"buildtools="cmake"builddir="tiny-AES-c-${pkgver}"packagename="${builddir}.tar.gz"# prepare / build / archive / package / check / cleanbuild 见仓库原文

HPKCHECK 详解

HPKCHECK 在 设备或已与编译机路径对齐的环境 中执行，用于跑交叉编译产物的测试（本库为 CTest）。由 lycium/test.sh 调度；需已设置 **LYCIUM_THIRDPARTY_ROOT**（一般为 lycium/../thirdparty）、OHOS_SDK_VER、LYCIUM_FAULT_PATH 等（以 test.sh 为准）。

文件头部与日志路径

source HPKBUILD > /dev/null 2>&1logfile=${LYCIUM_THIRDPARTY_ROOT}/${pkgname}/${pkgname}_${ARCH}_${OHOS_SDK_VER}_test.log

• **source HPKBUILD**：静默加载，获得 pkgname、builddir 等与构建一致的变量。
• **logfile**：例如 thirdparty/AES/AES_arm64-v8a_OpenHarmony_4.0.8.1_test.log（OHOS_SDK_VER 以你环境为准）。所有测试输出应追加到此文件，便于 CI 收集。

checkprepare()

本库为空实现 **return 0**。若将来需在跑测试前挂载目录、推送数据文件等，可写在此函数中。

openharmonycheck()

注意：tiny_aes_test 为 OHOS 架构二进制，不能在 macOS/Linux 宿主机上直接执行；须在 鸿蒙设备 / 模拟器 上 cd 到上述 **$ARCH-build**（或推送等价目录）后再执行 ctest 或 **./tiny_aes_test**。宿主机上若误跑 **HPKCHECK**，会因架构不符或找不到设备侧动态链接环境而失败。

HPKCHECK 全文对照

source HPKBUILD > /dev/null 2>&1logfile=${LYCIUM_THIRDPARTY_ROOT}/${pkgname}/${pkgname}_${ARCH}_${OHOS_SDK_VER}_test.logcheckprepare() {return 0}openharmonycheck() {    res=0cd"${builddir}/${ARCH}-build"echo"start test times: $(date)" >> "${logfile}" 2>&1    ctest --timeout 40000 >> "${logfile}" 2>&1    res=$?if [ $res -ne 0 ]; then        mkdir -p "${LYCIUM_FAULT_PATH}/${pkgname}"        [ -f Testing/Temporary/LastTest.log ] && cp Testing/Temporary/LastTest.log "${LYCIUM_FAULT_PATH}/${pkgname}/"ficd"$OLDPWD"echo"end test times: $(date)" >> "${logfile}" 2>&1return$res}

压缩

在 lycium_plusplus/lycium 下完成 ./build.sh AES 后，产物位于 **lycium/usr/AES/<ARCH>/**（或由 archive 输出到 **lycium/output/<ARCH>/**）。若需自行打测试包，可 cd 到包含 arm64-v8a 目录 的父目录后执行：

tar -zcvf arm64-v8a.tar.gz arm64-v8a

即可推送到鸿蒙 PC 上做运行验证。

测试验证

解压到鸿蒙 PC 桌面（路径示例）：

tar -zxf arm64-v8a.tar.gz

进入对应目录：

cd arm64-v8a/binls -l

在鸿蒙 PC 上若策略要求，可对二进制签名（示例）：

binary-sign-tool sign -inFile tiny_aes_test -outFile tiny_aes_test -selfSign "1"

按需添加执行权限：

chmod +x tiny_aes_test

执行测试：

./tiny_aes_test

预期与上游 test.c 一致，例如：

Testing AES128CBC encrypt: SUCCESS!CBC decrypt: SUCCESS!CTR encrypt: SUCCESS!CTR decrypt: SUCCESS!ECB decrypt: SUCCESS!ECB encrypt: SUCCESS!ECB encrypt verbose:...

欢迎大家一起共建鸿蒙 PC 生态