Object Storage Service:Include a V4 signature in a URL (recommended)

Use OSS SDKs to automatically implement V4 signatures

OSS SDKs support the automatic implementation of V4 signatures. We recommend that you use OSS SDKs to initiate requests. This eliminates the need to manually calculate signatures. For more information about how to sign requests by using the V4 signature algorithm when you use OSS SDKs for different programming languages, see the sample code of OSS SDKs. The following table provides references to the sample code used to sign requests by using the V4 signature algorithm when you use OSS SDKs for different programming languages.

URL signing

• Example

  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=20241203T034420Z&x-oss-expires=86400&x-oss-signature=70c542eaf652ac291c0c343d63ac24ede41c0526661d9d4c63c0906a2686160c&x-oss-signature-version=OSS4-HMAC-SHA256

  For readability, the fields in the x-oss-credential parameter in the preceding URL are separated by forward slashes (/). When you initiate a request, URI-encode the forward slashes (/) in the URL to convert them into %2F. Example:

  &x-oss-credential=<AccessKeyId>%2F20241203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request

• Query string parameters

  Parameter	Type	Required	Example	Description
  x-oss-signature-version	String	Yes	OSS4-HMAC-SHA256	The signature version and the algorithm used to calculate the signature. Set the value to OSS4-HMAC-SHA256.
  x-oss-credential	String	Yes	LTAI********************/20241203/cn-hangzhou/oss/aliyun_v4_request	The credentials that you can use to calculate the signature. Format: LTAI********************/<date>/<region>/oss/aliyun_v4_request AccessKeyId: the AccessKey ID in the AccessKey pair. date: the date when the request was initiated. region: the region in which the requested resource resides. oss: the name of the requested service. Set the value to oss. aliyun_v4_request: the description of the signature version in the request. Set the value to aliyun_v4_request.
  x-oss-date	String	Yes	20241203T034420Z	The time when the URL was signed. The time follows the ISO 8601 standard. To avoid time differences, an offset of 15 minutes after the URL was signed is allowed. Note The time is used as the timestamp for the string to sign. The value must be the same as that of the date field in the derived signing key.
  x-oss-expires	Integer	Yes	3600	The validity period of the signed URL. Unit: seconds. Minimum value: 1. Maximum value: 604800.
  x-oss-additional-headers	String	No	host	The headers that you want to add to calculate the signature. For example, you can add the host header. This way, the domain name from which the request is initiated cannot be changed. The following items describe the requirements for constructing the header: All headers in the x-oss-additional-headers parameter must be in lowercase letters. All headers in the x-oss-additional-headers parameter must be sorted in alphabetical order. All headers in an array are separated by semicolons (;) to obtain a string.
  x-oss-signature	String	Yes	77Dv****************	The description of the signature verification. The x-oss-signature parameter is not included in the signature calculation.
  x-oss-security-token	String	No	CAIS********************************	The security token issued by Security Token Service (STS). This parameter is required only when you use a security token to calculate a signature for the URL.

Signature calculation process

The method used to calculate a signature for a URL is similar to the method used to calculate a signature for the Authorization header. The following items describe the differences between the two methods:

• The x-oss-content-sha256 header that describes a payload hash is not used to calculate a signature for a URL. When you create a signed URL, you cannot evaluate the payload content. Instead, UNSIGNED-PAYLOAD is used.

• If a key in the query string parameters of a signed URL is the same as a header to be signed but their values are different, an error is reported. If a key has multiple values, all values of the key are compared at the same time. If the values are different, an error is reported.

• If you use the access credentials obtained from STS to access OSS resources in a signed URL, you must add the x-oss-security-token parameter to the query string of the URL.

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

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

"GET" | "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

Signature calculation example

In this example, a signed URL is created. You can share the signed URL to third-party users to allow the users to upload data to OSS. The following section describes how to include a V4 signature in the URL.

