在多分块上传时，TOS 支持在有效数据末尾以 Trailing Header 的形式携带有效数据的校验和。服务端会基于接收到的数据计算校验和，和 Trailing Header 中的校验和进行对比，以验证数据完整性。本文介绍使用 Trailing Header 和链式签名时的签名计算过程、签名示例等内容。 ## 签名所需函数

说明

Trailing Header 支持单独使用，如果单独使用，则不涉及本章的内容，详细介绍，请参见 Header 签名概述。

|**函数名** |**功能描述** | |---|---| |UriEncode() |对字符串进行编码，限制如下：

* 除了 `A`~`Z`、`a` ~ `z`、`0`~`9`、`-`、`.`、`_`、`~` 字符，其他字符都需要编码。

* 空格需要编码为 `%20`（不支持编码为 `+`）。

* 每个 URI 编码字节由 `%` 和两位十六进制数组成。十六进制值必须是大写。

* 除了对象名中的 `/` 无需编码，其他情况下的 `/` 都需要编码。 | |Lowercase() |将字符串转换成小写。 | |Hex() |16 进制编码。 | |SHA256Hash() |SHA256 算法。 | |HMAC\-SHA256() |HmacSHA256 算法。 | |Trim() |删除字符串开头和结尾的空白符。 | ## 签名 Header |**Header 名称** |**描述** | |---|---| |x\-tos\-content\-sha256 |用于指定客户端上传文件的格式，以及使用的签名方式，取值说明如下：

* STREAMING\-TOS4\-HMAC\-SHA256\-PAYLOAD：表示 Header 中包含 TOS V4 基础签名，数据中包含基于 HMAC\-SHA256 计算的链式签名，数据末尾不包含 Trailing Header。

* STREAMING\-TOS4\-HMAC\-SHA256\-PAYLOAD\-TRAILER：表示 Header 中包含 TOS V4 基础签名，数据中包含基于 HMAC\-SHA256 计算的链式签名，数据末尾包含 Trailing Header。

* STREAMING\-UNSIGNED\-PAYLOAD\-TRAILER：表示 Header 中包含 TOS V4 基础签名，数据中不包含链式签名，数据末尾包含 Trailing Header。

* STREAMING\-UNSIGNED\-PAYLOAD：表示 Header 中包含 TOS V4 基础签名，数据中不包含链式签名，数据末尾不包含 Trailing Header。 | |Content\-Encoding |本场景下，`Content-Encoding` 值建议包含 tos\-chunked 时，表示允许使用多分块的方式上传数据，需要配合 x\-tos\-content\-sha256 使用。

说明

在保存对象时，TOS 不会将 tos\-chunked 属性作为用户数据保存，下载对象时也不会在 Content\-Encoding 返回 tos\-chunked 属性。

| |x\-tos\-trailer |表示 Trailing Header 中校验和使用的算法，取值仅为 `x-tos-hash-crc64ecma` ，需要配合 `x-tos-content-sha256`、`Content-Encoding: tos-chunked` 使用。 | |x\-tos\-decoded\-content\-length |用于服务端校验接收到的有效数据长度是否正确。可选，设置为原始文件大小。

说明

设置 x-tos-decoded-content-length 值时，不包含由多分块编码引入的格式数据、签名数据、Trailing Header 数据的长度。例如：要上传一个 4GB 的文件，将值设置为 4294967296。

| |Content\-Length |可选，HTTP 请求体的长度。

说明

设置 Content-Length 值时，需要包含由多分块编码引入的格式数据、签名数据、Trailing Header 数据的长度。

Transfer\-Encoding: chunked 传输方式下，需要缺省。

| ## 签名计算过程

说明

Hash 代指 SHA256 算法。

HexEncode 代指转 16 进制编码。

TOS 兼容 S3 Multiple Chunks Including Trailing Headers 的访问请求，您也可以使用 S3 Multiple Chunks Including Trailing Headers 的方式上传对象到 TOS。

