HarmonyOS 云相册实战:ArkTS 里给 OBS 请求做 HMAC-SHA1 签名
最近在鸿蒙开发实践中心跟着「用 OBS 打造个人云相册 app」案例做练习,做到照片上传这一步卡住了:App 要直接调用 OBS 的 REST API 传照片,而 OBS 的 Header 签名得自己算。官方 SDK 不一定覆盖 ArkTS 直连的场景,手工算签名反而是最稳的办法。这篇文章把签名串的构造、ArkTS 里的实现思路和 403 排查清单一次讲清,都是这次实操里验证过的要点。
一、签名公式只有一行
Signature = Base64( HMAC-SHA1( SK, UTF-8 编码后的 StringToSign ) )
算好之后放进请求头:
Authorization: OBS <AccessKeyID>:<Signature>
三个细节别搞错:前缀固定是 OBS;AK 和签名之间用英文冒号隔开;签名是 HMAC 结果再 Base64 编码,不是把 HMAC 的十六进制字符串直接拼上去。
二、StringToSign 是六段拼接
StringToSign 由 6 段按固定顺序、用换行符 \n 拼起来。哪一段没有值,就填空字符串,但换行符不能省:
HTTP-Verb + “\n” + Content-MD5 + “\n” + Content-Type + “\n” + Date + “\n” + CanonicalizedHeaders + “\n” + CanonicalizedResource
| 段 | 是否必选 | 说明 |
|---|---|---|
| HTTP-Verb | 必选 | 大写的方法名:PUT、GET、DELETE、HEAD、POST |
| Content-MD5 | 可选 | 消息体 MD5 的 Base64 值;不设填空字符串 |
| Content-Type | 可选 | 如 text/plain;请求里不带该头域时填空字符串 |
| Date | 必选 | RFC 1123 格式的 GMT 时间,如 Sat, 12 Oct 2015 08:12:38 GMT;与服务器时间差超过 15 分钟会返回 403 |
| CanonicalizedHeaders | 可选 | 所有 x-obs- 前缀头域,规则见第三节 |
| CanonicalizedResource | 必选 | “/” + 桶名 + “/” + 对象名 + “?” + 子资源;无桶无对象时为 “/” |
以 PUT 上传对象为例,StringToSign 长这样:
PUT
text/plain
Mon, 14 Oct 2015 12:08:34 GMT
x-obs-acl:public-read
/bucket/object.txt
第二行 Content-MD5 是空的,但它后面的换行符必须保留,这是新手最容易丢的地方。
三、两处最容易算错的规则
1. CanonicalizedHeaders
- 只收
x-obs-前缀的头域; - 头域名全部转小写,头域值保留原大小写,
STANDARD不能写成standard; - 多个头域按头域名从小到大排字典序;
- 每个头域占一行,行尾带
\n; - 冒号后面不能加空格,
x-obs-acl: public-read是错的,必须写成x-obs-acl:public-read; - 同名头域的值用英文逗号合并;
- 用 STS 临时 AK/SK 时,必须带上
x-obs-security-token并参与签名。
2. CanonicalizedResource
| 场景 | CanonicalizedResource |
|---|---|
| 列桶(不指定桶) | / |
| 创建桶 mybucket | /mybucket |
| 上传对象 mybucket/object.txt | /mybucket/object.txt |
| 获取对象 ACL | /mybucket/object.txt?acl |
| 获取指定版本对象 | /mybucket/object.txt?versionId=xxx |
子资源有多个时按字典序排列、用 & 拼接,例如 ?acl&versionId=xxx,不能写成 ?versionId=xxx&acl。用自定义域名访问时,桶名位置换成域名。
四、ArkTS 里怎么实现
HarmonyOS 提供 @ohos.security.cryptoFramework 模块做 HMAC 计算。签名工具可以拆成四步:拼时间、拼头域、拼资源、算 HMAC。前面三步是纯字符串处理,代码如下:
// 1. 生成 RFC 1123 格式的 GMT 时间
// 注意:不同 JS 引擎的 Date.toUTCString() 输出可能不一致,手动拼接最可靠
function formatRFC1123GMT(date: Date): string {
const weeks = ['Sun', 'Mon', 'Tue', 'Wed', 'Thu', 'Fri', 'Sat'];
const months = ['Jan', 'Feb', 'Mar', 'Apr', 'May', 'Jun', 'Jul', 'Aug', 'Sep', 'Oct', 'Nov', 'Dec'];
const pad = (n: number): string => (n < 10 ? '0' + n : '' + n);
return `${weeks[date.getUTCDay()]}, ${pad(date.getUTCDate())} ${months[date.getUTCMonth()]} ${date.getUTCFullYear()} ${pad(date.getUTCHours())}:${pad(date.getUTCMinutes())}:${pad(date.getUTCSeconds())} GMT`;
}
// 2. 构造 CanonicalizedHeaders:筛 x-obs- 前缀、转小写、字典序、每行以 \n 结尾
function buildCanonicalizedHeaders(headers: Record<string, string>): string {
const keys = Object.keys(headers).filter((k) => k.toLowerCase().startsWith('x-obs-'));
if (keys.length === 0) {
return '';
}
return keys
.sort((a, b) => a.toLowerCase().localeCompare(b.toLowerCase()))
.map((k) => `${k.toLowerCase()}:${headers[k].trim()}`)
.join('\n') + '\n';
}
// 3. 构造 CanonicalizedResource
function buildCanonicalizedResource(bucket: string, objectName: string, subResource: string = ''): string {
let resource = `/${bucket}/${objectName}`;
if (subResource) {
resource += `?${subResource}`;
}
return resource;
}
// 4. 拼 StringToSign:6 段顺序固定,缺省段填空字符串
// 注意:canonicalizedHeaders 自带行尾 \n(无头域时为空字符串),这里不再补换行
function buildStringToSign(method: string, contentType: string, date: string, canonicalizedHeaders: string, resource: string): string {
return method + '\n' + '' + '\n' + contentType + '\n' + date + '\n' + canonicalizedHeaders + resource;
}
第五步算 HMAC:用 cryptoFramework.createMac('SHA1'),密钥取 SK 的 UTF-8 字节,输入取 StringToSign 的 UTF-8 字节,输出再做 Base64 编码就得到 Signature。最后把 Authorization: OBS ${ak}:${signature} 和 Date、x-obs- 头域一起发出去。实际写代码时,对照 cryptoFramework 的 Mac 接口文档确认密钥对象的创建方式即可,签名串本身按上面四步拼不会错。
五、403 SignatureDoesNotMatch 排查清单
服务端只会告诉你一句话:算出来的签名和你给的不一致。按出现频率从高到低排查:
- Date 时间差超过 15 分钟:打印你发出的 Date,和服务器当前 GMT 时间对比,HarmonyOS 设备时间不准是常见原因;
- CanonicalizedHeaders 没有按字典序排列:打印拼接后的头域字符串,确认 x-obs-acl 在 x-obs-date 之前;
- 头域名没有转小写:传了
X-OBS-ACL:public-read,签名串里必须写成x-obs-acl:public-read; - 冒号后多了无意义空格:
x-obs-acl: public-read不匹配服务端按x-obs-acl:public-read算出的签名; - Content-Type 大小写或值不一致:请求头里发的是 text/plain,签名串里写的是 text/html,或者反过来;
- SK 错误或已失效:去控制台确认 AK/SK 状态,用了 STS 临时密钥时 token 可能已过期;
- 临时密钥漏传 x-obs-security-token:用 STS 临时 AK/SK 时,该头域必须同时出现在请求头和 CanonicalizedHeaders 里;
- CanonicalizedResource 子资源没按字典序:
?versionId=xxx&acl应改为?acl&versionId=xxx; - 对象名含特殊字符:对象名含空格、中文时,URL 里要编码,但 CanonicalizedResource 里用原始对象名。
排查时最有效的一招,是把本地拼好的 StringToSign 原样打印出来,逐段和文档规则对一遍,九成问题都出在上面这九条里。
六、小结
给 OBS 请求手工签名,核心就三句话:公式是 Base64(HMAC-SHA1(SK, StringToSign));StringToSign 六段顺序固定、缺省填空、换行不能省;x-obs- 头域和子资源都要按字典序排、冒号后不加空格。把这三点做对,云相册的照片上传就能一次调通。
另外提醒一句安全事项:AK/SK 不要写进会发出去的客户端代码里。练习时可以用自己的测试账号密钥,正式产品里请用 STS 临时密钥或服务端签名下发的方式,避免长期密钥泄露。
本文源自在鸿蒙开发实践中心做「用 OBS 打造个人云相册 app」案例、并在 AI 开发者空间里查阅 OBS 官方签名文档后的实操记录,示例时间与桶名均为文档示例值。
- 点赞
- 收藏
- 关注作者
评论(0)