SDK簽名實現

OSS SDK已實現自動完成V4簽名。推薦采用OSS SDK的方式發起請求，可以免去手動簽名的過程。如果您想了解具體語言的簽名實現，請參考OSS SDK的代碼。OSS SDK簽名實現的文件請參見下表。

URL簽名描述

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

  上述URL中的x-oss-credential的值為方便展示各個字段的參數，使用正斜線（/）進行分隔。在實際請求時，需要對URL中的/執行UrlEncode，即轉化成%2F，示例如下：

  &x-oss-credential=LTAI********************%2F20241203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request

• URL中的QueryString參數說明

  參數	類型	是否必選	示例值	說明
  x-oss-signature-version	字符串	是	OSS4-HMAC-SHA256	指定簽名的版本和算法，固定值為OSS4-HMAC-SHA256。
  x-oss-credential	字符串	是	LTAI********************/20241203/cn-hangzhou/oss/aliyun_v4_request	指明派生密鑰的參數集，格式如下： LTAI********************/<date>/<region>/oss/aliyun_v4_request AccessKeyId：填寫訪問密鑰中的AccessKey ID。 date：填寫請求的日期， region：填寫請求所在的Region。 oss：請求的服務名稱，固定為oss。 aliyun_v4_request：請求的版本說明，固定為aliyun_v4_request。
  x-oss-date	字符串	是	20241203T034420Z	簽名URL的起始時間，為避免時鐘誤差，允許向后偏移15分鐘，格式為ISO8601。 說明 該時間用作StringToSign中的TimeStamp，取值必須與創建SigningKey中的Date是同一天。
  x-oss-expires	整數	是	3600	簽名URL的有效時長，單位為秒（s）。最小值為1，最大值為 604800（即7 天）。
  x-oss-additional-headers	字符串	否	host	除默認要加入簽名的Header以外，指定其他也需要簽名的Header。例如：添加簽名host，并禁止修改請求的域名。 該字段的構建方法說明如下： 額外頭部中的所有Header均要求小寫。 按照字典序升序排列額外頭部中的所有Header。 以分號連接數組中的元素，獲取字符串。
  x-oss-signature	字符串	是	77Dv****************	用于簽名認證的描述信息。x-oss-signature不參與簽名計算。
  x-oss-security-token	字符串	否	CAIS********************************	STS安全令牌。僅當使用STS構造URL簽名時，才需要設置此參數。

簽名計算過程

URL簽名計算方法與Header簽名計算方法基本類似。但由于簽名URL使用方法的不同，與Header簽名計算仍存在以下差異：

• 簽名URL的方式不包含描述payload的Header（x-oss-content-sha256）。原因是創建預簽名時，無法預估實際傳輸的payload。因此，在URL簽名過程中，直接使用UNSIGNED-PAYLOAD。

• 如果簽名URL的QueryParameter與待簽名Header中的Key相同但Value不同的情況，會出現報錯。同一個Key有多個Value的情況，會同時比較Key對應的所有Value，如果Value不一致也會出現報錯。

• 簽名URL中，如果通過STS訪問OSS，必須在QueryString中添加x-oss-security-token。

• QueryString中的x-oss-signature不參與簽名。

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

簽名計算示例

以創建一個預簽名URL，分享給其他用戶上傳數據為例，演示如何在URL包含V4簽名。

• 計算參數示例

  參數	值
  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

在URL包含V4簽名的步驟如下：

1. 構造CanonicalRequest。

   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. 構造待簽名字符串（StringToSign）。

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

3. 計算簽名。

   1. 計算SigningKey。

      說明

      為方便可讀，如下為SigningKey經Base64編碼后的字符串。

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

   2. 計算Signature。

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

4. 在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);

簽名計算完整示例代碼

使用上述計算參數示例，通過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 {

    /**
     * 簽名計算工具
     *
     * @return url
     */
    public static void main(String[] args) throws Exception {
        // 運行本代碼示例之前，請確保已設置環境變量OSS_ACCESS_KEY_ID和OSS_ACCESS_KEY_SECRET。
        String accesskeyid =  System.getenv().get("OSS_ACCESS_KEY_ID");
        String accesskeysecret =  System.getenv().get("OSS_ACCESS_KEY_SECRET");
        // 獲取當前時間并格式化為指定的 ISO8601 格式
        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'"));
        // 步驟1：構造CanonicalRequest。
        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);
        // 步驟2：構造待簽名字符串（StringToSign）。
        String stringToSign = "OSS4-HMAC-SHA256\n" +
                dateTimeStr + "\n" +
                dateStr + "/cn-hangzhou/oss/aliyun_v4_request\n" +
                DigestUtils.sha256Hex(canonicalRequest);

        // 步驟3：計算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);

        // 步驟4：在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 {
            // 初始化HMAC密鑰規格，指定算法為HMAC-SHA256并使用提供的密鑰。
            SecretKeySpec secretKeySpec = new SecretKeySpec(key, "HmacSHA256");

            // 獲取Mac實例，并通過getInstance方法指定使用HMAC-SHA256算法。
            Mac mac = Mac.getInstance("HmacSHA256");
            // 使用密鑰初始化Mac對象。
            mac.init(secretKeySpec);

            // 執行HMAC計算，通過doFinal方法接收需要計算的數據并返回計算結果的數組。
            byte[] hmacBytes = mac.doFinal(data.getBytes());

            return hmacBytes;
        } catch (Exception e) {
            throw new RuntimeException("Failed to calculate HMAC-SHA256", e);
        }
    }
}

返回結果如下：

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