在URL中包含V4簽名（推薦） - Object Storage Service

除了通過HTTP要求標頭部的Authorization欄位進行簽名授權外，您還可以產生一個包含簽名和其他必要的請求資訊的預簽名URL。通過這種方式，您可以在不透露訪問憑證的情況下，授予第三方在特定有效期間內對OSS資源的存取權限。本文介紹如何使用V4簽名演算法實現在URL中包含簽名。

SDK簽名實現

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

SDK	用戶端初始化樣本	簽名實現
Java	初始化	OSSV4Signer.java
PHP	初始化	SignerV4.php
Node.js	初始化	signatureUrlV4.js
Browser.js	初始化	signatureUrlV4.js
Python	初始化	auth.py
Go	初始化	v4.go
C++	初始化	SignerV4.cc
C	初始化	oss_auth.c

URL簽名描述

樣本

https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject?x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=<AccessKeyId>/20231203/cn-hangzhou/oss/aliyun_v4_request&x-oss-date=20231203T121212Z&x-oss-expires=86400&x-oss-additional-headers=host&x-oss-signature=<signature-to-be-calculated>

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

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

URL中的QueryString參數說明

參數	類型	是否必選	樣本值	說明
x-oss-signature-version	字串	是	OSS4-HMAC-SHA256	指定簽名的版本和演算法，固定值為OSS4-HMAC-SHA256。
x-oss-credential	字串	是	LTAI********************/20231203/cn-hangzhou/oss/aliyun_v4_request	指明衍生金鑰的參數集，格式如下： `<AccessKeyId>/<date>/<region>/oss/aliyun_v4_request` AccessKeyId：填寫存取金鑰中的AccessKey ID。 date：填寫請求的日期， region：填寫請求所在的Region。 oss：請求的服務名稱，固定為oss。 aliyun_v4_request：請求的版本說明，固定為aliyun_v4_request。
x-oss-date	字串	是	20231203T121212Z	簽名URL的起始時間，為避免時鐘誤差，允許向後位移15分鐘，格式為ISO8601。說明該時間用作StringToSign中的TimeStamp，取值必須與建立SigningKey中的Date是同一天。
x-oss-expires	整數	是	3600	簽名URL的有效時間長度，單位為秒（s）。最小值為1，最大值為 604800（即7 天）。
x-oss-additional-headers	字串	否	host	除預設要加入簽名的Header以外，指定其他需要簽名的Header。建議將請求中使用的所有Header都加入簽名。該欄位的構建方法說明如下：額外頭部中的所有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不參與簽名。

步驟1：構造CanonicalRequest

按照OSS簽名定義的規範，對請求進行格式化。

格式

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

各參數說明如下：

參數	類型	是否必選	樣本	說明
HTTP Verb	枚舉值	是	PUT	HTTP請求的Method，包含PUT、GET、POST、HEAD、DELETE、OPTIONS等。
Canonical URI	字串	是	/examplebucket/exampleobject	URI進行UriEncode後的字串，其中正斜線（/）不需要編碼。如果URI中不包含QueryString，則從正斜線（`/`）開始到URI末尾。如果URI中包含QueryString，則從正斜線（`/`）開始到問號（？）結束。根據請求URI包含的資源有差異，Canonical URI的填寫方法說明如下：如果請求的URI中既包含Bucket也包含Object，則Canonical URI填寫樣本為 `/examplebucket/exampleobject`。如果請求的URI中只包含Bucket不包含Object，則Canonical URI填寫樣本為`/examplebucket/`。如果請求的URI中不包含Bucket只包含Object，則Canonical URI填寫樣本為`/`。
Canonical Query String	字串	是	UriEncode("marker") + "=" + UriEncode("someMarker") + "&" + UriEncode("max-keys") + "=" + UriEncode("20") + "&" + UriEncode("prefix") + "=" + UriEncode("somePrefix")	針對QueryString執行UriEncode後的字串，單獨對key和value進行編碼。按QueryString的key進行排序，先編碼，再排序。如果有多個相同的key，按照原來添加的順序放置即可。只有key沒有value的情況下，只添加 key即可。如果沒有QueryString，則只需要放置Null 字元串`“”`，末尾仍然需要有分行符號。如果簽名URL的QueryParameter與待簽名Header中的Key相同但Value不同的情況，會出現報錯。同一個Key有多個Value的情況，會同時比較Key對應的所有Value，如果Value不一致也會出現報錯。
Canonical Headers	字串	是	`host:cname.com x-oss-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855 x-oss-date:20231203T121212Z`	對請求Header的列表格式化後的字串，Canonical Headers末尾仍需要添加分行符號。單個Header中的key和value通過冒號`:`分隔，Header與Header之間通過分行符號分隔。 Header的key必須小寫，value必須經過Trim（去除頭尾的空格）。按Header中key的字典序進行排列。請求時間通過`x-oss-date`來描述，要求格式必須是FormatISO8601（樣本值為20231203T121212Z）。簽名URL的方式不包含描述payload的Header（`x-oss-content-sha256`）。原因是建立預簽名時，無法預估實際傳輸的payload。因此，在URL簽名過程中，直接使用UNSIGNED-PAYLOAD。 Canonical Headers包含以下兩類： AdditionalHeader指定必須存在且參與簽名的Header 如果存在則加入簽名的Header包括： Content-Type Content-MD5 x-oss-*
Additional Headers	字串	是	content-length;host	用於指定需要加入簽名的Header。所有的Header必須是小寫，且按照字典序排列。
Hashed PayLoad	字串	是	UNSIGNED-PAYLOAD	僅支援UNSIGNED-PAYLOAD。

