Hesham/wintun
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

api: introduce wintun.h

Browse Source 
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>
This commit is contained in:
Simon Rozman 2020-10-17 15:11:34 +02:00 committed by Jason A. Donenfeld
parent 4ac9a6dcc6
commit 449876fdfd
10 changed files with 231 additions and 159 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

130
api/adapter.h
View File

@ -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.
*
* @param Adapter Adapter handle obtained with WintunGetAdapter or WintunCreateAdapter.
* @copydoc WINTUN_FREE_ADAPTER_FUNC
*/
void WINAPI
WintunFreeAdapter(_In_ WINTUN_ADAPTER *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
*/
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.
* @copydoc WINTUN_CREATE_ADAPTER_FUNC
*/
WINTUN_STATUS WINAPI
WintunCreateAdapter(
@ -201,31 +108,8 @@ WintunCreateAdapter(
_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.
* @copydoc WINTUN_DELETE_ADAPTER_FUNC
*/
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);

22
api/api.h
View File

@ -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);

1
api/api.vcxproj
View File

@ -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" />

3
api/api.vcxproj.filters
View File

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

2
api/driver.h
View File

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

16
api/logger.h
View File

@ -5,20 +5,14 @@
#pragma once
#include <Windows.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);
#include "wintun.h"
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

1
api/pch.h
View File

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

2
api/registry.h
View File

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

2
api/resource.h
View File

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

211
api/wintun.h Normal file
View File

@ -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);