This article explains the TOS V4 signature calculation process and signature examples for single-part upload.

Functions required for signature

Function name	Description
UriEncode()	Encode the string with the following restrictions: ExceptA~Z、a ~z、0~9、-、.、_、~Characters, other characters must be encoded. Spaces must be encoded as %20 (encoding as+）。 Each URI encoded byte consists of%and two hexadecimal digits. The hexadecimal representation must use uppercase letters. Except for</a> in the object name/which does not require encoding, in other cases/must be encoded.
Lowercase()	Converts a string to lowercase.
Hex()	Performs hexadecimal encoding.
SHA256Hash()	Implements the SHA-256 algorithm.
HMAC-SHA256()	Implements the HMAC-SHA256 algorithm.
Trim()	Removes whitespaces from both sides of a string.

Signature calculation process

You can include a signature in the Authorization header of an HTTP request.

Step 1: Construct the canonical request (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 the 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 for headers 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 headers. If the request includes a Content-Type header, CanonicalHeaders must include this header. The host header must be included in CanonicalHeaders. When using temporary AK/SK authentication, x-tos-security-token must be included, and CanonicalHeaders must include this header. CanonicalHeaders must include all x-tos-* headers.
SignedHeaders	List the headers used for signature calculation: 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	Hex(SHA256Hash(<payload>)) represents the hexadecimal result of the SHA256 calculation on the request payload. tip If the request has no payload, calculate Hex(SHA256Hash("")) (using an empty string). The resultant value is e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855. In presigning scenarios, you can use UNSIGNED-PAYLOAD instead of calculating the payload.

Step 2: Create the string to sign (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 signing algorithm, currently only supporting HMAC-SHA256.
RequestDate	Request UTC time using the following format: yyyyMMddTHHmmssZ.
CredentialScope	Credential scope value, formatted as: yyyyMMdd/region/tos/request.
CanonicalRequest	The result of the normalized request from the previous section.

Step 3: Calculate the SigningKey

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

Step 4: Calculate the signature

Step 5: Construct the Authorization Header

In the expression{}The part represents the intermediate process calculated above.

Sample case

The following example objects include the related information below.

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

Step 1: build the CanonicalRequest

Step 2: create the StringToSign

Step 3: calculate the SigningKey

Step 4: calculate the signature

Step 5: construct the Authorization Header

Signature method

Signature mechanism for multipart uploads

Trailing Header for multipart uploads

Torch Object Storage