# openvpn/tap-windows6 architecture

> Architecture diagram of the GitHub repository openvpn/tap-windows6, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-04-07). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/openvpn/tap-windows6
- Repository: https://github.com/openvpn/tap-windows6

## Overview

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`](https://github.com/openvpn/tap-windows6/blob/master/buildtap.py) (Build coordinator), [`src/tapdrvr.c`](https://github.com/openvpn/tap-windows6/blob/master/src/tapdrvr.c) (Driver core), [`src/adapter.c`](https://github.com/openvpn/tap-windows6/blob/master/src/adapter.c) (Adapter state), [`src/device.c`](https://github.com/openvpn/tap-windows6/blob/master/src/device.c) (Device state)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_driver["Kernel driver"]
  node_tapdrvr["Driver core<br/>kernel entry<br/>[tapdrvr.c]"]
  node_device["Device state<br/>kernel module<br/>[device.c]"]
  node_adapter["Adapter state<br/>kernel module<br/>[adapter.c]"]
  node_txpath["TX path<br/>packet egress<br/>[txpath.c]"]
  node_rxpath["RX path<br/>packet ingress<br/>[rxpath.c]"]
  node_oidrequest["OID handling<br/>ndis control<br/>[oidrequest.c]"]
  node_dhcp["DHCP support<br/>network setup<br/>[dhcp.c]"]
  node_macinfo["MAC info<br/>adapter metadata<br/>[macinfo.c]"]
  node_configh["Config template<br/>header template<br/>[config.h.in]"]
  node_inf["INF template<br/>driver install template<br/>[OemVista.inf.in]"]
  node_resource["Resource template<br/>rc template<br/>[resource.rc]"]
end

subgraph group_build["Build orchestration"]
  node_buildtap["Build coordinator<br/>python build<br/>[buildtap.py]"]
  node_paths["Paths<br/>metadata<br/>[paths.py]"]
  node_version["Versioning<br/>macro input<br/>[version.m4]"]
end

subgraph group_package["Packaging"]
  node_msmprops["MSM props<br/>msi template<br/>[config.props.in]"]
  node_msmcore["MSM runtime<br/>installer dll<br/>[installation.c]"]
  node_msi["MSI glue<br/>packaging code<br/>[msi.c]"]
  node_wxs["WiX definition<br/>installer definition<br/>[installer.wxs]"]
  node_nsis["NSIS installer<br/>standalone installer<br/>[tap-windows6.nsi]"]
end

subgraph group_sign["Signing"]
  node_createsub["Submission prep<br/>powershell release"]
  node_crosssign["Cross-sign<br/>powershell release<br/>[Cross-Sign.ps1]"]
  node_signfile["File sign<br/>powershell release<br/>[Sign-File.ps1]"]
  node_preparemsm["MSM prep<br/>powershell release<br/>[Prepare-Msm.ps1]"]
end

subgraph group_external["External boundaries"]
  node_windows{{"Windows NDIS<br/>kernel boundary"}}
  node_wdk["WDK toolchain<br/>build toolchain"]
  node_pnputil["tapinstall/devcon<br/>deployment tool"]
  node_mssign["Microsoft signing<br/>release service"]
  node_nsistool["NSIS<br/>packaging tool"]
  node_wix["WiX<br/>packaging tool"]
end

node_buildtap -->|"builds"| node_tapdrvr
node_buildtap -->|"packages"| node_msmcore
node_buildtap -->|"packages"| node_nsis
node_buildtap -->|"signs"| node_crosssign
node_buildtap -->|"uses"| node_paths
node_buildtap -->|"expands"| node_version
node_tapdrvr -->|"controls"| node_device
node_tapdrvr -->|"controls"| node_adapter
node_adapter -->|"sends"| node_txpath
node_adapter -->|"receives"| node_rxpath
node_tapdrvr -->|"handles"| node_oidrequest
node_tapdrvr -->|"coordinates"| node_dhcp
node_adapter -->|"uses"| node_macinfo
node_buildtap -->|"generates"| node_configh
node_buildtap -->|"generates"| node_inf
node_buildtap -->|"generates"| node_resource
node_buildtap -->|"generates"| node_msmprops
node_msmcore -->|"uses"| node_msi
node_msi -->|"authors"| node_wxs
node_buildtap -->|"drives"| node_createsub
node_createsub -->|"uses"| node_signfile
node_crosssign -->|"submits"| node_mssign
node_signfile -->|"applies"| node_mssign
node_preparemsm -->|"feeds"| node_wix
node_nsis -->|"requires"| node_nsistool
node_wxs -->|"requires"| node_wix
node_buildtap -->|"requires"| node_wdk
node_tapdrvr -->|"runs on"| node_windows
node_device -->|"installed by"| node_pnputil
node_adapter -->|"integrates with"| node_windows

click node_buildtap "https://github.com/openvpn/tap-windows6/blob/master/buildtap.py"
click node_paths "https://github.com/openvpn/tap-windows6/blob/master/paths.py"
click node_version "https://github.com/openvpn/tap-windows6/blob/master/version.m4"
click node_tapdrvr "https://github.com/openvpn/tap-windows6/blob/master/src/tapdrvr.c"
click node_device "https://github.com/openvpn/tap-windows6/blob/master/src/device.c"
click node_adapter "https://github.com/openvpn/tap-windows6/blob/master/src/adapter.c"
click node_txpath "https://github.com/openvpn/tap-windows6/blob/master/src/txpath.c"
click node_rxpath "https://github.com/openvpn/tap-windows6/blob/master/src/rxpath.c"
click node_oidrequest "https://github.com/openvpn/tap-windows6/blob/master/src/oidrequest.c"
click node_dhcp "https://github.com/openvpn/tap-windows6/blob/master/src/dhcp.c"
click node_macinfo "https://github.com/openvpn/tap-windows6/blob/master/src/macinfo.c"
click node_configh "https://github.com/openvpn/tap-windows6/blob/master/src/config.h.in"
click node_inf "https://github.com/openvpn/tap-windows6/blob/master/src/OemVista.inf.in"
click node_resource "https://github.com/openvpn/tap-windows6/blob/master/src/resource.rc"
click node_msmprops "https://github.com/openvpn/tap-windows6/blob/master/msm/config.props.in"
click node_msmcore "https://github.com/openvpn/tap-windows6/blob/master/msm/installation.c"
click node_msi "https://github.com/openvpn/tap-windows6/blob/master/msm/msi.c"
click node_wxs "https://github.com/openvpn/tap-windows6/blob/master/msm/installer.wxs"
click node_nsis "https://github.com/openvpn/tap-windows6/blob/master/installer/tap-windows6.nsi"
click node_createsub "https://github.com/openvpn/tap-windows6/blob/master/sign/Create-DriverSubmission.ps1"
click node_crosssign "https://github.com/openvpn/tap-windows6/blob/master/sign/Cross-Sign.ps1"
click node_signfile "https://github.com/openvpn/tap-windows6/blob/master/sign/Sign-File.ps1"
click node_preparemsm "https://github.com/openvpn/tap-windows6/blob/master/sign/Prepare-Msm.ps1"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_tapdrvr,node_device,node_adapter,node_txpath,node_rxpath,node_oidrequest,node_dhcp,node_macinfo,node_configh,node_inf,node_resource toneBlue
class node_buildtap,node_paths,node_version toneAmber
class node_msmprops,node_msmcore,node_msi,node_wxs,node_nsis toneMint
class node_createsub,node_crosssign,node_signfile,node_preparemsm toneRose
class node_windows,node_wdk,node_pnputil,node_mssign,node_nsistool,node_wix toneIndigo
```

