Alat pengembang · generator UUID
Mengapa crypto.randomUUID() Gagal di Halaman HTTP: Penjelasan Konteks Aman
· Cara kerjanya
uuid kriptografi browser-apis
crypto.randomUUID berfungsi di localhost dan di HTTPS, lalu menghilang di host pementasan-HTTP biasa. Postingan ini menjelaskan aturan konteks aman di balik perilaku tersebut dan cara menghasilkan UUID dengan aman jika diterapkan.
TypeError pada pementasan, baik-baik saja di tempat lain — gejala dan perbedaan lingkungan yang menyebabkannya
Pengembang memeriksa pekerjaan mereka di localhost:3000 dan generator UUID berfungsi dengan sempurna. Mereka diterapkan ke pementasan di http://staging. internal. contoh. com (polos HTTP di perusahaan LAN) dan kodenya memunculkan TypeError: crypto.randomUUID bukan fungsi. Kode yang sama dalam produksi di https://example. com berfungsi dengan baik. Ketidakkonsistenan ini membingungkan sampai mereka membaca dokumen MDN: crypto.randomUUID dibatasi untuk konteks yang aman. Konteks yang aman adalah HTTPS atau localhost; asal-HTTP biasa di LAN tidak aman menurut aturan browser, meskipun jaringannya bersifat pribadi. Cara mengatasinya adalah dengan menggunakan crypto.getRandomValues dengan operasi bit manual, atau untuk mengupgrade server staging ke HTTPS. Aturan konteks aman diperkenalkan untuk mencegah kebocoran API sensitif ke koneksi yang tidak terenkripsi.
Apa yang dimaksud dengan konteks aman — aturan browser yang mencadangkan API tertentu untuk asal HTTPS dan untuk localhost
Halaman di atas HTTP biasa dapat disadap oleh penyerang jaringan; mengekspos API kriptografi ke halaman tersebut akan memungkinkan penyerang menghasilkan pengidentifikasi menggunakan API yang telah disusupi. HTTPS mengenkripsi halaman dan semua komunikasi API sehingga penyerang di jaringan tidak dapat mencegat atau mengubah kode. Localhost dianggap aman karena hanya ada di mesin lokal dan tidak dapat disadap melalui jaringan. Asal HTTP lainnya (alamat LAN, domain publik tanpa HTTPS, proksi terbalik yang meneruskan ke HTTP) menurut definisinya tidak aman. Kripto Web API dibagi menjadi dua fungsi: crypto.randomUUID, dibatasi untuk konteks aman, dan crypto.getRandomValues, tersedia dalam konteks aman dan tidak aman. Keduanya menggunakan sistem operasi yang sama CSPRNG.
Bagian mana dari Kripto Web yang diberi gerbang — crypto.randomUUID dan crypto.subtle memerlukan konteks yang aman sedangkan crypto.getRandomValues tidak
Perbedaannya adalah getRandomValues tidak menyembunyikan fakta bahwa Anda menggunakan kriptografi; halaman yang menggunakannya harus secara eksplisit meminta byte acak. Fungsi randomUUID adalah kemudahan yang juga menerapkan konteks aman. Jika aplikasi Anda perlu membuat UUID pada halaman yang tidak aman, Anda harus menggunakan getRandomValues dan menyetel versi dan bit varian secara manual. RFC 9562 menentukan operasi bit: setel byte 6 ke (byte6 & 0x0f) | 0x40 untuk versi 4, dan byte 8 hingga (byte8 & 0x3f) | 0x80 untuk varian RFC. Pustaka ToolAcre melakukan hal ini sebagai cadangan ketika randomUUID tidak tersedia. Mereproduksi kegagalan: menayangkan laman sederhana dari asal HTTP biasa yang tidak dianggap berpotensi dapat dipercaya. Periksa apakah randomUUID terekspos, lalu bandingkan getRandomValues, yang diizinkan oleh referensi Kripto Web dalam konteks yang tidak aman.
Membangun UUID v4 dari getRandomValues — fallback masking dan format yang membuat Anda tetap berada di CSPRNG saat randomUUID hilang
Kode yang sama dalam file yang disajikan melalui HTTPS dapat mengekspos UUID acak. Jika produksi melaporkan "UUID acak bukan suatu fungsi", pertama-tama periksa apakah asal adalah konteks yang aman, kemudian verifikasi dukungan browser dan apakah skrip lain menggantikan objek kripto. Solusinya mungkin berupa HTTPS atau implementasi getRandomValues yang menyetel bit UUID secara eksplisit. Polyfill Math.random bukanlah pengganti yang setara: ia mereproduksi bentuk sambil membatalkan kontrak sumber kriptografi. Pengujian yang hanya menyatakan tanda hubung dan digit versi akan melewatkan substitusi tersebut, jadi tinjau jalur sumber serta string yang dihasilkan.
Contoh praktis — mereproduksi kegagalan pada http:// asal dan mengonfirmasi perbaikan
Namun pengenalnya sekarang dapat diprediksi. Penyerang yang menangkap beberapa UUID dari sistem Anda dapat memprediksi UUID berikutnya. Jika suatu aplikasi secara keliru memperlakukan pengidentifikasi tersebut sebagai kredensial pembawa, prediktabilitas menjadi kegagalan otorisasi dan bukan cacat kosmetik. Strategi yang benar adalah meningkatkan server ke HTTPS (selalu merupakan langkah yang tepat untuk halaman mana pun dengan autentikasi atau data sensitif) atau menggunakan getRandomValues dengan operasi bit eksplisit (yang membutuhkan lebih banyak kode tetapi baik secara kriptografis). Konteks aman diterapkan oleh browser; Anda tidak dapat mengatasinya dengan variabel konfigurasi atau lingkungan. Generator ToolAcre diterapkan di HTTPS, sehingga crypto.randomUUID tersedia. Saat Anda membuat UUID di alat, alat tersebut akan menggunakan randomUUID (jika pemeriksaan konteks aman lolos) atau getRandomValues dengan operasi bit (jika Anda menggunakan HTTP biasa, meskipun ini jarang terjadi).
Mengapa Anda tidak boleh melakukan polyfill dengan Math.random — jalan pintas yang menggiurkan dan biaya keamanan yang ditimbulkannya
Tidak ada jalur yang kembali ke Math.random. Jika Anda membuat generator UUID Anda sendiri dan menargetkan asal yang tidak aman, gunakan getRandomValues dan lakukan sendiri operasi bitnya. Uji pada HTTPS dan localhost untuk mengonfirmasi randomUUID berfungsi, lalu uji pada http:// origin untuk mengonfirmasi bahwa fallback getRandomValues Anda sudah benar. Memahami batasan konteks aman membantu Anda merancang strategi penerapan. Jika aplikasi Anda harus berjalan di LAN pribadi tanpa HTTPS (infrastruktur lama, sistem tertanam), fallback getRandomValues adalah langkah maju Anda. Jika Anda punya pilihan, tingkatkan ke HTTPS di mana saja; ini gratis dengan Let's Encrypt, dan investasinya terbayar dalam keamanan di seluruh aplikasi. Pengembangan di localhost tidak memiliki batasan, jadi ujilah generator UUID Anda di localhost dan pada pementasan HTTPS sebelum diterapkan ke produksi. Produksi harus selalu HTTPS.
Yang tidak tercakup dalam hal ini — runtime server seperti Node.js dan Deno, yang mengekspos API tanpa aturan konteks aman
Pembatasan ini bukan merupakan bug atau gangguan; ini adalah fitur keamanan yang mencegah kecelakaan dan memaksa Anda memikirkan enkripsi. Pola yang lebih luas adalah bahwa API kriptografi web dilindungi oleh konteks yang aman. crypto.getRandomValues, kripto. tak kentara. mengenkripsi, kripto. tak kentara. generateKey, dan semua operasi sensitif lainnya memerlukan HTTPS atau localhost. Tidak ada pengecualian, tidak ada override, tidak ada cara untuk menonaktifkan centang. Satu halaman yang tidak aman melanggar jaminan keamanan bagi pengguna Anda. Bahkan jika Anda berhati-hati dalam menggunakan API kripto hanya pada halaman tertentu, kesalahan (atau ketergantungan yang menyertakan generator UUID) dapat membocorkan pembuatan keacakan ke halaman yang tidak terenkripsi. Generator ToolAcre menerapkan hal ini pada tingkat kode: jika randomUUID tidak tersedia (konteks tidak aman), ia menggunakan getRandomValues, yang tersedia tetapi memperingatkan peninjau kode mana pun bahwa sesuatu yang tidak biasa sedang terjadi.
Kesimpulan: perbaiki asal, bukan generatornya — ToolAcre disajikan melalui HTTPS, sehingga generatornya berjalan dalam konteks yang aman sesuai desain
Lebih baik lagi, ia menolak untuk membuat pengenal jika konteks aman benar-benar tidak tersedia (di lingkungan di mana getRandomValues juga tidak tersedia, yang jarang terjadi tetapi mungkin terjadi pada sistem lama atau sistem tertanam). Memigrasikan sistem yang ada ke HTTPS untuk mendukung API kriptografi yang aman adalah proyek yang umum. Mulailah dengan asal tempat UUID dibuat (server autentikasi Anda, backend API, atau layanan aplikasi kunci). Dapatkan sertifikat TLS (Let's Encrypt menyediakannya secara gratis). Konfigurasikan server web Anda untuk melayani HTTPS secara default dan mengalihkan permintaan HTTP ke HTTPS. Uji dengan beberapa browser dan klien API untuk memastikan semuanya berfungsi. Kemudian audit kode Anda untuk mencari API kripto yang tersisa yang mungkin dipanggil pada halaman yang tidak terenkripsi dan perbaiki. Generator ToolAcre mengasumsikan HTTPS; jika Anda menggunakannya, Anda sudah menjadi bagian dari perjalanan ke sana.