Object Storage Service:(Recommended) V4 signatures in presigned URLs

Use OSS SDKs to generate presigned URLs

OSS SDKs handle signature calculation automatically. Use an SDK unless you have a specific reason to implement signing manually.

The following table lists the V4 signing implementation for each SDK.

Presigned URL structure

A presigned URL carries all authentication information as query parameters. The following example shows the structure (line breaks added for readability):

https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject
  ?x-oss-additional-headers=host
  &x-oss-credential=LTAI********************/20241203/cn-hangzhou/oss/aliyun_v4_request
  &x-oss-date=20241203T034420Z
  &x-oss-expires=86400
  &x-oss-signature=70c542eaf652ac291c0c343d63ac24ede41c0526661d9d4c63c0906a2686160c
  &x-oss-signature-version=OSS4-HMAC-SHA256

The forward slashes (/) in x-oss-credential are shown here for readability. In the actual request, URI-encode them as %2F. For example: &x-oss-credential=LTAI********************%2F20241203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request

(x-oss-date − 15 minutes)  ≤  T  ≤  (x-oss-date + x-oss-expires)

How it works

The V4 presigned URL signing process follows the same three-step approach as Authorization header signing, with these differences:

• The x-oss-content-sha256 payload hash header is not used. Replace it with the fixed string UNSIGNED-PAYLOAD.

• The x-oss-signature parameter is not included in the signature calculation.

• If a query parameter key matches a header being signed but the values differ, OSS returns an error. If a key has multiple values, all values are compared.

• When using STS temporary access credentials, include x-oss-security-token in the query string.

HTTP Verb + "\n" +
Canonical URI + "\n" +
Canonical Query String + "\n" +
Canonical Headers + "\n" +
Additional Headers + "\n" +
Hashed Payload

"GET\n" +
UriEncode(<Resource>) + "\n" +
UriEncode(<QueryParam1>) + "=" + UriEncode(<Value>) + "&" + UriEncode(<QueryParam2>) + "\n" +
Lowercase(<HeaderName1>) + ":" + Trim(<value>) + "\n" + Lowercase(<HeaderName2>) + ":" + Trim(<value>) + "\n\n" +
Lowercase(<AdditionalHeaderName1>) + ";" + Lowercase(<AdditionalHeaderName2>) + "\n" +
UNSIGNED-PAYLOAD

"OSS4-HMAC-SHA256" + "\n" +
dateTimeStr + "\n" +
dateStr + "/" + region + "/oss/aliyun_v4_request" + "\n" +
SHA256Hex(canonicalRequest)

String stringToSign = "OSS4-HMAC-SHA256\n" +
    dateTimeStr + "\n" +
    dateStr + "/cn-hangzhou/oss/aliyun_v4_request\n" +
    DigestUtils.sha256Hex(canonicalRequest);

signingKey = HMAC-SHA256(
               HMAC-SHA256(
                 HMAC-SHA256(
                   HMAC-SHA256("aliyun_v4" + accessKeySecret, dateStr),
                   region),
                 "oss"),
               "aliyun_v4_request")

signature = Hex(HMAC-SHA256(signingKey, stringToSign))

Complete example: generate a presigned GET URL

The following Java example calculates a V4 signature and builds a presigned URL for downloading an object. Replace the placeholder values (examplebucket, exampleobject, cn-hangzhou) with your actual values before running.

import com.aliyun.oss.common.utils.BinaryUtil;
import org.apache.commons.codec.digest.DigestUtils;
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.net.URL;
import java.time.ZonedDateTime;
import java.time.format.DateTimeFormatter;
import java.util.TimeZone;

public class Demo {

