Cara menyiapkan Signed HTTP Exchange menggunakan Web Packager

Pelajari cara menayangkan Signed HTTP Exchange (SXG) menggunakan Web Packager.

Katie Hempenius
Katie Hempenius
X

Signed exchange (SXG) adalah mekanisme pengiriman yang memungkinkan autentikasi asal resource secara independen dari cara pengirimannya. Petunjuk berikut menjelaskan cara menyiapkan Signed Exchange menggunakan Web Packager. Petunjuk disertakan untuk sertifikat yang ditandatangani sendiri dan CanSignHttpExchanges.

Menayangkan SXG menggunakan sertifikat yang ditandatangani sendiri

Penggunaan sertifikat yang ditandatangani sendiri untuk menayangkan SXG terutama digunakan untuk tujuan demonstrasi dan pengujian. SXG yang ditandatangani dengan sertifikat yang ditandatangani sendiri akan menghasilkan pesan error di browser saat digunakan di luar lingkungan pengujian dan tidak boleh ditayangkan ke crawler.

Prasyarat

Untuk mengikuti petunjuk ini, Anda harus menginstal openssl dan Go di lingkungan pengembangan.

Membuat sertifikat yang ditandatangani sendiri

Bagian ini menjelaskan cara membuat sertifikat dengan tanda tangan sendiri yang dapat digunakan dengan pertukaran yang ditandatangani.

Petunjuk

  1. Buat kunci pribadi.

    openssl ecparam -out priv.key -name prime256v1 -genkey

    Kunci pribadi akan disimpan sebagai file bernama priv.key.

  2. Buat permintaan penandatanganan sertifikat (CSR).

    openssl req -new -sha256 -key priv.key -out cert.csr -subj '/O=Web Packager Demo/CN=example.com'

    Permintaan penandatanganan sertifikat adalah blok teks yang dienkode yang menyampaikan informasi yang diperlukan untuk meminta sertifikat dari certificate authority(CA). Meskipun Anda tidak akan meminta sertifikat dari CA, Anda tetap perlu membuat permintaan penandatanganan sertifikat.

    Perintah di atas membuat permintaan penandatanganan sertifikat untuk organisasi bernama Web Packager Demo yang memiliki nama umum example.com. Nama umum harus berupa nama domain situs yang sepenuhnya memenuhi syarat yang berisi konten yang ingin Anda paketkan sebagai SXG.

    Dalam penyiapan SXG produksi, ini akan menjadi situs yang Anda miliki. Namun, di lingkungan pengujian seperti yang dijelaskan dalam petunjuk ini, situs tersebut dapat berupa situs mana pun.

  3. Buat sertifikat yang memiliki ekstensi CanSignHttpExchanges.

    openssl x509 -req -days 90 -in cert.csr -signkey priv.key -out cert.pem -extfile <(echo -e "1.3.6.1.4.1.11129.2.1.22 = ASN1:NULL\nsubjectAltName=DNS:example.com")

    Perintah ini menggunakan kunci pribadi dan CSR yang dibuat pada langkah 1 dan 2 untuk membuat file sertifikat cert.pem. Flag -extfile mengaitkan sertifikat dengan ekstensi sertifikat CanSignHttpExchanges (1.3.6.1.4.1.11129.2.1.22 adalah ID objek untuk ekstensi CanSignHttpExchanges). Selain itu, tanda -extfile juga menentukan example.com sebagai Nama Alternatif Subjek.

    Jika penasaran dengan konten cert.pem, Anda dapat melihatnya menggunakan perintah berikut:

    openssl x509 -in cert.pem -noout -text

    Anda telah selesai membuat kunci pribadi dan sertifikat. Anda akan memerlukan file priv.key dan cert.pem di bagian berikutnya.

Menyiapkan server Web Packager untuk pengujian

Prasyarat

  1. Instal Web Packager.

    git clone https://github.com/google/webpackager.git

  2. Build webpkgserver.

    cd webpackager/cmd/webpkgserver
go build .

    webpkgserver adalah biner tertentu dalam project Web Packager.

  3. Pastikan webpkgserver telah diinstal dengan benar.

    ./webpkgserver --help

    Perintah ini akan menampilkan informasi tentang penggunaan webpkgserver. Jika tidak berhasil, langkah pemecahan masalah pertama yang baik adalah memverifikasi bahwa GOPATH Anda dikonfigurasi dengan benar.