### 计算种子签名 #### 步骤 1：构造规范化请求（CanonicalRequest） ```Plain CanonicalRequest = HTTPMethod + '\n' + CanonicalURI + '\n' + CanonicalQueryString + '\n' + CanonicalHeaders + '\n' + SignedHeaders + '\n' + HashedPayload ``` 参数说明如下。 |**参数** |**描述** | |---|---| |HTTPMethod |HTTP 请求的 Method，如 PUT、GET、HEAD、DELETE 等。 | |CanonicalURI |UriEncode(` ** `)

* 如果 URL 中的 `PATH` 为空，则 CanonicalURI 为 `/`。

* 如果完整路径为 `[https://bucketname.tos-cn-beijing.volces.com/object](https://bucketname.tos-cn-beijing.volces.com/object)`，则 CanonicalURI 为 `/object`。 | |CanonicalQueryString |请求中 Query 参数的编码格式：

UriEncode(` ** `) + '=' + UriEncode(` ** `) + '&' + UriEncode(` ** `) + '=' + UriEncode(` ** `) + '&' +

...

UriEncode(` ** `) + '=' + UriEncode(` ** `)

说明

请求中的 Query 参数编码后按照 ASCII 字节顺序进行上述格式处理。

所有 Query 参数必须参与计算。

如果没有 Query 参数，则 CanonicalQueryString 为空字符串。

| |CanonicalHeaders |请求中 Header 的编码格式：

Lowercase(` ** `) + ':' + Trim(` ** `) + '\n'

Lowercase(` ** `) + ':' + Trim(` ** `) + '\n'

...

Lowercase(` ** `) +':' + Trim(` ** `) + '\n'

说明

HeaderName 按字典序排列。

CanonicalHeaders 无需包含全部头域。

如果请求中存在 Content-Type 头域，则 CanonicalHeaders 必须包含该头域。

CanonicalHeaders 必须包含 host 头域。

使用临时 AK/SK 鉴权时，必须携带 x-tos-security-token，CanonicalHeaders 必须包含该头域。

CanonicalHeaders 必须包含所有 x-tos-* 的头域。

| |SignedHeaders |指定参与签名的 Header：

Lowercase(` ** `) + ';' + Lowercase(` ** `) + ... + Lowercase(` ** `)

说明

CanonicalHeaders 中的 HeaderName 按字典序排列。

SignedHeaders 里的 HeaderName 必须在请求的头域中。

| |HashedPayload |常量：STREAMING\-TOS4\-HMAC\-SHA256\-PAYLOAD\-TRAILER | #### 步骤 2：创建签名字符串（StringToSign）签名字符串主要包含请求以及正规化请求的元数据信息，由签名算法、请求日期、信任状和正规化请求哈希值连接组成，伪代码如下： ```Plain StringToSign = Algorithm + '\n' + RequestDate + '\n' + CredentialScope + '\n' + HexEncode(Hash(CanonicalRequest)) ``` 参数说明如下。 |**参数** |**说明** | |---|---| |Algorithm |签名的算法，目前仅支持 HMAC\-SHA256 的签名算法。 | |RequestDate |请求 UTC 时间，请使用如下格式：`yyyyMMddTHHmmssZ`。 | |CredentialScope |凭证范围值，格式为：`yyyyMMdd/region/tos/request`。 | |CanonicalRequest |上一小节正规化请求的结果。 | #### 步骤 3：计算签名秘钥（SigningKey）在计算签名前，首先从私有访问密钥（Secret AccessKey）派生出签名密钥（SigningKey），而不是直接使用私有访问密钥。具体计算过程如下： ```Plain 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") ``` #### 步骤 4：计算种子签名 ```Plain Signature = HexEncode(HMAC-SHA256(kSigning, StringToSign)) ``` #### 步骤 5：构建 Authorization Header ```Plain Authorization: TOS4-HMAC-SHA256 Credential={AccessKeyId}/{CredentialScope},SignedHeaders={SignedHeaders}, Signature={Signature} ``` ### 计算链式签名 #### 计算每个分块的签名 **步骤 1：创建待签名字符串（StringToSign）** 签名字符串由签名算法、请求日期、信任状、前一个签名字符串、空行哈希值、分块内容哈希值组成，伪代码如下： ```Plain StringToSign = Algorithm + '\n' + RequestDate + '\n' + CredentialScope + '\n' + PreviousSignature + '\n' + Hash("") + '\n' + Hash(ChunkData) ```

