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

API 簽名算法

本篇目錄

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

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

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

空間管理簽名算法

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

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

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 請求傳遞給服務(wù)器，分別是身份驗證標頭和查詢字符串請求身份驗證替代項。

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

Authorization: UCloud UCloudPublicKey:SignatureCopyErrorSuccess

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

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-開頭，此類標頭需要按照下面指定的方法構(gòu)造 CanonicalizedUCloudHeaders 字符串后加入到 StringToSign 中。

備注：

計算CanonicalizedUCloudHeaders步驟

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

根據(jù)標頭名稱按字典順序排列標頭集。

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

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

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

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

最后，請向生成的列表中的每個標準化標頭附加換行字符（U+000A）。通過將此列表中所有的標頭規(guī)范化為單個字符串，構(gòu)建 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 的請求中的各個參數(shù)，程序中的各變量取值如下（采用偽代碼描述）

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 [email protected]: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 [email protected]:S5FVD2w613MKb/hisjaqHdjvn9U=

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

以下是查詢字符串經(jīng)身份驗證的 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 請求參數(shù)和 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為一個塊進行切分后的塊個數(shù), 占4個字節(jié)，以小端模式保存。
    blkN:第N(N>=0)個數(shù)據(jù)塊的數(shù)據(jù)。CopyErrorSuccess