How openvpn/tap-windows6 works
1. What this repository is
- This is the build, packaging, and signing repository for the Windows TAP-Windows NDIS 6 driver used by OpenVPN and similar software.
- The central runtime artifact is the kernel-mode driver (tap0901.sys), while the rest of the repo exists to build, package, install, and sign it for multiple Windows architectures.
2. Main architectural boundary: kernel driver vs. build/release tooling
- The src/ tree is the actual driver code that runs in kernel mode under Windows NDIS.
- Everything else is release engineering around that driver: Python build orchestration (buildtap.py), installer creation (installer/), MSM packaging (msm/), and code-signing/release scripts (sign/).
3. Driver subsystem layout in src/
- tapdrvr.c is the driver entry and top-level control logic.
- device.c/.h and adapter.c/.h model the device and network adapter lifecycle.
- txpath.c and rxpath.c implement transmit and receive packet paths.
- oidrequest.c handles NDIS OID requests, which is how Windows networking components query/control the adapter.
- dhcp.c contains DHCP-related handling for TAP-specific network setup behavior.
- macinfo.c, constants.h, types.h, proto.h, and prototypes.h provide supporting adapter metadata, types, and shared declarations.
4. Driver runtime interaction points
- The driver sits between Windows’ network stack/NDIS and the virtual TAP device exposed to user space.
- It receives control/query requests via NDIS OIDs, handles packet injection/egress through the TX/RX paths, and maintains device state across plug/unplug and start/stop transitions.
- The driver is therefore an integration layer: not an application server, but a kernel networking component with strict Windows driver-model boundaries.
5. Generated configuration and compile-time inputs
- Several files are template inputs used during build:
- src/config.h.in, src/OemVista.inf.in, src/resource.rc.in, and msm/config.props.in.
- version.m4 and paths.py define build/version/package metadata.
- These templates are expanded into architecture- and version-specific outputs that end up in dist/.
6. Build orchestration
- buildtap.py is the top-level build coordinator.
- It drives driver compilation, optional tapinstall/devcon building, signing, and packaging.
- The build targets are Windows-driver-toolchain-centric: Microsoft WDK/EWDK, Visual Studio toolchains, and optional HLK/test-signing modes.
7. Packaging outputs and installer boundary
- The build produces a dist/ tree containing the driver package for each architecture (i386, amd64, arm64) plus supporting files.
- installer/tap-windows6.nsi defines an NSIS-based installer executable.
- The msm/ subtree builds a Windows Installer merge module (MSM) via a Visual Studio solution and WiX-backed packaging; this is for embedding the driver into larger MSI-based products.
8. MSM packaging internals
- msm/ contains a small native installer DLL (dllmain.c, installation.c, msi.c, etc.) that appears to be the code embedded into the merge module.
- This is a separate packaging path from the NSIS installer: it is intended for enterprise/MSI consumption rather than standalone installation.
- The MSM flow is sensitive to signed dist/ contents and is architecture-dependent.
9. Driver installation and external tooling
- Runtime installation/removal is done with tapinstall.exe or devcon.exe, which are external utilities, not part of the driver itself.
- The repository supports either building those tools from Microsoft driver samples or reusing prebuilt binaries.
- This matters architecturally because driver deployment is split between the driver package and an external PnP control utility.
10. Signing and release pipeline
- The sign/ directory contains PowerShell scripts for cross-signing, attestation submission packaging, extraction, and file signing.
- The release flow targets Microsoft’s driver-signing ecosystem, including timestamping and cross-certificates.
- The build/sign/package process operates on the dist/ tree, so signed artifacts are a post-build release boundary rather than part of the source runtime.
11. Platform and compatibility structure
- The repo explicitly targets Windows 7+ through NDIS 6.20/6.30, with ARM64 requiring NDIS 6.30.
- Packaging and signing workflows are architecture-aware (i386, amd64, arm64) and sometimes diverge by platform, especially for Windows 10 attestation-signed artifacts.
12. How data/artifacts flow through the repo
- Source templates and driver code in src/ are compiled into the kernel driver.
- The build populates dist/ with per-architecture driver packages and optional helper binaries.
- Installer and MSM packaging consume dist/.
- Signing scripts operate on the same output tree to produce release-signed deliverables for distribution.
13. What to draw in an architecture diagram
- Show a central kernel driver block with packet/OID/device-management submodules inside it.
- Surround it with build-time subsystems: Python build orchestration, template generation, installer/MSM packaging, and signing.
- Add external dependencies/boundaries: Windows NDIS/kernel, WDK/EWDK toolchain, tapinstall/devcon, Microsoft signing services, and optional WiX/NSIS packaging tools.
14. Key takeaway
- This repo is not an application stack; it is a driver product pipeline.
- The architectural center is the TAP NDIS driver in src/, and the rest of the repository exists to turn that driver into signed, installable packages for multiple Windows platforms.
Main entry points: buildtap.py Build coordinator · tapdrvr.c Driver core · adapter.c Adapter state · device.c Device state
Components 29
Kernel driver
NDIS 6 TAP driver runtime and shared compile-time inputs.
- Driver core · Driver entry point and top-level control logic.
src/tapdrvr.c - Device state · Device lifecycle and state management.
src/device.c - Adapter state · Network adapter lifecycle and attachment logic.
src/adapter.c - TX path · Transmit path for outbound packet flow.
src/txpath.c - RX path · Receive path for inbound packet flow.
src/rxpath.c - OID handling · NDIS OID query and control request handling.
src/oidrequest.c - DHCP support · DHCP-related TAP adapter behavior.
src/dhcp.c - MAC info · Adapter address and identity helpers.
src/macinfo.c - Config template · Generated configuration header input.
src/config.h.in - INF template · Windows driver package INF template.
src/OemVista.inf.in - Resource template · Driver resource template input.
src/resource.rc
Build orchestration
Top-level build metadata and Python coordination.
- Build coordinator · Top-level driver build, sign, and package orchestrator.
buildtap.py - Paths · Build and packaging path metadata.
paths.py - Versioning · Version and release metadata used during generation.
version.m4
Packaging
Standalone installer and MSI merge-module packaging paths.
- MSM props · Merge-module build properties template.
msm/config.props.in - MSM runtime · Native code embedded into the merge module.
msm/installation.c - MSI glue · MSI-facing packaging logic for the merge module.
msm/msi.c - WiX definition · WiX authoring for the merge module package.
msm/installer.wxs - NSIS installer · Standalone Windows installer script.
installer/tap-windows6.nsi
Signing
Release signing and submission scripts.
- Submission prep · Packages artifacts for driver submission.
sign/Create-DriverSubmission.ps1 - Cross-sign · Cross-signing and timestamping workflow.
sign/Cross-Sign.ps1 - File sign · Signs individual release artifacts.
sign/Sign-File.ps1 - MSM prep · Prepares MSM artifacts for packaging.
sign/Prepare-Msm.ps1
External boundaries
Toolchains, Windows driver stack, and signing services outside the repo.
- Windows NDIS · Windows kernel networking and NDIS environment.
- WDK toolchain · Microsoft driver build toolchain and Visual Studio environment.
- tapinstall/devcon · External PnP installation utilities used for driver deployment.
- Microsoft signing · Driver signing, attestation, and timestamping services.
- NSIS · External installer compiler for the standalone EXE.
- WiX · External MSI authoring/tooling used by merge-module packaging.
Connections 30
- Build coordinator → Driver core: builds · Coordinates compilation of the kernel driver.
- Build coordinator → MSM runtime: packages · Drives optional MSM build steps.
- Build coordinator → NSIS installer: packages · Generates standalone installer outputs.
- Build coordinator → Cross-sign: signs · Invokes release signing workflow.
- Build coordinator → Paths: uses · Resolves build and output paths.
- Build coordinator → Versioning: expands · Consumes version metadata during generation.
- Driver core → Device state: controls · Driver core manages device lifecycle.
- Driver core → Adapter state: controls · Driver core manages adapter lifecycle.
- Adapter state → TX path: sends · Adapter hands outbound traffic to TX path.
- Adapter state → RX path: receives · Adapter accepts inbound traffic from RX path.
- Driver core → OID handling: handles · Driver entry routes NDIS OID control requests.
- Driver core → DHCP support: coordinates · Driver core coordinates DHCP behavior.
- Adapter state → MAC info: uses · Adapter state uses MAC/identity helpers.
- Build coordinator → Config template: generates · Expands compile-time configuration headers.
- Build coordinator → INF template: generates · Expands driver package INF files.
- Build coordinator → Resource template: generates · Produces resource-script inputs.
- Build coordinator → MSM props: generates · Expands MSM packaging properties.
- MSM runtime → MSI glue: uses · MSM runtime code feeds MSI packaging logic.
- MSI glue → WiX definition: authors · MSI logic is consumed by WiX package definition.
- Build coordinator → Submission prep: drives · Build output is prepared for driver submission.
- Submission prep → File sign: uses · Submission packaging relies on file signing.
- Cross-sign → Microsoft signing: submits · Release artifacts are sent to Microsoft signing services.
- File sign → Microsoft signing: applies · Signing scripts apply certificates and timestamps.
- MSM prep → WiX: feeds · MSM preparation targets WiX-backed packaging.
- NSIS installer → NSIS: requires · Standalone installer depends on NSIS tooling.
- WiX definition → WiX: requires · Merge-module definition is compiled by WiX tooling.
- Build coordinator → WDK toolchain: requires · Builds against the Windows driver toolchain.
- Driver core → Windows NDIS: runs on · Kernel driver executes within the Windows NDIS boundary.
- Device state → tapinstall/devcon: installed by · Driver package is activated via external PnP tools.
- Adapter state → Windows NDIS: integrates with · Adapter lifecycle is governed by Windows networking.