• Parameters

  Parameter	Example
  AccessKeyId	accesskeyid
  AccessKeySecret	accesskeysecret
  Bucket	examplebucket
  Object	exampleobject
  Region	cn-hangzhou

• GetObject

  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
  host:examplebucket.oss-cn-hangzhou.aliyuncs.com

To include a V4 signature in a URL, perform the following steps:

1. Create a canonical request.

   String resourcePath = "exampleobject";
           String endpoint = "https://examplebucket.oss-cn-hangzhou.aliyuncs.com";
           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";
   
           String urlStr = endpoint + "/" + resourcePath + "?" + queryString;
           URL url = new URL(urlStr);

2. Create a string to sign.

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

3. Calculate the signature.

   1. Calculate the signing key.

      Note

      For readability, the following example describes the Base64-encoded value of the signing key.

       dateKey = hmacsha256(("aliyun_v4" + accesskeysecret).getBytes(), dateStr);
       dateRegionKey = hmacsha256(dateKey, "cn-hangzhou");
       dateRegionServiceKey = hmacsha256(dateRegionKey, "oss");
       signingKey = hmacsha256(dateRegionServiceKey, "aliyun_v4_request");

   2. Calculate the signature.

      result = hmacsha256(signingKey, stringToSign);
      String signature = BinaryUtil.toHex(result);
      signature:eee300fa39f52127a02af5f9bb86c0fd8b6776fc19101d9a6a7982c9d0edcc04

4. Add the signature to the URL.

   String resourcePath = "exampleobject";
           String endpoint = "https://examplebucket.oss-cn-hangzhou.aliyuncs.com";
           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";
   
           String urlStr = endpoint + "/" + resourcePath + "?" + queryString;
           URL url = new URL(urlStr);
           System.out.println("url:" + url);

Complete sample code used to obtain a V4 signed URL

The parameters provided in the preceding signature calculation example are used to describe the complete process of obtaining a V4 signed URL by using OSS SDK for Java.

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 {

    /**
     * Signature calculation tool
     *
     * @return url
     */
    public static void main(String[] args) throws Exception {
        // Before you run the sample code, make sure that the OSS_ACCESS_KEY_ID and OSS_ACCESS_KEY_SECRET environment variables are configured. 
        String accesskeyid =  System.getenv().get("OSS_ACCESS_KEY_ID");
        String accesskeysecret =  System.getenv().get("OSS_ACCESS_KEY_SECRET");
        // Query and display the current time in the ISO 8601 standard.
        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: Create a 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:" + canonicalRequest);
        // Step 2: Create a string to sign. 
        String stringToSign = "OSS4-HMAC-SHA256\n" +
                dateTimeStr + "\n" +
                dateStr + "/cn-hangzhou/oss/aliyun_v4_request\n" +
                DigestUtils.sha256Hex(canonicalRequest);

        // Step 3: Calculate 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");

        byte[] result = hmacsha256(signingKey, stringToSign);
        String signature = BinaryUtil.toHex(result);
        System.out.println("signature:" + signature);

        // Step 4: Add the signature to the URL. 
        String resourcePath = "exampleobject";
        String endpoint = "https://examplebucket.oss-cn-hangzhou.aliyuncs.com";
        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";

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

    public static byte[] hmacsha256(byte[] key, String data) {
        try {
            // Initialize the HMAC key specification, set the algorithm to HMAC-SHA256, and use the provided key. 
            SecretKeySpec secretKeySpec = new SecretKeySpec(key, "HmacSHA256");

            // Obtain a Mac instance and use the getInstance method to set the algorithm to HMAC-SHA256. 
            Mac mac = Mac.getInstance("HmacSHA256");
            // Use the key to initialize the Mac instance. 
            mac.init(secretKeySpec);

            // Calculate the HMAC value. Use the doFinal method to receive the data to be calculated and return the calculation results in arrays. 
            byte[] hmacBytes = mac.doFinal(data.getBytes());

            return hmacBytes;
        } 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