ASP.NET Core Blazor WebAssembly Falhas de verificação de integridade e cache do pacote .NET

Este artigo explica como o Blazor WebAssembly armazena em cache o tempo de execução e o pacote de aplicativos do WebAssembly .NET e como diagnosticar e resolver falhas de integridade.

Quando um aplicativo Blazor WebAssembly é carregado no navegador, o aplicativo baixa recursos de inicialização do servidor:

• Código JavaScript para inicializar o aplicativo
• Tempo de execução e assemblies do .NET
• Dados específicos da localidade

Com exceção Blazordo arquivo de manifesto de inicialização (blazor.boot.json) antes do lançamento do .NET 10†, os arquivos de runtime do .NET do WebAssembly e do pacote de aplicativos são armazenados em cache nos clientes. A Blazor configuração de inicialização, embutida no dotnet.js .NET 10 ou posterior, contém um manifesto dos arquivos que compõem o aplicativo que deve ser baixado junto com um hash do conteúdo do arquivo usado para detectar se algum dos recursos de inicialização foi alterado. Blazor armazena os arquivos baixados em cache usando a API Cache do navegador.

Observação

†Se atualizar um aplicativo para o .NET 10 ou posterior e o aplicativo depender do blazor.boot.json arquivo de manifesto para processamento personalizado, recomendamos coletar as informações diretamente do build.

Quando o Blazor WebAssembly baixa os arquivos de inicialização de um aplicativo, ele instrui o navegador a executar verificações de integridade nas respostas. Blazor envia os valores de hash SHA-256 para DLL (.dll), WebAssembly (.wasm) e outros arquivos na Blazor configuração de inicialização, que não é armazenada em cache nos clientes. Os hashes de arquivos armazenados em cache são comparados aos hashes na configuração de inicialização Blazor. Para arquivos armazenados em cache com um hash correspondente, Blazor usa os arquivos armazenados em cache. Caso contrário, os arquivos serão solicitados do servidor. Depois que um arquivo é baixado, o hash é verificado novamente para validação de integridade. Um erro será gerado pelo navegador, em caso de falha na verificação de integridade de qualquer arquivo baixado.

O algoritmo do Blazor para gerenciar a integridade do arquivo:

• Garante que o aplicativo não corre o risco de carregar um conjunto inconsistente de arquivos, por exemplo, se uma nova implantação for aplicada ao servidor Web, enquanto o usuário estiver em processo de download dos arquivos do aplicativo. Os arquivos inconsistentes podem resultar em um aplicativo com defeito.
• Garante que o navegador do usuário nunca armazene em cache respostas inconsistentes ou inválidas, o que pode impedir que o aplicativo seja iniciado mesmo que o usuário atualize a página manualmente.
• Torna seguro armazenar as respostas em cache e não verificar alterações no lado do servidor até que os hashes SHA-256 esperados sejam alterados, fazendo com que as cargas de página subsequentes envolvam menos solicitações e sejam concluídas mais rapidamente.

Se o servidor Web retornar respostas que não correspondem aos hashes SHA-256 esperados, um erro semelhante ao exemplo a seguir será exibido no console do desenvolvedor do navegador:

Falha ao localizar um código hash válido no atributo 'integrity' para o 'https://myapp.example.com/_framework/MyBlazorApp.dll' do recurso com a integridade SHA-256 calculada 'IIa70iwvmEg5WiDV17OpQ5eCztNYqL186J56852RpJY='. O recurso foi bloqueado.

Na maioria dos casos, o aviso não indica um problema na verificação de integridade. Em vez disso, o aviso geralmente significa que existe algum outro problema.

Para obter a origem de referência de inicialização do Blazor WebAssembly, confira arquivo Boot.WebAssembly.ts no dotnet/aspnetcorerepositório GitHub.

Observação

