= Introduction =

Microsoft has some documentation about HLK testing and WHQL signing, but it is quite incomplete, and there is lots of room for speculation and anecdotes. Practical testing is often required to understand the requirements fully. Therefore some of the requirements documented in this article are bound to change.

Different Windows versions have different kernel-mode signing options:

* Windows 7/8/8.1/Server 2012r2
 * Cross-signing
 * WHQL-certified (HCR)
* Windows 10 desktop
 * Attestation signing
 * WHQL-certified (HLK)
* Windows Server 2016/2019
 * WHQL-certified (HLK)

In this article we focus on HLK testing, which allows getting a WHQL signature for a kernel-mode driver. This is the only way to make a driver load on Windows Server 2016 and later.

= HLK testing environment =

HLK testing always requires a HLK !Controller/Studio node, plus one or more HLK clients.

According to practical testing done by [https://www.wintun.net/ wintun] developers it is possible to get a code signature that is valid for all Windows 10 platforms using the following HLK clients:

* HLK controller: Windows Server 2016
* HLK clients
 * Windows Server 2019 (64-bit)
 * Windows Server 2019 core (64-bit)
 * Windows 10 desktop (32-bit)

Wintun was able to pass HLK testing without any ''physical'' HLK clients. But due to wintun's narrower scope it had to pass much fewer HLK tests (~50 in total) than tap-windows6.

For tap-windows6 testing a couple of extra nodes are needed:

* OpenVPN server (for "Run tests" in HLK, see below)
* Support machine: required by some of the HLK tests

There are some additional requirements for tap-windows6 that stem from generic [https://docs.microsoft.com/en-us/windows-hardware/test/hlk/testref/lan-testing-prerequisites LAN testing prerequisites]:

* HLK client needs at least 4 virtual processor cores (unverified)
* HLK client need to be physical computers, not virtualized (unverified)

For HLK software installation please refer to the official MS documentation, check out [https://github.com/Puppet-Finland/puppet-hlk/ puppet-hlk] or try out the [https://docs.microsoft.com/en-us/windows-hardware/test/hlk/getstarted/getstarted-vhlk Windows Virtual Hardware Lab Kit].

= Preparing for installation of test-signed drivers =

Installation of HLK client software automatically enables test signing mode in Windows. Tap-windows6 build system supports test-signing the driver automatically. You need to put the automatically generated test certificate to the Windows certificate store on the HLK clients. After that you can install the test-signed driver without signature errors.

= OpenVPN setup for HLK =

The "Run tests" in HLK fail consistently unless the tap-windows6 adapter has an IPv6 gateway address. This can be resolved by installing an OpenVPN server and joining all HLK clients connect to it. Launching OpenVPN client on the HLK client creates an instance of tap-windows6 adapter on the system with proper IPv6 gateway address.

Use the latest available OpenVPN and generate certificates and keys with [https://github.com/OpenVPN/easy-rsa/ EasyRSA 3] for example.

OpenVPN server configuration is fairly simple:

{{{
# OpenVPN server test configuration for Windows Hardware Lab Kit test server
#
# We need this for HLK "Run tests" which ping6 the gateway of the interface
# bound to the driver being tested.
#
server 10.218.112.0 255.255.255.0
server-ipv6 2001:db8:6666::1/64
port 1194
proto udp
dev tun5
comp-lzo
persist-key
persist-tun
keepalive 10 120
verb 4
duplicate-cn
max-clients 15
status hlk-openvpn-status.log
<ca>
# CA certicate here
</ca>

<cert>
# Server certificate here
</cert>

<key>
# Server private key here
</key>

key-direction 0
<tls-auth>
# TLS auth key here
</tls-auth>
}}}

OpenVPN setup on HLK clients:

{{{
# OpenVPN client test configuration for Windows Hardware Lab Kit test clients
#
# We need this for HLK "Run tests" which ping6 the gateway of the interface
# bound to the driver being tested.
#

# Replace "x.x.x.x" with OpenVPN server's (public) IPv4 address 
remote x.x.x.x 1194
client
proto udp
dev tun
comp-lzo
persist-key
persist-tun
keepalive 10 120
verb 4
status hlk-openvpn-status.log

<ca>
# CA certificate here
</ca>

<cert>
# Client certificate here
</cert>

<key>
# Client private key here
</key>

key-direction 1
<tls-auth>
# TLS auth key here
</tls-auth>
}}}

= Firewall rules for HLK server and clients =

Installing HLK software automatically opens ports in the Windows firewall for HLK traffic. In case HLK controller and HLK clients are not in the same switch some firewall (e.g. EC2 security group rules) might block HLK traffic. Here is a reference for the ports which need to be open for HLK tests to work:

* HLK clients -> OpenVPN server udp/1194
* HLK clients -> HLK controller tcp/1771 (HLK Server Receiver Port)
* HLK clients -> HLK controller tcp/1782 (HLKSvc Receiver Port)
* HLK clients -> HLK controller tcp/445 (HLKInstall Samba share)
* HLK controller -> HLK clients tcp/1771 (HLK Server Receiver Port)

Outbound traffic is assumed to be unrestricted. If not, adjust egress rules accordingly. Also note that IPv6 traffic needs to flow properly in the OpenVPN virtual network as HLK tests require IPv6.

= External links =

* [https://github.com/Puppet-Finland/puppet-hlk/ puppet-hlk]: Puppet module for setting up HLK controllers and HLK clients
* [https://docs.microsoft.com/en-us/windows-hardware/test/hlk/getstarted/getstarted-vhlk Windows Virtual Hardware Lab Kit]
* [https://aka.ms/HLKPlaylist] Compatibility Play Lists (Understanding is these are the only ones necessary to get signed)