Tanda tangan

Tanda tangan adalah salah satu metode untuk mengautentikasi permintaan yang dikirim ke Cloud Storage XML API. Tanda tangan digunakan, misalnya, saat bekerja dengan URL yang ditandatangani atau formulir HTML. Halaman ini berlaku untuk tanda tangan yang dibuat menggunakan proses penandatanganan V4, yang merupakan proses yang direkomendasikan untuk membuat tanda tangan.

Tanda tangan bersifat khusus untuk Cloud Storage XML API dan berbeda dengan token OAuth 2.0. Token OAuth 2.0 juga dapat digunakan dengan XML API dan lebih umum berlaku di seluruh layanan Google Cloud, termasuk Cloud Storage JSON API.

Ringkasan

Tanda tangan memberikan identitas dan autentikasi yang kuat, yang memastikan bahwa permintaan ke Cloud Storage diproses menggunakan otoritas akun tertentu. Tanda tangan mendapatkan autentikasi tersebut tanpa mengungkapkan informasi penting yang sensitif, yang disebut secrets atau secrets, yang terkait dengan akun tersebut.

Saat Anda membuat permintaan dengan tanda tangan, Cloud Storage akan menggunakan salinan informasi penting untuk menghitung tanda tangan yang setara untuk permintaan tersebut. Jika tanda tangan yang disertakan dalam permintaan cocok dengan tanda tangan yang dihitung oleh Cloud Storage, Cloud Storage akan mengetahui bahwa tanda tangan itu dibuat menggunakan rahasia atau kunci pribadi yang relevan.

Di Cloud Storage, tanda tangan harus digunakan saat bekerja dengan:

Selain itu, tanda tangan dapat digunakan saat membuat:

  • Permintaan yang ditandatangani langsung ke XML API.

Menggunakan tanda tangan dalam permintaan langsung berguna saat melakukan migrasi sederhana dari Amazon S3; tetapi, alur autentikasi yang direkomendasikan untuk permintaan langsung adalah menggunakan token OAuth 2.0.

Struktur

Komponen dan proses untuk membuat tanda tangan bergantung pada kegunaannya dan kunci autentikasi yang Anda gunakan; umumnya, ada dua komponen tanda tangan: kunci penandatanganan dan informasi permintaan. Anda menerapkan algoritma penandatanganan ke kedua komponen ini untuk membuat tanda tangan. Tabel di bawah ini merangkum berbagai kasus penggunaan untuk tanda tangan dan komponen yang Anda perlukan dalam setiap kasus untuk membuat tanda tangan:

Kasus penggunaan Kunci Penandatanganan Minta informasi
Formulir HTML dengan kunci RSA Gunakan kunci pribadi RSA secara langsung Dokumen kebijakan yang dienkode base64
Formulir HTML dengan kunci HMAC Didapatkan dari rahasia kunci HMAC Dokumen kebijakan yang dienkode base64
URL yang ditandatangani atau permintaan yang ditandatangani dengan kunci RSA Gunakan kunci pribadi RSA secara langsung String untuk ditandatangani
URL yang ditandatangani atau permintaan yang ditandatangani dengan kunci HMAC Didapatkan dari rahasia kunci HMAC String untuk ditandatangani

String untuk ditandatangani

string-to-sign mencakup informasi meta tentang permintaan Anda dan hash permintaan kanonis yang ingin Anda tanda tangani.

Struktur

String untuk ditandatangani harus berenkode UTF-8 dan memiliki struktur berikut, termasuk penggunaan newline di antara setiap elemen:

SIGNING_ALGORITHM
ACTIVE_DATETIME
CREDENTIAL_SCOPE
HASHED_CANONICAL_REQUEST

Algoritme penandatanganan

Nilai yang digunakan untuk SIGNING_ALGORITHM bergantung pada jenis kunci yang digunakan dan ekstensi yang digunakan untuk header atau parameter kueri:

Kasus penggunaan Nilai untuk SIGNING_ALGORITHM
Ekstensi x-goog-* dan kunci RSA GOOG4-RSA-SHA256
Ekstensi x-goog-* dan kunci HMAC GOOG4-HMAC-SHA256
Ekstensi x-amz-* dan kunci HMAC AWS4-HMAC-SHA256

Tanggal dan waktu aktif

