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>
This commit is contained in:
Simon Rozman
Jason A. Donenfeld
parent
4ac9a6dcc6
commit
449876fdfd
130
api/adapter.h
130
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.
|
||||
*
|
||||
* @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
22
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);
|
||||
|
||||
@ -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" />
|
||||
|
||||
@ -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">
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "api.h"
|
||||
#include "wintun.h"
|
||||
#include <Windows.h>
|
||||
|
||||
#define WINTUN_HWID L"Wintun"
|
||||
|
||||
16
api/logger.h
16
api/logger.h
@ -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
|
||||
|
||||
@ -13,6 +13,7 @@
|
||||
#include "nci.h"
|
||||
#include "registry.h"
|
||||
#include "resource.h"
|
||||
#include "wintun.h"
|
||||
|
||||
#include <bcrypt.h>
|
||||
#include <cfgmgr32.h>
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "api.h"
|
||||
#include "wintun.h"
|
||||
|
||||
#define MAX_REG_PATH \
|
||||
256 /* Maximum registry path length \
|
||||
|
||||
@ -5,7 +5,7 @@
|
||||
|
||||
#pragma once
|
||||
|
||||
#include "api.h"
|
||||
#include "wintun.h"
|
||||
#include <Windows.h>
|
||||
|
||||
/**
|
||||
|
||||
211
api/wintun.h
Normal file
211
api/wintun.h
Normal 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);
|
||||
Loading…
Reference in New Issue
Block a user