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

API 簽名算法

本篇目錄

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

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

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

空間管理簽名算法

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

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

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

其中 Signature 的偽代碼計(jì)算方式如下：

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

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

文件管理簽名算法

文件管理的簽名有兩種不同的方式通過(guò) HTTP 請(qǐng)求傳遞給服務(wù)器，分別是身份驗(yàn)證標(biāo)頭和查詢字符串請(qǐng)求身份驗(yàn)證替代項(xiàng)。

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

Authorization: UCloud UCloudPublicKey:SignatureCopyErrorSuccess

其中，Signature 是一個(gè)哈希值，具體為請(qǐng)求中特定元素的 HMAC-SHA1（RFC2104），因此 Signature 會(huì)因請(qǐng)求不同而異。如果客戶端請(qǐng)求中隨附的 Signature 與服務(wù)端計(jì)算出的 Signature 相匹配，則證明請(qǐng)求者擁有 UCloud 允許的訪問(wèn)權(quán)限。以下是 Authorization 身份驗(yàn)證標(biāo)頭構(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 中包括兩類(lèi)標(biāo)頭元素：

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

備注：

計(jì)算CanonicalizedUCloudHeaders步驟

將每個(gè)以X-UCloud-開(kāi)頭的 HTTP 標(biāo)頭名稱(chēng)轉(zhuǎn)換為小寫(xiě)。例如X-UCloud-Date”改為“x-ucloud-date。

根據(jù)標(biāo)頭名稱(chēng)按字典順序排列標(biāo)頭集。

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

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

通過(guò)將折疊空格（包括換行符）替換為單個(gè)空格，“展開(kāi)”跨多個(gè)行的長(zhǎng)標(biāo)頭（按照 RFC2616 中第 4.2 節(jié)允許的方式）。

刪除標(biāo)頭中冒號(hào)周?chē)目崭?。例如，?biāo)頭x-ucloud-meta-username:fred,barney改為x-ucloud-meta-username:fred,barney。

最后，請(qǐng)向生成的列表中的每個(gè)標(biāo)準(zhǔn)化標(biāo)頭附加換行字符（U+000A）。通過(guò)將此列表中所有的標(biāo)頭規(guī)范化為單個(gè)字符串，構(gòu)建 CanonicalizedUcloudHeaders 元素。

示例

確定使用 API 接口，例如使用 PUTFile 接口，簽名前的請(qǐng)求如下

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

拼接簽名字符串對(duì)照 step1 的請(qǐng)求中的各個(gè)參數(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 分配給您的私鑰對(duì)簽名字符串做 hmac-sha1 運(yùn)算

hmacstring = hmac-sha1(privateKey, string2sign)CopyErrorSuccess

對(duì)生成的 hmacstring 做 base64 運(yùn)算

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

生成最終簽名格式

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

生成帶簽名的 HTTP 請(qǐng)求

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=

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

以下是查詢字符串經(jīng)身份驗(yàn)證的 US3 REST 請(qǐng)求示例。

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

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

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

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

文件 ETag 生成方法

文件 ETag 可用于查詢文件是否可以進(jìn)行秒傳。

具體算法的偽代碼如下:

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