You need to enable JavaScript to run this app.
导航
对象存储
  • 文档首页
    • /对象存储/API 参考/签名机制/签名机制
签名机制
最近更新时间：2024.09.19 15:19:38首次发布时间：2021.10.13 16:14:07
我的收藏

对象存储会对每个访问的请求进行身份验证，因此您需要在请求中包含签名信息。本文介绍对象存储的 API 签名机制。

签名验证

通过 AK/SK 对请求进行签名时，TOS 通过验证签名的方式，识别请求的发送者身份。

  • AK(Access Key ID): 访问密钥 ID，用于标识用户。
  • SK(Secret Access Key): 与访问密钥 ID 结合使用的密钥，用于加密签名。

说明

查看 AKSK 信息的具体步骤，请参见查看 AKSK 信息。

当您想以个人身份向 TOS 发送请求时，首先需要按照 TOS 格式生成签名字符串，再使用 SK 对字符串进行加密。 TOS 收到请求后，以同样的方式进行计算签名。如果计算出来的签名和请求的签名一致，则请求有效，否则 TOS 返回 HTTP 403 错误。
签名可以包含在请求的 Header 中，也可以包含在 URL 的 Query 参数中，您可以根据具体应用场景，使用不同的签名方式。

计算签名所需要的函数

函数名

功能描述

UriEncode()

对字符串进行编码，该功能存在以下约束：

  • 除了 A~Z、a ~ z、0~9、-、.、_、~ 这些字符，其他字符都要编码。
  • 空格要编码成 %20（不能编码成+）。
  • 每个 URI 编码字节由 % 和两位十六进制数组成。十六进制值必须是大写。
  • 除了对象名中的 / 不编码，其他情况下 / 都需要编码。

Lowercase()

将字符串转换成小写。

Hex()

16 进制编码。

SHA256Hash()

SHA256 算法。

HMAC-SHA256()

HmacSHA256 算法。

Trim()

删除字符串开头和结尾的空白符。

Header 中包含签名

您可以在 HTTP 请求中增加 Authorization 的 Header 来包含签名信息。
Authorization 的计算过程如下：

构造规范化请求 （CanonicalRequest）

说明

  • Hash 代指 SHA256 算法。
  • HexEncode 代指转 16 进制编码。
CanonicalRequest = 
    HTTPMethod + '\n' + 
    CanonicalURI + '\n' + 
    CanonicalQueryString + '\n' + 
    CanonicalHeaders + '\n' + 
    SignedHeaders + '\n' + 
    HashedPayload

参数说明如下。

参数

描述

HTTPMethod

HTTP 请求的 Method，如 PUT、GET、HEAD、DELETE 等。

CanonicalURI