    public static void main(String[] args) throws Exception {
        // Load credentials from environment variables
        String accessKeyId     = System.getenv("OSS_ACCESS_KEY_ID");
        String accessKeySecret = System.getenv("OSS_ACCESS_KEY_SECRET");

        // Get the current UTC time
        ZonedDateTime now = ZonedDateTime.now(TimeZone.getTimeZone("UTC").toZoneId());
        String dateStr     = now.format(DateTimeFormatter.ofPattern("yyyyMMdd"));
        String dateTimeStr = now.format(DateTimeFormatter.ofPattern("yyyyMMdd'T'HHmmss'Z'"));

        // Step 1: Build the canonical request
        String canonicalRequest =
            "GET\n" +
            "/examplebucket/exampleobject\n" +
            "x-oss-additional-headers=host" +
                "&x-oss-credential=" + accessKeyId + "%2F" + dateStr + "%2Fcn-hangzhou%2Foss%2Faliyun_v4_request" +
                "&x-oss-date=" + dateTimeStr +
                "&x-oss-expires=86400" +
                "&x-oss-signature-version=OSS4-HMAC-SHA256\n" +
            "host:examplebucket.oss-cn-hangzhou.aliyuncs.com\n" +
            "\n" +
            "host\n" +
            "UNSIGNED-PAYLOAD";
        System.out.println("canonicalRequest:\n" + canonicalRequest);

        // Step 2: Build the string to sign
        String stringToSign =
            "OSS4-HMAC-SHA256\n" +
            dateTimeStr + "\n" +
            dateStr + "/cn-hangzhou/oss/aliyun_v4_request\n" +
            DigestUtils.sha256Hex(canonicalRequest);

        // Step 3: Derive the signing key and compute the signature
        byte[] dateKey              = hmacSHA256(("aliyun_v4" + accessKeySecret).getBytes(), dateStr);
        byte[] dateRegionKey        = hmacSHA256(dateKey, "cn-hangzhou");
        byte[] dateRegionServiceKey = hmacSHA256(dateRegionKey, "oss");
        byte[] signingKey           = hmacSHA256(dateRegionServiceKey, "aliyun_v4_request");

        String signature = BinaryUtil.toHex(hmacSHA256(signingKey, stringToSign));
        System.out.println("signature: " + signature);

        // Step 4: Assemble the presigned URL
        String endpoint    = "https://examplebucket.oss-cn-hangzhou.aliyuncs.com";
        String objectKey   = "exampleobject";
        String queryString =
            "x-oss-additional-headers=host" +
            "&x-oss-credential=" + accessKeyId + "%2F" + dateStr + "%2Fcn-hangzhou%2Foss%2Faliyun_v4_request" +
            "&x-oss-date=" + dateTimeStr +
            "&x-oss-expires=86400" +
            "&x-oss-signature=" + signature +
            "&x-oss-signature-version=OSS4-HMAC-SHA256";

        URL url = new URL(endpoint + "/" + objectKey + "?" + queryString);
        System.out.println("url: " + url);
    }

    public static byte[] hmacSHA256(byte[] key, String data) {
        try {
            SecretKeySpec secretKeySpec = new SecretKeySpec(key, "HmacSHA256");
            Mac mac = Mac.getInstance("HmacSHA256");
            mac.init(secretKeySpec);
            return mac.doFinal(data.getBytes());
        } catch (Exception e) {
            throw new RuntimeException("Failed to calculate HMAC-SHA256", e);
        }
    }
}

Sample output

signature: eee300fa39f52127a02af5f9bb86c0fd8b6776fc19101d9a6a7982c9d0edcc04
url: https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject?x-oss-additional-headers=host&x-oss-credential=LTAI********************%2F20241203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-date=20241203T032307Z&x-oss-expires=86400&x-oss-signature=eee300fa39f52127a02af5f9bb86c0fd8b6776fc19101d9a6a7982c9d0edcc04&x-oss-signature-version=OSS4-HMAC-SHA256

What's next

• Download or preview objects using presigned URLs — use a presigned GET URL to share objects without exposing credentials.

• Object uploads by using presigned URLs — use a presigned PUT URL to let clients upload directly to OSS.

• Garbled characters when previewing .txt objects — troubleshoot encoding issues when using a presigned URL to preview plain-text objects in a browser.