Validação de Drivers do Windows

Artigo
09/23/2024

Use as ferramentas InfVerif, Driver Verifier Driver Isolation e ApiValidator para testar o pacote de driver quanto à conformidade com os requisitos de Drivers do Windows descritos em Introdução ao desenvolvimento de drivers do Windows.

InfVerif

O InfVerif é uma ferramenta que valida a sintaxe INF e verifica se o INF está em conformidade com os requisitos e as restrições.

Use InfVerif com /w para verificar se um Driver do Windows:

Atende ao princípio declarativo (D) dos Princípios d Design do DCH
Está em conformidade com o requisito de isolamento do pacote de driver de Introdução ao desenvolvimento de drivers do Windows

Para obter mais detalhes, consulte Execução do InfVerif da linha de comando.

O InfVerif valida os requisitos de isolamento de Driver com o argumento "/w", conforme mostrado aqui:

infverif.exe /w <INF file> [<INF file>]

Se o InfVerif não relatar erros ao validar com /w, o INF atende ao requisito de Isolamento do Pacote de Driver dos Drivers do Windows.

Direcionamento de versões atuais e anteriores do Windows

Se o INF contiver a sintaxe introduzida em uma versão recente do Windows, como a Diretiva INF AddEventProvider, que está disponível a partir do Windows 10 versão 1809 e você também deseja direcionar versões anteriores do Windows, use decorações INF para marcar entradas INF específicas da versão. Para obter um código de exemplo mostrando como usar decorações de versão do sistema operacional, consulte Combinação de extensões de plataforma com versões de sistema operacional.

Os arquivos INF usando decorações de versão do sistema operacional podem falhar para InfVerif porque os requisitos de isolamento de driver podem não ter suprote nas versões anteriores do Windows. Para validar esse INF, você pode especificar a versão mínima do Windows em que as verificações de isolamento de driver devem ser aplicadas, usando o argumento "/wbuild". Por exemplo, um arquivo INF que usa a diretiva AddEventProvider pode usar o seguinte para aplicar somente verificações de isolamento de driver para o Windows 10 versão 1809 e posterior:

infverif.exe /w /wbuild NTAMD64.10.0.0.17763 <INF file> [<INF file>]

Verificações de isolamento de driver do verificador de driver

Para se qualificar como um Driver do Windows, um pacote de driver deve atender aos requisitos de Isolamento do Pacote de Driver . A partir do Windows 11, o Verificador de Driver (DV) pode monitorar binários do kernel para leituras e gravações do Registro e do sistema de arquivos que não são permitidas para pacotes de driver isolados.

Você pode exibir as violações à medida que elas acontecem em um depurador de kernel, examiná-las conforme relatado no log de eventos do sistema ou configurar o DV para interromper o sistema e gerar um despejo de memória com detalhes quando ocorrer uma violação. Você pode iniciar o desenvolvimento do driver com o primeiro e o segundo método e, em seguida, alternar para o segundo à medida que o driver se aproximar da conclusão.

Para habilitar as verificações de isolamento do driver para que elas sejam relatadas por meio do depurador de kernel e do log de eventos do sistema, mas não verifiquem o sistema:

verifier /rc 33 36 /driver myDriver.sys [myDriver2.sys ...]

Para configurar o DV para verificação de bugs quando ocorrer uma violação de isolamento do driver, use a seguinte sintaxe:

verifier /onecheck /rc 33 36 /driver myDriver1.sys [myDriver2.sys ...]

Independentemente do método de monitoramento escolhido, você precisará reinicializar para habilitar as configurações de verificação. Para fazer isso da linha de comando, especifique:

shutdown /r /t 0

Veja a seguir alguns exemplos de mensagens de erro, conforme visto no depurador de kernel:

Exemplo: ZwCreateKey fornece caminho absoluto completo:

DRIVER_ISOLATION_VIOLATION: <driver name>: Registry operations should not use absolute paths. Detected creation of unisolated registry key \Registry\Machine\SYSTEM

Exemplo: ZwCreateKey fornece caminho relativo a um identificador que não é de uma API aprovada:

DRIVER_ISOLATION_VIOLATION: <driver name>: Registry operations should only use key handles returned from WDF or WDM APIs. Detected creation of unisolated registry key \REGISTRY\MACHINE\SYSTEM\SomeKeyThatShouldNotExist

