Permintaan kanonis

Permintaan kanonis menentukan elemen permintaan yang harus disertakan pengguna saat mengirim permintaan yang diautentikasi oleh tanda tangan V4, seperti URL bertanda tangan, ke Cloud Storage.

Ringkasan

Permintaan kanonis adalah string yang mewakili permintaan HTTP tertentu ke Cloud Storage. Anda menggunakan permintaan kanonis beserta kunci kriptografis, seperti kunci RSA, untuk membuat tanda tangan yang kemudian disertakan dalam permintaan yang sebenarnya sebagai autentikasi.

Permintaan kanonis mencakup informasi seperti kata kerja HTTP, parameter string kueri, dan header yang diharapkan akan digunakan dalam permintaan sebenarnya, serta objek, bucket, atau resource lain yang akan diminta.

Permintaan kanonis memastikan bahwa saat menerima permintaan, Cloud Storage dapat menghitung tanda tangan yang sama dengan yang Anda hitung. Jika versi Anda dan versi yang dihitung oleh Cloud Storage tidak cocok, permintaan akan gagal.

Struktur

Permintaan kanonis memiliki struktur berikut, termasuk penggunaan baris baru di antara setiap elemen:

HTTP_VERB
PATH_TO_RESOURCE
CANONICAL_QUERY_STRING
CANONICAL_HEADERS

SIGNED_HEADERS
PAYLOAD

Kata kerja HTTP

Permintaan yang ditandatangani dapat menggunakan kata kerja HTTP berikut, yang harus ditentukan sebagai bagian dari permintaan kanonis:

  • DELETE
  • GET
  • HEAD
  • POST1
  • PUT

1 URL yang ditandatangani hanya dapat digunakan untuk permintaan POST yang memulai upload yang dapat dilanjutkan. Lihat Menggunakan URL yang ditandatangani dengan upload yang dapat dilanjutkan untuk informasi selengkapnya.

Jalur resource

Permintaan kanonis mencakup jalur ke resource tempat permintaan diterapkan. Jalur ke resource adalah segala hal yang mengikuti nama host, tetapi mendahului string kueri.

Misalnya, jika URL Cloud Storage adalah https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg, jalur ke resource adalah /example-bucket/cat-pics/tabby.jpeg.

Jika Anda menggunakan URL Cloud Storage alternatif seperti https://example-bucket.storage.googleapis.com/cat-pics/tabby.jpeg, jalur ke resource tersebut adalah /cat-pics/tabby.jpeg.

Untuk mengetahui endpoint URL tambahan yang dapat digunakan dengan URL yang ditandatangani, lihat endpoint permintaan XML API.

Saat menentukan jalur resource, Anda harus mengenkode persen karakter yang dicadangkan berikut: ?=!#$&'()*+,:;@[]" Semua encoding persen lain yang digunakan di URL juga harus disertakan dalam jalur resource.

String Kueri Kanonis

Permintaan kanonis menentukan setiap parameter string kueri yang nantinya akan disertakan dalam permintaan bertanda tangan yang menggunakan tanda tangan yang relevan, dengan pengecualian parameter string kueri X-Goog-Signature atau X-Amz-Signature. String kueri yang ditentukan dalam permintaan kanonis disebut string kueri kanonis

String kueri adalah segala sesuatu yang diikuti tanda tanya (?) di akhir jalur resource.

Misalnya, jika URL Cloud Storage adalah https://storage.googleapis.com/example-bucket/cat-pics/tabby.jpeg?generation=1360887697105000&userProject=my-project, string kuerinya adalah generation=1360887697105000&userProject=my-project.

Saat membuat string kueri kanonis:

  • Parameter dalam string kueri harus diurutkan menurut nama menggunakan pengurutan leksikografis berdasarkan nilai poin kode.

  • Setiap parameter dalam string kueri harus dipisahkan dengan &.

  • Jika string kueri kanonis Anda kosong, bagian dari keseluruhan permintaan kanonis ini hanyalah baris baru (\n).

Parameter string kueri yang diperlukan

Sebagian besar parameter string kueri ditambahkan sesuai kebutuhan, tetapi hal berikut harus disertakan dalam permintaan kanonis saat Anda ingin menggunakannya untuk membuat URL yang ditandatangani:

  • X-Goog-Algorithm: Algoritma yang akan Anda gunakan untuk menandatangani URL. Nilai yang valid adalah GOOG4-RSA-SHA256 dan GOOG4-HMAC-SHA256.
  • X-Goog-Credential: Kredensial yang akan Anda gunakan untuk menandatangani URL. Kredensial terdiri dari pemberi otorisasi dan cakupan kredensial yang diberikan dalam format: AUTHORIZER%2FCREDENTIAL_SCOPE. Pemberi otorisasi dapat berupa nama akun layanan atau ID akses kunci HMAC.
  • X-Goog-Date: Tanggal dan waktu URL yang ditandatangani dapat digunakan, dalam format dasar ISO 8601 YYYYMMDD'T'HHMMSS'Z'.
  • X-Goog-Expires: Masa aktif URL yang ditandatangani, diukur dalam hitungan detik dari X-Goog-Date. Nilai habis masa berlaku terpanjang adalah 604.800 detik (7 hari).
  • X-Goog-SignedHeaders: Daftar nama header yang dipisahkan titik koma yang ditentukan dalam permintaan kanonis. Header ini juga dikenal sebagai header bertanda tangan. host harus berupa salah satu nama header.

