Windows 드라이버 유효성 검사

아티클
08/14/2024

InfVerif, 드라이버 검증 도구 드라이버 격리 검사 및 ApiValidator 도구를 사용하여 Windows 드라이버 개발 시작에 설명된 Windows 드라이버 요구 사항을 준수하는지 드라이버 패키지를 테스트합니다.

InfVerif

InfVerif 는 INF 구문의 유효성을 검사하고 INF가 요구 사항 및 제한을 준수하는지 확인하는 도구입니다.

InfVerif를 /w 사용하여 Windows 드라이버가 있는지 확인합니다.

DCH 디자인 원칙의 선언적(D) 원칙을 충족합니다.
Windows 드라이버 개발 시작의 드라이버 패키지 격리 요구 사항을 준수합니다.

자세한 내용은 명령줄에서 InfVerif 실행을 참조 하세요.

InfVerif는 다음과 같이 '/w' 인수를 사용하여 드라이버 격리 요구 사항의 유효성을 검사합니다.

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

/w를 사용하여 유효성을 검사할 때 InfVerif에서 오류를 보고하지 않으면 INF는 Windows 드라이버의 드라이버 패키지 격리 요구 사항을 충족합니다.

현재 및 이전 버전의 Windows를 대상으로 지정

INF에 Windows 10 버전 1809부터 사용할 수 있는 INF AddEventProvider 지시문과 같은 최신 버전의 Windows에 도입된 구문이 포함되어 있고 이전 Windows 버전을 대상으로 지정하려는 경우 INF 장식을 사용하여 버전별 INF 항목을 표시합니다. OS 버전 장식을 사용하는 방법을 보여 주는 샘플 코드는 플랫폼 확장과 운영 체제 버전 결합을 참조 하세요.

이전 Windows 버전에서는 드라이버 격리 요구 사항이 지원되지 않을 수 있으므로 OS 버전 장식을 사용하는 INF 파일이 InfVerif에 실패할 수 있습니다. 이러한 INF의 유효성을 검사하려면 '/wbuild' 인수를 사용하여 드라이버 격리 검사를 적용해야 하는 최소 Windows 버전을 지정할 수 있습니다. 예를 들어 AddEventProvider 지시문을 사용하는 INF 파일은 다음을 사용하여 Windows 10 버전 1809 이상에만 드라이버 격리 검사를 적용할 수 있습니다.

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

드라이버 검증 도구 드라이버 격리 확인

Windows 드라이버 자격을 얻으려면 드라이버 패키지가 드라이버 패키지 격리 요구 사항을 충족해야 합니다. Windows 11 부터 DV(드라이버 검증 도구 )는 격리된 드라이버 패키지에 허용되지 않는 레지스트리 및 파일 시스템 읽기 및 쓰기에 대한 커널 이진 파일을 모니터링할 수 있습니다.

커널 디버거에서 발생하는 위반을 보거나, 시스템 이벤트 로그에 보고된 위반을 검토하거나, DV를 구성하여 시스템을 중지하고 위반이 발생할 때 세부 정보가 포함된 메모리 덤프를 생성할 수 있습니다. 첫 번째 및 두 번째 메서드를 사용하여 드라이버 개발을 시작한 다음 드라이버가 완료될 무렵에 두 번째 메서드로 전환할 수 있습니다.

커널 디버거 및 시스템 이벤트 로그를 통해 보고되지만 시스템을 버그 검사하지 않도록 드라이버 격리 검사를 사용하도록 설정하려면 다음을 수행합니다.

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

드라이버 격리 위반이 발생할 때 버그 검사를 수행하도록 DV를 구성하려면 다음 구문을 사용합니다.

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

선택한 모니터링 방법에 관계없이 확인 설정을 사용하도록 설정하려면 다시 부팅해야 합니다. 명령줄에서 이 작업을 수행하려면 다음을 지정합니다.

shutdown /r /t 0

커널 디버거에 표시된 오류 메시지의 몇 가지 예는 다음과 같습니다.

예: ZwCreateKey 는 전체 절대 경로를 제공합니다.

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

예: ZwCreateKey 는 승인된 API가 아닌 핸들을 기준으로 경로를 제공합니다.

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

드라이버에서 DV 드라이버 격리 검사를 사용하도록 설정하여 디바이스 기본 사항 테스트를 실행하여 드라이버 격리 위반을 조기에 catch하는 것이 좋습니다.

참고 항목

DV는 동일한 위반에 대한 보고서의 홍수로 사용자를 범람시키고 싶지 않으므로 각 고유 오류의 보고를 제한할 수 있는 제한 메커니즘이 있습니다. Windows 11 24H2부터 지정된 테스트 실행 또는 일련의 테스트에 대한 드라이버 격리 위반의 전체 집합이 표시되는지 확인하기 위해 다음을 사용하여 드라이버 격리 위반을 다시 설정하도록 요청할 수 있습니다.