Considere executar testes de Fundamentos do Dispositivo com verificações de isolamento de driver DV habilitadas em seu driver para ajudar a detectar violações de isolamento de driver antecipadamente.

Observação

O DV não deseja inundar os usuários com um dilúvio de relatórios da mesma violação. Por isso, ele tem um mecanismo de restrição para limitar o número de relatórios de cada erro. A partir do Windows 11 24H2, para garantir que você veja o conjunto completo de violações de isolamento de driver para qualquer execução de um teste ou de uma série de testes, você pode solicitar a redefinição da restrição das violações de isolamento de driver usando:

verificador/dif 33/ação 1

Se você não fizer isso antes de executar um teste e se essas violações já tiverem ocorrido antes do início dele, talvez você não veja determinadas violações durante sua execução.

Conformidade do WHCP

Atualmente, o programa WHCP (Programa de Compatibilidade de Hardware do Windows) não exige o isolamento completo do pacote de driver. No entanto, a partir do Windows 11 24H2, o programa WHCP começa a incluir requisitos relacionados ao isolamento do driver. Para habilitar o mesmo nível de validação de isolamento do pacote de driver que o HLK (Hardware Lab Kit) tem como parte da aplicação dos requisitos do WHCP, use a seguinte sintaxe:

Verifier /dif 33 /33 whcp /driver myDriver.sys [myDriver2.sys ...]

Ao usar essa sintaxe, todas as violações de isolamento de driver ainda serão relatadas, mas as que não estão sendo aplicadas no momento para o HLK serão relatadas como avisos, e não como erros. As que forem listadas como avisos não causarão falhas de HLK e não farão com que o sistema verifique os bugs, se você habilitar as verificações de isolamento de driver com /onecheck para que ele gere uma verificação de bugs quando ocorrer uma violação.

Ao exibir eventos com um depurador de kernel, os que forem considerados erros serão prefixados com DRIVER_ISOLATION_VIOLATION. Já os que forem avisos serão prefixados com DRIVER_ISOLATION_WARNING.

Ao exibir eventos no log de eventos do sistema, os que tiverem um ErrorLevel atributo de 0 serão considerados erros, e os que tiverem outro ErrorLevel valor não serão considerados erros. Consulte a seção "Exibir violações no log de eventos do sistema" abaixo para obter mais informações.

Exibir violações no log de eventos do sistema

As violações do Verificador de Driver são relatadas no log de eventos do sistema do provedor Microsoft-Windows-Kernel-XDV e com uma ID de evento de "4". No Windows 11 24H2 e versões posteriores, os eventos conterão um valor ErrorLevel. Eventos com um ErrorLevel valor de 0 são considerados erros de acordo com o modo de isolamento de driver ativo (conformidade com isolamento completo de driver x conformidade com isolamento WHCP) quando a violação foi gerada. Eventos com outros ErrorLevel valores não são considerados erros. Por exemplo, um evento com esses atributos seria considerado um erro:

EventData
	RuleId	0x210001
	ErrorMessage	Registry operations should not use absolute paths. Detected opening of unisolated registry key \Registry\Machine\System\CurrentControlSet\Services\ExampleDriver\Parameters
	Module	\SystemRoot\System32\drivers\ExampleDriver.sys
	Irql	0
	ErrorLevel	0x0

Já um evento com esses atributos não seria considerado um erro:

EventData
	RuleId	0x210001
	ErrorMessage	Registry operations should only use key handles returned from WDF or WDM APIs. Detected querying of value under unisolated registry key \REGISTRY\MACHINE\SYSTEM\ControlSet001\Control
	Module	\SystemRoot\System32\drivers\ExampleDriver.sys
	Irql	0
	ErrorLevel	0xf4240

Se você estiver usando o aplicativo Visualizador de Eventos para visualizar o log de eventos do sistema, filtre a exibição do log usando o menu no lado direito do aplicativo. Para fazer isso, clique em "Filtrar log atual". Na caixa de diálogo que aparecer, se você acessar a guia XML e editar a consulta manualmente, poderá usar essa consulta para filtrar o log de eventos do sistema e exibir apenas as violações do DV que devem ser consideradas erros:

<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and (EventData/Data[@Name='ErrorLevel']='0')]</Select>
  </Query>
</QueryList>

Se você quiser filtrar a exibição do log de eventos para mostrar todas as violações do DV que devem ser consideradas erros após um determinado período (por exemplo, após o início da aprovação de um teste), faça o seguinte:

<QueryList>
  <Query Id="0" Path="System">
    <Select Path="System">*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and System/TimeCreated[@SystemTime&gt;='2024-01-24T23:00:00.0Z'] and (EventData/Data[@Name='ErrorLevel']='0')]</Select>
  </Query>
</QueryList>

Se preferir um arquivo XML que possa ser carregado para exibição, use a ferramenta wevtutil para gerar esse XML com base nas mesmas consultas:

wevtutil qe System /q:"*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and (EventData/Data[@Name='ErrorLevel']='0')]" /e:Events > DriverVerifierErrors.xml

wevtutil qe System /q:"*[System/Provider[@Name='Microsoft-Windows-Kernel-XDV'] and System[(EventID='4')] and System/TimeCreated[@SystemTime>='2024-01-24T23:00:00.0Z'] and (EventData/Data[@Name='ErrorLevel']='0')]" /e:Events > DriverVerifierErrors.xml

Drivers KMDF

Quando os drivers KMDF usam APIs WDF para acessar o Registro, como WdfRegistryCreateKey, WdfRegistryOpenKey, or WdfRegistryQueryValue, the registry access happens via wdf01000.sys instead of the KMDF driver binary directly. Para exibir violações causadas pelo binário do driver KMDF, habilite as verificações de isolamento de driver em wdf01000.sys além do binário do driver KMDF. Observe que, ao fazer isso, você verá violações de todos os drivers KMDF no sistema que estão usando o WDF para seus acessos ao Registro.

ApiValidator

A ferramenta ApiValidator verifica se as APIs que seus binários chamam são válidas para um driver do Windows. A ferramenta retornará um erro se os binários chamarem uma API que está fora do conjunto de APIs válidas para Drivers do Windows. Esta ferramenta faz parte do WDK para Windows 10.

O ApiValidator valida que um driver oferece suporte a Camadas de API, um dos requisitos para Drivers do Windows. Para obter uma lista completa de requisitos, consulte Introdução ao desenvolvimento de drivers do Windows.

Execução de ApiValidator no Visual Studio

Se a propriedade Target Platform do seu projeto de driver estiver definida como Driver do Windows, o Visual Studio executará o ApiValidator automaticamente como uma etapa pós-compilação.

Para exibir todas as mensagens exibidas pelo ApiValidator, navegue até Ferramentas->Opções->Projetos e Soluções->Compilar e Executar e defina o detalhamento de saída da compilação do projeto MSBuild como Detalhado. Ao criar da linha de comando, adicione a opção /v:detailed ou /v:diag ao comando build para aumentar o detalhamento.

Para o exemplo de driver umdf2_fx2, os erros de validação de API têm a seguinte aparência:

Warning  1   warning : API DecodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 2   warning : API DisableThreadLibraryCalls in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 3   warning : API EncodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 4   warning : API GetCurrentProcessId in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 5   warning : API GetCurrentThreadId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.  C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 6   warning : API GetSystemTimeAsFileTime in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 7   warning : API IsDebuggerPresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 8   warning : API IsProcessorFeaturePresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.   C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Warning 9   warning : API QueryPerformanceCounter in kernel32.dll is not supported. osrusbfx2um.dll calls this API. C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe    osrusbfx2um
Error   10  error MSB3721: The command ""C:\Program Files (x86)\Windows Kits\10\bin\x64\ApiValidator.exe" -DriverPackagePath:"C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\Debug\\" -SupportedApiXmlFiles:"C:\Program Files (x86)\Windows Kits\10\build\universalDDIs\x86\UniversalDDIs.xml" -ApiExtractorExePath:"C:\Program Files (x86)\Windows Kits\10\bin\x64"" exited with code -1.    C:\Program Files (x86)\Windows Kits\10\build\WindowsDriver.common.targets   1531    5   osrusbfx2um

Correção de erros de validação