樣本

"GET" | "PUT" | ... + "\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

步驟2：構造待簽名字串（StringToSign）

將格式化後的請求進行統一的計算處理，得到待簽名的字串。

格式

"OSS4-HMAC-SHA256" + "\n" +
TimeStamp + "\n" +
Scope + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))

參數說明如下：

參數	類型	是否必選	樣本	說明
OSS4-HMAC-SHA256	枚舉值	是	OSS4-HMAC-SHA25	指明使用的簽名雜湊演算法，取值必須是OSS4-HMAC-SHA256。
TimeStamp	字串	是	20231203T121212Z	指明當前的UTC時間，格式必須是 ISO8601。
Scope	字串	是	20231203/cn-hangzhou/oss/aliyun_v4_request	指明擷取Region衍生金鑰的參數集，格式如下： `<SignDate>/<Region>/oss/aliyun_v4_request` SignDate：填寫請求的日期。 Region：填寫請求所在的Region。 oss：請求的服務名稱，固定為oss。 aliyun_v4_request：請求的版本說明，固定為aliyun_v4_request。
CanonicalRequest	字串	是	PUT /examplebucket/exampleobject x-oss-additional-headers=host&x-oss-credential=accesskeyid%2F20231203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-date=20231203T121212Z&x-oss-expires=86400&x-oss-signature-version=OSS4-HMAC-SHA256 host:examplebucket.oss-cn-hangzhou.aliyuncs.com x-oss-meta-author:alice x-oss-meta-magic:abracadabra host UNSIGNED-PAYLOAD	上一步驟構造出來的字串。

樣本

"OSS4-HMAC-SHA256" + "\n" +
FormatISO8601 + "\n" +
20231203/cn-hangzhou/oss/aliyun_v4_request + "\n" +
Hex(SHA256Hash(<CanonicalRequest>))

步驟3：計算Signature

使用簽名金鑰組待簽名字串進行計算。

計算SigningKey。

HMAC-SHA256(HMAC-SHA256(HMAC-SHA256(HMAC-SHA256("aliyun_v4" + SK, Date), Region), "oss"), "aliyun_v4_request");

計算Signature。

HEX(HMAC-SHA256(SigningKey, StringToSign))

簽名計算樣本

以建立一個預簽名URL，分享給其他使用者上傳資料為例，示範如何在URL包含V4簽名。

計算樣本參數說明
參數
值
AccessKeyId
accesskeyid
AccessKeySecret
accesskeysecret
Timestamp
20231203T121212Z
Bucket
examplebucket
Object
exampleobject
Region
cn-hangzhou

PutObject

