Come configurare Signed Exchange utilizzando Web Packager

Scopri come pubblicare gli scambi firmati (SXG) utilizzando Web Packager.

Katie Hempenius
Katie Hempenius
X

Un Signed Exchange (SXG) è un meccanismo di pubblicazione che consente di autenticare l'origine di una risorsa indipendentemente dal modo in cui è stata pubblicata. Le istruzioni riportate di seguito spiegano come configurare gli scambi firmati utilizzando Web Packager. Sono incluse istruzioni sia per i certificati autofirmati sia per quelli CanSignHttpExchanges.

Pubblicare SXG utilizzando un certificato autofirmato

L'utilizzo di un certificato autofirmato per pubblicare gli SXG viene utilizzato principalmente per scopi dimostrativi e di test. Gli SXG firmati con un certificato autofirmato genereranno messaggi di errore nel browser se utilizzati al di fuori degli ambienti di test e non devono essere pubblicati per i crawler.

Prerequisiti

Per seguire queste istruzioni, devi avere installato openssl e Go nel tuo ambiente di sviluppo.

Genera un certificato autofirmato

Questa sezione spiega come generare un certificato autofirmato che può essere utilizzato con le piattaforme di scambio pubblicitario con firma.

Istruzioni

  1. Genera una chiave privata.

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

    La chiave privata verrà salvata come file denominato priv.key.

  2. Crea una richiesta di firma del certificato (CSR).

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

    Una richiesta di firma del certificato è un blocco di testo codificato che trasmette le informazioni necessarie per richiedere un certificato a un'autorità di certificazione(CA). Anche se non richiederai un certificato a un'autorità di certificazione, è comunque necessario creare una richiesta di firma del certificato.

    Il comando riportato sopra crea una richiesta di firma del certificato per un'organizzazione Web Packager Demo con il nome comune example.com. Il nome comune deve essere il nome di dominio completo del sito che contiene i contenuti che vuoi pacchettizzare come SXG.

    In una configurazione SXG di produzione, si tratta di un sito di tua proprietà. Tuttavia, in un ambiente di test come quello descritto in queste istruzioni, può essere qualsiasi sito.

  3. Crea un certificato con l'estensione 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")

    Questo comando utilizza la chiave privata e la CSR create nei passaggi 1 e 2 per creare il file del certificato cert.pem. Il flag -extfile associa il certificato all'estensione del certificato CanSignHttpExchanges (1.3.6.1.4.1.11129.2.1.22 è l'identificatore dell'oggetto per l'estensione CanSignHttpExchanges). Inoltre, il flag -extfile definisce anche example.com come Nome alternativo dell'oggetto.

    Se vuoi conoscere i contenuti di cert.pem, puoi visualizzarli utilizzando il seguente comando:

    openssl x509 -in cert.pem -noout -text

    Hai completato la creazione di chiavi e certificati privati. Nella sezione successiva avrai bisogno dei file priv.key e cert.pem.

Configura il server Web Packager per i test

Prerequisiti

  1. Installa Web Packager.

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

  2. Build webpkgserver.

    cd webpackager/cmd/webpkgserver
go build .

    webpkgserver è un file binario specifico all'interno del progetto Web Packager.

  3. Verifica che webpkgserver sia stato installato correttamente.

    ./webpkgserver --help

    Questo comando dovrebbe restituire informazioni sull'utilizzo di webpkgserver. Se questo non funziona, un buon primo passaggio per la risoluzione dei problemi è verificare che il GOPATH sia configurato correttamente.

