署名は、Cloud Storage XML API に送信されるリクエストを認証する方法の一つです。署名は、署名付き URL や HTML フォームを処理する場合などに使用されます。このページは、署名の作成に推奨される V4 署名プロセスを使用して作成された署名に適用されます。
署名は Cloud Storage XML API に固有のものであり、OAuth 2.0 トークンとは異なります。OAuth 2.0 トークンは XML API でも使用できますが、Cloud Storage JSON API など、Google Cloud サービス全体でより一般的に使用されます。
概要
署名により、識別と強固な認証が提供され、Cloud Storage へのリクエストが特定のアカウントの権限を使用して処理されるようになります。署名を使用すると、そのアカウントに関連付けられたシークレットまたは秘密鍵という重要な機密情報を開示せずに、そのような認証が行われます。
署名付きのリクエストを作成すると、Cloud Storage は鍵情報のコピーを使用して、リクエストの同等の署名を計算します。リクエストに含まれる署名が Cloud Storage によって計算された署名と一致する場合、Cloud Storage は関連するシークレットまたは秘密鍵を使用して署名が作成されたことを認識します。
Cloud Storage では、次を処理する場合に署名を使用する必要があります。
また、XML API リクエストの Authorization ヘッダーで署名を使用することもできます。
直接リクエストでの署名の使用は、Amazon S3 から簡単に移行する場合に役立ちます。ただし、直接リクエストの認証フローでは OAuth 2.0 トークンを使用することをおすすめします。
構造
署名を作成するためのコンポーネントとプロセスは、署名の用途と使用する認証鍵によって異なります。署名には大まかに、署名鍵とリクエスト情報という 2 つのコンポーネントがあります。これら 2 つのコンポーネントに署名アルゴリズムを適用して、署名を作成します。次の表は、署名のさまざまなユースケースと署名を作成するために各ケースで必要なコンポーネントをまとめたものです。
| ユースケース | 署名鍵 | リクエスト情報 |
|---|---|---|
| RSA 鍵を使用した HTML フォーム | RSA 秘密鍵を直接使用する | Base64 エンコードのポリシー ドキュメント |
| HMAC キーを使用した HTML フォーム | HMAC キーのシークレットから導き出す | Base64 エンコードのポリシー ドキュメント |
| RSA 鍵を使用した署名付き URL または署名付きヘッダー | RSA 秘密鍵を直接使用する | 署名対象文字列 |
| HMAC キーを使用した署名付き URL または署名付きヘッダー | HMAC キーのシークレットから導き出す | 署名対象文字列 |
署名対象文字列
署名対象文字列には、リクエストについてのメタ情報と署名する正規リクエストのハッシュが含まれます。
構造
署名対象文字列は 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'）で表示されます。
署名付き URL の場合、署名はアクティブな日時の 15 分前から指定した有効期限まで使用できます。アクティブな日時は、署名付き URL の
X-Goog-Dateクエリ文字列パラメータと一致し、認証情報スコープで指定した日付を使用する必要があります。署名付きヘッダーを含むリクエストの場合、署名はアクティブな日時の 15 分前からアクティブな日時の 15 分後まで使用できます。アクティブな日時は、署名を使用するリクエストの
x-goog-dateヘッダーと一致し、認証情報スコープで指定した日付を使用する必要があります。
認証情報スコープ
リクエストの認証情報スコープ。
正規リクエストのハッシュ
正規リクエストの 16 進エンコードの 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 フォームでバケット フィールドを使用しない場合も）。
同じフィールドに複数の条件ステートメントを使用する場合は、それぞれに個別の HTML フォームを作成する必要があります。条件ステートメントでは次の 3 種類の条件を使用できます。
完全一致
フィールドの完全一致を実行します。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.iam.gserviceaccount.com/20191102/us-central1/storage/goog4_request"},
{"x-goog-date": "20191102T043530Z"}
]
}
このポリシー ドキュメントは、次の条件を定義します。
- フォームの有効期限は 2020 年 6 月 16 日 11 時 11 分 11 秒（UTC）です。
- ファイル名の先頭には任意の文字を使用できます。
- ファイルはバケット
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 S3x-amz拡張機能を使用する場合、この値はs3です。 - REQUEST_TYPE: リクエストの種類。Cloud Storage リソースにアクセスするほとんどの場合、この値は
goog4_requestです。Amazon S3x-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 キーのシークレットから導き出す |
RSA 鍵と IAM signBlob メソッドを使用して署名対象文字列またはポリシー ドキュメントに署名する際のガイドについては、署名を作成するをご覧ください。
署名鍵を 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 S3x-amz拡張機能を使用する場合、この値はAWS4です。 - HMAC_KEY_SECRET: リクエストを作成して署名するために使用している HMAC 鍵のシークレット。
- DATE、LOCATION、SERVICE、REQUEST_TYPE: この値は、認証情報スコープで指定された値と一致している必要があります。
署名後
署名を完成させるには、メッセージ ダイジェストという署名の出力を 16 進エンコードする必要があります。
例
ポリシー ドキュメントに署名するための擬似コードは次のとおりです。
EncodedPolicy = Base64Encode(PolicyDocument) MessageDigest = SigningAlgorithm(SigningKey, EncodedPolicy) Signature = HexEncode(MessageDigest)
署名対象文字列に署名するための擬似コードは次のとおりです。
MessageDigest = SigningAlgorithm(SigningKey, StringToSign) Signature = HexEncode(MessageDigest)
制限事項
チャンクされた転送エンコードを使用してアップロードする場合は、署名を使用してアップロードを認証できません。アップロードでチャンクされた転送エンコードを使用する場合は、OAuth 2.0 トークンを使用します。
次のステップ
- 署名付き URL で署名を使用する。
Authorizationヘッダーを含むリクエストで署名を使用する。- HTML フォームで署名を使用する。