api: introduce wintun.h

The SDK header for deployment containing datatype and function
declarations for use by C/C++ clients.

As we shall not distribute MSVC wintun.lib files, making clients need to
use GetProcAddress(), this file contains function type declarations
rather then __declspec(dllimport) function declarations.

Signed-off-by: Simon Rozman <simon@rozman.si>

api/adapter.h

@@ -5,11 +5,9 @@
 
 #pragma once
 
-#include "api.h"
+#include "wintun.h"
 #include <SetupAPI.h>
-#include <IPExport.h>
 
-#define MAX_POOL 256
 #define MAX_INSTANCE_ID MAX_PATH /* TODO: Is MAX_PATH always enough? */
 
 typedef struct _SP_DEVINFO_DATA_LIST
@@ -80,6 +78,9 @@ AdapterInit();
 void
 AdapterCleanup();
 
+/**
+ * Wintun adapter descriptor.
+ */
 typedef struct _WINTUN_ADAPTER
 {
     GUID CfgInstanceID;
@@ -90,107 +91,13 @@ typedef struct _WINTUN_ADAPTER
 } WINTUN_ADAPTER;
 
 /**
- * Releases Wintun adapter resources.
+ * @copydoc WINTUN_FREE_ADAPTER_FUNC
- *
- * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter.
  */
 void WINAPI
 WintunFreeAdapter(_In_ WINTUN_ADAPTER *Adapter);
 
 /**
- * Finds a Wintun adapter by its name.
+ * @copydoc WINTUN_CREATE_ADAPTER_FUNC
- *
- * @param Pool          Name of the adapter pool.
- *
- * @param Name          Adapter name.
- *
- * @param Adapter       Pointer to a handle to receive the adapter handle. Must be released with WintunFreeAdapter.
- *
- * @return ERROR_SUCCESS on success; ERROR_FILE_NOT_FOUND if adapter with given name is not found; ERROR_ALREADY_EXISTS
- * if adapter is found but not a Wintun-class or not a member of the pool; Win32 error code otherwise
- */
-WINTUN_STATUS WINAPI
-WintunGetAdapter(
-    _In_z_count_c_(MAX_POOL) const WCHAR *Pool,
-    _In_z_count_c_(MAX_ADAPTER_NAME) const WCHAR *Name,
-    _Out_ WINTUN_ADAPTER **Adapter);
-
-/**
- * Returns the name of the Wintun adapter.
- *
- * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter
- *
- * @param Name          Pointer to a string to receive adapter name
- *
- * @return ERROR_SUCCESS on success; Win32 error code otherwise.
- */
-WINTUN_STATUS WINAPI
-WintunGetAdapterName(_In_ const WINTUN_ADAPTER *Adapter, _Out_cap_c_(MAX_ADAPTER_NAME) WCHAR *Name);
-
-/**
- * Sets name of the Wintun adapter.
- *
- * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter
- *
- * @param Name          Adapter name
- *
- * @return ERROR_SUCCESS on success; Win32 error code otherwise.
- */
-WINTUN_STATUS WINAPI
-WintunSetAdapterName(_In_ const WINTUN_ADAPTER *Adapter, _In_z_count_c_(MAX_ADAPTER_NAME) const WCHAR *Name);
-
-/**
- * Returns the GUID of the adapter.
- *
- * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter
- *
- * @param Guid          Pointer to GUID to receive adapter ID.
- */
-void WINAPI
-WintunGetAdapterGUID(_In_ const WINTUN_ADAPTER *Adapter, _Out_ GUID *Guid);
-
-/**
- * Returns the LUID of the adapter.
- *
- * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter
- *
- * @param Luid          Pointer to LUID to receive adapter LUID.
- */
-void WINAPI
-WintunGetAdapterLUID(_In_ const WINTUN_ADAPTER *Adapter, _Out_ LUID *Luid);
-
-/**
- * Returns a handle to the adapter device object.
- *
- * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter.
- *
- * @param Handle        Pointer to receive the adapter device object handle. Must be released with CloseHandle.
- *
- * @return ERROR_SUCCESS on success; Win32 error code otherwise.
- */
-WINTUN_STATUS WINAPI
-WintunGetAdapterDeviceObject(_In_ const WINTUN_ADAPTER *Adapter, _Out_ HANDLE *Handle);
-
-/**
- * Creates a Wintun adapter.
- *
- * @param Pool          Name of the adapter pool.
- *
- * @param Name          The requested name of the adapter.
- *
- * @param RequestedGUID  The GUID of the created network adapter, which then influences NLA generation
- *                      deterministically. If it is set to NULL, the GUID is chosen by the system at random, and hence
- *                      a new NLA entry is created for each new adapter. It is called "requested" GUID because the API
- *                      it uses is completely undocumented, and so there could be minor interesting complications with
- *                      its usage.
- *
- * @param Adapter       Pointer to a handle to receive the adapter handle. Must be released with
- *                      WintunFreeAdapter.
- *
- * @param RebootRequired  Pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot. Must be
- *                      initialised to FALSE manually before this function is called.
- *
- * @return ERROR_SUCCESS on success; Win32 error code otherwise.
  */
 WINTUN_STATUS WINAPI
 WintunCreateAdapter(
@@ -201,31 +108,8 @@ WintunCreateAdapter(
     _Inout_ BOOL *RebootRequired);
 
 /**
- * Deletes a Wintun adapter.
+ * @copydoc WINTUN_DELETE_ADAPTER_FUNC
- *
- * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter.
- *
- * @param RebootRequired  Pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot. Must be
- *                      initialised to FALSE manually before this function is called.
- *
- * @return ERROR_SUCCESS on success or the adapter was not found; Win32 error code otherwise.
  */
 WINTUN_STATUS WINAPI
 WintunDeleteAdapter(_In_ const WINTUN_ADAPTER *Adapter, _Inout_ BOOL *RebootRequired);
 
-typedef BOOL(CALLBACK *WINTUN_ENUM_FUNC)(_In_ const WINTUN_ADAPTER *Adapter, _In_ LPARAM Param);
-
-/**
- * Enumerates all Wintun adapters.
- *
- * @param Pool          Name of the adapter pool.
- *
- * @param Func          Callback function. To continue enumeration, the callback function must return TRUE; to stop
- *                      enumeration, it must return FALSE.
- *
- * @param Param         An application-defined value to be passed to the callback function.
- *
- * @return ERROR_SUCCESS on success; Win32 error code otherwise.
- */
-WINTUN_STATUS WINAPI
-WintunEnumAdapters(_In_z_count_c_(MAX_POOL) const WCHAR *Pool, _In_ WINTUN_ENUM_FUNC Func, _In_ LPARAM Param);

api/api.h

@@ -14,27 +14,5 @@
 #    define _L(x) __L(x)
 #endif
 
-typedef _Return_type_success_(return == ERROR_SUCCESS) DWORD WINTUN_STATUS;
-
 extern HINSTANCE ResourceModule;
 extern SECURITY_ATTRIBUTES *SecurityAttributes;
-
-/**
- * Returns the version of the Wintun driver and NDIS system currently loaded.
- *
- * @param DriverVersionMaj  Pointer to a DWORD to receive the Wintun driver major version number.
- *
- * @param DriverVersionMin  Pointer to a DWORD to receive the Wintun driver minor version number.
- *
- * @param NdisVersionMaj  Pointer to a DWORD to receive the NDIS major version number.
- *
- * @param NdisVersionMin  Pointer to a DWORD to receive the NDIS minor version number.
- *
- * @return ERROR_SUCCESS on success; Win32 error code otherwise.
- */
-WINTUN_STATUS WINAPI
-WintunGetVersion(
-    _Out_ DWORD *DriverVersionMaj,
-    _Out_ DWORD *DriverVersionMin,
-    _Out_ DWORD *NdisVersionMaj,
-    _Out_ DWORD *NdisVersionMin);

api/api.vcxproj

@@ -202,6 +202,7 @@
     <ClInclude Include="pch.h" />
     <ClInclude Include="registry.h" />
     <ClInclude Include="resource.h" />
+    <ClInclude Include="wintun.h" />
   </ItemGroup>
   <ItemGroup>
     <ClCompile Include="api.c" />

api/api.vcxproj.filters

@@ -52,6 +52,9 @@
     <ClInclude Include="adapter.h">
       <Filter>Header Files</Filter>
     </ClInclude>
+    <ClInclude Include="wintun.h">
+      <Filter>Header Files</Filter>
+    </ClInclude>
   </ItemGroup>
   <ItemGroup>
     <ClCompile Include="api.c">

api/driver.h

@@ -5,7 +5,7 @@
 
 #pragma once
 
-#include "api.h"
+#include "wintun.h"
 #include <Windows.h>
 
 #define WINTUN_HWID L"Wintun"

api/logger.h

@@ -5,20 +5,14 @@
 
 #pragma once
 
-#include <Windows.h>
+#include "wintun.h"
-
-typedef enum _WINTUN_LOGGER_LEVEL
-{
-    WINTUN_LOG_INFO = 0,
-    WINTUN_LOG_WARN,
-    WINTUN_LOG_ERR
-} WINTUN_LOGGER_LEVEL;
-
-typedef BOOL(CALLBACK *WINTUN_LOGGER_FUNC)(_In_ WINTUN_LOGGER_LEVEL Level, _In_z_ const WCHAR *Message);
 
 extern WINTUN_LOGGER_FUNC Logger;
 
-VOID WINAPI
+/**
+ * @copydoc WINTUN_SET_LOGGER_FUNC
+ */
+void WINAPI
 WintunSetLogger(_In_ WINTUN_LOGGER_FUNC NewLogger);
 
 _Post_equals_last_error_ DWORD

api/pch.h

@@ -13,6 +13,7 @@
 #include "nci.h"
 #include "registry.h"
 #include "resource.h"
+#include "wintun.h"
 
 #include <bcrypt.h>
 #include <cfgmgr32.h>

api/registry.h

@@ -5,7 +5,7 @@
 
 #pragma once
 
-#include "api.h"
+#include "wintun.h"
 
 #define MAX_REG_PATH \
     256 /* Maximum registry path length \

api/resource.h

@@ -5,7 +5,7 @@
 
 #pragma once
 
-#include "api.h"
+#include "wintun.h"
 #include <Windows.h>
 
 /**

api/wintun.h

@@ -0,0 +1,211 @@
+/* SPDX-License-Identifier: GPL-2.0
+ *
+ * Copyright (C) 2018-2020 WireGuard LLC. All Rights Reserved.
+ */
+
+#pragma once
+
+#include <Windows.h>
+#include <IPExport.h>
+
+typedef _Return_type_success_(return == ERROR_SUCCESS) DWORD WINTUN_STATUS;
+
+/**
+ * A handle representing Wintun adapter
+ */
+typedef void *WINTUN_ADAPTER_HANDLE;
+
+#define MAX_POOL 256
+
+/**
+ * Creates a Wintun adapter.
+ *
+ * @param Pool          Name of the adapter pool.
+ *
+ * @param Name          The requested name of the adapter.
+ *
+ * @param RequestedGUID  The GUID of the created network adapter, which then influences NLA generation
+ *                      deterministically. If it is set to NULL, the GUID is chosen by the system at random, and hence
+ *                      a new NLA entry is created for each new adapter. It is called "requested" GUID because the API
+ *                      it uses is completely undocumented, and so there could be minor interesting complications with
+ *                      its usage.
+ *
+ * @param Adapter       Pointer to a handle to receive the adapter handle. Must be released with
+ *                      WintunFreeAdapter.
+ *
+ * @param RebootRequired  Pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot. Must be
+ *                      initialised to FALSE manually before this function is called.
+ *
+ * @return ERROR_SUCCESS on success; Win32 error code otherwise.
+ */
+typedef WINTUN_STATUS(WINAPI *WINTUN_CREATE_ADAPTER_FUNC)(
+    _In_z_count_c_(MAX_POOL) const WCHAR *Pool,
+    _In_z_count_c_(MAX_ADAPTER_NAME) const WCHAR *Name,
+    _In_opt_ const GUID *RequestedGUID,
+    _Out_ WINTUN_ADAPTER_HANDLE *Adapter,
+    _Inout_ BOOL *RebootRequired);
+
+/**
+ * Deletes a Wintun adapter.
+ *
+ * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter.
+ *
+ * @param RebootRequired  Pointer to a boolean flag to be set to TRUE in case SetupAPI suggests a reboot. Must be
+ *                      initialised to FALSE manually before this function is called.
+ *
+ * @return ERROR_SUCCESS on success or the adapter was not found; Win32 error code otherwise.
+ */
+typedef WINTUN_STATUS(
+    WINAPI *WINTUN_DELETE_ADAPTER_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _Inout_ BOOL *RebootRequired);
+
+/**
+ * Called by WintunEnumAdapters for each adapter in the pool.
+ *
+ * @param Adapter       Adapter handle.
+ *
+ * @param Param         An application-defined value passed to the WintunEnumAdapters.
+ *
+ * @return Non-zero to continue iterating adapters; zero to stop.
+ */
+typedef BOOL(CALLBACK *WINTUN_ENUM_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _In_ LPARAM Param);
+
+/**
+ * Enumerates all Wintun adapters.
+ *
+ * @param Pool          Name of the adapter pool.
+ *
+ * @param Func          Callback function. To continue enumeration, the callback function must return TRUE; to stop
+ *                      enumeration, it must return FALSE.
+ *
+ * @param Param         An application-defined value to be passed to the callback function.
+ *
+ * @return ERROR_SUCCESS on success; Win32 error code otherwise.
+ */
+typedef WINTUN_STATUS(WINAPI *WINTUN_ENUM_ADAPTERS_FUNC)(
+    _In_z_count_c_(MAX_POOL) const WCHAR *Pool,
+    _In_ WINTUN_ENUM_FUNC Func,
+    _In_ LPARAM Param);
+
+/**
+ * Releases Wintun adapter resources.
+ *
+ * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter.
+ */
+typedef void(WINAPI *WINTUN_FREE_ADAPTER_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter);
+
+/**
+ * Finds a Wintun adapter by its name.
+ *
+ * @param Pool          Name of the adapter pool.
+ *
+ * @param Name          Adapter name.
+ *
+ * @param Adapter       Pointer to a handle to receive the adapter handle. Must be released with WintunFreeAdapter.
+ *
+ * @return ERROR_SUCCESS on success; ERROR_FILE_NOT_FOUND if adapter with given name is not found; ERROR_ALREADY_EXISTS
+ * if adapter is found but not a Wintun-class or not a member of the pool; Win32 error code otherwise
+ */
+typedef WINTUN_STATUS(WINAPI *WINTUN_GET_ADAPTER_FUNC)(
+    _In_z_count_c_(MAX_POOL) const WCHAR *Pool,
+    _In_z_count_c_(MAX_ADAPTER_NAME) const WCHAR *Name,
+    _Out_ WINTUN_ADAPTER_HANDLE *Adapter);
+
+/**
+ * Returns a handle to the adapter device object.
+ *
+ * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter.
+ *
+ * @param Handle        Pointer to receive the adapter device object handle. Must be released with CloseHandle.
+ *
+ * @return ERROR_SUCCESS on success; Win32 error code otherwise.
+ */
+typedef WINTUN_STATUS(
+    WINAPI *WINTUN_GET_ADAPTER_DEVICE_OBJECT_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _Out_ HANDLE *Handle);
+
+/**
+ * Returns the GUID of the adapter.
+ *
+ * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter
+ *
+ * @param Guid          Pointer to GUID to receive adapter ID.
+ */
+typedef void(WINAPI *WINTUN_GET_ADAPTER_GUID_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _Out_ GUID *Guid);
+
+/**
+ * Returns the LUID of the adapter.
+ *
+ * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter
+ *
+ * @param Luid          Pointer to LUID to receive adapter LUID.
+ */
+typedef void(WINAPI *WINTUN_GET_ADAPTER_LUID_FUNC)(_In_ WINTUN_ADAPTER_HANDLE Adapter, _Out_ LUID *Luid);
+
+/**
+ * Returns the name of the Wintun adapter.
+ *
+ * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter
+ *
+ * @param Name          Pointer to a string to receive adapter name
+ *
+ * @return ERROR_SUCCESS on success; Win32 error code otherwise.
+ */
+typedef WINTUN_STATUS(WINAPI *WINTUN_GET_ADAPTER_NAME_FUNC)(
+    _In_ WINTUN_ADAPTER_HANDLE Adapter,
+    _Out_cap_c_(MAX_ADAPTER_NAME) WCHAR *Name);
+
+/**
+ * Returns the version of the Wintun driver and NDIS system currently loaded.
+ *
+ * @param DriverVersionMaj  Pointer to a DWORD to receive the Wintun driver major version number.
+ *
+ * @param DriverVersionMin  Pointer to a DWORD to receive the Wintun driver minor version number.
+ *
+ * @param NdisVersionMaj  Pointer to a DWORD to receive the NDIS major version number.
+ *
+ * @param NdisVersionMin  Pointer to a DWORD to receive the NDIS minor version number.
+ *
+ * @return ERROR_SUCCESS on success; Win32 error code otherwise.
+ */
+typedef WINTUN_STATUS(WINAPI *WINTUN_GET_VERSION_FUNC)(
+    _Out_ DWORD *DriverVersionMaj,
+    _Out_ DWORD *DriverVersionMin,
+    _Out_ DWORD *NdisVersionMaj,
+    _Out_ DWORD *NdisVersionMin);
+
+/**
+ * Sets name of the Wintun adapter.
+ *
+ * @param Adapter       Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter
+ *
+ * @param Name          Adapter name
+ *
+ * @return ERROR_SUCCESS on success; Win32 error code otherwise.
+ */
+typedef WINTUN_STATUS(WINAPI *WINTUN_SET_ADAPTER_NAME_FUNC)(
+    _In_ WINTUN_ADAPTER_HANDLE Adapter,
+    _In_z_count_c_(MAX_ADAPTER_NAME) const WCHAR *Name);
+
+typedef enum _WINTUN_LOGGER_LEVEL
+{
+    WINTUN_LOG_INFO = 0,
+    WINTUN_LOG_WARN,
+    WINTUN_LOG_ERR
+} WINTUN_LOGGER_LEVEL;
+
+/**
+ * Called by internal logger to report diagnostic messages
+ *
+ * @param Level         Message level.
+ *
+ * @param Message       Message text.
+ *
+ * @return Anything - return value is ignored.
+ */
+typedef BOOL(CALLBACK *WINTUN_LOGGER_FUNC)(_In_ WINTUN_LOGGER_LEVEL Level, _In_z_ const WCHAR *Message);
+
+/**
+ * Sets logger callback function.
+ *
+ * @param NewLogger     Pointer to callback function to use as a new global logger.
+ */
+typedef void(WINAPI *WINTUN_SET_LOGGER_FUNC)(_In_ WINTUN_LOGGER_FUNC NewLogger);