Istruzioni

  1. Vai alla directory webpkgserver (potresti trovarti già in questa directory).

    cd /path/to/cmd/webpkgserver

  2. Crea un file webpkgsever.toml copiando l'esempio.

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

    Questo file contiene le opzioni di configurazione per webpkgserver.

  3. Apri webpkgserver.toml con un editor a tua scelta e apporta le seguenti modifiche:

    • Modifica la riga #AllowTestCert = false in AllowTestCert = true.
    • Modifica la riga PEMFile = 'path/to/your.pem' in modo che rifletta il percorso del certificato PEM cert.pem che hai creato. Non modificare la riga che menziona TLS.PEMFile: si tratta di un'opzione di configurazione diversa.
    • Modifica la riga KeyFile = 'priv.key' in modo che rifletta il percorso della chiave privata priv.key che hai creato. Non modificare la riga che fa riferimento a TLS.KeyFile, si tratta di un'opzione di configurazione diversa.
    • Modifica la riga #CertURLBase = '/webpkg/cert' in CertURLBase = 'data:'. CertURLBase indica la posizione di pubblicazione del certificato SXG. Queste informazioni vengono utilizzate per impostare il parametro cert-url nell'intestazione Signature dell'SXG. Negli ambienti di produzione, CertURLBase viene utilizzato come segue: CertURLBase = 'https://mysite.com/'. Tuttavia, per i test locali, CertURLBase = 'data:' può essere utilizzato per indicare a webpkgserver di utilizzare un URL di dati per inserire il certificato in linea nel campo cert-url. Per i test locali, questo è il modo più pratico per pubblicare il certificato SXG.
    • Modifica la riga Domain = 'example.org' in modo che rifletta il dominio per cui hai creato un certificato. Se hai seguito alla lettera le istruzioni riportate in questo articolo, questo valore dovrebbe essere modificato in example.com. webpkgserver recupererà i contenuti solo dal dominio indicato da webpkgserver.toml. Se provi a recuperare pagine da un dominio diverso senza aggiornare webpkgserver.toml, nei log di webpkgserver verrà visualizzato il messaggio di errore URL doesn't match the fetch targets.

    Facoltativo

    Se vuoi attivare o disattivare il precaricamento delle risorse secondarie, le seguenti opzioni di configurazione webpkgserver.toml sono pertinenti:

    • Per fare in modo che webpkgserver inserisca direttive per il precaricamento delle risorse secondarie di stili e script come SXG, modifica la riga #PreloadCSS = false in PreloadCSS = true. Inoltre, modifica la riga #PreloadJS = false in PreloadJS = true.

      In alternativa all'utilizzo di questa opzione di configurazione, puoi aggiungere manualmente intestazioni Link: rel="preload" e tag <link rel="preload"> al codice HTML di una pagina.

    • Per impostazione predefinita, webpkgserver sostituisce i tag <link rel="preload"> esistenti con i tag <link> equivalenti necessari per recuperare questi contenuti come SXG. In questo modo, webpkgserver imposterà le direttive allowed-alt-sxg e header-integrity in base alle esigenze. Gli autori HTML non devono aggiungerle manualmente. Per aggiustare questo comportamento e mantenere i precaricamenti esistenti non SXG, imposta #KeepNonSXGPreloads (default = false) su KeepNonSXGPreloads = true. Tieni presente che l'attivazione di questa opzione potrebbe rendere SXG non idoneo per la cache SXG di Google in base a questi requisiti.

  4. Avvia webpkgserver.

    ./webpkgserver

    Se il server è stato avviato correttamente, dovresti vedere i seguenti messaggi di log: shell Listening at 127.0.0.1:8080 Successfully retrieved valid OCSP. Writing to cache in /private/tmp/webpkg

    I messaggi di log potrebbero avere un aspetto leggermente diverso. In particolare, la directory utilizzata da webpkgserver per memorizzare nella cache i certificati varia in base al sistema operativo.

    Se non vedi questi messaggi, un buon primo passaggio per la risoluzione dei problemi è verificare webpkgserver.toml.

    Se aggiorni webpkgserver.toml, devi riavviare webpkgserver.

  5. Avvia Chrome utilizzando il seguente comando: 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`

    Questo comando indica a Chrome di ignorare gli errori del certificato associati a cert.pem. Ciò consente di testare gli SXG utilizzando un certificato di test. Se Chrome viene avviato senza questo comando, l'ispezione dell'SXG in DevTools mostrerà l'errore Certificate verification error: ERR_CERT_INVALID.

    Nota:

    Potresti dover modificare questo comando in base alla posizione di Chrome sul tuo computer e alla posizione di cert.pem. Se hai eseguito correttamente questa operazione, dovresti visualizzare un avviso sotto la barra degli indirizzi. L'avviso dovrebbe essere simile a questo: You are using an unsupported command-line flag: --ignore-certificate-errors-spki-list=9uxADcgc6/ho0mJLRMBcOjfBaN21k0sOInoMchr9CMY=.

    Se l'avviso non include una stringa hash, non hai indicato correttamente la posizione del certificato SXG.

  6. Apri la scheda Rete di DevTools, quindi visita il seguente URL: http://localhost:8080/priv/doc/https://example.com.

    Viene inviata una richiesta all'istanza webpackager in esecuzione su http://localhost:8080 per un SXG contenente i contenuti di https://example.com. /priv/doc/ è l'endpoint API predefinito utilizzato da webpackager.

    Screenshot della scheda Rete di DevTools che mostra un SXG e il relativo certificato.

    Nella scheda Rete sono elencate le seguenti risorse:

    • Una risorsa di tipo signed-exchange. Questo è l'SXG.
    • Una risorsa di tipo cert-chain+cbor. Questo è il certificato SXG. I certificati SXG devono utilizzare il formato application/cert-chain+cbor.
    • Una risorsa di tipo document. Questi sono i contenuti pubblicati tramite SXG.

    Se non vedi queste risorse, prova a svuotare la cache del browser, quindi carica di nuovo http://localhost:8080/priv/doc/https://example.com.

    Fai clic sulla scheda Anteprima per visualizzare ulteriori informazioni sull'exchange firmato e sulla relativa firma.

    Screenshot della scheda Anteprima che mostra un file SXG

Pubblicare piattaforme di scambio pubblicitario con firma utilizzando un certificato CanSignHttpExchanges

Le istruzioni riportate in questa sezione spiegano come pubblicare gli SXG utilizzando un CanSignHttpExchanges. L'utilizzo in produzione degli SXG richiede un certificato CanSignHttpExchanges.

Per brevità, queste istruzioni sono scritte presupponendo che tu comprenda i concetti discussi nella sezione Configurare Signed Exchange utilizzando un certificato autofirmato.

Prerequisiti

  • Hai un certificato CanSignHttpExchanges. In questa pagina sono elencate le CA che offrono questo tipo di certificato.

  • Se non hai un certificato, puoi configurare webpkgserver in modo che recuperi automaticamente i certificati dall'autorità di certificazione. Puoi seguire le istruzioni su cosa inserire in webpkgserver.toml in questa pagina.

  • Sebbene non sia un requisito, è vivamente consigliato eseguire webpkgserver dietro un edge server. Se non utilizzi un edge server, dovrai configurare le opzioni TLS.PEMFile e TLS.KeyFile in webpkgserver.toml. Per impostazione predefinita, webpkgserver viene eseguito tramite HTTP. Tuttavia, i certificati SXG devono essere pubblicati tramite HTTPS per essere considerati validi dal browser. La configurazione di TLS.PEMFile e TLS.KeyFile consente a webpkgserver di utilizzare HTTPS e quindi di inviare il certificato SXG direttamente al browser.

Istruzioni

  1. Crea un file PEM concatenando il certificato SXG del tuo sito seguito dal certificato CA del tuo sito. Ulteriori istruzioni su questo argomento sono disponibili qui.

    PEM è un formato di file comunemente utilizzato come "contenitore" per l'archiviazione di più certificati.

  2. Crea un nuovo file webpkgsever.toml copiando l'esempio.

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

  3. Apri webpkgserver.toml con l'editor che preferisci e apporta le seguenti modifiche:

    • Modifica la riga PEMFile = cert.pem in modo che rifletta la posizione del file PEM contenente la catena di certificati completa.
    • Modifica la riga KeyFile = 'priv.key' in modo che rifletta la posizione della chiave privata corrispondente al file PEM.
    • Modifica la riga Domain = 'example.org' in base al tuo sito.
    • (Facoltativo) Per fare in modo che webpkgserver rinnovi automaticamente il certificato SXG ogni 90 giorni (45 giorni per Google), configura le opzioni nella sezione [SXG.ACME] di webpkgserver.toml. Questa opzione si applica solo ai siti con un account ACME di DigiCert o Google configurato.

  4. Configura il server edge per inoltrare il traffico all'istanza webpkgserver.

    Esistono due tipi principali di richieste gestite da webpkgserver: richieste per gli SXG (pubblicate dall'endpoint /priv/doc/) e richieste per il certificato SXG (pubblicate dall'endpoint /webpkg/cert/). Le regole di riscrittura dell'URL per ciascuno di questi tipi di richiesta variano leggermente. Per maggiori informazioni, consulta Eseguire il servizio in un edge server front-end.

    Nota:

    Per impostazione predefinita, webpkgserver serve il certificato SXG all'indirizzo /webpkg/cert/$CERT_HASH, ad esempio /webpkg/cert/-0QmE0gvoedn92gtwI3s7On9zPevJGm5pn2RYhpZxgY. Per generare $CERT_HASH, esegui il seguente comando: shell openssl base64 -in cert.pem -d | openssl dgst -sha256 -binary | base64 | tr /+ _- | tr -d =