摘要：通常我們將此過程稱為簽署請求并且我們將輸出算法稱為簽名，因為它會模擬真實簽名的安全屬性。查詢字符串請求身份驗證方法與普通的方法稍有差異，不同之處僅在于請求參數和元素的格式。請注意，在中，位置元素已替換為。

API 簽名算法

本篇目錄

US3 REST API 基于 HMAC（哈希消息身份驗證碼）密鑰使用自定義 HTTP 方案進行身份驗證。要對請求進行身份驗證，您首先需要合并請求的選定元素以形成一個字符串。然后，您可以使用 UCloud 私有訪問密鑰來計算該字符串的 HMAC。通常我們將此過程稱為“簽署請求”并且我們將輸出 HMAC 算法稱為“簽名”，因為它會模擬真實簽名的安全屬性。最后，您可以使用本部分中介紹的語法，作為請求的參數添加此簽名。

系統收到經身份驗證的請求時，將提取您申領的 UCloud 私有訪問密鑰，并以相同的使用方式將它用于計算已收到的消息的簽名。然后，它會將計算出的簽名與請求者提供的簽名進行對比。如果兩個簽名相匹配，則系統認為請求者必須擁有對 UCloud 私有訪問密鑰的訪問權限，因此充當向其頒發密鑰的委托人的頒發機構。如果兩個簽名不匹配，那么請求將被丟棄，同時系統將返回錯誤消息。

基于以上的原理，我們對空間管理和文件管理兩套接口提供兩種原理一樣但是細節不同的鑒權過程。

空間管理簽名算法

賬戶的公私鑰可以在 UCloud 控制臺中 API 產品 - API 密鑰，點擊顯示 API 密鑰獲取。

空間管理的簽名使用查詢字符串的簽名方式，客戶端通過把簽名字段作為一個 query 字段傳遞給服務端請求授權驗證。攜帶了簽名（Signature）的創建空間請求具有如下的格式:

GET /Type=public&BucketName=demobucket&PublicKey=uclouddemo@mail.com45207436768156091&Action=CreateBucket&Signature=13f7989d4a5a8ued83c0e57ah43b3607bc506c7c HTTP/1.1CopyErrorSuccess

其中 Signature 的偽代碼計算方式如下：

//生成請求的 query 字典
querys = {"PublicKey" : publicKey} + {其他 query 字段}
//對 query 字典按照字典排序方式(lexicographical order)排序
querys = querys.sort()
//生成 signstring
signstring = ""
for key, value in querys {
   signstring += key + value
}
//將私鑰加入簽名
signstring += privateKey
//按照SHA1(RFC 3174)計算簽名
signature = sha1(signstring)
//以16進制顯示簽名
signature = HEX(signature)CopyErrorSuccess

其他空間管理 API 的簽名均可使用同樣的計算方式生成。

文件管理簽名算法

文件管理的簽名有兩種不同的方式通過 HTTP 請求傳遞給服務器，分別是身份驗證標頭和查詢字符串請求身份驗證替代項。

該方式使用 Authorization 頭部字段傳遞簽名數據，并放置于各 HTTP 請求的報文頭中，如下圖所示，身份驗證標頭具有以下形式：

Authorization: UCloud UCloudPublicKey:SignatureCopyErrorSuccess

其中，Signature 是一個哈希值，具體為請求中特定元素的 HMAC-SHA1（RFC2104），因此 Signature 會因請求不同而異。如果客戶端請求中隨附的 Signature 與服務端計算出的 Signature 相匹配，則證明請求者擁有 UCloud 允許的訪問權限。以下是 Authorization 身份驗證標頭構造的偽代碼：

Authorization = "UCloud" + " " + UCloudPublicKey + ":" + Signature
Signature = Base64( HMAC-SHA1( UCloudPrivateKey, UTF-8-Encoding-Of( StringToSign ) ) )
StringToSign = HTTP-Verb + "
" +
    Content-MD5 + "
" +
    Content-Type + "
" +
    Date + "
" +
    CanonicalizedUCloudHeaders +
    CanonicalizedResource
CanonicalizedUCloudHeaders = <described below>
CanonicalizedResource = "/" + Bucket + "/" + KeyCopyErrorSuccess

StringToSign 中包括兩類標頭元素：

一類是位置標頭，僅有 3 個，分別是 Content-MD5、Content-Type 和 Date，在 StringToSign 中不包括這些標頭的名稱，僅包括它們在請求中的值，如果請求中這些標頭不存在，需要用空字符串("")代替；另一類是 UCloud 附加標頭，以X-UCloud-開頭，此類標頭需要按照下面指定的方法構造 CanonicalizedUCloudHeaders 字符串后加入到 StringToSign 中。

備注：

計算CanonicalizedUCloudHeaders步驟

將每個以X-UCloud-開頭的 HTTP 標頭名稱轉換為小寫。例如X-UCloud-Date”改為“x-ucloud-date。

根據標頭名稱按字典順序排列標頭集。

按照 RFC2616 中第 4.2 節中的規定，將相同名稱的標頭字段合并為一個header-name:comma-separated-value-list對，各值之間不留空格。