Tanggal dan waktu tanda tangan dapat digunakan, dalam format dasar ISO 8601 YYYYMMDD'T'HHMMSS'Z'.

  • Untuk URL yang ditandatangani, tanda tangan dapat digunakan mulai 15 menit sebelum tanggal aktif hingga waktu habis masa berlaku yang Anda tentukan. Tanggal dan waktu aktif harus cocok dengan parameter string kueri X-Goog-Date URL yang ditandatangani dan harus menggunakan hari yang sama dengan yang Anda tentukan dalam cakupan kredensial.

  • Untuk permintaan yang ditandatangani, tanda tangan dapat digunakan mulai 15 menit sebelum tanggal dan waktu aktif hingga 15 menit setelah tanggal dan waktu aktif. Tanggal aktif harus cocok dengan header permintaan x-goog-date permintaan yang ditandatangani dan harus menggunakan hari yang sama dengan yang Anda tentukan dalam cakupan kredensial.

Cakupan Kredensial

Cakupan kredensial untuk permintaan.

Hash permintaan kanonis

Hash SHA-256 berenkode hex dari permintaan kanonis. Gunakan fungsi hash SHA-256 untuk membuat nilai hash permintaan kanonis. Bahasa pemrograman Anda harus memiliki library untuk membuat hash SHA-256. Contoh nilai hash terlihat seperti berikut:

436b7ce722d03b17d3f790255dd57904f7ed61c02ac5127a0ca8063877e4e42c

Contoh

Berikut contoh string untuk ditandatangani dengan format yang benar, dengan newline ditampilkan sebagai baris baru sebenarnya, bukan \n:

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

Dokumen kebijakan

Dokumen kebijakan menentukan data yang dapat diupload oleh pengguna yang memiliki akses ke formulir HTML yang sesuai ke Cloud Storage. Dokumen kebijakan memberikan otorisasi untuk memastikan bahwa formulir HTML dapat mengupload file ke bucket target. Anda dapat menggunakan dokumen kebijakan untuk mengizinkan pengunjung situs mengupload file ke Cloud Storage.

Dokumen kebijakan dibuat di JavaScript Object Notation (JSON). Dokumen kebijakan harus berenkode UTF-8 dan Base64. Dokumen kebijakan berisi bagian-bagian berikut:

Entri Deskripsi
expiration Waktu habis masa berlaku dokumen kebijakan, dalam format dasar ISO 8601 YYYYMMDD'T'HHMMSS'Z'. Dokumen kebijakan yang sudah tidak berlaku akan menyebabkan formulir HTML rusak.
conditions Array kondisi yang harus dipenuhi setiap upload.

Bagian conditions harus mencakup:

  • Pernyataan kondisi untuk setiap kolom yang Anda gunakan dalam formulir HTML, kecuali untuk kolom x-goog-signature, file, dan policy.

  • Pernyataan kondisi "bucket", meskipun Anda tidak menggunakan kolom bucket dalam formulir HTML.

Jika ingin menggunakan beberapa pernyataan kondisi untuk kolom yang sama, Anda harus membuat formulir HTML terpisah untuk masing-masing pernyataan. Ada tiga jenis kondisi yang dapat digunakan dalam pernyataan kondisi Anda:

  • Pencocokan Persis

    Melakukan pencocokan persis untuk suatu kolom. Nilai yang digunakan di kolom yang ditentukan pada formulir HTML harus cocok dengan nilai yang ditetapkan dalam kondisi ini. Tetapkan kondisi ini menggunakan salah satu gaya sintaksis berikut:

    {"field" : "value"}
     
    ["eq", "$field", "value"]

    Semua kolom formulir HTML yang valid, kecuali Content-Length, dapat menggunakan pencocokan persis.

  • Dimulai Dengan

    Jika nilai kolom harus diawali dengan awalan tertentu, gunakan kondisi starts-with dengan sintaksis berikut:

    ["starts-with", "$field", "value"]

    Jika nilai kolom tidak memiliki batasan, gunakan kondisi starts-with dengan sintaksis berikut:

    ["starts-with", "$field", ""]

    Semua kolom formulir HTML yang valid, kecuali Content-Length, dapat menggunakan kondisi starts-with.

  • Rentang Panjang Konten

    Menentukan rentang nilai yang dapat diterima yang dapat digunakan di kolom Content-Length. Tentukan kondisi ini menggunakan sintaksis berikut:

    ["content-length-range", min_range, max_range]

Contoh

Berikut adalah contoh dokumen kebijakan:

{"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"}
  ]
}

