Come configurare Signed Exchange utilizzando Web Packager

Scopri come gestire Signed Exchange (SXG) utilizzando Web Packager.

Katie Hempenius
Katie Hempenius
X

Una Signed Exchange (SXG) è un meccanismo di consegna che consente di autenticare l'origine di una risorsa, indipendentemente da come è stata erogata. Le seguenti istruzioni spiegano come configurare Signed Exchange utilizzando Web Packager. Sono incluse le istruzioni per i certificati autofirmati e CanSignHttpExchanges.

Gestisci SXG utilizzando un certificato autofirmato

L'utilizzo di un certificato autofirmato per gestire SXG viene usato principalmente a scopo dimostrativo 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 forniti ai crawler.

Prerequisiti

Per seguire queste istruzioni, devi aver 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 Signed Exchange.

Istruzioni

  1. Generare 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 di certificato è un blocco di testo codificato che trasmette le informazioni necessarie per richiedere un certificato a un'autorità di certificazione(CA). Anche se non richiedi un certificato a una CA, è comunque necessario creare una richiesta di firma del certificato.

    Il comando riportato sopra crea una richiesta di firma del certificato per un'organizzazione denominata Web Packager Demo che ha il nome comune example.com. Il nome comune deve essere il nome di dominio completo del sito che include 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 richiesta di firma del certificato creata nei passaggi 1 e 2 per creare il file di certificato cert.pem. Il flag -extfile associa il certificato all'estensione di 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 del soggetto.

    Se i contenuti di cert.pem sono curiosi, puoi visualizzarli utilizzando il seguente comando:

    openssl x509 -in cert.pem -noout -text

    Hai terminato la creazione di chiavi e certificati privati. Nella sezione successiva ti serviranno i 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. Crea webpkgserver.

    cd webpackager/cmd/webpkgserver
go build .

    webpkgserver è un programma 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 questa operazione 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 essere 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:

    • Cambia la riga #AllowTestCert = false in AllowTestCert = true.
    • Modifica la riga PEMFile = 'path/to/your.pem' per riflettere il percorso del certificato PEM, cert.pem, che hai creato. Non modificare la riga che menziona TLS.PEMFile: questa è un'opzione di configurazione diversa.
    • Modifica la riga KeyFile = 'priv.key' per riflettere il percorso della chiave privata, priv.key, che hai creato. Non modificare la riga in cui menziona TLS.KeyFile: è un'opzione di configurazione diversa.
    • Cambia la riga #CertURLBase = '/webpkg/cert' in CertURLBase = 'data:'. CertURLBase indica la località di pubblicazione del certificato SXG. Questa informazione viene utilizzata per impostare il parametro cert-url nell'intestazione Signature dell'SXG. Negli ambienti di produzione, viene utilizzato CertURLBase in questo modo: CertURLBase = 'https://mysite.com/'. Tuttavia, per i test locali, è possibile usare CertURLBase = 'data:' per indicare a webpkgserver di utilizzare un URL di dati per incorporare il certificato nel campo cert-url. Per i test locali, questo è il modo più conveniente per pubblicare il certificato SXG.
    • Modifica la riga Domain = 'example.org' per riflettere il dominio per cui hai creato un certificato. Se hai seguito letteralmente le istruzioni riportate in questo articolo, il valore dovrebbe essere cambiato in example.com. webpkgserver recupererà solo i contenuti dal dominio indicato da webpkgserver.toml. Se tenti di recuperare le pagine da un altro dominio senza aggiornare webpkgserver.toml, i log webpkgserver mostreranno il messaggio di errore URL doesn't match the fetch targets.

    Facoltativo

    Se vuoi abilitare o disabilitare il precaricamento delle sottorisorse, sono pertinenti le seguenti opzioni di configurazione di webpkgserver.toml:

    • Per fare in modo che webpkgserver inserisca istruzioni per il precaricamento delle risorse del foglio di stile e dello script come SXG, modifica la riga #PreloadCSS = false in PreloadCSS = true. Inoltre, modifica la riga #PreloadJS = false in PreloadJS = true.

      In alternativa a questa opzione di configurazione, puoi aggiungere manualmente le intestazioni Link: rel="preload" e i 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 eseguire l'override di questo comportamento e mantenere i precaricamenti non SXG esistenti, modifica il valore #KeepNonSXGPreloads (default = false) in 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 i certificati nella cache varia a seconda del sistema operativo.

    Se non vedi questi messaggi, un primo passaggio per risolvere il problema è ricontrollare webpkgserver.toml.

    Se aggiorni webpkgserver.toml, devi riavviare webpkgserver.

  5. Avvia Chrome utilizzando questo 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 di certificato associati a cert.pem. In questo modo è possibile testare SXG utilizzando un certificato di test. Se Chrome viene avviato senza questo comando, l'ispezione di SXG in DevTools mostrerà l'errore Certificate verification error: ERR_CERT_INVALID.

    Nota:

    Potresti dover modificare questo comando in modo che rifletta la posizione di Chrome sul tuo computer e la posizione di cert.pem. Se l'operazione è stata eseguita correttamente, sotto la barra degli indirizzi dovrebbe essere visualizzato un avviso. 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 Network DevTools che mostra un SXG e il relativo certificato.

    Le seguenti risorse sono elencate nella scheda Rete:

    • 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. Si tratta dei contenuti pubblicati tramite SXG.

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

    Fai clic sulla scheda Anteprima per visualizzare ulteriori informazioni sulla piattaforma Signed Exchange e sulla sua firma.

    Screenshot della scheda Anteprima che mostra un SXG

Gestisci gli scambi firmati utilizzando un certificato CanSignHttpExchanges

Le istruzioni in questa sezione spiegano come gestire SXG utilizzando un certificato CanSignHttpExchanges. L'utilizzo in produzione di SXG richiede un certificato CanSignHttpExchanges.

Per brevità, queste istruzioni vengono scritte partendo dal presupposto che tu comprenda i concetti descritti nella sezione Configurare le piattaforme di scambio pubblicitario firmate utilizzando un certificato autofirmato.

Prerequisiti

  • Hai un certificato CanSignHttpExchanges. Questa pagina elenca le CA che offrono questo tipo di certificato.

  • Se non disponi di un certificato, puoi configurare webpkgserver in modo che recuperi automaticamente i certificati dalla tua CA. Puoi seguire le indicazioni stradali per i contenuti in webpkgserver.toml in questa pagina.

  • Sebbene non sia un requisito, è vivamente consigliato eseguire webpkgserver dietro un server perimetrale. Se non utilizzi un server perimetrale, dovrai configurare le opzioni TLS.PEMFile e TLS.KeyFile in webpkgserver.toml. Per impostazione predefinita, webpkgserver viene eseguito su HTTP. Tuttavia, i certificati SXG devono essere forniti 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 pubblicare il certificato SXG direttamente al browser.

Istruzioni

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

    PEM è un formato file comunemente utilizzato come "container" 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 di tua scelta 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' per riflettere il 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 DigiCert o Google ACME.

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

    Esistono due tipi principali di richieste gestite da webpkgserver: richieste per SXG (gestite dall'endpoint /priv/doc/) e richieste per il certificato SXG (gestite dall'endpoint /webpkg/cert/). Le regole di riscrittura degli URL per ciascuno di questi tipi di richiesta variano leggermente. Per ulteriori informazioni, consulta Esecuzione dietro il server perimetrale front-end.

    Nota:

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