Como configurar trocas assinadas usando o Web Packager

Aprenda a veicular trocas assinadas (SXGs) usando o Web Packager.

Katie Hempenius
Katie Hempenius
X

Uma troca assinada (SXG, na sigla em inglês) é um mecanismo de entrega que permite autentica a origem de um recurso independente de como ele foi entregue. As instruções a seguir explicam como configurar as trocas assinadas usando o Web Packager. As instruções são incluídas para certificados autoassinados e CanSignHttpExchanges.

Servir SXGs usando um certificado autoassinado

O uso de um certificado autoassinado para fornecer SXGs é usado principalmente para demonstração e testes. Os SXGs assinados com um certificado autoassinado geram mensagens de erro no navegador quando usados fora de ambientes de teste e não podem ser veiculados para rastreadores.

Pré-requisitos

Para seguir estas instruções, você precisa ter o openssl e o Go instalados no seu ambiente de desenvolvimento.

Gerar um certificado autoassinado

Esta seção explica 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).

    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 certificadora(AC). Embora você não solicite um certificado de uma AC, 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 seria um site seu. No entanto, em um ambiente de teste como o descrito nestas instruções, pode ser qualquer site.

  3. Crie um certificado com 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 flag -extfile associa o certificado à extensão de certificado CanSignHttpExchanges (1.3.6.1.4.1.11129.2.1.22 é o identificador de objeto da extensão CanSignHttpExchanges). Além disso, a flag -extfile também define example.com como um nome alternativo do assunto.

    Se você quiser saber o conteúdo de cert.pem, use o seguinte comando:

    openssl x509 -in cert.pem -noout -text

    A criação de chaves e certificados privados foi concluída. Você vai 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 .

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

  3. Verifique se o webpkgserver foi instalado corretamente.

    ./webpkgserver --help

    Esse comando precisa retornar informações sobre o uso de webpkgserver. Se isso não funcionar, uma boa primeira etapa de 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 para webpkgserver.

  3. Abra webpkgserver.toml com o editor de sua escolha e faça as seguintes alterações:

    • Mude a linha #AllowTestCert = false para AllowTestCert = true.
    • Mude a linha PEMFile = 'path/to/your.pem' para refletir o caminho para o certificado PEM, cert.pem, que você criou. Não mude a linha que menciona TLS.PEMFile. Essa é uma opção de configuração diferente.
    • Mude a linha KeyFile = 'priv.key' para refletir o caminho da chave privada priv.key que você criou. Não mude a linha que menciona TLS.KeyFile. Essa é uma opção de configuração diferente.
    • Mude a linha #CertURLBase = '/webpkg/cert' para CertURLBase = 'data:'. CertURLBase indica o local de veiculação do certificado 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 inserir o certificado no campo cert-url. Para testes locais, essa é a maneira mais conveniente de exibir o certificado SXG.
    • Mude a linha Domain = 'example.org' para refletir o domínio para o qual você criou um certificado. Se você seguiu as instruções deste artigo literalmente, ele precisa ser alterado para example.com. O webpkgserver só vai buscar conteúdo do domínio indicado por webpkgserver.toml. Se você tentar buscar páginas de um domínio diferente sem atualizar webpkgserver.toml, os registros webpkgserver vão mostrar a mensagem de erro URL doesn't match the fetch targets.

    Opcional

    Se você quiser ativar ou desativar o pré-carregamento de subrecursos, as seguintes opções de configuração webpkgserver.toml são relevantes:

    • Para que webpkgserver insira diretivas para pré-carregar a folha de estilo e os subrecursos de script como SXGs, mude a linha #PreloadCSS = false para PreloadCSS = true. Além disso, mude a linha #PreloadJS = false para PreloadJS = true.

      Como alternativa a essa 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"> existentes pelas tags <link> equivalentes necessárias para buscar esse conteúdo como SXG. Ao fazer isso, o webpkgserver define as diretivas allowed-alt-sxg e header-integrity conforme necessário. Os autores de HTML não precisam adicioná-las manualmente. Para modificar esse comportamento e manter os carregamentos prévios não SXG, mude #KeepNonSXGPreloads (default = false) para KeepNonSXGPreloads = true. Ativar essa opção pode fazer com que a SXG não se qualifique para o cache das SXG do Google de acordo com estes requisitos.

  4. Inicie webpkgserver.

    ./webpkgserver

    Se o servidor tiver sido iniciado, 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 usado por webpkgserver para armazenar certificados em cache varia de acordo com o sistema operacional.

    Se você não encontrar essas mensagens, uma boa primeira etapa de solução de problemas é verificar webpkgserver.toml.

    Se você atualizar webpkgserver.toml, reinicie 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 permite testar SXGs usando um certificado de teste. Se o Chrome for iniciado sem esse comando, a inspeção do SXG no DevTools vai mostrar o erro Certificate verification error: ERR_CERT_INVALID.

    Observação:

    Talvez seja necessário ajustar esse comando para refletir a localização do Chrome na máquina, bem como a localização de cert.pem. Se você fez isso corretamente, um aviso 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 Network 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 um SXG e o certificado dele.

    Os seguintes recursos estão listados na guia Rede:

    • Um recurso com o tipo signed-exchange. Este é o SXG.
    • Um recurso com o tipo cert-chain+cbor. Este é o certificado da SXG. Os certificados SXG precisam usar o formato application/cert-chain+cbor.
    • Um recurso com o tipo document. Este é o conteúdo que foi veiculado pelo SXG.

    Se você não encontrar esses recursos, tente limpar o cache do navegador e recarregar http://localhost:8080/priv/doc/https://example.com.

    Clique na guia Visualizar para conferir mais informações sobre a troca assinada e a assinatura.

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

