阿里云 V4 签名实战(第3篇)· C++:手写 OSS PutObject V4 签名(CMake + OpenSSL,附完整工程)

简介: 签名算法与语言无关,坑全在字符串处理里。本篇用 C++17 header-only 签名器实现 OSS V4 签名(OSS4-HMAC-SHA256)并经 libcurl 完成 PutObject:二进制安全的 HMAC 密钥链、std::map 规范化头、自实现 URI 编码、UTC 时间生成,CMake 一键构建并把官方文档示例接入 CTest,与 Python 版实现交叉验证逐字节一致,附 7 条 C++ 签名踩坑清单。

「V4 签名实战」系列第 3 篇,语言轮到 C++。签名原理在第 1 篇(Python)已逐字节讲透,本篇聚焦 C++ 落地时的工程问题:header-only 签名器设计、二进制安全的 HMAC 中间值、自实现 URI 编码、CMake + OpenSSL 构建,以及如何把官方文档示例做成 CTest 自测。签名算法本身与第 1 篇完全同源,两份实现共用同一组官方测试向量。

配套完整工程(可直接导入编辑器构建运行):
https://github.com/zhoubiao188/aliyun-v4-signature-examples/tree/main/cpp-oss-putobject-v4

一、C++ 实现签名的四个工程难点

手写 OSS V4 签名在 Python 里是 130 行的事,在 C++ 里真正的难点不在算法,而在工程细节:

  1. HMAC 中间值是二进制:派生密钥链 kDate → kRegion → kService → kSigning 每一步的输出都是 32 字节二进制摘要,要作为下一步的 key。C++ 里必须用 std::string(二进制安全)传递,一旦经过 c_str()、strlen 或 char* 拼接,遇到 0x00 字节就会截断——这是 C++ 版签名最隐蔽的 bug 来源;
  2. 规范化头的排序:签名要求头名小写 + 字典序。C++ 里直接用 std::map<std::string, std::string>,天然按 key 字典序遍历,比手工排序可靠;
  3. URI 编码不能偷懒:libcurl 的 curl_easy_escape 会把空格编成 + 之外还有细节差异,OSS V4 要求"仅 A-Za-z0-9-._~ 不编码、空格为 %20、路径保留 /",自己写 20 行才是正解;
  4. 时间必须 UTC:x-oss-date 形如 20261009T145101Z,要用 gmtime_r + strftime,误用 localtime 在东八区会把签名时间提前 8 小时,直接 RequestTimeTooSkewed。

二、工程结构与构建

cpp-oss-putobject-v4/
├── CMakeLists.txt
├── include/oss_v4_signer.hpp   # header-only 签名器(可直接复用到你的项目)
├── src/main.cpp                # libcurl 发起 PutObject
└── test/test_signature.cpp     # 官方示例向量自测(接入 CTest)

构建与运行(依赖只有一个 OpenSSL Crypto 和 libcurl):

# macOS:  brew install cmake openssl
# Ubuntu: sudo apt install cmake g++ libssl-dev libcurl4-openssl-dev

cmake -B build -DCMAKE_BUILD_TYPE=Release
# macOS 找不到 OpenSSL 时追加: -DOPENSSL_ROOT_DIR=$(brew --prefix openssl)
cmake --build build

ctest --test-dir build --output-on-failure      # ① 官方向量自测(无需网络和真实 AK)
./build/oss_putobject_v4 --dry-run              # ② 打印签名全过程
export ALIBABA_CLOUD_ACCESS_KEY_ID=<AK>
export ALIBABA_CLOUD_ACCESS_KEY_SECRET=<SK>
export OSS_BUCKET=<你的Bucket>
./build/oss_putobject_v4                        # ③ 真实上传,预期 HTTP 200 + ETag

CMakeLists 只有三块值得看:find_package(OpenSSL REQUIRED)、find_package(CURL REQUIRED),以及把自测挂进 CTest:

add_executable(v4_selftest test/test_signature.cpp)
target_include_directories(v4_selftest PRIVATE include)
target_link_libraries(v4_selftest PRIVATE OpenSSL::Crypto)   # 自测不需要 curl

enable_testing()
add_test(NAME v4_selftest COMMAND v4_selftest)

三、核心代码逐段讲解

HMAC 与 SHA256(OpenSSL 的 HMAC 接口返回二进制,用 std::string 原样接住):

inline std::string hmac_sha256(const std::string& key, const std::string& msg) {
   
    unsigned char md[EVP_MAX_MD_SIZE];
    unsigned int md_len = 0;
    HMAC(EVP_sha256(), key.data(), static_cast<int>(key.size()),
         reinterpret_cast<const unsigned char*>(msg.data()), msg.size(), md, &md_len);
    return std::string(reinterpret_cast<char*>(md), md_len);
}

派生密钥链——四步 HMAC,上一步输出直接做下一步 key,全程二进制安全:

std::string k_date    = hmac_sha256("aliyun_v4" + sk, date);        // 日期取 x-oss-date 前 8 位
std::string k_region  = hmac_sha256(k_date, region);
std::string k_service = hmac_sha256(k_region, "oss");
std::string k_signing = hmac_sha256(k_service, "aliyun_v4_request");
std::string signature = to_hex(hmac_sha256(k_signing, string_to_sign));

