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

欢迎大家加入鸿蒙PC社区

项目信息

项目名称	tiny-AES-c
适配前地址	https://github.com/kokke/tiny-AES-c
适配地址 AtomGit	https://atomgit.com/oh-tpc/aes
开源协议	上游 Unlicense；本仓库 HPK/脚本等 MIT（见 LICENSE）
源码版本	1.0.0（tag v1.0.0）
编译平台	macOS ARM64 交叉编译（示例）
测试平台	鸿蒙 PC 6.0
依赖项	无（仅 OHOS SDK、cmake、make 等 lycium 基础环境）

说明：文档文件名含历史命名 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/ 下标准布局：

内容	路径（相对上述前缀）
静态库	lib/libtiny-aes.a
头文件	include/aes.h
测试可执行文件	bin/tiny_aes_test

应用集成时：-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"，标识该 JSON 为 HNP 打包配置。
name	组件/包对外名称，本库为 "tiny-AES-c"，与上游库名一致，便于在工具链或仓库中识别。
version	与 HPKBUILD 中 pkgver（及上游 tag v1.0.0）保持一致；升级源码版本时需同步修改，避免与 README.OpenSource、产物版本脱节。
install	安装规则对象。本库为 {} 表示使用默认/目录布局（lib/、include/、bin/ 已由 package() 放好）；若后续需按平台规范声明拷贝路径、权限等，可在此扩展（以 hnpcli 与官方文档为准）。

当前文件内容示例：

{
    "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. 六类产物清单（对照社区规范）

文件	说明
HPKBUILD	下载、prepare、build、package、archive、cleanbuild
HPKCHECK	openharmonycheck + CTest
README_zh.md	中文适配与使用说明
README.OpenSource	开源信息 JSON（上游 + 本仓 MIT 说明）
SHA512SUM	源码包校验（可选但建议）
.gitignore	忽略源码包、构建目录、日志等

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

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

9. 常见问题速查

现象	处理
wget 下载 GitHub archive/refs/tags 失败	已改用 codeload 的 source URL。
archive 阶段 cp ../hnp.json 失败	已改为 cp "${PWD}/hnp.json"（在库目录下执行）。
pack: command not found	armeabi-v7a 未设置 HNP_TOOL 时，对 hnpcli 做存在性判断，缺失则跳过 pack。
CRLF 相关语法/编译错误	prepare 中对 aes.c/aes.h/test.c 统一去 \\r。

HPKBUILD 详解

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

元变量与下载相关

变量 / 选项	本库取值	说明
pkgname	AES	与 thirdparty/ 下目录名必须一致，./build.sh 才能找到该库；同时决定安装路径 $LYCIUM_ROOT/usr/AES/$ARCH/。
pkgver	1.0.0	上游 v1.0.0，与 builddir / packagename、hnp.json 的 version 建议保持一致。
pkgrel	0	适配脚本自身的发布修订号，与上游版本独立。
pkgdesc / url	见脚本	描述与主页，便于维护与文档生成。
archs	armeabi-v7a arm64-v8a	每个元素触发一轮完整构建；路径中 $ARCH 即当前架构名。
license	Unlicense	指上游 tiny-AES-c 许可证；本仓库另有 MIT 的 LICENSE 覆盖 HPK 等文件。
depends / makedepends	空	无其它 HPK 依赖；构建机需自备 cmake、make、OHOS SDK（由 lycium 环境检查）。
source	codeload.github.com/.../tar.gz/v${pkgver}	build_hpk.sh 用 wget 下载；codeload 在 macOS 上较 github.com/.../archive/refs/tags/... 稳定。
downloadpackage / autounpack	true	自动下载 packagename 并解压；若为 false 需自管源码。
buildtools	cmake	走 CMake 分支：build_hpk.sh 会组装 cmakedependpath，向 build "$@" 传入 toolchain、CMAKE_INSTALL_PREFIX、DOHOS_ARCH 等。
builddir	tiny-AES-c-${pkgver}	解压后源码根目录名；prepare/build/package 均 cd "$builddir"。
packagename	${builddir}.tar.gz	磁盘上的源码压缩包文件名，与 SHA512SUM 中第二列一致。

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

变量	来源	用途
OHOS_SDK	用户环境	cmake、hnpcli 路径前缀。
ARCH	build_hpk.sh 遍历 archs	构建目录 $ARCH-build、安装路径 usr/AES/$ARCH/。
LYCIUM_ROOT	lycium/build.sh	一般为 lycium 根目录；usr/、output/ 均相对此根。
buildlog	build_hpk.sh 每架构设置	形如 AES-1.0.0-$ARCH-lycium_build.log；build() 将 cmake/make 输出追加进去。
MAKE	lycium/build.sh	通常为 make -j8；build() 使用 $MAKE -C "$ARCH-build"。

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=AES
pkgver=1.0.0
source="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>&1
logfile=${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()

步骤	行为
进入构建目录	cd "${builddir}/${ARCH}-build"，必须与 HPKBUILD 中 -B"$ARCH-build" 一致，即 tiny-AES-c-1.0.0/arm64-v8a-build 这类路径。
记录时间	echo "start test times: $(date)" >> "${logfile}"
执行测试	ctest --timeout 40000 >> "${logfile}" 2>&1，跑 HPKBUILD 里 add_test 注册的 tiny_aes_upstream_tests（即 tiny_aes_test）。
失败处理	若 res != 0，mkdir -p "${LYCIUM_FAULT_PATH}/AES"，存在则复制 Testing/Temporary/LastTest.log 便于定位。
收尾	cd "$OLDPWD"，写入结束时间，return $res

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

HPKCHECK 全文对照

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

checkprepare() {
    return 0
}

openharmonycheck() {
    res=0
    cd "${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}/"
    fi
    cd "$OLDPWD"
    echo "end test times: $(date)" >> "${logfile}" 2>&1
    return $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/bin
ls -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 AES128

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

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