Os links de documentação para o código fonte de referência do .NET geralmente carregam a ramificação padrão do repositório, que representa o desenvolvimento atual para a próxima versão do .NET. Para selecionar uma marca para uma versão específica, use a lista suspensa para Alternar branches ou marcas. Para saber mais, confira Como selecionar uma marca de versão do código-fonte do ASP.NET Core (dotnet/AspNetCore.Docs #26205).

Diagnosticar problemas de integridade

Quando um aplicativo é criado, o manifesto de inicialização gerado descreve os hashes SHA-256 dos recursos de inicialização no momento em que a saída do build é produzida. A verificação de integridade é aprovada desde que os hashes SHA-256 no manifesto de inicialização correspondam aos arquivos entregues ao navegador.

Motivos comuns para dessa falha incluem:

• A resposta do servidor Web é um erro (por exemplo, 404 – Não Encontrado ou 500 – Erro do Servidor Interno), em vez do arquivo solicitado pelo navegador. Isso é relatado pelo navegador como uma falha na verificação de integridade e não como falha de resposta.
• Algo alterou o conteúdo dos arquivos entre o build e a entrega dos arquivos no navegador. Isso pode acontecer:
  • Se você ou as ferramentas de build modificarem manualmente o resultado da compilação.
  • Se algum aspecto do processo de implantação tiver modificado os arquivos. Por exemplo, se você usar um mecanismo de implantação baseado em Git, tenha em mente que o Git converte de forma transparente as terminações de linha no estilo Windows em terminações de linha no estilo Unix, se você confirmar os arquivos no Windows e marcá-los no Linux. Alterar as terminações de linha de arquivo altera os hashes SHA-256. Para evitar esse problema, use .gitattributes para tratar artefatos de build como arquivos binary.
  • O servidor web modifica o conteúdo do arquivo durante a entrega. Por exemplo, algumas CDNs (redes de distribuição de conteúdo) tentam minificar o HTML automaticamente, modificando-o. Talvez seja necessário desabilitar esses recursos.
• O manifesto de inicialização não carrega corretamente ou é armazenado em cache incorretamente no cliente. As causas comuns incluem uma das seguintes opções:
  • Código de desenvolvedor personalizado configurado incorretamente ou com defeito.
  • Uma ou mais camadas de cache intermediárias configuradas incorretamente.

Para diagnosticar qual dessas opções se aplica ao seu caso:

1. Observe qual arquivo está disparando o erro, lendo a mensagem de erro.
2. Abra as ferramentas de desenvolvedor no navegador e dê uma olhada na guia Rede. Se necessário, recarregue a página para ver a lista de solicitações e respostas. Localize o arquivo que está disparando o erro nessa lista.
3. Verifique o código de status HTTP na resposta. Se o servidor retornar algo diferente de 200 – OK (ou outro código de status 2xx), significa que há um problema no lado do servidor para diagnosticar. Por exemplo, o código de status 403 significa que há um problema de autorização, enquanto o código de status 500 significa que o servidor está falhando de maneira não especificada. Veja os logs do lado do servidor para diagnosticar e corrigir o aplicativo.
4. Se o código de status for 200 – OK para o recurso, examine o conteúdo da resposta nas ferramentas de desenvolvedor do navegador e verifique se o conteúdo corresponde aos dados esperados. Por exemplo, um problema comum é configurar incorretamente o roteamento de modo que as solicitações retornem os dados do index.html até mesmo para outros arquivos. Verifique se as respostas às solicitações do .wasm são binários do WebAssembly e se as respostas às solicitações do .dll são binários de assembly do .NET. Caso contrário, significa que há um problema de roteamento do lado do servidor que precisa ser diagnosticado.
5. Procure validar a saída publicada e implantada do aplicativo com o script do PowerShell Solucionar problemas de integridade.

Se você confirmar que o servidor está retornando dados plausivelmente corretos, deve haver outra coisa modificando o conteúdo entre o build e a entrega do arquivo. Para investigar isso:

• Examine a cadeia de ferramentas de build e o mecanismo de implantação, caso estejam modificando os arquivos depois que os arquivos são compilados. Um exemplo disso é quando o Git transforma as terminações de linha de arquivo, conforme descrito anteriormente.
• Examine o servidor Web ou a configuração da CDN, caso estejam configurados para modificar as respostas dinamicamente (por exemplo, tentando minificar o HTML). Não há problema se o servidor Web implementa a compactação HTTP (por exemplo, retornando content-encoding: br ou content-encoding: gzip), pois isso não afeta o resultado após a descompactação. No entanto, não é aceitável que o servidor web modifique os dados descompactados.

Script do PowerShell para Solucionar Problemas de Integridade

Use o script do PowerShell integrity.ps1 para validar um aplicativo Blazor publicado e implantado. O script é fornecido para o PowerShell Core 7 ou posterior como ponto de partida, quando o aplicativo tem problemas de integridade que a estrutura Blazor não pode identificar. A personalização do script pode ser necessária para seus aplicativos, incluindo se estiver em execução na versão do PowerShell posterior à versão 7.2.0.

O script verifica os arquivos na pasta publish e baixados pelo aplicativo implantado para detectar problemas nos diferentes manifestos que contêm hashes de integridade. Essas verificações devem detectar os problemas mais comuns:

• Você modificou um arquivo na saída publicada sem perceber.
• O aplicativo não foi implantado corretamente no destino de implantação ou algo foi alterado no ambiente do destino de implantação.
• Há diferenças entre o aplicativo implantado e a saída da publicação do aplicativo.

Invoque o script com o seguinte comando em um shell de comando do PowerShell:

.\integrity.ps1 {BASE URL} {PUBLISH OUTPUT FOLDER}

No exemplo a seguir, o script é executado em um aplicativo em execução local em https://localhost:5001/:

.\integrity.ps1 https://localhost:5001/ C:\TestApps\BlazorSample\bin\Release\net6.0\publish\

Espaços reservados:

• {BASE URL}: a URL do aplicativo implantado. A barra à direita (/) é necessária.
• {PUBLISH OUTPUT FOLDER}: o caminho para a pasta ou o local publish do aplicativo em que o aplicativo é publicado para implantação.

Observação

Ao clonar o repositório GitHub dotnet/AspNetCore.Docs, o script integrity.ps1 pode ser colocado em quarentena pelo Bitdefender ou por outro verificador de vírus presente no sistema. Normalmente, o arquivo é interceptado pela tecnologia de verificação heurística de um verificador de vírus, que apenas procura padrões em arquivos que podem indicar a presença de malware. Para impedir que o verificador de vírus coloque o arquivo em quarentena, adicione uma exceção ao verificador de vírus antes de clonar o repositório. O exemplo a seguir é um caminho típico para o script em um sistema Windows. Ajuste o caminho conforme necessário para outros sistemas. O espaço reservado {USER} é o segmento de caminho do usuário.

C:\Users\{USER}\Documents\GitHub\AspNetCore.Docs\aspnetcore\blazor\host-and-deploy\webassembly\_samples\integrity.ps1

Aviso: criar exceções no verificador de vírus é perigoso e isso só deve ser feito quando você tiver certeza de que o arquivo está seguro.

Comparar a soma de verificação de um arquivo com um valor de soma de verificação válido não garante a segurança do arquivo, mas modificar um arquivo de forma a manter um valor de soma de verificação não é trivial para usuários mal-intencionados. Portanto, as somas de verificação são úteis como uma abordagem de segurança geral. Compare a soma de verificação do arquivo local integrity.ps1 com um dos seguintes valores:

• SHA256: 32c24cb667d79a701135cb72f6bae490d81703323f61b8af2c7e5e5dc0f0c2bb
• MD5: 9cee7d7ec86ee809a329b5406fbf21a8

Obtenha a soma de verificação do arquivo no sistema operacional Windows com o comando a seguir. Forneça o caminho e o nome do arquivo para o espaço reservado {PATH AND FILE NAME} e indique o tipo de soma de verificação a ser produzida para o espaço reservado {SHA512|MD5}, SHA256 ou MD5:

CertUtil -hashfile {PATH AND FILE NAME} {SHA256|MD5}

Se você tiver algum motivo para se preocupar com o fato de que a validação da soma de verificação não é segura o suficiente no seu ambiente, consulte a liderança de segurança da sua organização para obter diretrizes.

Para obter mais informações, confira Visão geral da proteção contra ameaças pelo Microsoft Defender Antivírus.

Desabilitar a verificação de integridade para aplicativos não PWA

Na maioria dos casos, não desabilite a verificação de integridade. Desabilitar a verificação de integridade não resolve o problema subjacente que causou as respostas inesperadas e resulta na perda dos benefícios listados anteriormente.

Pode haver casos em que o servidor Web não pode ser invocado para retornar respostas consistentes e você não tem escolha a não ser desabilitar temporariamente as verificações de integridade até que o problema subjacente seja resolvido.

Para desabilitar as verificações de integridade, adicione o seguinte a um grupo de propriedades no arquivo de projeto do aplicativo Blazor WebAssembly (.csproj):

<BlazorCacheBootResources>false</BlazorCacheBootResources>

BlazorCacheBootResources também desabilita o comportamento padrão do Blazor de armazenar em cache os arquivos .dll, .wasm e outros arquivos com base nos hashes SHA-256, pois a propriedade indica que os hashes SHA-256 não podem ser considerados corretos. Mesmo com essa configuração, o cache HTTP normal do navegador ainda pode armazenar em cache esses arquivos, mas se isso acontecerá ou não depende da configuração do servidor Web e dos cabeçalhos cache-control atendidos.

Observação

A propriedade BlazorCacheBootResources não desabilita as verificações de integridade para PWAs (Aplicativos Web Progressivos). Para obter diretrizes relativas aos PWAs, confira a seção Desabilitar verificação de integridade para PWAs.

Não é possível fornecer uma lista completa de cenários em que é necessário desabilitar a verificação de integridade. Os servidores podem responder a uma solicitação de maneiras arbitrárias fora do escopo da estrutura Blazor. A estrutura fornece a configuração BlazorCacheBootResources para tornar o aplicativo executável às custas de perder a garantia de integridade que o aplicativo pode fornecer. Novamente, não recomendamos desabilitar a verificação de integridade, especialmente para implantações de produção. Os desenvolvedores devem procurar resolver o problema de integridade subjacente que está causando falha na verificação de integridade.

Alguns casos gerais que podem causar problemas de integridade são:

• Em execução em HTTP, onde a integridade não pode ser verificada.
• Se o processo de implantação modificar os arquivos após a publicação de alguma forma.
• Se o host modificar os arquivos de alguma forma.

Desabilitar a verificação de integridade para PWAs

O modelo de PWA (Aplicativo Web Progressivo) do Blazor contém um arquivo service-worker.published.js sugerido, que é responsável por buscar e armazenar arquivos de aplicativo para uso offline. Esse é um processo separado do mecanismo normal de inicialização do aplicativo e tem sua própria lógica de verificação de integridade separada.

Dentro do arquivo service-worker.published.js, a seguinte linha está presente:

.map(asset => new Request(asset.url, { integrity: asset.hash }));

Para desabilitar a verificação de integridade, remova o parâmetro integrity alterando a linha para o seguinte:

.map(asset => new Request(asset.url));

Novamente, desabilitar a verificação de integridade significa que você perderá as garantias de segurança oferecidas pela verificação de integridade. Por exemplo, existe o risco de que, se o navegador do usuário estiver armazenando em cache o aplicativo no momento exato em que você implantar uma nova versão, ele poderá armazenar em cache alguns arquivos da implantação antiga e outros da nova implantação. Se isso acontecer, o aplicativo ficará paralisado em um estado interrompido até que você implante uma nova atualização.