本頁面中的部分或全部資訊可能不適用於 Trusted Cloud by S3NS。

本頁面由 Cloud Translation API 翻譯而成。

簽名

簽章是驗證傳送至 Cloud Storage XML API 要求的方法之一。舉例來說，使用已簽署網址或 HTML 表單時，就需要簽章。本頁內容適用於使用 V4 簽署程序建立的簽章，這是建議的簽章建立程序。

簽章專用於 Cloud Storage XML API，與 OAuth 2.0 權杖不同；OAuth 2.0 權杖也可用於 XML API，且更廣泛適用於 Trusted Cloud by S3NS 服務，包括 Cloud Storage JSON API。

總覽

「簽名」可鑑別身分並提供強大的驗證機制，確保 Cloud Storage 要求是透過特定帳戶的授權進行處理。簽名可完成這類驗證，且不會揭露與帳戶相關的敏感金鑰資訊，也就是「密鑰」或「私密金鑰」。

當您提出附有簽名的要求時，Cloud Storage 會使用金鑰資訊副本，為該要求計算對等簽名。如果要求中包含的簽名與 Cloud Storage 計算的簽名相符，Cloud Storage 就會知道該簽名是使用相關密鑰或私密金鑰建立。

在 Cloud Storage 中，使用下列項目時必須使用簽章：

已簽署的網址。
HTML 表單。

此外，簽章可用於 XML API 要求的 Authorization 標頭。

執行從 Amazon S3 簡易遷移時，在直接要求中使用簽章很有用，但建議您使用 OAuth 2.0 權杖，做為直接要求的驗證流程。

結構

建立簽章的元件和程序取決於簽章的用途和您使用的驗證金鑰。一般來說，簽章有兩個元件：簽署金鑰和要求資訊。您會對這兩個元件套用簽署演算法，藉此建立簽章。下表摘要說明簽章的各種用途，以及在每種情況下建構簽章所需的元件：

用途	簽署金鑰	索取資訊
含有 RSA 金鑰的 HTML 表單	直接使用 RSA 私密金鑰	Base64 編碼的政策文件
含有 HMAC 金鑰的 HTML 表單	從 HMAC 金鑰的密鑰衍生	Base64 編碼的政策文件
使用 RSA 金鑰簽署的網址或簽署的標頭	直接使用 RSA 私密金鑰	String-to-sign
使用 HMAC 金鑰的已簽署網址或已簽署標頭	從 HMAC 金鑰的密鑰衍生	String-to-sign

待簽署的字串

待簽署字串包含要求的中繼資訊，以及您要簽署的標準要求雜湊。

結構

欲簽署字串必須採用 UTF-8 編碼，且具備下列結構，包括在各個元素之間使用新行：

SIGNING_ALGORITHM
ACTIVE_DATETIME
CREDENTIAL_SCOPE
HASHED_CANONICAL_REQUEST

簽署演算法

您為 SIGNING_ALGORITHM 使用的值取決於您使用的金鑰類型，以及您為標頭或查詢參數使用的擴充功能：

用途	「`SIGNING_ALGORITHM`」的值
`x-goog-*` 擴充功能和 RSA 金鑰	`GOOG4-RSA-SHA256`
`x-goog-*` 擴充功能和 HMAC 金鑰	`GOOG4-HMAC-SHA256`
`x-amz-*` 擴充功能和 HMAC 金鑰	`AWS4-HMAC-SHA256`

啟用日期時間

簽章可使用的日期和時間，採用 ISO 8601 基本格式 YYYYMMDD'T'HHMMSS'Z'。

如果是已簽署的網址，簽章可從有效日期時間前 15 分鐘開始使用，直到您指定的到期時間為止。有效日期時間必須與已簽署網址的 X-Goog-Date 查詢字串參數相符，且必須使用您在憑證範圍中指定的同一天。
對於含有簽署標頭的要求，簽章的有效時間為有效日期時間前 15 分鐘，到有效日期時間後 15 分鐘。有效日期時間必須與使用簽章的要求 x-goog-date 標頭相符，且有效日期時間必須與您在憑證範圍中指定的日期相同。