https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject?x-oss-signature-version=OSS4-HMAC-SHA256&x-oss-credential=accesskeyid/20231203/cn-hangzhou/oss/aliyun_v4_request&x-oss-date=20231203T121212Z&x-oss-expires=86400&x-oss-additional-headers=host&x-oss-signature=<signature-to-be-calculated>
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
x-oss-meta-author: alice
x-oss-meta-magic: abracadabra

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

構造CanonicalRequest。

PUT
/examplebucket/exampleobject
x-oss-additional-headers=host&x-oss-credential=accesskeyid%2F20231203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-date=20231203T121212Z&x-oss-expires=86400&x-oss-signature-version=OSS4-HMAC-SHA256
host:examplebucket.oss-cn-hangzhou.aliyuncs.com
x-oss-meta-author:alice
x-oss-meta-magic:abracadabra

host
UNSIGNED-PAYLOAD

構造待簽名字串（StringToSign）。

OSS4-HMAC-SHA256
20231203T121212Z
20231203/cn-hangzhou/oss/aliyun_v4_request
672d815902f04dd8aa90a558931f471cc7269d08a122a5e9028022d9f723332c

計算簽名。
1. 計算SigningKey。
  說明
  為方便可讀，如下為SigningKey經Base64編碼後的字串。
```
WVjaYR8lCj9YC5PUS2RSZQANYbuh9DhMFxjU1NtZKfc=
```
2. 計算Signature。
```
2c6c9f10d8950fb150290ef6f42570e33cd45d6a57ec7887de75fa2ec45b4c72
```

在URL中加入簽名。

https://examplebucket.oss-cn-hangzhou.aliyuncs.com?x-oss-additional-headers=host&x-oss-credential=accesskeyid%2F20231203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-date=20231203T121212Z&x-oss-expires=86400&x-oss-signature=2c6c9f10d8950fb150290ef6f42570e33cd45d6a57ec7887de75fa2ec45b4c72&x-oss-signature-version=OSS4-HMAC-SHA256
Host: examplebucket.oss-cn-hangzhou.aliyuncs.com
x-oss-meta-author: alice
x-oss-meta-magic: abracadabra

簽名計算完整範例程式碼

以上述簽名計算樣本提供的參數為例，通過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;

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");
        // 步驟1：構造CanonicalRequest。
        String canonicalRequest =
                "PUT\n" +
                        "/examplebucket/exampleobject\n" +
                        "x-oss-additional-headers=host&x-oss-credential="+accesskeyid+"%2F20231203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-date=20231203T121212Z&x-oss-expires=86400&x-oss-signature-version=OSS4-HMAC-SHA256\n" +
                        "host:examplebucket.oss-cn-hangzhou.aliyuncs.com\n" +
                        "x-oss-meta-author:alice\n" +
                        "x-oss-meta-magic:abracadabra\n" +
                        "\n" +
                        "host\n" +
                        "UNSIGNED-PAYLOAD";

        // 步驟2：構造待簽名字串（StringToSign）。
        String stringToSign = "OSS4-HMAC-SHA256\n" +
                "20231203T121212Z\n" +
                "20231203/cn-hangzhou/oss/aliyun_v4_request\n" +
                DigestUtils.sha256Hex(canonicalRequest);

        // 步驟3：計算Signature。
        byte[] dateKey = hmacsha256(("aliyun_v4" + accesskeysecret).getBytes(), "20231203");
        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+"%2F20231203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&" +
                "x-oss-date=20231203T121212Z&" +
                "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:2c6c9f10d8950fb150290ef6f42570e33cd45d6a57ec7887de75fa2ec45b4c72
url:https://examplebucket.oss-cn-hangzhou.aliyuncs.com/exampleobject?x-oss-additional-headers=host&x-oss-credential=accesskeyid%2F20231203%2Fcn-hangzhou%2Foss%2Faliyun_v4_request&x-oss-date=20231203T121212Z&x-oss-expires=86400&x-oss-signature=2c6c9f10d8950fb150290ef6f42570e33cd45d6a57ec7887de75fa2ec45b4c72&x-oss-signature-version=OSS4-HMAC-SHA256

參數	值
AccessKeyId	accesskeyid
AccessKeySecret	accesskeysecret
Timestamp	20231203T121212Z
Bucket	examplebucket
Object	exampleobject
Region	cn-hangzhou