规范化请求——std::map 自动字典序,每行头以 \n 结尾,五段拼接:

std::string canonical_headers;
for (const auto& kv : headers)                       // std::map 天然按 key 排序
    canonical_headers += kv.first + ":" + trim(kv.second) + "\n";

std::string canonical_request = method + "\n" + canonical_uri + "\n" + canonical_query +
                                "\n" + canonical_headers + "\n" + additional_str + "\n" +
                                "UNSIGNED-PAYLOAD";  // 当前 V4 仅支持此固定值

待签串与 Authorization:

std::string scope = date + "/" + region + "/oss/aliyun_v4_request";
std::string string_to_sign = "OSS4-HMAC-SHA256\n" + x_oss_date + "\n" + scope + "\n" +
                             sha256_hex(canonical_request);
std::string authorization = "OSS4-HMAC-SHA256 Credential=" + ak + "/" + scope +
                            ",Signature=" + signature;

发起请求(libcurl,把签名相关头逐个挂上):

curl_slist* hdrs = nullptr;
hdrs = curl_slist_append(hdrs, ("Authorization: " + r.authorization).c_str());
hdrs = curl_slist_append(hdrs, "x-oss-content-sha256: UNSIGNED-PAYLOAD");
hdrs = curl_slist_append(hdrs, ("x-oss-date: " + std::string(x_oss_date)).c_str());
hdrs = curl_slist_append(hdrs, ("content-type: " + content_type).c_str());
curl_easy_setopt(curl, CURLOPT_URL, url.c_str());
curl_easy_setopt(curl, CURLOPT_CUSTOMREQUEST, "PUT");
curl_easy_setopt(curl, CURLOPT_POSTFIELDS, body.data());
curl_easy_setopt(curl, CURLOPT_HTTPHEADER, hdrs);

四、官方向量自测:跨语言交叉验证

test/test_signature.cpp 使用与第 1 篇 Python 完全相同的官方文档测试向量,构建后 ctest 输出:

[PASS] CanonicalRequest 的 SHA256(官方示例值)
       c46d96390bdbc2d739ac9363293ae9d710b14e48081fcb22cd8ad54b63136eca
[PASS] StringToSign(用文档 SigningKey HMAC = 官方签名)
       053edbf550ebd239b32a9cdfd93b0b2b3f2d223083aa61f75e9ac16856d61f23
[PASS] 本工程 SigningKey(官方 SDK 公式,对照项)
       8a01ff4efcc65ca2cbc75375045c61ab5f3fa8b9a2d84f0add27ef16a25feb3c

第三项的 SigningKey 与 Python 篇实现算出的值逐字节相同——两门语言、两份独立实现、同一个官方公式,这就是"测试向量背书"的价值:它证明的不是代码跑通了,而是每一处换行、排序、编码都与官方规范一致。CMake 已把自测挂进 CTest,cmake --build 后顺手 ctest 即可回归。

五、踩坑清单

  1. HMAC 中间值过 c_str()/strlen:二进制摘要含 0x00,C 字符串函数会截断,密钥链输出全错;全程 std::string;
  2. localtime 而非 gmtime_r:UTC 时间错 8 小时,RequestTimeTooSkewed;
  3. 用 curl_easy_escape 做 URI 编码:它的转义集与 OSS V4 规范不一致(空格、波浪号等差异),自行实现 20 行才可靠;
  4. std::map 被换成 std::unordered_map:迭代顺序不再是字典序,规范化头排序直接破坏;
  5. macOS 找不到 OpenSSL 头文件:Apple 自带 LibreSSL 且不在默认路径,brew install openssl 后加 -DOPENSSL_ROOT_DIR=$(brew --prefix openssl);
  6. 自测没接入构建系统:签名代码改一行没回归就上线是最危险的,CTest 里挂上官方向量,改坏当场爆;
  7. EVP_MAX_MD_SIZE 忘了用:摘要缓冲区按固定 32 字节硬编码虽然对 HMAC-SHA256 恰好不错,但读 md_len 才是正途。

六、小结与下一篇预告

本篇把 OSS V4 签名在 C++ 里完整落地:header-only 签名器 + libcurl 上传 + CTest 官方向量回归,签名器只有两个头文件依赖,可直接拷进任何 C++ 项目。三种语言写完同一套签名后你会发现:算法永远不变,变的只是字符串与字节的处理习惯——而签名 bug 几乎全部藏在字符串处理里。

下一篇(第 4 篇)回到 Python:手写 ACS3-HMAC-SHA256 签名调用 CDN DescribeCdnDomainLogs,对比 OSS 专用签名与全系 OpenAPI 通用签名的结构差异。欢迎收藏仓库:https://github.com/zhoubiao188/aliyun-v4-signature-examples

声明:本文为作者个人实践笔记,签名细节以阿里云官方签名文档为准;文中无任何真实密钥。