Petunjuk

  1. Buka direktori webpkgserver (Anda mungkin sudah berada di direktori ini).

    cd /path/to/cmd/webpkgserver

  2. Buat file webpkgsever.toml dengan menyalin contoh.

    cp ./webpkgserver.example.toml ./webpkgserver.toml

    File ini berisi opsi konfigurasi untuk webpkgserver.

  3. Buka webpkgserver.toml dengan editor pilihan Anda dan buat perubahan berikut:

    • Ubah baris #AllowTestCert = false menjadi AllowTestCert = true.
    • Ubah baris PEMFile = 'path/to/your.pem' agar sesuai dengan jalur ke sertifikat PEM, cert.pem, yang Anda buat. Jangan ubah baris yang menyebutkan TLS.PEMFile—ini adalah opsi konfigurasi yang berbeda.
    • Ubah baris KeyFile = 'priv.key' untuk mencerminkan jalur kunci pribadi, priv.key, yang Anda buat. Jangan ubah baris yang menyebutkan TLS.KeyFile—ini adalah opsi konfigurasi yang berbeda.
    • Ubah baris #CertURLBase = '/webpkg/cert' menjadi CertURLBase = 'data:'. CertURLBase menunjukkan lokasi penayangan sertifikat SXG. Informasi ini digunakan untuk menetapkan parameter cert-url di header Signature SXG. Di lingkungan produksi, CertURLBase digunakan seperti ini: CertURLBase = 'https://mysite.com/'. Namun, untuk pengujian lokal, CertURLBase = 'data:' dapat digunakan untuk menginstruksikan webpkgserver menggunakan URL data untuk menyisipkan sertifikat di kolom cert-url. Untuk pengujian lokal, ini adalah cara paling praktis untuk menayangkan sertifikat SXG.
    • Ubah baris Domain = 'example.org' untuk mencerminkan domain yang sertifikatnya Anda buat. Jika Anda telah mengikuti petunjuk dalam artikel ini secara verbatim, nilai ini akan diubah menjadi example.com. webpkgserver hanya akan mengambil konten dari domain yang ditunjukkan oleh webpkgserver.toml. Jika Anda mencoba mengambil halaman dari domain lain tanpa memperbarui webpkgserver.toml, log webpkgserver akan menampilkan pesan error URL doesn't match the fetch targets.

    Opsional

    Jika Anda ingin mengaktifkan atau menonaktifkan pramuat sub-resource, opsi konfigurasi webpkgserver.toml berikut relevan:

    • Agar webpkgserver menyisipkan perintah untuk memuat ulang sub-resource stylesheet dan skrip sebagai SXG, ubah baris #PreloadCSS = false menjadi PreloadCSS = true. Selain itu, ubah baris #PreloadJS = false menjadi PreloadJS = true.

      Sebagai alternatif untuk menggunakan opsi konfigurasi ini, Anda dapat menambahkan header Link: rel="preload" dan tag <link rel="preload"> secara manual ke HTML halaman.

    • Secara default, webpkgserver mengganti tag <link rel="preload"> yang ada dengan tag <link> yang setara yang diperlukan untuk mengambil konten ini sebagai SXG. Dengan demikian, webpkgserver akan menetapkan perintah allowed-alt-sxg dan header-integrity sesuai kebutuhan—penulis HTML tidak perlu menambahkannya secara manual. Untuk mengganti perilaku ini dan mempertahankan pramuat non-SXG yang ada, ubah #KeepNonSXGPreloads (default = false) menjadi KeepNonSXGPreloads = true. Perhatikan bahwa mengaktifkan opsi ini dapat membuat SXG tidak memenuhi syarat untuk cache SXG Google sesuai dengan persyaratan ini.

  4. Mulai webpkgserver.

    ./webpkgserver

    Jika server berhasil dimulai, Anda akan melihat pesan log berikut: shell Listening at 127.0.0.1:8080 Successfully retrieved valid OCSP. Writing to cache in /private/tmp/webpkg

    Pesan log Anda mungkin terlihat sedikit berbeda. Secara khusus, direktori yang digunakan webpkgserver untuk meng-cache sertifikat bervariasi menurut sistem operasi.

    Jika Anda tidak melihat pesan ini, langkah pemecahan masalah pertama yang baik adalah memeriksa kembali webpkgserver.toml.

    Jika mengupdate webpkgserver.toml, Anda harus memulai ulang webpkgserver.

  5. Luncurkan Chrome menggunakan perintah berikut: shell /Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome \ --user-data-dir=/tmp/udd \ --ignore-certificate-errors-spki-list=`openssl x509 -noout -pubkey -in cert.pem | openssl pkey -pubin -outform der | openssl dgst -sha256 -binary | base64`

    Perintah ini menginstruksikan Chrome untuk mengabaikan error sertifikat yang terkait dengan cert.pem. Hal ini memungkinkan pengujian SXG menggunakan sertifikat pengujian. Jika Chrome diluncurkan tanpa perintah ini, memeriksa SXG di DevTools akan menampilkan error Certificate verification error: ERR_CERT_INVALID.

    Catatan:

    Anda mungkin perlu menyesuaikan perintah ini untuk mencerminkan lokasi Chrome di komputer, serta lokasi cert.pem. Jika Anda telah melakukannya dengan benar, Anda akan melihat peringatan yang ditampilkan di bawah kolom URL. Peringatan akan terlihat seperti ini: You are using an unsupported command-line flag: --ignore-certificate-errors-spki-list=9uxADcgc6/ho0mJLRMBcOjfBaN21k0sOInoMchr9CMY=.

    Jika peringatan tidak menyertakan string hash, Anda belum menunjukkan lokasi sertifikat SXG dengan benar.

  6. Buka tab Jaringan DevTools, lalu buka URL berikut: http://localhost:8080/priv/doc/https://example.com.

    Tindakan ini akan membuat permintaan ke instance webpackager yang berjalan di http://localhost:8080 untuk SXG yang berisi konten https://example.com. /priv/doc/ adalah endpoint API default yang digunakan oleh webpackager.

    Screenshot tab Jaringan DevTools yang menampilkan SXG dan sertifikatnya.

    Resource berikut tercantum di tab Jaringan:

    • Resource dengan jenis signed-exchange. Ini adalah SXG.
    • Resource dengan jenis cert-chain+cbor. Ini adalah sertifikat SXG. Sertifikat SXG harus menggunakan format application/cert-chain+cbor.
    • Resource dengan jenis document. Ini adalah konten yang telah dikirimkan melalui SXG.

    Jika Anda tidak melihat resource ini, coba hapus cache browser, lalu muat ulang http://localhost:8080/priv/doc/https://example.com.

    Klik tab Preview untuk melihat informasi selengkapnya tentang Signed Exchange dan tanda tangannya.

    Screenshot tab Pratinjau yang menampilkan SXG

