署名

署名は、Cloud Storage XML API に送信されるリクエストを認証する方法の一つです。署名は、署名付き URL や HTML フォームを処理する場合などに使用されます。このページは、署名の作成に推奨される V4 署名プロセスを使用して作成された署名に適用されます。

概要

署名により、識別と強固な認証が提供され、Cloud Storage へのリクエストが特定のアカウントの権限を使用して処理されるようになります。署名を使用すると、そのアカウントに関連付けられたシークレットまたは秘密鍵という重要な機密情報を開示せずに、そのような認証が行われます。

署名付きのリクエストを作成すると、Cloud Storage は鍵情報のコピーを使用して、リクエストの同等の署名を計算します。リクエストに含まれる署名が Cloud Storage によって計算された署名と一致する場合、Cloud Storage は関連するシークレットまたは秘密鍵を使用して署名が作成されたことを認識します。

Cloud Storage では、次を処理する場合に署名を使用する必要があります。

また、署名は次の場合に使用できます。

  • XML API に対して署名付きの直接リクエストを送信する。

直接リクエストでの署名の使用は、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 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 キーのシークレットから導き出す

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 S3 x-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 トークンを使用します。

次のステップ