憑證範圍

要求的憑證範圍。

標準要求的雜湊

標準化要求的十六進位編碼 SHA-256 雜湊。使用 SHA-256 雜湊函式建立標準化要求的雜湊值。您的程式設計語言應擁有用來建立 SHA-256 雜湊的程式庫。雜湊值範例如下：

436b7ce722d03b17d3f790255dd57904f7ed61c02ac5127a0ca8063877e4e42c

範例

以下是格式正確的待簽署字串範例，其中新行會顯示為實際的新行，而不是 \n：

GOOG4-RSA-SHA256
20191201T190859Z
20191201/us-central1/storage/goog4_request
54f3076005db23fbecdb409d25c0ccb9fb8b5e24c59f12634654c0be13459af0

政策文件

政策文件會定義可存取對應 HTML 表單的使用者，可上傳至 Cloud Storage 的內容。政策文件提供授權，確保 HTML 表單可將檔案上傳至目標值區。您可以使用政策文件，允許網站訪客將檔案上傳至 Cloud Storage。

政策文件是以 JavaScript Object Notation (JSON) 格式建構而成。政策文件必須採用 UTF-8 和 Base64 編碼。政策文件包含下列章節：

項目	說明
`expiration`	政策文件的到期時間，採用 ISO 8601 基本格式 `YYYYMMDD'T'HHMMSS'Z'`。過期的政策文件會導致 HTML 表單失效。
`conditions`	每個上傳項目都必須符合的一系列條件。

conditions 區段必須包含：

HTML 表單中使用的每個欄位的條件陳述式，但 x-goog-signature、file 和 policy 欄位除外。
"bucket" 條件陳述式，即使您未在 HTML 表單中使用 bucket 欄位。

如要為同一個欄位使用多個條件陳述式，請為每個陳述式建立個別的 HTML 表單。條件陳述式可使用三種條件：

完全比對

針對欄位執行精確比對，HTML 表單指定欄位中使用的值，必須與此條件中設定的值相符。請使用下列任一語法樣式設定這項條件：
```
{"field" : "value"}
```
```
["eq", "$field", "value"]
```
除了 Content-Length 以外，所有有效的 HTML 表單欄位都可以使用完全相符。
開頭為

如果欄位值開頭必須為特定前置字元，請使用 starts-with 條件，並採用下列語法：
```
["starts-with", "$field", "value"]
```
如果欄位值沒有限制，請使用 starts-with 條件，語法如下：
```
["starts-with", "$field", ""]
```
除了 Content-Length 以外，所有有效的 HTML 表單欄位都可以使用 starts-with 條件。
內容長度範圍

指定可在 Content-Length 欄位中使用的可接受值範圍。請使用下列語法指定這項條件：
```
["content-length-range", min_range, max_range]
```

範例

以下是政策文件範例：

{"expiration": "2020-06-16T11:11:11Z",
 "conditions": [
  ["starts-with", "$key", ""],
  {"bucket": "travel-maps"},
  {"success_action_redirect": "http://www.example.com/success_notification.html"},
  ["eq", "$Content-Type", "image/jpeg"],
  ["content-length-range", 0, 1000000],
  {"x-goog-algorithm": "GOOG4-RSA-SHA256"},
  {"x-goog-credential": "example_account@example_project.s3ns-system.iam.gserviceaccount.com/20191102/us-central1/storage/goog4_request"},
  {"x-goog-date": "20191102T043530Z"}
  ]
}

這份政策文件定義了下列條件：

表單將於世界標準時間 2020 年 6 月 16 日 11:11:11 過期。
檔案名稱開頭可使用任何有效字元。
檔案必須上傳至 travel-maps 值區。
上傳成功後，使用者會重新導向至 http://www.example.com/success_notification.html。
該表單僅允許上傳圖片。
使用者無法上傳大於 1 MB 的檔案。

憑證範圍

憑證範圍是字串，會同時出現在要簽署的字串和政策文件中。憑證範圍的結構如下：