例如，可以將元數據標頭x-ucloud-meta-username:fred和x-ucloud-meta-username:barney合并為單個標頭x-ucloud-meta-username:fred,barney。

通過將折疊空格（包括換行符）替換為單個空格，“展開”跨多個行的長標頭（按照 RFC2616 中第 4.2 節允許的方式）。

刪除標頭中冒號周圍的空格。例如，標頭x-ucloud-meta-username:fred,barney改為x-ucloud-meta-username:fred,barney。

最后，請向生成的列表中的每個標準化標頭附加換行字符（U+000A）。通過將此列表中所有的標頭規范化為單個字符串，構建 CanonicalizedUcloudHeaders 元素。

示例

確定使用 API 接口，例如使用 PUTFile 接口，簽名前的請求如下

PUT /demokey HTTP/1.1 Host: demobucket.ufile.ucloud.cn Content-Length: 11434 Content-Type: image/jpeg X-UCloud-Foo: foo X-UCloud-Bar: bar1 X-UCloud-Bar: bar2

拼接簽名字符串對照 step1 的請求中的各個參數，程序中的各變量取值如下（采用偽代碼描述）

bucket = "demobucket"
key = "demokey"
http_verb = "PUT"
content_md5 = "" 
content_type = "image/jpeg"
date = "" 
canonicalized_ucloud_headers = "x-ucloud-foo:foo" + "
" + "x-ucloud-bar:bar1,bar2" + 
"
canonicalized_resource = "/" + "demobucket" + "/" + "demokey"
string2sign = "PUT" + "
"
    + "" + "
"
    + "image/jpg" + "
"
    + "" + "
"
    + "x-ucloud-foo:foo" + "
" + "x-ucloud-bar:bar1,bar2" + "
"
    + "/demobucket/demokey"CopyErrorSuccess

即

string2sign = "PUT

image/jpeg

x-ucloud-foo:foo
x-ucloud-bar:bar1,bar2
/demobucket/demokey"CopyErrorSuccess

使用 UCloud 分配給您的私鑰對簽名字符串做 hmac-sha1 運算

hmacstring = hmac-sha1(privateKey, string2sign)CopyErrorSuccess

對生成的 hmacstring 做 base64 運算

base64string = base64(hmacstring) = S5FVD2w613MKb/hisjaqHdjvn9U=CopyErrorSuccess

生成最終簽名格式

signature = UCloud demouser@ucloud.cn13424346821929713944:S5FVD2w613MKb/hisjaqHdjvn9U=

生成帶簽名的 HTTP 請求

PUT /demokey HTTP/1.1 Host: demobucket.ufile.ucloud.cn Content-Length: 11434 Content-Type: image/jpeg X-UCloud-Foo: foo X-UCloud-Bar: bar1 X-UCloud-Bar: bar2 Authorization: UCloud demouser@ucloud.cn13424346821929713944:S5FVD2w613MKb/hisjaqHdjvn9U=

可以通過傳遞請求信息作為查詢字符串參數，而不是使用 AuthorizationHTTP 標頭來驗證特定類型的請求。這在允許第三方瀏覽器直接訪問您的 US3 私有空間的文件，而無需代理請求時非常有用。其概念是構建一個“預簽名”的請求并將其編碼為最終用戶瀏覽器可檢索的 URL。此外，您還可以通過指定過期時間來限制預簽名請求。

以下是查詢字符串經身份驗證的 US3 REST 請求示例。

GET /demokey.jpg?UCloudPublicKey=AKIAIOSFODNN7EXAMPLE&Expires=1141889120&Signature=vjbyPxybdZaNmGa%2ByT272YEAiv4%3D HTTP/1.1
Host: demobucket.s3.ucloud.cn
Date: Mon, 26 Mar 2007 19:37:58 +0000CopyErrorSuccess

查詢字符串請求身份驗證方法與普通的方法稍有差異，不同之處僅在于 Signature 請求參數和 StringToSign 元素的格式。下面的偽語法演示了查詢字符串請求身份驗證方法。

Signature = URL-Encode( Base64( HMAC-SHA1( UCloudPrivateKey, UTF-8-Encoding-Of( StringToSign ) ) ) );
StringToSign = HTTP-VERB + "
" +
    "
" +
    "
" +
    Expires + "
" +
    CanonicalizedUCloudHeaders +
    CanonicalizedResource; CopyErrorSuccess

請注意，在 StringToSign 中，HTTPDate 位置元素已替換為 Expires。CanonicalizedUCloudHeaders 和 CanonicalizedResource 是相同的。

文件 ETag 生成方法

文件 ETag 可用于查詢文件是否可以進行秒傳。

具體算法的偽代碼如下:

if filesize<=4MB:
    hash = base64_url_safe(blkcnt, sha(file))
else:
    hash = base64_url_safe(blkcnt, sha(sha(blk0), sha(blk1)...))
字段含義
    blkcnt:文件以4MB為一個塊進行切分后的塊個數, 占4個字節，以小端模式保存。
    blkN:第N(N>=0)個數據塊的數據。CopyErrorSuccess