Docs

Torch Object Storage

Signature Mechanism

Pre-signed URL with the X-Tos-Policy query parameter

Typically, pre-signed URLs grant access to individual objects only. If you want a pre-signed URL that lists all directories in a bucket and enables querying and downloading objects under the directories, pre-sign the URL with the query parameter X-Tos-Policy. This topic describes how to use a pre-signed URL to grant access to a batch of objects within a validity period, without configuring the bucket or objects themselves.

Format of pre-signed URLs in listing scenarios

Parameters

Parameter	Description	Required
X-Tos-Algorithm	The version and algorithm of the signature. Currently, only TOS4-HMAC-SHA256 is supported.	Yes
X-Tos-Credential	Contains the AK, date, region, and service information format is <acces-key-id>/<date>/<region>/tos/request, where date is in yyyyMMdd format	Yes
X-Tos-Date	The UTC timestamp of the request in the format of yyyyMMddTHHmmssZ.	Yes
X-Tos-Expires	The validity period of the URL in seconds. This value is an integer with a minimum of 1 and a maximum of 2,592,000 (30 days), meaning the signature is valid for up to 30 days.	Yes
X-Tos-Policy	The access control policy of the pre-signed URL for objects in the bucket. The value should be a Base64-encoded policy.	Yes
X-Tos-Signature	The calculated signature.	Yes
X-Tos-Security-Token	When using the temporary AK/SK for authentication, this header must be present with the SecurityToken as its value.	No

Policy

The query parameter X-Tos-Policy value "Policy" is a JSON text encoded in UTF-8 and Base64. It declares the conditions the request using this URL must meet to validate the request's legitimacy.

Below is a sample policy.

Below are the "conditions" items supported in the policy.

Parameter	Type	Note	Restriction
bucket	string	Specifies the acceptable bucket name. Supported match type: Exact Match	There must be one and only one.
key	string	The object name or prefix of the object name. Supported match types: Exact Match, Starts With.	There must be one and can be multiple ones.

"Conditions" match types

Match Type	Note
Exact Match	The bucket name or object name must exactly match the value declared in "conditions". For example, to specify that the key must be "a", set a condition {"key": "a"}, which is equivalent to ["eq", "$key", "a"].
Starts With	The object name must start with the specified value. The following example shows that the object name must start with user/user1: ["starts-with", "$key", "user/user1/"]
Match Any Content	To apply no restriction to the object name, use "starts-with" with an empty value (""). The following example shows no validation on the key: ["starts-with", "$key", ""]

warning

When multiple key rules exist, the rules are combined with an OR relationship. If any one rule matches successfully, the request passes the validity check.

Signature calculation

This section describes the difference in signature calculation between using pre-signed URLs with the X-Tos-Policy query parameter and the Authorization header. The only difference lies in the construction of the CanonicalRequest; all other processes are the same.

CanonicalRequest contains only CanonicalQueryString and HashedPayload.

CanonicalQueryString contains only X-Tos-Algorithm, X-Tos-Credential, X-Tos-Date, X-Tos-Expires, X-Tos-Policy, and X-Tos-Security-Token.

When using a temporary AK/SK for authentication, X-Tos-Security-Token must be included.

Use UNSIGNED-PAYLOAD instead of HashedPayload, as the request content is unknown.

Sample pre-signing process

For the bucket examplebucket, to share all objects with the prefixes abc/ and aaa/abc/, as well as the two specific objects named exampleobject and exampleobject1, the following Policy can be constructed.

Below are the parameters for calculating the signature.

Parameter	Value
Region	cn-beijing
Request time	Sat, 1 Jan 2022 00:00:00 GMT
AccessKeyId	testAK
SecretAccessKey	testSK
Pre-signed URL validity period	86,400 seconds

Policy

Below is the Base64- and URL-encoded JSON policy.

CanonicalRequest

StringToSign

SigningKey

Signture

Generating the request URL

URL generation method

Concatenate the signature calculated above with CanonicalQueryString to yield the signature query parameters used to generate the URLs for ListObjects, ListObjectVersions, HeadObject, and GetObject methods. Using the signature query parameters, you can generate the respective URLs. The signature query parameters are as follows.

Concatenate the BucketName, EndPoint, Path, signature query parameters, and additional query parameters in the following manner to generate the request URL. For object listing, leave ObjectKey empty. For object querying and acquisition, ObjectKey is the object name. Additional query parameters relate to the method’s specific behavior and are explained in the next section.

warning

During URL generation, there is no strict requirement for the order of query parameters. In this document, the signature query parameters are placed before additional query parameters for illustration only.

Sample URL generation

Note:

examplebucket is the bucket name in the policy.

tos-cn-beijing.volces.com is the Endpoint, corresponding to the cn-beijing region used in signature calculation.

Listing objects

If other users want to list all objects shared with the prefix abc based on this signed query parameter, they can use the query parameter prefix=abc to generate the following specific URL, then access the URL via a GET request to list the objects.

Additional query parameters

Additional query parameters control certain specific behaviors of the request. For example, using the query parameter prefix=abc/abc/ lists objects with the prefix abc/abc/. Using the query parameter versions lists multiple versions of objects. For more parameter options, see the ListObjects and ListObjectVersions sections under request parameters and headers.

Querying/Getting an object

The URL for querying and getting an object is the same. Sending a HEAD request to the URL queries the information about that object, while sending a GET request gets the object.

The following URL queries/gets version 123 of object "exampleobject" in bucket "examplebucket":

Here, "examplebucket" is the bucket name in the policy, and "exampleobject" is the name of the object to query/get.

Additional query parameters:

Control the specific behavior of this request. For parameter options, see the headObject and getObject sections under request parameters and headers.

warning

You can control the behavior of headObject and getObject requests by carrying headers in the Header. If needed, include the corresponding headers in the request URL.

Last updated: 2026.08.10 10:28:50