Como configurar trocas assinadas usando o Web Packager

Saiba como exibir trocas assinadas (SXGs) usando o Web Packager.

Katie Hempenius
Katie Hempenius
X

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

  1. Gere uma chave privada.

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

    A chave privada será salva como um arquivo chamado priv.key.

  2. 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 comum example.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.

  3. 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 certificado CanSignHttpExchanges (1.3.6.1.4.1.11129.2.1.22 é o identificador de objetos da extensão CanSignHttpExchanges). Além disso, a sinalização -extfile também define example.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 e cert.pem na próxima seção.

Configurar o servidor do Web Packager para testes

Pré-requisitos

  1. Instale o Web Packager.

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

  2. Crie o webpkgserver.

    cd webpackager/cmd/webpkgserver
go build .

    O webpkgserver é um binário específico no projeto Web Packager.

  3. 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

  1. Navegue até o diretório webpkgserver (talvez você já esteja nesse diretório).

    cd /path/to/cmd/webpkgserver

  2. 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.

  3. Abra webpkgserver.toml com um editor de sua preferência e faça as seguintes mudanças:

    • Mude a linha #AllowTestCert = false para AllowTestCert = 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 mencionando TLS.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 mencionando TLS.KeyFile. Essa é uma opção de configuração diferente.
    • Mude a linha #CertURLBase = '/webpkg/cert' para CertURLBase = 'data:'. CertURLBase indica o local de exibição do certificado de SXG. Essas informações são usadas para definir o parâmetro cert-url no cabeçalho Signature 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 instruir webpkgserver a usar um URL de dados para deixar o certificado inline no campo cert-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 para example.com. webpkgserver buscará apenas o conteúdo do domínio indicado por webpkgserver.toml. Se você tentar buscar páginas de um domínio diferente sem atualizar o webpkgserver.toml, os registros webpkgserver vão mostrar a mensagem de erro URL 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 para PreloadCSS = true. Além disso, altere a linha #PreloadJS = false para PreloadJS = 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 diretivas allowed-alt-sxg e header-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) para KeepNonSXGPreloads = true. Ativar essa opção pode tornar as SXG desqualificadas para o cache das SXG do Google de acordo com estes requisitos.

  4. 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 o webpkgserver.

  5. 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 erro Certificate 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.

  6. 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 em http://localhost:8080 para uma SXG que contém o conteúdo de https://example.com. /priv/doc/ é o endpoint de API padrão usado por webpackager.

    Captura de tela da guia &quot;Rede&quot; do DevTools mostrando uma SXG e o certificado.

    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 formato application/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.

    Captura de tela da guia &quot;Visualização&quot; mostrando uma SXG

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ções TLS.PEMFile e TLS.KeyFile em webpkgserver.toml. Por padrão, o webpkgserver é executado em HTTP. No entanto, os certificados SXG precisam ser exibidos por HTTPS para serem considerados válidos pelo navegador. A configuração de TLS.PEMFile e TLS.KeyFile permite que webpkgserver use HTTPS e, portanto, exiba o certificado SXG diretamente ao navegador.

Instruções

  1. 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.

  2. Crie um novo arquivo webpkgsever.toml copiando o exemplo.

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

  3. 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] de webpkgserver.toml. Essa opção só é válida para sites com uma conta da DigiCert ou do Google ACME.

  4. 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 =