Dokumen kebijakan ini menentukan kondisi berikut:

  • Formulir ini akan habis berlaku pada 16 Juni 2020 pukul 11.11.11 UTC.
  • Nama file dapat dimulai dengan karakter apa pun yang valid.
  • File harus diupload ke bucket travel-maps.
  • Jika upload berhasil, pengguna akan dialihkan ke http://www.example.com/success_notification.html.
  • Formulir ini hanya mengizinkan upload gambar.
  • Pengguna tidak dapat mengupload file yang lebih besar dari 1 MB.

Cakupan kredensial

Cakupan kredensial adalah string yang muncul di dokumen string dan kebijakan. Cakupan kredensial memiliki struktur berikut:

DATE/LOCATION/SERVICE/REQUEST_TYPE

Cakupan kredensial memiliki komponen berikut:

  • DATE: Tanggal ketika tanda tangan dapat digunakan, dengan format YYYYMMDD.
  • LOCATION: Untuk resource Cloud Storage, Anda dapat menggunakan nilai apa pun untuk LOCATION. Nilai yang direkomendasikan untuk digunakan adalah lokasi yang terkait dengan resource tempat tanda tangan diterapkan. Contohnya, us-central1 Parameter ini dibuat untuk menjaga kompatibilitas dengan Amazon S3.
  • SERVICE: Nama layanan. Pada umumnya saat mengakses resource Cloud Storage, nilai ini adalah storage. Jika menggunakan ekstensi x-amz Amazon S3, nilainya adalah s3.
  • REQUEST_TYPE: Jenis permintaan. Pada umumnya saat mengakses resource Cloud Storage, nilainya adalah goog4_request. Jika menggunakan ekstensi x-amz Amazon S3, nilainya adalah aws4_request.

Sebagai contoh, cakupan kredensial standar terlihat seperti berikut:

20191102/us-central1/storage/goog4_request

Sementara cakupan kredensial yang menggunakan string untuk ditandatangani dengan ekstensi x-amz akan terlihat seperti ini:

20150830/us-east1/s3/aws4_request

Penandatanganan

Untuk membuat tanda tangan, Anda menggunakan algoritma penandatanganan, yang juga dikenal sebagai fungsi hash kriptografi, untuk menandatangani string untuk ditandatangani atau dokumen kebijakan. Algoritme penandatanganan yang Anda gunakan bergantung pada jenis kunci autentikasi yang Anda miliki:

Kunci autentikasi Algoritme penandatanganan Kunci penandatanganan
Kunci RSA RSA-SHA256 Gunakan kunci pribadi RSA secara langsung
Kunci HMAC HMAC-SHA256 Didapatkan dari rahasia kunci HMAC

Baca artikel Membuat tanda tangan untuk panduan cara menandatangani dokumen kebijakan atau string untuk ditandatangani menggunakan kunci RSA dan metode signBlob IAM.

Mendapatkan kunci penandatanganan dari kunci HMAC

Saat menandatangani dengan kunci HMAC, Anda harus membuat kunci penandatanganan berenkode UTF-8 yang berasal dari rahasia kunci HMAC Anda. Kunci turunan sifatnya khusus untuk tanggal, lokasi, layanan, dan jenis permintaan yang terkait dengan permintaan Anda. Kode semu berikut menunjukkan cara mendapatkan kunci penandatanganan:

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")

Kode semu memiliki komponen berikut:

  • PREFIX: Pada umumnya saat mengakses resource Cloud Storage, nilai ini adalah GOOG4. Saat menggunakan ekstensi x-amz Amazon S3, nilai ini adalah AWS4.
  • HMAC_KEY_SECRET: Rahasia kunci HMAC yang Anda gunakan untuk membuat dan menandatangani permintaan.
  • DATE, LOCATION, SERVICE, REQUEST_TYPE: Nilai ini harus cocok dengan nilai yang ditentukan dalam cakupan kredensial.

Setelah penandatanganan

Untuk menyelesaikan tanda tangan, output penandatanganan, yang disebut ringkasan pesan harus dienkode dengan hex.

Contoh

Berikut adalah kode semu untuk menandatangani dokumen kebijakan:

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

Berikut ini adalah kode semu untuk menandatangani string untuk ditandatangani:

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

Batasan

Tanda tangan tidak dapat digunakan untuk mengautentikasi upload jika upload menggunakan potongan encoding transfer. Gunakan token OAuth 2.0 jika ingin menggunakan potongan encoding transfer dalam upload Anda.

Langkah selanjutnya