verifier /dif 33 /action 1

테스트를 실행하기 전에 이 작업을 수행하지 않으면 테스트를 시작하기 전에 해당 위반이 이미 발생한 경우 테스트를 실행하는 동안 특정 위반이 표시되지 않을 수 있습니다.

WHCP 규정 준수

현재 Windows WHCP(하드웨어 호환성 프로그램) 프로그램은 전체 드라이버 패키지 격리를 요구하지 않습니다. 그러나 Windows 11 24H2부터 WHCP 프로그램은 드라이버 격리 관련 요구 사항을 포함하여 시작됩니다. HLK(하드웨어 랩 키트)와 동일한 수준의 드라이버 패키지 격리 유효성 검사를 사용하도록 설정하려면 WHCP 요구 사항을 적용하는 과정의 일부로 다음 구문을 사용합니다.

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

이 구문을 사용하는 경우 모든 드라이버 격리 위반이 계속 보고되지만 HLK에 현재 적용되지 않는 위반은 오류 대신 경고로 보고됩니다. 경고로 나열된 항목은 HLK 오류를 일으키지 않으며 위반이 발생할 때 버그 검사를 생성하도록 /onecheck를 사용하여 드라이버 격리 검사를 사용하도록 설정하는 경우 시스템이 버그 검사를 수행하지 않습니다.

커널 디버거를 사용하여 이벤트를 볼 때 오류로 간주되는 이벤트에는 접두사 DRIVER_ISOLATION_VIOLATION 로 지정되고 경고인 이벤트에는 접두 DRIVER_ISOLATION_WARNING사를 붙입니다.

시스템 이벤트 로그에서 이벤트를 볼 때 특성이 0인 ErrorLevel 이벤트는 오류로 간주되며 다른 ErrorLevel 값을 가진 이벤트는 오류로 간주되지 않습니다. 자세한 내용은 아래의 "시스템 이벤트 로그에서 위반 보기" 섹션을 참조하세요.

시스템 이벤트 로그에서 위반 보기

드라이버 검증 도구 위반은 공급자 Microsoft-Windows-Kernel-XDV 의 시스템 이벤트 로그와 이벤트 ID가 '4'인 것으로 보고됩니다. Windows 11 24H2 이상에서는 이벤트에 값이 ErrorLevel 포함됩니다. 값이 0인 ErrorLevel 이벤트는 위반이 생성되었을 때 드라이버 격리 모드 활성(전체 드라이버 격리 준수 및 WHCP 격리 준수)에 따라 오류로 간주됩니다. 다른 ErrorLevel 값이 있는 이벤트는 오류로 간주되지 않습니다. 예를 들어 이러한 특성이 있는 이벤트는 오류로 간주됩니다.

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

이러한 특성이 있는 이벤트는 오류로 간주되지 않습니다.

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

이벤트 뷰어 애플리케이션을 사용하여 시스템 이벤트 로그를 보는 경우 "현재 로그 필터링"을 클릭하여 애플리케이션 오른쪽의 메뉴를 사용하여 로그 보기를 필터링할 수 있습니다. 팝업 대화 상자에서 XML 탭으로 이동하여 쿼리를 수동으로 편집하는 경우 이 쿼리를 사용하여 시스템 이벤트 로그를 오류로 간주해야 하는 DV 위반으로 필터링할 수 있습니다.

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

이벤트 로그 보기를 특정 시간(예: 테스트 통과가 시작된 시간 이후) 후 오류로 간주되어야 하는 모든 DV 위반으로 필터링하려는 경우 다음을 수행할 수 있습니다.

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

또는 로드할 수 있는 XML 파일을 보려면 wevtutil을 사용하여 동일한 쿼리를 기반으로 이러한 XML을 생성할 수 있습니다.

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

KMDF 드라이버

KMDF 드라이버가 WDF API를 사용하여 WdfRegistryCreateKey, WdfRegistryOpenKey 또는 WdfRegistryQueryValue와 같은 레지스트리에 액세스하는 경우 레지스트리 액세스는 KMDF 드라이버 이진 파일이 아닌 wdf01000.sys 통해 직접 수행됩니다. KMDF 드라이버 이진으로 인한 위반을 보려면 KMDF 드라이버 이진 파일 외에도 wdf01000.sys 드라이버 격리 검사를 사용하도록 설정하세요. 이렇게 하면 레지스트리 액세스에 WDF를 사용하는 시스템의 모든 KMDF 드라이버에서 위반이 표시됩니다.

ApiValidator

ApiValidator 도구는 이진 파일이 호출하는 API가 Windows 드라이버에 대해 유효한지 확인합니다. 이진 파일이 Windows 드라이버용 유효한 API 집합 외부에 있는 API를 호출하는 경우 이 도구는 오류를 반환합니다. 이 도구는 Windows 10용 WDK의 일부입니다.