相关文章
|
1月前
|
人工智能 安全 小程序
阿里云服务器199元1年购买与使用常见问题:2核4G5M带宽,续费同价,企业用户专享
阿里云199元/年通用算力型u1实例(ecs.u1-c1m2.large)面向企业实名认证用户,配置2核4G、5Mbps固定公网带宽、80GB ESSD Entry云盘,主打"续费同价",活动延至2029年3月31日,最长可同价使用5年,适合建站、开发测试、后台管理、小程序及跨境出海等通用场景;个人账号无法购买,同一企业主体最多保有一台,适合预算敏感的中小企业长期选用。
|
15天前
|
缓存 文字识别 BI
‌一文读懂通义千问 Qwen3‑VL‑Plus:旗舰视觉语言模型能力拆解、API 调用实战及行业解决方案‌
Qwen3‑VL‑Plus不是一款"更强的识图工具",而是一个‌从感知到决策、从分析到执行的完整视觉智能体基座‌。它以原生多模态融合打破感知壁垒,以256K超长上下文突破信息边界,以思考模式混合设计兼顾深度与速度,以百炼平台的全链路生态让落地门槛降至最低。 对于开发者,几行代码即可接入;对于企业,可视化智能体编排无需深度编码;对于行业,法务、财务、产品、媒体、教育……每一个需要"看懂画面"的场景,都能找到它的用武之地。 ‌现在就前往阿里云百炼大模型服务平台页面,领取免费Tokens,开启你的视觉智能体实战之旅。
214 1
|
30天前
|
弹性计算 运维 安全
在阿里云 ECS 上跑 GoTry:Node 22 环境与出网配置的落地步骤
本文详解GoTry(Danceiny/gotry)在阿里云ECS上的部署实践:需Node 22.15+、2vCPU/4GiB起步,WASM依赖Z3要求内存充足;推荐NAT网关出网+SSH隧道访问3080端口;强调环境固化、状态隔离与中文文档优先。
60 2
|
1月前
|
设计模式 缓存 安全
Agent Harness 深度拆解:从一个类比推导出 12 个组件
本文另辟蹊径,不罗列12个组件,而是以“裸LLM=无内存/硬盘/I/O的CPU”为心智模型,用第一性原理推导出长周期任务必然引发的5大问题(上下文腐化、错误累积、跨会话失忆、权限越界、无法自验),再逐一对映12个组件为何必然存在——讲清Harness不是设计模式,而是必须跑起来的运行时系统。(239字)
|
2月前
|
存储 弹性计算 Serverless
阿里云免费中心:上百款云产品免费用,包括云服务器、云数据库、Tokens、免费存储等云产品,0元直达
阿里云免费中心提供超176款云产品新用户免费试用,涵盖ECS、OSS、RDS、FC、无影云电脑等,含300–660元额度、500GB云盘、120小时云电脑等福利;学生还可享12个月ECS。注意:仅限未购过该产品的账号,停机仍计费,到期未释放将产生费用。(239字)
570 1
|
2月前
|
人工智能 运维 BI
QwenWork 千问办公实战全指南:Qwen3.8 基座六大核心能力,桌面与云端 Agent、API 示例及计费选型解析
本文完整梳理QwenWork产品定位、Qwen3.8基座带来的技术增益、六大核心能力、各行业落地业务场景,提供curl、Python底层API可运行代码,拆解席位+积分混合计费体系,讲解参数调优、业务选型、高频故障排查,帮助个人从业者、企业技术管理者理清产品能力边界,完成POC验证和业务落地。
413 3
|
2月前
|
Web App开发 人工智能 搜索推荐
信源权重低也能被AI引用?GEO实操指南
本文由Geo专家于磊基于实证研究,系统解答低权重网站在生成式引擎(GEO)时代的引用困境:揭示“信源等级”新内涵,指出低权重非劣势而是机会;用普林斯顿、斯坦福等权威研究证实——加证据、置结论、优结构比堆关键词更有效;提供6条可落地路径与GEO-16自查清单,助中小站点从“被检索”到“被引用”。
196 2
|
2月前
|
人工智能 PyTorch 云栖大会
亮点抢先看!AMD、中兴通讯等企业大咖解码下一代 OS|2026 云栖大会
一览来自 AMD、中兴通讯、阿里云、英特尔,以及上海交通大学等企业/高校专家的精彩金句和重磅议题。
|
2月前
|
存储 人工智能 自然语言处理
阿里云千问办公 QwenWork详细介绍:产品核心能力、典型场景、价格及常见问题解答
阿里云千问办公(QwenWork)是通义实验室推出的AI原生办公平台,依托Qwen3.8大模型,支持自然语言生成PPT、Excel、网页、视频等;具备浏览器自动化、深度检索、钉钉/飞书集成、定时任务及多端协同能力,真正实现“对话即交付”。
882 2
|
2月前
|
人工智能 Kubernetes 测试技术
会AI的测试开发,薪资到底能高多少?我扒了100份JD
2026年测试岗巨变:手工测试需求降47%,测开岗涨340%。AI测试开发年薪达35–100万+,远超传统测开;岗位核心已从“验证功能”转向“评测能力”,要求大模型、Agent、RAG等实战经验。

热门文章

最新文章