UriEncode(<PATH>)

  • 如果 URL 中的 PATH 为空，则 CanonicalURI为/。
  • 如果完整路径为 [https://bucketname.tos-cn-beijing.volces.com/object](https://bucketname.tos-cn-beijing.volces.com/object)，则CanonicalURI为/object。

CanonicalQueryString

请求中 Query 参数的编码格式：
UriEncode(<QueryParam1>) + '=' + UriEncode(<value>) + '&' + UriEncode(<QueryParam2>) + '=' + UriEncode(<value>) + '&' +
...
UriEncode(<QueryParamN>) + '=' + UriEncode(<value>)

说明

  • 请求中的 Query 参数编码后按照 ASCII 字节顺序进行上述格式处理。
  • 所有 Query 参数必须参与计算。
  • 如果没有 Query 参数，则 CanonicalQueryString 为空字符串。

CanonicalHeaders

请求中 Header 的编码格式：
Lowercase(<HeaderName1>) + ':' + Trim(<value>) + '\n'
Lowercase(<HeaderName2>) + ':' + Trim(<value>) + '\n'
...
Lowercase(<HeaderNameN>) +':' + Trim(<value>) + '\n'

说明

  • HeaderName 按字典序排列。
  • CanonicalHeaders 不必包含全部头域。
  • 如果请求中存在 Content-Type 头域，则 CanonicalHeaders 必须包含该头域。
  • CanonicalHeaders 必须包含 host 头域。
  • 使用临时 AK/SK 鉴权时，必须携带 x-tos-security-token，CanonicalHeaders 必须包含该头域。
  • CanonicalHeaders 必须包含所有 x-tos-* 的头域。

SignedHeaders

指明参与签名的 Header 有哪些：
Lowercase(<HeaderName1>) + ';' + Lowercase(<HeaderName2>) + ... + Lowercase(<HeaderNameN>)

说明

  • CanonicalHeaders 中的 HeaderName 按字典序排列。
  • SignedHeaders 里的 HeaderName 必须在请求的头域中。

HashedPayload

Hex(SHA256Hash(<payload>)

说明

  • 请求中 payload 进行 SHA256 计算后的 16 进制表示。
  • 如果请求中没有 payload，则计算空字符串 Hex(SHA256Hash(""))，该值为 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855。
  • 预签名的情况下，也可以不计算 payload，使用 UNSIGNED-PAYLOAD 代替。

创建签名字符串 （StringToSign）

签名字符串主要包含请求以及正规化请求的元数据信息，由签名算法、请求日期、信任状和正规化请求哈希值连接组成，伪代码如下：

StringToSign = Algorithm + '\n' + RequestDate + '\n' + CredentialScope + '\n' + HexEncode(Hash(CanonicalRequest))

参数说明如下。

参数

说明

Algorithm

指代签名的算法，目前仅支持 HMAC-SHA256 的签名算法。

RequestDate

指代请求 UTC 时间，请使用如下格式：yyyyMMddTHHmmssZ。

CredentialScope

指代凭证范围值，格式为：yyyyMMdd/region/tos/request。

CanonicalRequest

指代上一小节正规化请求的结果。

计算签名秘钥（SigningKey）

在计算签名前，首先从私有访问密钥（Secret AccessKey）派生出签名密钥（SigningKey），而不是直接使用私有访问密钥。具体计算过程如下：

kSecret = *Your Secret Access Key*
kDate = HMAC-SHA256(kSecret, Date)
kRegion = HMAC-SHA256(kDate, Region)
kService = HMAC-SHA256(kRegion, "tos")
kSigning = HMAC-SHA256(kService, "request")

计算签名

Signature = HexEncode(HMAC-SHA256(kSigning, StringToSign))

然后构建 Header：

Authorization: TOS4-HMAC-SHA256 Credential={AccessKeyId}/{CredentialScope}, SignedHeaders={SignedHeaders}, Signature={Signature}

表达式中{}部分表示上文计算的中间过程。

签名示例

以下载对象为例，相关信息如下。

参数

值

桶名

examplebucket

对象名

exampleobject

区域

cn-beijing

时间

Sat, 1 Jan 2022 00:00:00 GMT

AccessKeyId

testAK

SecretAccessKey

testSK

CanonicalRequest

GET
/exampleobject

host:examplebucket.tos-cn-beijing.volces.com
x-tos-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-tos-date:20220101T000000Z

host;x-tos-content-sha256;x-tos-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

StringToSign

TOS4-HMAC-SHA256
20220101T000000Z
20220101/cn-beijing/tos/request
c5b4f2fac36f0a3351d91753998bd811d1c446c186a2b3fb2b9e420630f13534

SigningKey

HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("testSK", "20220101"), "cn-beijing"), "tos"), "request")

Signture

d40b66cf0054d1642843670d10fa095e1609c7896f25df217770b0abe717693b

Authorization header

TOS4-HMAC-SHA256 Credential=testAK/20220101/cn-beijing/tos/request, SignedHeaders=host;x-tos-content-sha256;x-tos-date, Signature=d40b66cf0054d1642843670d10fa095e1609c7896f25df217770b0abe717693b

签名方式