Parameter string kueri ini kemudian harus digunakan dalam URL yang ditandatangani itu sendiri, bersama dengan parameter string kueri X-Goog-Signature, yang berisi tanda tangan yang mengautentikasi permintaan.

Header Kanonis

Permintaan kanonis mencakup header apa pun yang selanjutnya harus disertakan dalam permintaan bertanda tangan yang menggunakan tanda tangan yang relevan. Namun, permintaan yang ditandatangani tersebut dapat menyertakan header tambahan yang tidak ditentukan dalam permintaan kanonis, kecuali seperti yang disebutkan dalam header wajib. Header yang ditentukan dalam permintaan kanonis disebut header kanonis.

Header kanonis dapat mencakup header kustom serta header ekstensi yang dimulai dengan x-goog-.

Saat menentukan header kanonis, perhatikan hal-hal berikut:

  • Gunakan huruf kecil untuk semua nama header.
  • Urutkan semua header berdasarkan nama header menggunakan pengurutan leksikografis berdasarkan nilai titik kode.
  • Pisahkan setiap header dengan baris baru (\n).
  • Hapus nama header duplikat dengan membuat satu nama header dengan daftar nilai yang dipisahkan koma. Pastikan tidak ada spasi kosong di antara nilai, dan pastikan urutan daftar yang dipisahkan koma sesuai dengan urutan header yang muncul dalam permintaan Anda. Untuk mengetahui informasi selengkapnya, lihat RFC 7230 bagian 3.2.
  • Ganti spasi kosong atau baris baru lipat (CRLF atau LF) apa pun dengan satu spasi. Untuk informasi selengkapnya tentang spasi kosong lipat, lihat RFC 7230, bagian 3.2.4..

  • Hapus spasi kosong di sekitar titik dua yang muncul setelah nama header.

    Misalnya, menggunakan header kustom x-goog-acl: private tanpa menghapus spasi setelah tanda titik dua akan menampilkan error 403 Forbidden, karena tanda tangan permintaan yang Anda hitung tidak cocok dengan tanda tangan yang dihitung Cloud Storage.

Contoh

Jika Anda memiliki set header berikut:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

Konstruksi header kanonis dalam permintaan kanonis adalah:

content-type:text/plain
host:storage.googleapis.com
x-goog-meta-reviewer:jane,john

Header kanonis yang diperlukan

Sebagian besar header, seperti content-type, ditambahkan sesuai kebutuhan, tetapi header berikut harus selalu ditentukan dalam header kanonis jika Anda ingin menggunakannya dalam permintaan yang ditandatangani:

  • host: URI yang digunakan untuk mengakses Cloud Storage.
  • Header diawali dengan x-goog-. Satu-satunya header semacam ini yang bersifat opsional untuk disertakan sebagai header kanonis adalah x-goog-content-sha256.
  • Header diawali dengan x-amz-. Satu-satunya header semacam ini yang bersifat opsional untuk disertakan sebagai header kanonis adalah x-amz-content-sha256.

Header bertanda tangan

Header bertanda tangan adalah bagian nama dari header kanonis.

Untuk membuat daftar header bertanda tangan, konversikan semua nama header menjadi huruf kecil, urutkan berdasarkan kode karakter, dan gunakan titik koma (;) untuk memisahkan masing-masing.

Contoh

Jika Anda memiliki set header berikut:

host: storage.googleapis.com
content-type: text/plain
x-goog-meta-reviewer: jane
x-goog-meta-reviewer: john

Pembuatan header yang ditandatangani dalam permintaan kanonis adalah:

content-type;host;x-goog-meta-reviewer

Payload

  • Jika permintaan kanonis Anda akan digunakan untuk membuat URL yang ditandatangani, nilai ini harus berupa string UNSIGNED-PAYLOAD.

  • Jika permintaan kanonis Anda akan digunakan untuk membuat tanda tangan yang akan digunakan dalam header Authorization:

    • Gunakan UNSIGNED-PAYLOAD jika Anda ingin mengizinkan payload arbitrer sebagai bagian dari permintaan.

    • Gunakan UNSIGNED-PAYLOAD jika permintaan akan memulai upload yang dapat dilanjutkan, karena header x-goog-content-sha256 diabaikan untuk upload yang dapat dilanjutkan.

    • Jika Anda hanya ingin mengizinkan payload tertentu, nilai ini harus berupa hash SHA-256 berenkode hex huruf kecil dari payload yang diinginkan. Untuk mewajibkan payload kosong, gunakan string kosong sebagai input untuk fungsi hash. Contoh payload yang di-hash (dalam hal ini adalah payload kosong) adalah:

      e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Contoh

Berikut adalah contoh permintaan kanonis yang diformat dengan benar, dengan baris baru ditampilkan sebagai baris baru yang sebenarnya, bukan \n:

GET
/example-bucket/tabby.jpeg

host:storage.googleapis.com
x-amz-content-sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
x-amz-date:20190301T190859Z

host;x-amz-content-sha256;x-amz-date
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855

Langkah berikutnya