Docs

Torch Object Storage

The header contains a signature

Header signature overview

When carrying a signature in the Header, the signature algorithm depends on the transfer method used when uploading the object. In object storage TOS, file upload transfer methods mainly include single-part upload and multipart upload, suitable for different file transfer scenarios.

Terminology

Terminology	Note
Checksum	A checksum is a data integrity verification mechanism used to detect errors or unintended modifications during data transmission or storage. Its core principle is to perform specific calculations on the original data to generate a short check value (the checksum). The recipient recalculates and compares the checksum to determine if the data has been corrupted. TOS currently supports two types of checksums: Checksum calculation based on the Md5 algorithm, added in the Header as Content-MD5. Checksum calculation based on the Sha256 algorithm, added in the Header as x-tos-content-sha256.
TOS V4 basic signing Header	The signature calculated based on the TOS V4 signature algorithm is included in the Header through the Authorization field. See Signature mechanism for single-part upload for detailed calculation method

Single-part upload

Single-part upload refers to the method of transferring all valid data in a single part.

When using the TOS V4 basic signature for single-part uploads, two signature calculation methods are supported: signature with checksum and signature without checksum. The details are as follows:

Using signature with checksum

You can include the checksum of valid data in the V4 basic signature calculation. If the content or checksum changes during data transfer, the signature verification will fail, ensuring security during the data transfer process.

However, to obtain the checksum of the valid data in advance, the client usually needs to load all data into memory first to calculate the checksum. Then, it must perform signature calculation based on the checksum. When sending data, the client reads the data into memory a second time for transmission, which may reduce client performance.

To ensure data integrity while avoiding loading all data into memory for checksum calculation at once, it is recommended to use multipart upload.

Use signature without checksum

When calculating the TOS V4 base signature, the checksum of valid data is not included. This method cannot guarantee data integrity in non-HTTPS scenarios and is not recommended.

Multipart upload

Multipart upload refers to splitting valid data into multiple fixed or variable length parts, then uploading them separately.

The data structure of a single part is as follows:

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

ChunkSize: the size of the valid data chunk (excluding signatures and format data). For example, when uploading a 65KB object with a fixed chunk size of 64KB, the data is split into three chunks: the first chunk is 64KB, the second chunk is 1KB, and the last chunk is 0 bytes.

Signature: the signature data of the chunk, required only when using chained signatures.

ChunkData: valid data of the chunk.

After the last chunk of valid data, a chunk containing 0 bytes must be written to indicate the end. The basic multi-chunk data format is as follows:

When signing multi-chunk uploads, TOS supports the following signature calculation methods:

Including only the TOS V4 basic signature

Similar to single-chunk uploads, when calculating the signature for multi-chunk uploads, it is possible to choose whether to include a checksum in the signature. If the checksum is included in the signature, the client still needs to read all data at once to calculate the checksum, causing additional performance overhead.

Includes TOS V4 basic signature plus chained signature

The TOS V4 basic signature does not carry checksum information, but each chunk of data begins with the chunk's signature information, which includes request parameters, the checksum of the current chunk's valid data, and the previous chunk's signature information. By calculating while transmitting, it effectively avoids performance degradation caused by the client reading all data at once to calculate the checksum. It also suits scenarios where the client cannot pre-calculate the checksum for all data due to unknown content length but must ensure data transmission security.

Multipart upload also supports using Trailing Header, which carries a checksum of all valid data after the last chunk, enabling data integrity verification on the server side. Trailing Header and chained signature are two different methods that both effectively ensure security during transmission. Users are advised to choose at least one or use both when uploading.

When using multipart upload, specify x-tos-content-sha256 to indicate the upload format and the signature method used.

