Saiba como exibir trocas assinadas (SXGs) usando o Web Packager.
Uma troca assinada (SXG) é um mecanismo de entrega que possibilita autenticar a origem de um recurso independentemente de como ele foi entregue.
As instruções a seguir explicam como configurar trocas assinadas usando o
Web Packager. As instruções estão incluídas para
certificados autoassinados e CanSignHttpExchanges
.
Veicular SXGs usando um certificado autoassinado
O uso de um certificado autoassinado para exibir SXGs é usado principalmente para fins de demonstração e teste. As SXGs assinadas com um certificado autoassinado gerarão mensagens de erro no navegador quando usadas fora de ambientes de teste e não podem ser exibidas aos rastreadores.
Pré-requisitos
Para seguir estas instruções, você precisará ter o openssl e o Go instalados no ambiente de desenvolvimento.
Gerar um certificado autoassinado
Nesta seção, explicamos como gerar um certificado autoassinado que pode ser usado com trocas assinadas.
Instruções
Gere uma chave privada.
openssl ecparam -out priv.key -name prime256v1 -genkey
A chave privada será salva como um arquivo chamado
priv.key
.Crie uma solicitação de assinatura de certificado (CSR, na sigla em inglês).
openssl req -new -sha256 -key priv.key -out cert.csr -subj '/O=Web Packager Demo/CN=example.com'
Uma solicitação de assinatura de certificado é um bloco de texto codificado que transmite as informações necessárias para solicitar um certificado de uma autoridade de certificação(CA). Embora você não precise solicitar um certificado de uma CA, ainda é necessário criar uma solicitação de assinatura de certificado.
O comando acima cria uma solicitação de assinatura de certificado para uma organização chamada
Web Packager Demo
que tem o nome comumexample.com
. O nome comum precisa ser o nome de domínio totalmente qualificado do site que contém o conteúdo que você quer empacotar como SXG.Em uma configuração de SXG de produção, esse site é de sua propriedade. No entanto, em um ambiente de teste como o descrito nestas instruções, ele pode ser qualquer site.
Crie um certificado que tenha a extensão
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")
Esse comando usa a chave privada e a CSR criadas nas etapas 1 e 2 para criar o arquivo de certificado
cert.pem
. A sinalização-extfile
associa o certificado à extensão de certificadoCanSignHttpExchanges
(1.3.6.1.4.1.11129.2.1.22
é o identificador de objetos da extensãoCanSignHttpExchanges
). Além disso, a sinalização-extfile
também defineexample.com
como um Nome alternativo do assunto.Se você quiser saber mais sobre o conteúdo de
cert.pem
, visualize-o usando o seguinte comando:openssl x509 -in cert.pem -noout -text
Você concluiu a criação de chaves privadas e certificados. Você precisará dos arquivos
priv.key
ecert.pem
na próxima seção.
Configurar o servidor do Web Packager para testes
Pré-requisitos
Instale o Web Packager.
git clone https://github.com/google/webpackager.git
Crie o
webpkgserver
.cd webpackager/cmd/webpkgserver go build .
O
webpkgserver
é um binário específico no projeto Web Packager.Verifique se
webpkgserver
foi instalado corretamente../webpkgserver --help
Esse comando retornará informações sobre o uso de
webpkgserver
. Se isso não funcionar, uma boa primeira etapa da solução de problemas é verificar se o GOPATH está configurado corretamente.
Instruções
Navegue até o diretório
webpkgserver
(talvez você já esteja nesse diretório).cd /path/to/cmd/webpkgserver
Crie um arquivo
webpkgsever.toml
copiando o exemplo.cp ./webpkgserver.example.toml ./webpkgserver.toml
Esse arquivo contém as opções de configuração de
webpkgserver
.Abra
webpkgserver.toml
com um editor de sua preferência e faça as seguintes mudanças:- Mude a linha
#AllowTestCert = false
paraAllowTestCert = true
. - Altere a linha
PEMFile = 'path/to/your.pem'
para refletir o caminho para o certificado PEM,cert.pem
, que você criou. Não altere a linha mencionandoTLS.PEMFile
. Essa é uma opção de configuração diferente. - Altere a linha
KeyFile = 'priv.key'
para refletir o caminho da chave privada,priv.key
, que você criou. Não altere a linha mencionandoTLS.KeyFile
. Essa é uma opção de configuração diferente. - Mude a linha
#CertURLBase = '/webpkg/cert'
paraCertURLBase = 'data:'
.CertURLBase
indica o local de exibição do certificado de SXG. Essas informações são usadas para definir o parâmetrocert-url
no cabeçalhoSignature
da SXG. Em ambientes de produção,CertURLBase
é usado desta forma:CertURLBase = 'https://mysite.com/'
. No entanto, para testes locais,CertURLBase = 'data:'
pode ser usado para instruirwebpkgserver
a usar um URL de dados para deixar o certificado inline no campocert-url
. Para testes locais, essa é a maneira mais conveniente de disponibilizar o certificado SXG. - Altere a linha
Domain = 'example.org'
para refletir o domínio para o qual você criou um certificado. Se você tiver seguido as instruções deste artigo na íntegra, mude paraexample.com
.webpkgserver
buscará apenas o conteúdo do domínio indicado porwebpkgserver.toml
. Se você tentar buscar páginas de um domínio diferente sem atualizar owebpkgserver.toml
, os registroswebpkgserver
vão mostrar a mensagem de erroURL doesn't match the fetch targets
.
Opcional
Para ativar ou desativar o pré-carregamento de sub-recursos, as seguintes opções de configuração
webpkgserver.toml
são relevantes:Para que
webpkgserver
insira diretivas para pré-carregamento de folha de estilo e subrecursos de script como SXGs, altere a linha#PreloadCSS = false
paraPreloadCSS = true
. Além disso, altere a linha#PreloadJS = false
paraPreloadJS = true
.Como alternativa ao uso dessa opção de configuração, é possível adicionar manualmente cabeçalhos
Link: rel="preload"
e tags<link rel="preload">
ao HTML de uma página.Por padrão,
webpkgserver
substitui as tags<link rel="preload">
atuais pelas tags<link>
equivalentes necessárias para buscar esse conteúdo como SXG. Ao fazer isso,webpkgserver
vai definir as diretivasallowed-alt-sxg
eheader-integrity
conforme necessário. Os autores de HTML não precisam adicioná-las manualmente. Para substituir esse comportamento e manter os pré-carregamentos não SXG atuais, mude#KeepNonSXGPreloads (default = false)
paraKeepNonSXGPreloads = true
. Ativar essa opção pode tornar as SXG desqualificadas para o cache das SXG do Google de acordo com estes requisitos.
- Mude a linha
Inicie
webpkgserver
../webpkgserver
Se o servidor tiver sido iniciado corretamente, você verá as seguintes mensagens de registro:
shell Listening at 127.0.0.1:8080 Successfully retrieved valid OCSP. Writing to cache in /private/tmp/webpkg
As mensagens de registro podem ser um pouco diferentes. Especificamente, o diretório que o
webpkgserver
usa para armazenar certificados em cache varia de acordo com o sistema operacional.Se você não vir essas mensagens, uma boa primeira etapa da solução de problemas é verificar novamente
webpkgserver.toml
.Se você atualizar o
webpkgserver.toml
, reinicie owebpkgserver
.Inicie o Chrome usando o seguinte 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`
Esse comando instrui o Chrome a ignorar os erros de certificado associados a
cert.pem
. Isso possibilita testar as SXGs usando um certificado de teste. Se o Chrome for iniciado sem esse comando, a inspeção das SXG no DevTools exibirá o erroCertificate verification error: ERR_CERT_INVALID
.Observação:
Pode ser necessário ajustar esse comando para refletir a localização do Chrome na sua máquina, bem como a localização de
cert.pem
. Se você fez isso corretamente, um aviso vai ser exibido abaixo da barra de endereço. O aviso será semelhante a este:You are using an unsupported command-line flag: --ignore-certificate-errors-spki-list=9uxADcgc6/ho0mJLRMBcOjfBaN21k0sOInoMchr9CMY=.
Se o aviso não incluir uma string de hash, você não indicou corretamente o local do certificado SXG.
Abra a guia Rede do DevTools e acesse o seguinte URL:
http://localhost:8080/priv/doc/https://example.com
.Isso faz uma solicitação à instância
webpackager
em execução emhttp://localhost:8080
para uma SXG que contém o conteúdo dehttps://example.com
./priv/doc/
é o endpoint de API padrão usado porwebpackager
.Os seguintes recursos estão listados na guia Rede:
- Um recurso com o tipo
signed-exchange
. Estas são as SXG. - Um recurso com o tipo
cert-chain+cbor
. Este é o certificado de SXG. Os certificados SXG precisam usar o formatoapplication/cert-chain+cbor
. - Um recurso com o tipo
document
. Esse é o conteúdo enviado via SXG.
Se você não encontrar esses recursos, limpe o cache do navegador e recarregue
http://localhost:8080/priv/doc/https://example.com
.Clique na guia Preview para conferir mais informações sobre a troca assinada e a assinatura dela.
- Um recurso com o tipo
Veicular trocas assinadas usando um certificado CanSignHttpExchanges
As instruções nesta seção explicam como exibir SXGs usando um
certificado CanSignHttpExchanges
. O uso de SXGs em produção requer um
certificado CanSignHttpExchanges
.
Para facilitar, estas instruções foram escritas com o pressuposto de que você entende os conceitos discutidos na seção Configurar trocas assinadas usando um certificado autoassinado.
Pré-requisitos
Você tem um certificado de
CanSignHttpExchanges
. Esta página lista as ACs que oferecem esse tipo de certificado.Se você não tiver um certificado, poderá configurar o webpkgserver para recuperar automaticamente os certificados da sua AC. Você pode seguir as instruções sobre o que acontece em
webpkgserver.toml
nesta página.Embora não seja um requisito, é altamente recomendável executar
webpkgserver
atrás de um servidor de borda. Se você não usar um servidor de borda, será necessário configurar as opçõesTLS.PEMFile
eTLS.KeyFile
emwebpkgserver.toml
. Por padrão, owebpkgserver
é executado em HTTP. No entanto, os certificados SXG precisam ser exibidos por HTTPS para serem considerados válidos pelo navegador. A configuração deTLS.PEMFile
eTLS.KeyFile
permite quewebpkgserver
use HTTPS e, portanto, exiba o certificado SXG diretamente ao navegador.
Instruções
Crie um arquivo PEM concatenando o certificado SXG do site seguido do certificado de AC. Confira mais instruções neste link.
PEM é um formato de arquivo muito usado como "contêiner" para armazenar vários certificados.
Crie um novo arquivo
webpkgsever.toml
copiando o exemplo.cp ./webpkgserver.example.toml ./webpkgserver.toml
Abra
webpkgserver.toml
com o editor de sua preferência e faça as mudanças abaixo:- Altere a linha
PEMFile = cert.pem
para refletir o local do arquivo PEM que contém a cadeia completa de certificados. - Altere a linha
KeyFile = 'priv.key'
para refletir o local da chave privada correspondente ao seu arquivo PEM. - Mude a linha
Domain = 'example.org'
para refletir seu site. - (Opcional) Para que
webpkgserver
renove automaticamente o certificado SXG a cada 90 dias (45 dias para o Google), configure as opções na seção[SXG.ACME]
dewebpkgserver.toml
. Essa opção só é válida para sites com uma conta da DigiCert ou do Google ACME.
- Altere a linha
Configure seu servidor de borda para encaminhar tráfego para a instância
webpkgserver
.Há dois tipos principais de solicitações processadas pelo
webpkgserver
: solicitações de SXGs, que são veiculadas pelo endpoint/priv/doc/
, e solicitações para o certificado de SXG, que são exibidas pelo endpoint/webpkg/cert/
. As regras de reescrita de URL para cada um desses tipos de solicitação variam um pouco. Para mais informações, consulte Executar por trás do servidor de borda front-end.Observação:
Por padrão,
webpkgserver
exibe o certificado de SXG em/webpkg/cert/$CERT_HASH
, por exemplo,/webpkg/cert/-0QmE0gvoedn92gtwI3s7On9zPevJGm5pn2RYhpZxgY
. Para gerar$CERT_HASH
, execute o seguinte comando:shell openssl base64 -in cert.pem -d | openssl dgst -sha256 -binary | base64 | tr /+ _- | tr -d =