DATE/LOCATION/SERVICE/REQUEST_TYPE

憑證範圍包含下列元件：

DATE：簽章可供使用的日期，格式為 YYYYMMDD。
LOCATION：如果是 Cloud Storage 資源，LOCATION可使用任何值。建議使用的值是簽章適用的資源所關聯的位置。例如：us-central1。這個參數的存在是為了保持與 Amazon S3 的相容性。
SERVICE：服務名稱。在大多數情況下，存取 Cloud Storage 資源時，這個值為 storage。使用 Amazon S3 x-amz 擴充功能時，這個值為 s3。
REQUEST_TYPE：要求類型。在大多數情況下，存取 Cloud Storage 資源時，這個值為 goog4_request。使用 Amazon S3 x-amz 擴充功能時，這個值為 aws4_request。

舉例來說，一般憑證範圍如下所示：

20191102/us-central1/storage/goog4_request

使用字串簽章搭配 x-amz 擴充功能時，憑證範圍如下：

20150830/us-east1/s3/aws4_request

簽署

如要建立簽名，請使用簽署演算法 (也稱為加密編譯雜湊函式)，簽署待簽署的字串或政策文件。簽署演算法會產生訊息摘要，必須經過十六進位編碼才能建立最終簽章。使用的簽署演算法取決於您擁有的驗證金鑰類型：

驗證金鑰	簽署演算法	簽署金鑰
RSA 金鑰	RSA-SHA256	直接使用 RSA 私密金鑰
HMAC 金鑰	HMAC-SHA256	從 HMAC 金鑰的密鑰衍生

您可以使用 IAM signBlob 方法執行 RSA-SHA256 簽署演算法。使用 gcloud CLI 等工具和大多數 Trusted Cloud 用戶端程式庫時，您可以透過 signBlob 方法建立已簽署的網址。

您也可以使用具備 RSA 簽名程式庫的程式設計語言 (例如 pyopenssl 程式庫)，在本地建立 RSA 金鑰簽章；不過，我們不建議使用這種方法，因為您必須建立及下載服務帳戶的私密金鑰。

從 HMAC 金鑰衍生簽署金鑰

使用 HMAC 金鑰簽署時，您必須建立從 HMAC 金鑰密鑰衍生的 UTF-8 編碼簽署金鑰。衍生金鑰專屬於與您要求相關聯的日期、地點、服務和要求類型。下列虛擬程式碼說明如何衍生簽署金鑰：

key_date = HMAC-SHA256("PREFIX" + HMAC_KEY_SECRET, "DATE")
key_region = HMAC-SHA256(key_date, "LOCATION")
key_service = HMAC-SHA256(key_region, "SERVICE")
signing_key = HMAC-SHA256(key_service, "REQUEST_TYPE")

虛擬程式碼包含下列元件：

PREFIX：在存取 Cloud Storage 資源時，這個值通常為 GOOG4。使用 Amazon S3 x-amz 擴充功能時，這個值為 AWS4。
HMAC_KEY_SECRET：用於發出及簽署要求的 HMAC 金鑰密鑰。
DATE、LOCATION、SERVICE、REQUEST_TYPE：這些值必須與憑證範圍中指定的值相符。

衍生簽署金鑰後，請使用包含 HMAC-SHA256 簽署演算法程式庫的程式設計語言，在本地建立簽章。

簽署後

如要完成簽署，簽署的輸出內容 (稱為「訊息摘要」) 必須經過十六進位編碼。

範例

以下是簽署政策文件的虛擬程式碼：

EncodedPolicy = Base64Encode(PolicyDocument)
MessageDigest = SigningAlgorithm(SigningKey, EncodedPolicy)
Signature = HexEncode(MessageDigest)

以下是簽署待簽署字串的虛擬程式碼：

MessageDigest = SigningAlgorithm(SigningKey, StringToSign)
Signature = HexEncode(MessageDigest)

後續步驟

在已簽署的網址中使用簽章。
在含有 Authorization 標頭的要求中使用簽章。
在 HTML 表單中使用簽名。