Value of x-tos-content-sha256	Description
sha256 value of valid data	This indicates the header contains a TOS V4 base signature, and the V4 base signature includes a checksum of the valid data. Besides this, it does not include a chained signature or trailing header.
STREAMING-TOS4-HMAC-SHA256-PAYLOAD	This indicates the header contains a TOS V4 base signature, the data includes a chained signature calculated based on HMAC-SHA256, and the data end does not include a trailing header.
STREAMING-TOS4-HMAC-SHA256-PAYLOAD-TRAILER	This indicates that the Header contains the TOS V4 base signature, the data includes a chain signature calculated using HMAC-SHA256, and the data ends with a trailing header.
STREAMING-UNSIGNED-PAYLOAD-TRAILER	This indicates that 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	This indicates the header contains a TOS V4 base signature. The data does not include a chained signature, and the data end does not include a trailing header.

tip

Multipart upload can be used together with Transfer-Encoding: chunked. If Transfer-Encoding: chunked is used, the Content-Length header is not required.

Multipart upload request example

Without using chained signature and Trailing Header

PUT /objectName HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 GMT
Authorization: authorization string
Content-Encoding: tos-chunked
x-tos-content-sha256: STREAMING-UNSIGNED-PAYLOAD
x-tos-decoded-content-length: 12
Content-Length: 25

6
hello
5
world
1
!
0

Using chained signature without Trailing Header

PUT /objectName HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 GMT
Authorization: authorization string
Content-Encoding: tos-chunked
x-tos-content-sha256: STREAMING-TOS4-HMAC-SHA256-PAYLOAD
x-tos-decoded-content-length: 12
Content-Length: 342

6;chunk-signature=b474d8862b1487a5145d686f57f013e54db672cee1c953b3010fb58501ef5aa2
hello
5;chunk-signature=1a7e8d3c0f9b2a5e4d6c7b8a9f0e1d2c3b4a5d6e7f8091a2b3c4d5e6f7a8b9
world
1;chunk-signature=f42e5c8a3b7d6091e2a4f8c5d7b3a0e6f1c9d2a8b7e4f5c6d3e8a9b0c1d2e3
!
0;chunk-signature=b6c6ea8a5354eaf15b3cb7646744f4275b71ea724fed81ceb9323e279d449df9

Use trailing header without chain signature

PUT /objectName HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 GMT
Authorization: authorization string
Content-Encoding: tos-chunked
x-tos-content-sha256: STREAMING-UNSIGNED-PAYLOAD-TRAILER
x-tos-decoded-content-length: 12
Content-Length: 56
x-tos-trailer: x-tos-hash-crc64ecma

6
hello
5
world
1
!
0
x-tos-hash-crc64ecma:smtwW8C72Y8=

Use both chain signature and trailing header

PUT /objectName HTTP/1.1
Host: bucketname.tos-cn-beijing.volces.com
Date: Fri, 30 Jul 2021 08:05:36 GMT
Authorization: authorization string
Content-Encoding: tos-chunked
x-tos-content-sha256: STREAMING-AWS4-HMAC-SHA256-PAYLOAD-TRAILER
x-tos-trailer: x-tos-hash-crc64ecma
x-tos-decoded-content-length: 12
Content-Length: 464

6;chunk-signature=b474d8862b1487a5145d686f57f013e54db672cee1c953b3010fb58501ef5aa2
hello
5;chunk-signature=1a7e8d3c0f9b2a5e4d6c7b8a9f0e1d2c3b4a5d6e7f8091a2b3c4d5e6f7a8b9
world
1;chunk-signature=f42e5c8a3b7d6091e2a4f8c5d7b3a0e6f1c9d2a8b7e4f5c6d3e8a9b0c1d2e3
!
0;chunk-signature=b6c6ea8a5354eaf15b3cb7646744f4275b71ea724fed81ceb9323e279d449df9
x-tos-hash-crc64ecma:smtwW8C72Y8=
x-tos-trailer-signature:41e14ac611e27a8bb3d66c3bad6856f209297767d5dd4fc87d8fa9e422e03faf

Signature method

Signature mechanism for single-part upload

Signature mechanism for multipart upload

Trailing header for multipart upload

Last updated: 2025.10.15 14:28:34