仓颉运行时安全底座解析:libboundscheck 安全 C 函数库的引入、集成与构建实践
仓颉运行时安全底座解析:libboundscheck 安全 C 函数库的引入、集成与构建实践
导读:本文以仓颉运行时(cangjie_runtime)开源仓库中的 runtime/third_party/README.md 为核心,系统讲解运行时依赖的第三方开源软件 libboundscheck(即 OpenHarmony 社区的
third_party_bounds_checking_function安全 C 函数库):它为何被引入、以何种形态参与运行时构建、在源码中如何被调用,以及跨平台构建时的特殊处理。读完本文,你将掌握仓颉运行时第三方依赖的引入机制、securec.h安全函数族的典型应用场景,并能独立定位与排查该依赖相关的构建与链接问题。
一、libboundscheck 是什么,仓颉运行时为什么需要它
libboundscheck 是 OpenHarmony 社区维护的开源 C 语言安全函数库,仓库名称为 third_party_bounds_checking_function。它提供了一组带边界检查的 _s 后缀安全函数,例如 memcpy_s、memset_s、sprintf_s、snprintf_s、vsprintf_s、strtok_s 等。这类函数在拷贝、格式化、置零等操作前会校验目标缓冲区长度,从而在源头上降低缓冲区溢出、字符串越界写入等内存安全风险。
仓颉运行时本身是一个用 C/C++ 实现的运行时系统,覆盖对象模型、GC(垃圾回收)、线程模型(CJThread)、异常处理、栈回溯、日志等大量模块。这些模块的底层实现离不开字符串拼接、日志格式化、内存搬运等操作,而 runtime/src/Base/ 下的基础组件正是通过 libboundscheck 提供的安全函数来完成这些操作的:
- runtime/src/Base/CString.h 直接
#include "securec.h",runtime/src/Base/CString.cpp 中的构造函数、Append、SubStr、Replace等实现大量使用memcpy_s、sprintf_s、strtok_s、vsprintf_s; - runtime/src/Base/Log.cpp 与 runtime/src/Base/LogFile.cpp 使用
sprintf_s/vsprintf_s完成日志行格式化,保证写入固定长度缓冲区时不会越界; - runtime/src/Base/TimeUtils.cpp 使用
sprintf_s格式化时间戳。
从源码统计看,securec.h 被 runtime 目录下 40 余个源文件直接包含,覆盖 Base、Heap(如 GcThreadPool.cpp、RegionInfo.h、RegionManager.h、IdleBarrier.cpp)、Mutator(如 SafepointPageManager.h)、Signal(如 SignalUtils.cpp、SignalStack.cpp)、UnwindStack(如 MachineFrame.cpp)、Inspector、Sanitizer 以及 CJThread 的 aio 网络栈(domainsock、tcpsock、udpsock、rawsock、netpoll、sock 等)大量文件。可以说,libboundscheck 是仓颉运行时内存安全基础能力的重要支撑。
二、依赖来源与版本管理:OpenHarmony-v6.0-Release
原文档明确了该依赖的代码来源与版本信息:
- 上游开源仓库:OpenHarmony 社区的
third_party_bounds_checking_function; - 固定版本:
OpenHarmony-v6.0-Release标签。
这一版本约束并非仅停留在文档描述中,而是被构建脚本强制执行。在 runtime/config.cmake 中可以看到完整的依赖拉取逻辑:
# Provide secure functions.
set(BOUNDSCHECK ${CMAKE_SOURCE_DIR}/third_party/third_party_bounds_checking_function)
if(NOT EXISTS ${BOUNDSCHECK})
set(REPOSITORY_PATH https://gitcode.com/openharmony/third_party_bounds_checking_function)
message(STATUS "Set boundscheck REPOSITORY_PATH: ${REPOSITORY_PATH}")
execute_process(
COMMAND git clone --branch OpenHarmony-v6.0-Release ${REPOSITORY_PATH} ${BOUNDSCHECK}
)
endif()
关键点解读:
- 克隆目标目录为
runtime/third_party/third_party_bounds_checking_function,与文档描述完全对应; - 使用
git clone --branch OpenHarmony-v6.0-Release固定到指定版本标签,保证不同时间、不同环境下的构建可复现; - 若目录已存在(例如开发者已手动放置源码),则跳过克隆,直接复用本地目录——这为离线构建或镜像同步留出了空间。
三、使用方式:头文件包含 + 链接库(动态库/静态库)
原文档指出,libboundscheck 被仓颉运行时"以包含头文件的方式使用,并通过链接库(动态库或静态库)的方式依赖"。这两条在构建系统中均有明确的落点:
1. 头文件包含(编译期)
runtime/config.cmake 在克隆完成后设置头文件路径并注入全局 include 目录:
set(BOUNDSCHECK_ROOT ${CMAKE_CURRENT_SOURCE_DIR}/third_party/third_party_bounds_checking_function CACHE FILEPATH "" FORCE)
set(BOUNDSCHECK_INCLUDE ${BOUNDSCHECK_ROOT}/include)
...
include_directories(${BOUNDSCHECK_INCLUDE})
随后,runtime/CMakeLists.txt 与 runtime/src/CMakeLists.txt 也分别通过 include_directories(${BOUNDSCHECK_INCLUDE}) 将 securec.h 所在的 include 目录加入编译搜索路径,因此各模块源码只需 #include "securec.h" 即可直接调用安全函数。
2. 链接库(链接期)
在 runtime/CMakeLists.txt 中,boundscheck 被显式加入运行时最终链接的库列表(Windows 与非 Windows 分支均包含):
list(APPEND LINK_LIBS "boundscheck" "Base" "Common" "Concurrency" "Loader" ...)
此外,CJThread 线程模型在各目标平台的构建脚本中同样通过 -lboundscheck 参与链接,见 runtime/build/cmake/toolchain/macos_aarch64.cmake、runtime/build/cmake/toolchain/ios_cangjie.cmake、runtime/build/cmake/toolchain/android_aarch64_cangjie.cmake 以及 runtime/build/cmake/toolchain/windows_x86_64.cmake 等文件中的 -lboundscheck 链接参数。
关于"动态库或静态库"两种形态:构建系统默认将 boundscheck 编译为共享库(见下文第四节),而仓颉运行时在部分平台(如 iOS、macOS、Windows 及 Linux/OHOS 等)会额外聚合生成静态库 cangjie-runtime-static,因此整体依赖形态覆盖动态与静态两种场景,与原文档描述一致。
四、构建集成:CMake 子项目自动构建
原文档说明该依赖"通过 CMake 作为子目标项目引入,编译过程中会自动完成构建并建立依赖关系"。其完整机制分为两步:
步骤一:向第三方目录注入构建配置
在 runtime/config.cmake 中有一行容易被忽略的关键操作:
file(COPY build/cmake/CMakeLists.txt DESTINATION ${BOUNDSCHECK}/)
它把仓颉运行时自带的一份 CMakeLists 配置(runtime/build/cmake/CMakeLists.txt)复制到克隆下来的 boundscheck 目录中,从而用仓颉运行时侧定制的构建脚本接管第三方库的编译,而不是依赖上游仓库自带的构建体系。
步骤二:以子目录方式加入构建
add_subdirectory(third_party/third_party_bounds_checking_function)
add_subdirectory 会触发对注入的 CMakeLists.txt 的解析,自动完成 boundscheck 的编译,并建立与 cangjie-runtime 之间的依赖关系,无需开发者手动干预。
注入的构建配置做了哪些定制
runtime/build/cmake/CMakeLists.txt 的内容值得细读,它体现了跨平台适配的精细处理:
if (WINDOWS_FLAG MATCHES 1)
# MSVCRT already provides most of secure functions,
# so only files listed below need to be compiled from boundscheck library,
# to avoid "multiple definition" error.
list(APPEND SRC_FILE src/memset_s.c src/snprintf_s.c src/vsnprintf_s.c src/secureprintoutput_a.c)
else()
aux_source_directory(./src SRC_FILE)
endif()
...
# Build shared library.
add_library(boundscheck SHARED ${SRC_FILE})
要点说明:
- 非 Windows 平台:通过
aux_source_directory(./src SRC_FILE)全量编译 boundscheck 的src目录下所有源文件; - Windows 平台:由于 MSVCRT 运行库本身已经提供了大部分
_s安全函数,若再全量编译会导致与 CRT 符号重复定义(multiple definition)的链接错误,因此只从 boundscheck 编译memset_s.c、snprintf_s.c、vsnprintf_s.c、secureprintoutput_a.c四个补齐缺口; - 该配置还会剥离从上层继承的
-fvisibility=hidden编译选项,并针对 Windows 使用-static与x86_64-w64-mingw32工具链适配; - 产物为共享库目标
boundscheck,随后作为LINK_LIBS的一员被链接进cangjie-runtime。
五、源码级应用:安全函数在运行时中的典型调用
为了让读者对"依赖如何被使用"有具体感知,这里列出几个可直接在仓库中验证的典型场景。
1. 字符串容器 CString
runtime/src/Base/CString.cpp 是使用最密集的模块之一。例如构造与扩容时用 memcpy_s 做带容量校验的拷贝,并检查返回值 EOK:
PRINT_FATAL_IF(memcpy_s(str, capacity, initStr, initLen) != EOK,
"CString::CString memcpy_s failed");
此外还使用了 sprintf_s 做整数格式化、strtok_s 做带上下文的字符串切分(strtok_s(tmp.str, s, &tmpSave))、vsprintf_s 做可变参数格式化。所有调用都伴随返回值检查,失败即走 PRINT_FATAL_IF 崩溃路径,避免带病继续运行。
2. 日志与时间格式化
runtime/src/Base/Log.cpp 与 runtime/src/Base/LogFile.cpp 使用 sprintf_s / vsprintf_s 把日志级别、线程 ID、时间戳等内容格式化进固定大小的栈上缓冲区;runtime/src/Base/TimeUtils.cpp 用 sprintf_s 生成 YYYY-MM-DD HH:MM:SS.mmm 格式的时间字符串。固定缓冲区 + 边界校验的组合,保证了日志路径不会因格式化溢出而破坏内存。
3. 大块内存操作的 2GB 分块封装
一个容易被忽略的细节是 boundscheck 的 SECUREC_MEM_MAX_LEN(2GB)上限约束。runtime/src/Base/MemUtils.h 中的注释明确说明:
// memset_s wrapper for the situation that memset size is greater than SECUREC_MEM_MAX_LEN(2GB).
void MemorySet(uintptr_t dest, size_t destMax, int c, size_t count);
// memcpy_s wrapper for the situation that memcpy size is greater than SECUREC_MEM_MAX_LEN(2GB).
void MemoryCopy(uintptr_t dest, size_t destMax, const uintptr_t src, size_t count);
对应实现 runtime/src/Base/MemUtils.cpp 将超过 SECUREC_MEM_MAX_LEN 的大块操作按 2GB 为单位循环分块,逐段调用 memset_s / memcpy_s,并用 CHECK_E 检查每个分块的返回值。运行时中涉及超大内存搬运/置零的场景(如堆内存管理)正是通过这层封装规避了安全函数自身的长度上限。
六、依赖治理:解耦与符号管理
仓颉运行时对第三方依赖并非"引入即完事",还会从对外发布的角度做解耦治理。一个典型例子是 Demangler 模块:
runtime/src/Demangler/StdString.h 在注释中明确说明,该类型"helps remove the dependency on CString and boundscheck (an indirect dependency) of the cangjie-demangle library that we export to other users"——即通过提供与 CString API 兼容的 std::string 代理类型,使对外发布的 cangjie-demangle 动态库不再间接依赖 CString 与 boundscheck,从而缩小对外库的依赖面。
同时,runtime/src/Demangler/CMakeLists.txt 仅在内部测试目标 demangleTest 的链接中保留 boundscheck(针对 OHOS/Android/Linux 分别追加 hilog_ndk.z、hitrace_ndk.z、-landroid -llog 等平台库),生产库本身不携带该依赖。这体现了"内部依赖、外部隔离"的依赖治理思路。
七、构建验证:如何实际构建包含该依赖的运行时
libboundscheck 的克隆、编译与链接全部内嵌在仓颉运行时构建流程中,开发者无需单独手动编译该库。根据 runtime/build_runtime_zh.md,独立构建运行时使用 build.py,例如:
$ python3 build.py build --target native --build-type release -v 0.0.1
常用参数速览:
--target <value>:构建目标,默认native(Linux/macOS 原生),还支持windows-x86_64、ohos-aarch64、ohos-x86_64等交叉编译目标;-t, --build-type <value>:release、debug、relwithdebinfo(区分大小写),默认release;--prefix <value>:产物安装路径,默认安装到 runtime 目录下output/common;-hwasan/--cjlib-sanitizer-support:分别用于使能 HWASAN 与构建 sanitizer 版本的运行时(可选asan、tsan、hwasan)。
构建过程中,config.cmake 会自动完成 boundscheck 的克隆、build/cmake/CMakeLists.txt 的注入以及子目录构建;产物中的动态库(如 Linux 上的 libcangjie-runtime.so)即包含对 boundscheck 的链接引用。交叉编译场景(OHOS/Android/Windows)下,boundscheck 会随目标工具链(对应 runtime/build/cmake/toolchain/ 下的各平台配置文件)一起被编译与链接。
八、总结
以 runtime/third_party/README.md 为索引,结合源码可以还原出 libboundscheck 在仓颉运行时中的完整生命周期:
| 环节 | 实现位置 | 作用 |
|---|---|---|
| 版本固定 | runtime/config.cmake | git clone --branch OpenHarmony-v6.0-Release 拉取指定版本 |
| 构建配置注入 | runtime/config.cmake | 复制 build/cmake/CMakeLists.txt 覆盖第三方构建逻辑 |
| 子项目引入 | runtime/CMakeLists.txt | add_subdirectory 自动编译 |
| 头文件可见性 | runtime/CMakeLists.txt、runtime/src/CMakeLists.txt | include_directories(${BOUNDSCHECK_INCLUDE}) |
| 链接 | runtime/CMakeLists.txt | LINK_LIBS 中加入 boundscheck |
| 平台适配 | runtime/build/cmake/CMakeLists.txt | Windows 仅编译 4 个补齐源文件,避免与 MSVCRT 重复定义 |
| 源码调用 | 40 余个源文件 #include "securec.h" |
memcpy_s、memset_s、sprintf_s、vsprintf_s、strtok_s、snprintf_s 等安全函数 |
这套"固定版本 + 构建配置注入 + 子目录自动构建 + 平台差异化裁剪 + 对外解耦"的第三方依赖治理模式,保证了仓颉运行时在 Linux、OHOS、Android、Windows、macOS、iOS 等多个目标平台上都能以统一、安全、可复现的方式获得边界检查能力,也是理解仓颉运行时内存安全底座的入口之一。