## Components

### Kernel driver

NDIS 6 TAP driver runtime and shared compile-time inputs.

- [Driver core](https://github.com/openvpn/tap-windows6/blob/master/src/tapdrvr.c): kernel entry · Driver entry point and top-level control logic. · `src/tapdrvr.c`
- [Device state](https://github.com/openvpn/tap-windows6/blob/master/src/device.c): kernel module · Device lifecycle and state management. · `src/device.c`
- [Adapter state](https://github.com/openvpn/tap-windows6/blob/master/src/adapter.c): kernel module · Network adapter lifecycle and attachment logic. · `src/adapter.c`
- [TX path](https://github.com/openvpn/tap-windows6/blob/master/src/txpath.c): packet egress · Transmit path for outbound packet flow. · `src/txpath.c`
- [RX path](https://github.com/openvpn/tap-windows6/blob/master/src/rxpath.c): packet ingress · Receive path for inbound packet flow. · `src/rxpath.c`
- [OID handling](https://github.com/openvpn/tap-windows6/blob/master/src/oidrequest.c): ndis control · NDIS OID query and control request handling. · `src/oidrequest.c`
- [DHCP support](https://github.com/openvpn/tap-windows6/blob/master/src/dhcp.c): network setup · DHCP-related TAP adapter behavior. · `src/dhcp.c`
- [MAC info](https://github.com/openvpn/tap-windows6/blob/master/src/macinfo.c): adapter metadata · Adapter address and identity helpers. · `src/macinfo.c`
- [Config template](https://github.com/openvpn/tap-windows6/blob/master/src/config.h.in): header template · Generated configuration header input. · `src/config.h.in`
- [INF template](https://github.com/openvpn/tap-windows6/blob/master/src/OemVista.inf.in): driver install template · Windows driver package INF template. · `src/OemVista.inf.in`
- [Resource template](https://github.com/openvpn/tap-windows6/blob/master/src/resource.rc): rc template · Driver resource template input. · `src/resource.rc`

### Build orchestration

Top-level build metadata and Python coordination.

- [Build coordinator](https://github.com/openvpn/tap-windows6/blob/master/buildtap.py): python build · Top-level driver build, sign, and package orchestrator. · `buildtap.py`
- [Paths](https://github.com/openvpn/tap-windows6/blob/master/paths.py): metadata · Build and packaging path metadata. · `paths.py`
- [Versioning](https://github.com/openvpn/tap-windows6/blob/master/version.m4): macro input · Version and release metadata used during generation. · `version.m4`

### Packaging

Standalone installer and MSI merge-module packaging paths.

- [MSM props](https://github.com/openvpn/tap-windows6/blob/master/msm/config.props.in): msi template · Merge-module build properties template. · `msm/config.props.in`
- [MSM runtime](https://github.com/openvpn/tap-windows6/blob/master/msm/installation.c): installer dll · Native code embedded into the merge module. · `msm/installation.c`
- [MSI glue](https://github.com/openvpn/tap-windows6/blob/master/msm/msi.c): packaging code · MSI-facing packaging logic for the merge module. · `msm/msi.c`
- [WiX definition](https://github.com/openvpn/tap-windows6/blob/master/msm/installer.wxs): installer definition · WiX authoring for the merge module package. · `msm/installer.wxs`
- [NSIS installer](https://github.com/openvpn/tap-windows6/blob/master/installer/tap-windows6.nsi): standalone installer · Standalone Windows installer script. · `installer/tap-windows6.nsi`

### Signing

Release signing and submission scripts.

- [Submission prep](https://github.com/openvpn/tap-windows6/blob/master/sign/Create-DriverSubmission.ps1): powershell release · Packages artifacts for driver submission. · `sign/Create-DriverSubmission.ps1`
- [Cross-sign](https://github.com/openvpn/tap-windows6/blob/master/sign/Cross-Sign.ps1): powershell release · Cross-signing and timestamping workflow. · `sign/Cross-Sign.ps1`
- [File sign](https://github.com/openvpn/tap-windows6/blob/master/sign/Sign-File.ps1): powershell release · Signs individual release artifacts. · `sign/Sign-File.ps1`
- [MSM prep](https://github.com/openvpn/tap-windows6/blob/master/sign/Prepare-Msm.ps1): powershell release · Prepares MSM artifacts for packaging. · `sign/Prepare-Msm.ps1`

### External boundaries

Toolchains, Windows driver stack, and signing services outside the repo.

- **Windows NDIS**: kernel boundary · Windows kernel networking and NDIS environment.
- **WDK toolchain**: build toolchain · Microsoft driver build toolchain and Visual Studio environment.
- **tapinstall/devcon**: deployment tool · External PnP installation utilities used for driver deployment.
- **Microsoft signing**: release service · Driver signing, attestation, and timestamping services.
- **NSIS**: packaging tool · External installer compiler for the standalone EXE.
- **WiX**: packaging tool · External MSI authoring/tooling used by merge-module packaging.

## Connections

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