Docs

Torch Object Storage

The header contains a signature

Signature mechanism for multi-part upload with trailing header

During multi-part upload, TOS supports carrying the checksum of valid data at the end of the data in the form of a trailing header. The server calculates the checksum based on the received data and compares it with the checksum in the trailing header to verify data integrity. This document describes the signature calculation process and signature examples when using trailing header and chained signature.

Functions required for signature

tip

Trailing header can be used independently. If used independently, this chapter's content does not apply. For details, see Header Signature Overview.

Function	Feature description
UriEncode()	Encode the string with the following restrictions: Except forA~Z、a ~z、0~9、-、.、_、~Characters must be encoded except for the listed characters. Spaces must be encoded as %20 (encoding as is not supported+）。 Each URI-encoded byte consists of%and two hexadecimal digits. The hexadecimal representation must use uppercase letters. Except for object names/No encoding required, otherwise/Encoding is required.
Lowercase()	Converts a string to lowercase.
Hex()	Performs hexadecimal encoding on a string.
SHA256Hash()	Implements the SHA-256 algorithm.
HMAC-SHA256()	Implements the HMAC-SHA256 algorithm.
Trim()	Removes whitespaces from both sides of a string.

Signature header

Header name	Description
x-tos-content-sha256	Specifies the format of the client-uploaded file and the signature method used. The values are explained as follows: STREAMING-TOS4-HMAC-SHA256-PAYLOAD: Indicates that the header contains the basic TOS V4 signature and the data includes a chained signature calculated based on HMAC-SHA256. The data does not contain a trailing header at the end. STREAMING-TOS4-HMAC-SHA256-PAYLOAD-TRAILER: indicates the Header contains the TOS V4 base signature, the data includes a chain signature calculated based on HMAC-SHA256, and the data ends with a Trailing Header. STREAMING-UNSIGNED-PAYLOAD-TRAILER: indicates the Header contains the TOS V4 base signature, the data does not include a chain signature, and the data ends with a Trailing Header. STREAMING-UNSIGNED-PAYLOAD: indicates the Header contains the TOS V4 base signature, the data does not include a chain signature, and the data does not end with a Trailing Header.
Content-Encoding	In this scenario, when the Content-Encoding value includes tos-chunked, it indicates that uploading data in multiple chunks is allowed and must be used together with x-tos-content-sha256. tip When saving an object, TOS does not store the tos-chunked attribute as user data, nor does it return the tos-chunked attribute in Content-Encoding when downloading the object.
x-tos-trailer	Indicates the algorithm used for checksum in Trailing Header; the value can only be x-tos-hash-crc64ecma. It must be used together with x-tos-content-sha256 and Content-Encoding: tos-chunked.
x-tos-decoded-content-length	Used for server-side verification of the received valid data length. Optional, set to the original file size. tip When setting the x-tos-decoded-content-length value, exclude the length of format data, signature data, and trailing header data introduced by multi-chunk encoding. For example: to upload a 4GB file, set the value to 4294967296.
Content-Length	Optional, the length of the HTTP request body. tip When setting the Content-Length value, include the length of format data introduced by chunked encoding, signature data, and trailing header data. Transfer-Encoding: chunked must be default for this transmission method.

Signature calculation process

tip

Hash() uses the SHA-256 algorithm.

HexEncode() converts text into hexadecimal encoding.

TOS supports access requests compatible with S3 Multiple Chunks Including Trailing Headers. You can also use the S3 Multiple Chunks Including Trailing Headers method to upload objects to TOS.

Calculate seed signature

Step 1: Construct the CanonicalRequest

The parameters are described below.

Parameter	Description
HTTPMethod	The method used by the HTTP request, for example, PUT, GET, HEAD, or DELETE.
CanonicalURI	UriEncode(<PATH>) If the PATH in the URL is empty, CanonicalURI is/。 If the full path is [https://bucketname.tos-cn-beijing.volces.com/object](https://bucketname.tos-cn-beijing.volces.com/object), CanonicalURI is /object.
CanonicalQueryString	Encoding format of Query parameters in request: UriEncode(<QueryParam1>) + '=' + UriEncode(<value>) + '&' + UriEncode(<QueryParam2>) + '=' + UriEncode(<value>) + '&' + ... UriEncode(<QueryParamN>) + '=' + UriEncode(<value>) tip Sort the encoded query parameters as per ASCII values of the characters. All query parameters must be included. If there are no query parameters, CanonicalQueryString is an empty string.
CanonicalHeaders	Encoding format of the header in the request: Lowercase(<HeaderName1>) + ':' + Trim(<value>) + '\n' Lowercase(<HeaderName2>) + ':' + Trim(<value>) + '\n' ... Lowercase(<HeaderNameN>) +':' + Trim(<value>) + '\n' tip Sort the HeaderNames in lexicographic order. CanonicalHeaders do not need to include all header fields. If the request contains the Content-Type header, CanonicalHeaders must include it. The host header must be included in CanonicalHeaders. When using temporary AK/SK authentication, the x-tos-security-token must be included, and CanonicalHeaders must include this header. CanonicalHeaders must include all x-tos-* headers.
SignedHeaders	Specify the headers to include in the signature: Lowercase(<HeaderName1>) + ';' + Lowercase(<HeaderName2>) + ... + Lowercase(<HeaderNameN>) tip Sort the HeaderNames in CanonicalHeaders in lexicographic order. HeaderNames in SignedHeaders must be present in the request header.
HashedPayload	Constant: STREAMING-TOS4-HMAC-SHA256-PAYLOAD-TRAILER

Step 2: Create the StringToSign

A StringToSign contains metadata of the request and canonical request. It is a concatenation of the signing algorithm, request date, credential scope, and hashed canonical request, as shown below:

The parameters are described below.

Parameter	Note
Algorithm	The signature algorithm currently supports only the HMAC-SHA256 algorithm.
RequestDate	Request UTC time using the format: yyyyMMddTHHmmssZ.
CredentialScope	Credential scope value in the format: yyyyMMdd/region/tos/request.
CanonicalRequest	Result of the normalization request in the previous section.

Step 3: Calculate the SigningKey

Before calculating the signature, derive SigningKey from the SK instead of using the latter directly. The calculation process is as follows:

Step 4: calculate the seed signature

Step 5: build the authorization header

calculate the chained signature

calculate the signature of each chunk

Step 1: create the string to sign (StringToSign)

The string to sign consists of the signing algorithm, request date, credential scope, previous signature string, empty line hash value, and chunk content hash value, as shown in the pseudocode below:

tip

PreviousSignature refers to the signature of the previous chunk. If the current chunk is the first chunk, PreviousSignature refers to the seed signature calculated in step 4 as SeedSignature.

Hash("") is a fixed value: e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Step 2: calculate the signature string

This step's calculation process is similar to steps 3 and 4 of computing the seed signature. For detailed calculation, see Step 3: Calculate the SigningKey and Step 4: Calculate the Seed Signature. After completion, you will obtain the ChunkSignature.

Step 3: Construct the chunk payload

Attach the signature content before the valid data in the following format:

IntHexBase(): a function that converts integers to hexadecimal numbers. For example, if the chunk size is 65536, the hexadecimal string is "10000".

ChunkSize: the size of the chunk's valid data, excluding signature and format data.

Signature: the signature string obtained from Step 2 of calculating each chunk's signature.

ChunkData: the chunk's valid data.

Calculate the signature of the last chunk

After the last valid chunk, add the signature of an empty chunk. For the detailed calculation process, refer to steps 1 to 3 of calculating the signature of each chunk, with the difference that ChunkData is empty.

Add trailing header

Step 1: Create the trailing header string to sign (StringToSign)

PreviousSignature: the signature of the previous chunk, which is the signature of the empty chunk obtained from calculating the signature of the last chunk.

TrailingHeaderName: the key of the trailing header, specified by x-tos-trailer.

Base64EncodeCheckSum: the checksum of all valid data calculated using the algorithm in the trailing header and then Base64 encoded. For example, if the Base64Encode checksum of the valid data is smtwW8C72Y8=, then Hash(TrailingHeaderName:Base64EncodeCheckSum\n) is equivalent to Hash("x-tos-hash-crc64ecma:smtwW8C72Y8=\n").

Step 2: Calculate the signature string

This step's calculation is similar to steps 3 and 4 of calculating the seed signature. For detailed calculation, see step 3: calculate signing key (SigningKey) and step 4: calculate seed signature. After completion, TrailingHeaderSignature is obtained.

Step 3: Construct the chunk's payload

tip

Base64EncodeCheckSum refers to the checksum calculated in step 1 of adding the Trailing Header.

TrailingHeaderSignature refers to the signature calculated in step 2 of adding the Trailing Header.

Sample case

Taking the downloaded object as an example, the related information is as follows.

Parameter	Value
Bucket name	examplebucket
Object name	exampleobject
Region	cn-beijing
Time	Sat, 1 Jan 2022 00:00:00 GMT
AccessKeyId	testAK
SecretAccessKey	testSK

Calculate the seed signature

Step 1: Construct the CanonicalRequest

Step 2: Create the StringToSign

Step 3: Calculate the SigningKey

Step 4: Calculate the seed signature

Step 5: Build the Authorization Header

calculate chained signature

step 1: calculate and add the first chunk signature

Example	Value
signature string (StringToSign)	TOS4-HMAC-SHA256-PAYLOAD 20220101T000000Z 20220101/cn-beijing/tos/request d40b66cf0054d1642843670d10fa095e1609c7896f25df217770b0abe717693b e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 bf718b6f653bebc184e1479f1935b8da974d701b893afcf49e701f3e2f9f9c5a
Signature	b474d8862b1487a5145d686f57f013e54db672cee1c953b3010fb58501ef5aa2
chunked data	10000;chunk-signature=b474d8862b1487a5145d686f57f013e54db672cee1c953b3010fb58501ef5aa2 <65536-bytes>

step 2: calculate and add the second chunk signature

Example	Value
Signature string (StringToSign)	TOS4-HMAC-SHA256-PAYLOAD 20220101T000000Z 20220101/cn-beijing/tos/request b474d8862b1487a5145d686f57f013e54db672cee1c953b3010fb58501ef5aa2 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 41edece42d63e8d9bf515a9ba6932e1c20cbc9f5a5d134645adb5db1b9737ea3
Signature	041169d545f3f4a02fe2e3d066bfb1798dd5f3417ae8cecd0e43690aafbe79d1
Data	400;chunk-signature=041169d545f3f4a02fe2e3d066bfb1798dd5f3417ae8cecd0e43690aafbe79d1 <1024 bytes>

step 3: calculate and add the last chunk signature

Example	Value
StringToSign	TOS4-HMAC-SHA256-PAYLOAD 20220101T000000Z 20220101/cn-beijing/tos/request 041169d545f3f4a02fe2e3d066bfb1798dd5f3417ae8cecd0e43690aafbe79d1 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
Signature	e05ab64fe1dfdbf0b5870abbaabdb063c371d4e96f2767e6934d90529c5ae850
Data	0;chunk-signature=e05ab64fe1dfdbf0b5870abbaabdb063c371d4e96f2767e6934d90529c5ae850

step 4: add trailing header

Example	Value
StringToSign	TOS4-HMAC-SHA256-TRAILER 20220101T000000Z 20220101/cn-beijing/tos/request e05ab64fe1dfdbf0b5870abbaabdb063c371d4e96f2767e6934d90529c5ae850 2e4ab969aa65b1ad6def2db10e4d3a8260683d194dbaf757f90e8a37960a4b3c
Signature	41e14ac611e27a8bb3d66c3bad6856f209297767d5dd4fc87d8fa9e422e03faf
Data	x-tos-hash-crc64ecma:smtwW8C72Y8= x-tos-trailer-signature:41e14ac611e27a8bb3d66c3bad6856f209297767d5dd4fc87d8fa9e422e03faf

signature method

single-chunk upload signature mechanism

multi-chunk upload signature mechanism

Last updated: 2025.10.15 14:28:34