Oferecer trocas assinadas usando um certificado CanSignHttpExchanges

As instruções desta seção explicam como veicular SXGs usando um certificado CanSignHttpExchanges. O uso de SXGs em produção requer um certificado CanSignHttpExchanges.

Para simplificar, estas instruções foram escritas com a suposição de que você entende os conceitos discutidos na seção Configurar trocas assinadas usando um certificado autoassinado.

Pré-requisitos

  • Você tem um certificado CanSignHttpExchanges. Esta página lista as ACs que oferecem esse tipo de certificado.

  • Se você não tiver um certificado, configure o webpkgserver para extrair automaticamente certificados da AC. Siga as instruções sobre o que vai em webpkgserver.toml nesta página.

  • Embora não seja um requisito, é altamente recomendável executar webpkgserver por trás de um servidor de borda. Se você não usar um servidor de borda, vai precisar configurar as opções TLS.PEMFile e TLS.KeyFile em webpkgserver.toml. Por padrão, o webpkgserver é executado por HTTP. No entanto, os certificados SXG precisam ser veiculados 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, forneça o certificado SXG diretamente ao navegador.

Instruções

  1. Crie um arquivo PEM concatenando o certificado SXG do seu site seguido pelo certificado de AC do seu site. Confira mais instruções aqui.

    PEM é um formato de arquivo usado geralmente como um "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 escolha e faça as seguintes alterações:

    • Mude a linha PEMFile = cert.pem para refletir o local do arquivo PEM que contém a cadeia de certificados completa.
    • Mude a linha KeyFile = 'priv.key' para refletir o local da chave privada correspondente ao arquivo PEM.
    • Mude a linha Domain = 'example.org' para refletir seu site.
    • (Opcional) Para que o webpkgserver renove automaticamente o certificado do SXG a cada 90 dias (45 dias para o Google), configure as opções na seção [SXG.ACME] do webpkgserver.toml. Essa opção só se aplica a sites com uma conta configurada do DigiCert ou do Google ACME.

  4. Configure o servidor de borda para encaminhar o tráfego para a instância webpkgserver.

    Há dois tipos principais de solicitações processadas por webpkgserver: solicitações para SXGs (que são atendidas pelo endpoint /priv/doc/) e solicitações para o certificado SXG (que são atendidas 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 Como executar por trás do servidor de borda do front-end.

    Observação:

    Por padrão, o webpkgserver serve o certificado 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 =