说明

PreviousSignature 指前一个分块的签名。如果当前分块是第一个分块，那么 PreviousSignature 指步骤 4：计算种子签名获得的 SeedSignature。

Hash("") 为固定值：e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

**步骤 2：计算签名字符串** 本步骤计算过程与计算种子签名的步骤 3 和步骤 4 类似，具体计算过程，请参见[步骤 3：计算签名秘钥（SigningKey）](https://www.volcengine.com/docs/6349/1747877#634fbd18)和[步骤 4：计算种子签名](https://www.volcengine.com/docs/6349/1747877#7a84cbb0)，执行完成后，将获得 `ChunkSignature`。 **步骤 3：构建分块的负载** 将签名内容拼接到有效数据前方，格式如下： ```Plain string(IntHexBase(ChunkSize)) + ";chunk-signature=" + Signature + \r\n + ChunkData + \r\n ``` * IntHexBase() ：将整数转化为十六进制数的函数。例如，若分块大小为 65536，则十六进制字符串为“10000“。 * ChunkSize：分块有效数据大小，不包含签名和格式数据。 * Signature：[计算每个分块的签名](https://www.volcengine.com/docs/6349/1747877#d4fc0a20)的步骤 2 获得的签名字符串。 * ChunkData：分块有效数据。 #### 计算最后一个分块的签名在最后一个有效分块后，添加空分块的签名。具体计算过程，请参见[计算每个分块的签名](https://www.volcengine.com/docs/6349/1747877#d4fc0a20)的步骤 1 ～步骤 3 ，区别在于 `ChunkData` 为空。 #### 添加 Trailing Header **步骤 1：创建 Trailing Header 待签名字符串（StringToSign）** ```Plain StringToSign = Algorithm + '\n' + RequestDate + '\n' + CredentialScope + '\n' + PreviousSignature + '\n' + Hash(TrailingHeaderName:Base64EncodeCheckSum\n) ``` * PreviousSignature：前一个分块的签名，也就是[计算最后一个分块的签名](https://www.volcengine.com/docs/6349/1747877#1386b906)获得的空分块的签名。 * TrailingHeaderName：TrailingHeader 的 Key，由 x\-tos\-trailer 指定。 * Base64EncodeCheckSum：全部有效数据，基于 TrailingHeader 中的算法计算出的校验和，并进行了 Base64 编码。例如有效数据的 Base64Encode 校验和为 `smtwW8C72Y8=`，那么 `Hash(TrailingHeaderName:Base64EncodeCheckSum\n)`，等价于 `Hash("x-tos-hash-crc64ecma:smtwW8C72Y8=\n")`。 **步骤 2：计算签名字符串** 本步骤计算过程与计算种子签名的步骤 3 和步骤 4 类似，具体计算过程，请参见[步骤 3：计算签名秘钥（SigningKey）](https://www.volcengine.com/docs/6349/1747877#634fbd18)和[步骤 4：计算种子签名](https://www.volcengine.com/docs/6349/1747877#7a84cbb0)，执行完成后，将获得 `TrailingHeaderSignature`。 **步骤 3：构建分块的负载** ```Plain x-tos-hash-crc64ecma:Base64EncodeCheckSum x-tos-trailer-signature:TrailingHeaderSignature ```

说明

Base64EncodeCheckSum 指添加 Trailing Header 的步骤 1 计算得到的校验和。

TrailingHeaderSignature 指添加 Trailing Header 的步骤 2 计算得到的签名。

## 签名示例以下载对象为例，相关信息如下。 |**参数** |**值** | |---|---| |桶名 |examplebucket | |对象名 |exampleobject | |区域 |cn\-beijing | |时间 |Sat, 1 Jan 2022 00:00:00 GMT | |AccessKeyId |testAK | |SecretAccessKey |testSK | ### 计算种子签名 #### 步骤 1：构造规范化请求（CanonicalRequest） ```Plain PUT /exampleobject host:examplebucket.tos-cn-beijing.volces.com x-tos-date:20220101T000000Z Content-Encoding: tos-chunked x-tos-content-sha256:STREAMING-TOS4-HMAC-SHA256-PAYLOAD-TRAILER host;x-tos-content-sha256;x-tos-date STREAMING-TOS4-HMAC-SHA256-PAYLOAD ``` #### 步骤 2：创建签名字符串（StringToSign） ```Plain TOS4-HMAC-SHA256 20220101T000000Z 20220101/cn-beijing/tos/request c5b4f2fac36f0a3351d91753998bd811d1c446c186a2b3fb2b9e420630f13534 ``` #### 步骤 3：计算签名秘钥（SigningKey） ```Plain e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 ``` #### 步骤 4：计算种子签名 ```Plain d40b66cf0054d1642843670d10fa095e1609c7896f25df217770b0abe717693b ``` #### 步骤 5：构建 Authorization Header ```Plain TOS4-HMAC-SHA256 Credential=testAK/20220101/cn-beijing/tos/request,SignedHeaders=host;x-tos-content-sha256;x-tos-date,Signature=d40b66cf0054d1642843670d10fa095e1609c7896f25df217770b0abe717693b ``` ### 计算链式签名 #### 步骤 1：计算并添加第一个分块签名 |**示例** |**值** | |---|---| |签名字符串（StringToSign） |TOS4\-HMAC\-SHA256\-PAYLOAD

20220101T000000Z

20220101/cn\-beijing/tos/request

d40b66cf0054d1642843670d10fa095e1609c7896f25df217770b0abe717693b

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

bf718b6f653bebc184e1479f1935b8da974d701b893afcf49e701f3e2f9f9c5a | |签名 |b474d8862b1487a5145d686f57f013e54db672cee1c953b3010fb58501ef5aa2 | |分块数据 |10000;chunk\-signature=b474d8862b1487a5145d686f57f013e54db672cee1c953b3010fb58501ef5aa2

<65536\-bytes\> | #### 步骤 2：计算并添加第二个分块签名 |**示例** |**值** | |---|---| |签名字符串（StringToSign） |TOS4\-HMAC\-SHA256\-PAYLOAD

20220101T000000Z

20220101/cn\-beijing/tos/request

b474d8862b1487a5145d686f57f013e54db672cee1c953b3010fb58501ef5aa2

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

41edece42d63e8d9bf515a9ba6932e1c20cbc9f5a5d134645adb5db1b9737ea3 | |签名 |041169d545f3f4a02fe2e3d066bfb1798dd5f3417ae8cecd0e43690aafbe79d1 | |数据 |400;chunk\-signature=041169d545f3f4a02fe2e3d066bfb1798dd5f3417ae8cecd0e43690aafbe79d1

<1024 bytes\> | #### 步骤 3：计算并添加最后一个分块签名 |**示例** |**值** | |---|---| |StringToSign |TOS4\-HMAC\-SHA256\-PAYLOAD

20220101T000000Z

20220101/cn\-beijing/tos/request

041169d545f3f4a02fe2e3d066bfb1798dd5f3417ae8cecd0e43690aafbe79d1

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 | |签名 |e05ab64fe1dfdbf0b5870abbaabdb063c371d4e96f2767e6934d90529c5ae850 | |数据 |0;chunk\-signature=e05ab64fe1dfdbf0b5870abbaabdb063c371d4e96f2767e6934d90529c5ae850 | #### 步骤 4：添加 Trailing Header |**示例** |**值** | |---|---| |StringToSign |TOS4\-HMAC\-SHA256\-TRAILER

20220101T000000Z

20220101/cn\-beijing/tos/request

e05ab64fe1dfdbf0b5870abbaabdb063c371d4e96f2767e6934d90529c5ae850

2e4ab969aa65b1ad6def2db10e4d3a8260683d194dbaf757f90e8a37960a4b3c | |签名 |41e14ac611e27a8bb3d66c3bad6856f209297767d5dd4fc87d8fa9e422e03faf | |数据 |x\-tos\-hash\-crc64ecma:smtwW8C72Y8=

x\-tos\-trailer\-signature:41e14ac611e27a8bb3d66c3bad6856f209297767d5dd4fc87d8fa9e422e03faf | ## 签名方式 * [单分块上传的签名机制](https://www.volcengine.com/docs/6349/74839) * [多分块上传的签名机制](https://www.volcengine.com/docs/6349/1747876)

对象存储