Cara menyiapkan Signed HTTP Exchange menggunakan Web Packager

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

Katie Hempenius
Katie Hempenius
X

Pertukaran bertanda tangan (SXG) adalah mekanisme pengiriman yang memungkinkan autentikasi asal resource secara terpisah dari cara pengirimannya. Petunjuk berikut menjelaskan cara menyiapkan Signed HTTP 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 menyalurkan 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 yang ditandatangani sendiri yang dapat digunakan dengan Signed HTTP Exchange.

Petunjuk

  1. Membuat kunci pribadi.

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

    Kunci pribadi akan disimpan sebagai file dengan nama 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 berenkode yang menyampaikan informasi yang diperlukan untuk meminta sertifikat dari certificate authority(CA). Meskipun Anda tidak akan meminta sertifikat dari CA, Anda masih 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 dan berisi konten yang ingin Anda kemas sebagai SXG.

    Dalam penyiapan SXG produksi, ini adalah situs yang Anda miliki. Namun, dalam lingkungan pengujian seperti yang dijelaskan dalam petunjuk ini, lokasi 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 ingin mengetahui 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. Bangun webpkgserver.

    cd webpackager/cmd/webpkgserver
go build .

    webpkgserver adalah biner khusus 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 telah 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 lakukan perubahan berikut:

    • Ubah baris #AllowTestCert = false menjadi AllowTestCert = true.
    • Ubah baris PEMFile = 'path/to/your.pem' untuk mencerminkan 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 memerintahkan webpkgserver agar menggunakan URL data agar menyisipkan sertifikat di kolom cert-url. Untuk pengujian lokal, ini adalah cara yang paling mudah untuk menyajikan sertifikat SXG.
    • Ubah baris Domain = 'example.org' untuk mencerminkan domain yang sertifikatnya Anda buat. Jika Anda telah mengikuti petunjuk dalam artikel ini kata demi kata, namanya akan diubah menjadi example.com. webpkgserver hanya akan mengambil konten dari domain yang ditunjukkan oleh webpkgserver.toml. Jika Anda mencoba mengambil halaman dari domain yang berbeda 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 subresource, opsi konfigurasi webpkgserver.toml berikut relevan:

    • Agar webpkgserver menyisipkan perintah untuk pramuat stylesheet dan subresource skrip sebagai SXG, ubah baris #PreloadCSS = false menjadi PreloadCSS = true. Selain itu, ubah baris #PreloadJS = false menjadi PreloadJS = true.

      Selain 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> 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. Perlu diingat bahwa mengaktifkan opsi ini dapat membuat SXG tidak memenuhi syarat untuk cache SXG Google sesuai 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 webpkgserver.toml diupdate, 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 untuk menguji SXG menggunakan sertifikat pengujian. Jika Chrome diluncurkan tanpa perintah ini, pemeriksaan 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 Anda, serta lokasi cert.pem. Jika telah melakukannya dengan benar, Anda akan melihat peringatan yang ditampilkan di bawah kolom URL. Peringatannya akan tampak 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 kunjungi URL berikut: http://localhost:8080/priv/doc/https://example.com.

    Tindakan ini 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 HTTP Exchange dan tanda tangannya.

    Screenshot tab Pratinjau yang menampilkan SXG

Menayangkan Signed HTTP Exchange menggunakan sertifikat CanSignHttpExchanges

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

Agar singkat, petunjuk ini ditulis dengan asumsi bahwa Anda memahami konsep yang dibahas di bagian Menyiapkan Pertukaran Bertanda Tangan dengan Sertifikat yang ditandatangani sendiri 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 agar otomatis mengambil sertifikat dari CA Anda. Anda dapat mengikuti petunjuk arah di webpkgserver.toml pada halaman ini.

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

Petunjuk

  1. Buat file PEM dengan menggabungkan sertifikat SXG situs Anda, diikuti dengan sertifikat CA situs Anda. Petunjuk lebih lanjut 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 otomatis sertifikat SXG setiap 90 hari (45 hari untuk Google), konfigurasikan opsi di bagian [SXG.ACME] dari webpkgserver.toml. Opsi ini hanya berlaku untuk situs dengan pembuatan akun DigiCert atau Google ACME.

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

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

    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 =