Se você alternou um projeto de driver UMDF de área de trabalho herdado para o Driver do Windows, verifique se está incluindo as bibliotecas corretas ao criar seus binários. Selecione e segure (ou clique com o botão direito do mouse) o projeto e escolha propriedades. Navegue até Vinculador->Entrada. As Dependências Adicionais devem conter:
```
%AdditionalDependencies);$(SDK_LIB_PATH)\OneCoreUAP.lib
```
Para revisar outras opções de vinculador para segmentar SKUs OneCore, consulte Criação para OneCore.
Remova ou substitua chamadas de API que não são permitidas uma de cada vez e execute novamente a ferramenta até que não haja erros.
Em alguns casos, você pode substituir essas chamadas por DDIs alternativas listadas nas páginas de referência para o DDI somente para desktop. Talvez seja necessário codificar uma solução alternativa se não houver uma substituição adequada. Se precisar, escreva um novo Driver do Windows dos modelos de driver no WDK.

Se você vir erros como os seguintes, consulte as diretrizes em Criação para OneCore.

ApiValidation: Error: FlexLinkTest.exe has a dependency on 'wtsapi32.dll!WTSEnumerateSessionsW' but is missing: IsApiSetImplemented("ext-ms-win-session-wtsapi32-l1-1-0")
ApiValidation: Error: FlexLinkTest.exe has a dependency on 'wtsapi32.dll!WTSFreeMemory' but is missing: IsApiSetImplemented("ext-ms-win-session-wtsapi32-l1-1-0")
ApiValidation: NOT all binaries are Universal

Execução de ApiValidator do Prompt de Comando

Você também pode executar Apivalidator.exe no prompt de comando. Na instalação do WDK, navegue até C:\Arquivos de Programas (x86)\Windows Kits\10\bin<arch> e C:\Arquivos de Programas (x86)\Windows Kits\10\build\universalDDIs<arch>.

Observações importantes:

ApiValidator requer os seguintes arquivos: ApiValidator.exe, Aitstatic.exe, Microsoft.Kits.Drivers.ApiValidator.dll e UniversalDDIs.xml.
O UniversalDDIs.xml deve corresponder à arquitetura binária que está sendo validada, por exemplo, para um driver x64 use o x64 UniversalDDI.xml
O ApiValidator testa apenas uma arquitetura de cada vez
Consulte Problemas conhecidos do ApiValidator abaixo para obter informações adicionais

Use a seguinte sintaxe:

Apivalidator.exe -DriverPackagePath: <driver folder path> -SupportedApiXmlFiles: (path to XML files containing supported APIs for Windows drivers)

Por exemplo, para verificar as APIs chamadas pelo exemplo Atividade no WDK, primeiro compile o exemplo no Visual Studio. Em seguida, abra um prompt de comando e navegue até o diretório que contém a ferramenta, por exemplo C:\Program Files (x86\Windows Kits\10\bin\x64. Insira o seguinte comando:

apivalidator.exe -DriverPackagePath:"C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2\_fx2\Debug" -SupportedApiXmlFiles:"c:\Program Files (x86)\Windows Kits\10\build\universalDDIs\x64\UniversalDDIs.xml"

O comando gera a seguinte saída:

ApiValidator.exe: Warning: API DecodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API DisableThreadLibraryCalls in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API EncodePointer in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetCurrentProcessId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetCurrentThreadId in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API GetSystemTimeAsFileTime in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API IsDebuggerPresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API IsProcessorFeaturePresent in kernel32.dll is not supported. osrusbfx2um.dll calls this API.
ApiValidator.exe: Warning: API QueryPerformanceCounter in kernel32.dll is not supported. osrusbfx2um.dll calls this API.

ApiValidator.exe Driver located at C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\Debug is NOT a Universal Driver

Solução de problemas do ApiValidator

Se ApiValidator.exe gerar um erro de formato incorreto, como o seguinte:

Error      1              error : AitStatic output file has incorrect format or analysis run on incorrect file types.     C:\Program Files (x86)\Windows Kits\10\src\usb\umdf2_fx2\driver\ApiValidator.exe            osrusbfx2um

Use esta solução alternativa:

Abra as propriedades do Projeto, navegue até Geral e renomeie o Diretório de Saída para o seguinte:
```
$(SolutionDir)$(Platform)\$(ConfigurationName)\
```
Recrie a solução.

Problemas conhecidos do ApiValidator

O ApiValidator não é executado no Arm64 porque AitStatic não funciona no Arm64.
Os binários do Arm64 podem ser testados em computadores x64, mas não em um computador x86.
O ApiValidator pode ser executado em x86 para testar binários x86 e binários Arm.
O ApiValidator pode ser executado em x64 para testar binários x86, x64, Arm e Arm64.

Compartilhar via