ApiValidator는 드라이버가 Windows 드라이버에 대한 요구 사항 중 하나인 API 계층을 지원하는지 확인합니다. 요구 사항의 전체 목록은 Windows 드라이버 개발 시작을 참조 하세요.

Visual Studio에서 ApiValidator 실행

드라이버 프로젝트의 대상 플랫폼 속성이 Windows 드라이버로 설정된 경우 Visual Studio는 빌드 후 단계로 ApiValidator를 자동으로 실행합니다.

ApiValidator에서 표시하는 모든 메시지를 보려면 Tools-Options-Projects 및 Solutions-Build> and Run으로 이동하고 MSBuild 프로젝트 빌드 출력 세부 정보 표시를 자세히 설정합니다.>> 명령줄에서 빌드할 때 빌드 명령에 /v:detailed 또는 /v:diag 스위치를 추가하여 자세한 내용을 확인합니다.

umdf2_fx2 드라이버 샘플의 경우 API 유효성 검사 오류는 다음과 같습니다.

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

유효성 검사 오류 수정

레거시 데스크톱 UMDF 드라이버 프로젝트를 Windows 드라이버로 전환한 경우 이진 파일을 빌드할 때 올바른 라이브러리를 포함하고 있는지 확인합니다. 프로젝트를 선택하고 길게(또는 마우스 오른쪽 단추로 클릭) 속성을 선택합니다. 링커 입력>으로 이동합니다. 추가 종속성에는 다음이 포함되어야 합니다.
```
%AdditionalDependencies);$(SDK_LIB_PATH)\OneCoreUAP.lib
```
OneCore SKU를 대상으로 하는 다른 링커 옵션을 검토하려면 OneCore용 빌드를 참조하세요.
한 번에 하나씩 허용되지 않는 API 호출을 제거하거나 바꾸고 오류가 없을 때까지 도구를 다시 실행합니다.
경우에 따라 이러한 호출을 데스크톱 전용 DDI의 참조 페이지에 나열된 대체 DDI로 바꿀 수 있습니다. 적절한 대체 방법이 없는 경우 해결 방법을 코딩해야 할 수 있습니다. 필요한 경우 WDK의 드라이버 템플릿에서 시작하는 새 Windows 드라이버를 작성합니다.

다음과 같은 오류가 표시되면 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

명령 프롬프트에서 ApiValidator 실행

명령 프롬프트에서 Apivalidator.exe 실행할 수도 있습니다. WDK 설치에서 C:\Program Files (x86)\Windows Kits\10\bin arch> 및 C:\Program Files (x86)\Windows Kits\10\build\universalDDIs<arch>로 이동합니다.<

중요 사항:

ApiValidator에는 ApiValidator.exe, Aitstatic.exe, Microsoft.Kits.Drivers.ApiValidator.dll 및 UniversalDDIs.xml 파일이 필요합니다.
예를 들어 x64 드라이버가 x64 UniversalDDI.xml 사용하는 경우와 같이 UniversalDDIs.xml 유효성을 검사하는 이진 아키텍처와 일치해야 합니다.
ApiValidator는 한 번에 하나의 아키텍처만 테스트합니다.
자세한 내용은 아래의 알려진 ApiValidator 문제를 참조하세요.

다음 구문을 사용합니다.

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

예를 들어 WDK의 활동 샘플에서 호출된 API를 확인하려면 먼저 Visual Studio에서 샘플을 빌드합니다. 그런 다음 명령 프롬프트를 열고 도구가 포함된 디렉터리로 이동합니다. 예를 들면 다음과 같습니다 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\x64\UniversalDDIs.xml"

이 명령은 다음 출력을 생성합니다.

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

ApiValidator 문제 해결

ApiValidator.exe 다음과 같은 잘못된 형식 오류를 출력하는 경우:

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

이 해결 방법을 사용합니다.

프로젝트 속성을 열고 일반으로 이동한 다음 출력 디렉터리의 이름을 다음으로 바꿉니다.
```
$(SolutionDir)$(Platform)\$(ConfigurationName)\
```
솔루션을 다시 빌드합니다.

알려진 ApiValidator 문제

AitStatic이 Arm64에서 작동하지 않으므로 ApiValidator는 Arm64에서 실행되지 않습니다.
Arm64 이진 파일은 x64 컴퓨터에서 테스트할 수 있지만 x86 컴퓨터에서는 테스트할 수 없습니다.
ApiValidator는 x86에서 실행하여 x86 이진 파일 및 Arm 이진 파일을 테스트할 수 있습니다.
ApiValidator는 x64에서 실행하여 x86, x64, Arm 및 Arm64 이진 파일을 테스트할 수 있습니다.

다음을 통해 공유