Menayangkan Signed HTTP Exchange menggunakan sertifikat CanSignHttpExchanges

Petunjuk di bagian ini menjelaskan cara menayangkan SXG menggunakan sertifikat CanSignHttpExchanges. Penggunaan SXG dalam produksi memerlukan sertifikat CanSignHttpExchanges.

Agar lebih ringkas, petunjuk ini ditulis dengan asumsi bahwa Anda memahami konsep yang dibahas di bagian Menyiapkan Signed Exchanges menggunakan sertifikat yang ditandatangani sendiri.

Prasyarat

  • Anda memiliki sertifikat CanSignHttpExchanges. Halaman ini mencantumkan CA yang menawarkan jenis sertifikat ini.

  • Jika tidak memiliki sertifikat, Anda dapat mengonfigurasi webpkgserver untuk mengambil sertifikat secara otomatis dari CA. Anda dapat mengikuti petunjuk untuk apa yang dimasukkan ke dalam webpkgserver.toml di halaman ini.

  • Meskipun bukan persyaratan, sebaiknya jalankan webpkgserver di belakang server edge. Jika tidak menggunakan server edge, Anda harus mengonfigurasi opsi TLS.PEMFile dan TLS.KeyFile di webpkgserver.toml. Secara default, webpkgserver berjalan melalui HTTP. Namun, sertifikat SXG harus ditayangkan melalui HTTPS agar dianggap valid oleh browser. Mengonfigurasi TLS.PEMFile dan TLS.KeyFile memungkinkan webpkgserver menggunakan HTTPS, sehingga menayangkan sertifikat SXG langsung ke browser.

Petunjuk

  1. Buat file PEM dengan menggabungkan sertifikat SXG situs Anda, diikuti dengan sertifikat CA situs Anda. Petunjuk selengkapnya tentang hal ini dapat ditemukan di sini.

    PEM adalah format file yang biasa digunakan sebagai "penampung" untuk menyimpan beberapa sertifikat.

  2. Buat file webpkgsever.toml baru dengan menyalin contoh.

    cp ./webpkgserver.example.toml ./webpkgserver.toml

  3. Buka webpkgserver.toml dengan editor pilihan Anda dan buat perubahan berikut:

    • Ubah baris PEMFile = cert.pem untuk mencerminkan lokasi file PEM yang berisi rantai sertifikat lengkap Anda.
    • Ubah baris KeyFile = 'priv.key' untuk mencerminkan lokasi kunci pribadi yang sesuai dengan File PEM Anda.
    • Ubah baris Domain = 'example.org' untuk mencerminkan situs Anda.
    • (Opsional) Agar webpkgserver memperpanjang sertifikat SXG secara otomatis setiap 90 hari (45 hari untuk Google), konfigurasikan opsi di bagian [SXG.ACME] di webpkgserver.toml. Opsi ini hanya berlaku untuk situs dengan penyiapan akun ACME DigiCert atau Google.

  4. Konfigurasikan server edge Anda untuk meneruskan traffic ke instance webpkgserver.

    Ada dua jenis permintaan utama yang ditangani oleh webpkgserver: permintaan untuk SXG (yang ditayangkan oleh endpoint /priv/doc/) dan permintaan untuk sertifikat SXG (yang ditayangkan oleh endpoint /webpkg/cert/). Aturan penulisan ulang URL untuk setiap jenis permintaan ini sedikit berbeda. Untuk mengetahui informasi selengkapnya, lihat Berjalan di belakang server edge frontend.

    Catatan:

    Secara default, webpkgserver menayangkan sertifikat SXG di /webpkg/cert/$CERT_HASH—misalnya, /webpkg/cert/-0QmE0gvoedn92gtwI3s7On9zPevJGm5pn2RYhpZxgY. Untuk membuat $CERT_HASH, jalankan perintah berikut: shell openssl base64 -in cert.pem -d | openssl dgst -sha256 -binary | base64 | tr /+ _- | tr -d =