Strumenti per sviluppatori · Generatore UUID
Perché crypto.randomUUID() fallisce sulle pagine HTTP: spiegazione dei contesti protetti
· Come funziona
uuid crittografia API del browser
crypto.randomUUID funziona su localhost e su HTTPS, quindi svanisce su un host di staging semplice-HTTP. Questo post spiega la regola del contesto sicuro alla base di tale comportamento e come generare un UUID in modo sicuro dove si applica.
TypeError sulla stadiazione, va bene ovunque: il sintomo e la differenza di ambiente che lo causa
Uno sviluppatore controlla il proprio lavoro su localhost:3000 e il generatore UUID funziona perfettamente. Vengono distribuiti nella gestione temporanea presso http://staging. interna. esempio. com (semplice HTTP sull'azienda LAN) e il codice genera TypeError: crypto.randomUUID non è una funzione. Lo stesso codice in produzione su https://example. com funziona bene. L'incoerenza è sconcertante finché non leggono i documenti MDN: crypto.randomUUID è limitato a contesti protetti. Un contesto sicuro è HTTPS o localhost; un'origine sempliceHTTP su LAN non è protetta dalla regola del browser, anche se la rete è privata. La soluzione consiste nell'utilizzare crypto.getRandomValues con operazioni bit manuali o nell'aggiornare il server di staging a HTTPS. La regola del contesto sicuro è stata introdotta per impedire la fuoriuscita di API sensibili da connessioni non crittografate.
Cos'è un contesto sicuro: la regola del browser che riserva determinate API per le origini HTTPS e per localhost
Una pagina su HTTP può essere intercettata da un utente malintenzionato di rete; l'esposizione delle API crittografiche a tale pagina consentirebbe a un utente malintenzionato di generare identificatori utilizzando un file API compromesso. HTTPS crittografa la pagina e tutte le comunicazioni API in modo che un utente malintenzionato sulla rete non possa intercettare o modificare il codice. Localhost viene considerato intrinsecamente sicuro perché esiste solo sul computer locale e non può essere intercettato sulla rete. Qualsiasi altra origine HTTP (un indirizzo LAN, un dominio pubblico senza HTTPS, un proxy inverso che inoltra a HTTP) non è sicura per definizione. Il Web Crypto API è suddiviso in due funzioni: crypto.randomUUID, limitato a contesti sicuri, e crypto.getRandomValues, disponibile sia in contesti sicuri che non sicuri. Entrambi utilizzano lo stesso sistema operativo CSPRNG.
Quali parti di Web Crypto sono protette: crypto.randomUUID e crypto.subtle richiedono un contesto sicuro mentre crypto.getRandomValues no
La differenza è che getRandomValues non nasconde il fatto che stai utilizzando la crittografia; una pagina che lo utilizza deve richiedere esplicitamente byte casuali. La funzione randomUUID è una comodità che impone anche un contesto sicuro. Se la tua applicazione deve generare UUID su una pagina non sicura, devi utilizzare getRandomValues e impostare manualmente i bit della versione e della variante. RFC 9562 specifica le operazioni sui bit: imposta byte 6 su (byte6 & 0x0f) | 0x40 per la versione 4 e dal byte 8 a (byte8 e 0x3f) | 0x80 per la variante RFC. La libreria ToolAcre fa esattamente questo come fallback quando randomUUID non è disponibile. Riproduzione dell'errore: fornire una pagina semplice da un'origine HTTP semplice che non viene trattata come potenzialmente affidabile. Controlla se randomUUID è esposto, quindi confronta getRandomValues, che il riferimento Web Crypto consente in contesti non sicuri.
Creazione di un UUID v4 da getRandomValues: il fallback di mascheramento e formattazione che ti mantiene su CSPRNG quando manca randomUUID
Lo stesso codice in un file servito su HTTPS può esporre randomUUID. Se la produzione segnala "randomUUID non è una funzione", controlla innanzitutto se l'origine è un contesto sicuro, quindi verifica il supporto del browser e se un altro script ha sostituito l'oggetto crittografico. Il rimedio potrebbe essere HTTPS o un'implementazione getRandomValues che imposta esplicitamente i bit UUID. Un polyfill Math.random non è un fallback equivalente: riproduce la forma eliminando il contratto di origine crittografica. I test che asseriscono solo trattini e cifre della versione mancheranno tale sostituzione, quindi rivedi il percorso di origine e la stringa risultante.
Esempio funzionante: riproduzione dell'errore su un'origine http:// e conferma della correzione
Ma l’identificatore è ora prevedibile. Un utente malintenzionato che cattura alcuni UUID dal tuo sistema può prevedere quello successivo. Se un'applicazione tratta erroneamente un identificatore di questo tipo come una credenziale del portatore, la prevedibilità diventa un errore di autorizzazione piuttosto che un difetto estetico. La strategia corretta è aggiornare il server a HTTPS (sempre la mossa giusta per qualsiasi pagina con autenticazione o dati sensibili) o utilizzare getRandomValues con operazioni bit esplicite (che richiede più codice ma è crittograficamente corretta). Il contesto sicuro viene applicato dal browser; non è possibile aggirare il problema con variabili di configurazione o di ambiente. Il generatore ToolAcre viene distribuito su HTTPS, quindi crypto.randomUUID è disponibile. Quando generi un UUID nello strumento, utilizza randomUUID (se il controllo del contesto protetto supera) o getRandomValues con operazioni bit (se sei su HTTP semplice, anche se questo è raro).
Perché non dovresti eseguire il polyfill con Math.random: la scorciatoia allettante e il costo in termini di sicurezza che comporta
Nessuno dei due percorsi ritorna a Math.random. Se stai creando il tuo generatore UUID e hai come target origini non sicure, utilizza getRandomValues ed esegui tu stesso le operazioni sui bit. Testa sia su HTTPS che su localhost per confermare il funzionamento di randomUUID, quindi prova su un'origine http:// per confermare che il fallback getRandomValues è corretto. Comprendere la restrizione del contesto protetto aiuta a progettare strategie di distribuzione. Se la tua applicazione deve essere eseguita su un LAN privato senza HTTPS (infrastruttura legacy, sistemi incorporati), il fallback getRandomValues è il tuo percorso da seguire. Se puoi scegliere, esegui l'upgrade a HTTPS ovunque; con Let's Encrypt è gratuito e l'investimento viene ripagato in termini di sicurezza nell'intera applicazione. Lo sviluppo su localhost non ha restrizioni, quindi testa il tuo generatore UUID su localhost e sullo staging HTTPS prima di distribuirlo in produzione. La produzione dovrebbe essere sempre HTTPS.
Cosa non copre: runtime del server come Node.js e Deno, che espongono API senza una regola di contesto sicuro
La restrizione non è un bug o un fastidio; è una funzionalità di sicurezza che previene gli incidenti e ti costringe a pensare alla crittografia. Lo schema più ampio è che le API di crittografia web sono controllate da un contesto sicuro. crypto.getRandomValues, crittografato. impercettibile. crittografare, crittografare. impercettibile. generateKey e tutte le altre operazioni sensibili richiedono HTTPS o localhost. Non esiste alcuna eccezione, nessuna sostituzione, nessun modo per disabilitare il controllo. Una singola pagina non sicura infrange le garanzie di sicurezza per i tuoi utenti. Anche se fai attenzione a utilizzare le API crittografiche solo su determinate pagine, un errore (o una dipendenza che include un generatore UUID) può far trapelare la generazione di casualità in una pagina non crittografata. Il generatore ToolAcre lo applica a livello di codice: se randomUUID non è disponibile (contesto non sicuro), utilizza getRandomValues, che è disponibile ma avvisa qualsiasi revisore del codice che sta accadendo qualcosa di insolito.
Conclusione: correggi l'origine, non il generatore: ToolAcre viene servito su HTTPS, quindi il suo generatore funziona in un contesto sicuro in base alla progettazione
Meglio ancora, si rifiuta di generare un identificatore se il contesto sicuro non è veramente disponibile (in ambienti in cui anche getRandomValues non è disponibile, cosa rara ma possibile nei sistemi più vecchi o incorporati). La migrazione di un sistema esistente a HTTPS per supportare le API di crittografia sicura è un progetto comune. Inizia con l'origine in cui vengono generati gli UUID (il tuo server di autenticazione, il backend API o il servizio dell'applicazione chiave). Acquisisci un certificato TLS (Let's Encrypt li fornisce gratuitamente). Configura il tuo server web per servire HTTPS per impostazione predefinita e reindirizzare le richieste HTTP a HTTPS. Prova con più browser e client API per assicurarti che tutto funzioni. Quindi controlla il tuo codice per eventuali API crittografiche rimanenti che potrebbero essere chiamate su pagine non crittografate e correggile. Il generatore ToolAcre presuppone HTTPS; se lo stai utilizzando, sei già a metà strada.