防火墙动态关键字

项目
06/13/2023

使用防火墙动态关键字 API 来管理Microsoft Defender防火墙中的动态关键字 (keyword) 地址。动态关键字地址用于创建一组 IP 地址，一个或多个防火墙规则可以引用这些 IP 地址。动态关键字地址支持 IPv4 和 IPv6。

注意

有关本主题中介绍的 API 的 API 参考内容，请参阅防火墙动态关键字参考。

对动态关键字 (keyword) 地址的操作

使用防火墙动态关键字 API，可以执行以下操作。

添加动态关键字 (keyword) 地址
删除动态关键字 (keyword) 地址
按 ID 或类型枚举动态关键字 (keyword) 地址
更新动态关键字 (keyword) 地址
订阅和处理动态关键字 (keyword) 地址更改通知

本主题后面提供了所有这些操作的代码示例。

添加动态关键字 (keyword) 地址后，它会在重启后保留。使用完对象后，必须删除动态关键字 (keyword) 地址。

有两类动态关键字 (keyword) 地址，如下两部分所述。

自动解决动态关键字 (keyword) 地址

第一种类型是 AutoResolve，其中关键字 (keyword) 字段表示可解析的名称，并且 IP 地址在创建时未定义。

这些对象旨在自动解析其 IP 地址。也就是说，不是在创建对象时通过管理员;也不通过操作系统 (操作系统) 自身。防火墙服务外部的组件必须为这些对象执行 IP 地址解析，并相应地更新它们。此类组件的实现超出了此内容的范围。

在调用 FWAddDynamicKeywordAddress0 函数时，通过在对象中设置FW_DYNAMIC_KEYWORD_ADDRESS_FLAGS_AUTO_RESOLVE标志，将动态关键字 (keyword) 地址指示为 AutoResolve。 应使用关键字 (keyword) 字段来表示要解析的值，即 FQDN () 或主机名的完全限定域名。对于这些对象，地址字段最初必须为 NULL。这些对象不会在整个启动周期中保留其 IP 地址，应在下一个启动周期中重新评估/重新填充其地址。

注意

AutoResolve 动态关键字 (keyword) 地址对象在 FWAddDynamicKeywordAddress0 和 FWDeleteDynamicKeywordAddress0 上触发通知，但不触发 FWUpdateDynamicKeywordAddress0 上的通知。

非自动重新解决动态关键字 (keyword) 地址

第二种类型是非 AutoResolve，其中关键字 (keyword) 字段为任意字符串，地址在创建时定义。

这些对象用于存储一组 IP 地址、子网或范围。此处的关键字 (keyword) 字段用于方便管理，并且可以将其设置为任何字符串。 创建地址字段时必须为非 NULL。这些对象的地址在重新启动后保留。

注意

非 AutoResolve 动态关键字 (keyword) 地址对象在 FWAddDynamicKeywordAddress0、FWDeleteDynamicKeywordAddress0 和 FWUpdateDynamicKeywordAddress0 上触发通知。

有关动态关键字 (keyword) 地址的详细信息

所有动态关键字 (keyword) 地址都必须具有唯一的 GUID 标识符来表示这些地址。

当动态关键字 (keyword) 地址发生更改时，FwpmDynamicKeywordSubscribe0 API 会向客户端发送通知。没有有效负载传递到客户端，无法准确描述系统上发生的变化。如果需要知道哪些对象发生了更改，则应使用 FWEnumDynamicKeywordAddressById0 或 FWEnumDynamicKeywordAddressesByType0 API 查询系统上对象的当前状态。可以使用各种标志仅请求一部分对象的通知。如果不使用标志，则会为所有对象传递更改通知。

防火墙规则可以使用动态关键字 (keyword) 地址，而不是为其远程地址条件显式定义 IP 地址。防火墙规则可以使用动态关键字 (keyword) 地址和静态定义的远程地址范围。单个动态关键字 (keyword) 地址对象可以跨多个防火墙规则重用。如果防火墙规则没有任何配置的远程地址， (，仅配置了尚未) 解析的 AutoResolve 对象，则不会强制实施该规则。此外，如果一个规则使用多个动态关键字 (keyword) 地址，则将对当前已解析的所有地址强制实施该规则，即使还有尚未解析的其他对象也是如此。更新动态关键字 (keyword) 地址时，所有关联的规则对象也将更新其远程地址。

操作系统 (OS) 本身不会在规则和动态关键字 (keyword) 地址之间强制实施任何依赖项。这意味着可以先创建任一对象，该规则可以引用尚不存在的动态关键字 (keyword) 地址 ID (在这种情况下，不会在) 强制执行该规则。此外，即使防火墙规则正在使用动态关键字 (keyword) 地址，也可以删除该地址。本主题概述管理员如何配置规则以使用动态关键字 (keyword) 地址。

代码示例

若要尝试每个代码示例，请先启动 Visual Studio，然后基于 控制台应用 项目模板创建新项目。只需将的内容 main.cpp 替换为代码列表。

大多数代码示例使用 WINDOWS 实现库 (WIL) 。安装 WIL 的一种便捷方法是转到 Visual Studio，单击“ 项目管理>NuGet 包...”>在搜索框中键入或粘贴 Microsoft.Windows.ImplementationLibrary ，在搜索结果中选择该项，然后单击“ 安装 ”为该项目安装包。

注意

NetFw 自由函数的指针类型通过 NetFw.h发布，但不会发布静态链接库。使用 LoadLibraryExW/GetProcAddress 模式调用这些函数，如这些代码示例所示。

添加动态关键字 (keyword) 地址

此示例演示如何使用 FWAddDynamicKeywordAddress0 函数。

// main.cpp in a Console App project.
#include <windows.h>
#include <wil/resource.h>
#include <netfw.h>

// {26548e4f-d486-4a1d-8a1d-22b0837cd53b}
const GUID DYNAMIC_KEYWORD_ADDRESS_ID_1 =
{
    0x26548e4f,
    0xd486,
    0x4a1d,
    {0x8a,0x1d,0x22,0xb0,0x83,0x7c,0xd5,0x3b}
};

// {e9d5c993-9369-4a96-8228-9c5c37aac51a}
const GUID DYNAMIC_KEYWORD_ADDRESS_ID_2 =
{
    0xe9d5c993,
    0x9369,
    0x4a96,
    {0x82,0x28,0x9c,0x5c,0x37,0xaa,0xc5,0x1a}
};

int main()
{
    DWORD error = ERROR_SUCCESS;
    PFN_FWADDDYNAMICKEYWORDADDRESS0 addDynamicKeywordAddressFn = NULL;
    HMODULE moduleHandle = NULL;
    FW_DYNAMIC_KEYWORD_ADDRESS0 autoResolveKeywordAddress = { 0 };
    FW_DYNAMIC_KEYWORD_ADDRESS0 nonAutoResolveKeywordAddress = { 0 };

    // Use LoadLibrary/GetProcAddress to invoke this function
    moduleHandle = LoadLibraryExW(L"firewallapi.dll", NULL, LOAD_LIBRARY_SEARCH_SYSTEM32);
    auto onExitFreeModuleHandle = wil::scope_exit([&]
        {
            if (moduleHandle)
            {
                FreeLibrary(moduleHandle);
            }
        });

    if (moduleHandle != NULL)
    {
        addDynamicKeywordAddressFn = (PFN_FWADDDYNAMICKEYWORDADDRESS0)GetProcAddress(
            moduleHandle,
            "FWAddDynamicKeywordAddress0"
        );
    }

    if (addDynamicKeywordAddressFn == NULL)
    {
        error = GetLastError();
        return error;
    }

    // Ensure the ID is unique. If not, the add operation will fail with ERROR_ALREADY_EXISTS
    // and you should invoke the API with a new ID.

    // Initialize and add an auto-resolve dynamic keyword address
    autoResolveKeywordAddress.id = DYNAMIC_KEYWORD_ADDRESS_ID_1;
    autoResolveKeywordAddress.keyword = L"bing.com";
    autoResolveKeywordAddress.flags = FW_DYNAMIC_KEYWORD_ADDRESS_FLAGS_AUTO_RESOLVE;
    // must be NULL as we have set the auto resolve flag
    autoResolveKeywordAddress.addresses = NULL;

    error = addDynamicKeywordAddressFn(&autoResolveKeywordAddress);
    if (error != ERROR_SUCCESS)
    {
        return error;
    }

    // Initialize and add a non auto-resolve dynamic keyword address
    nonAutoResolveKeywordAddress.id = DYNAMIC_KEYWORD_ADDRESS_ID_2;
    nonAutoResolveKeywordAddress.keyword = L"myServerIPs";
    nonAutoResolveKeywordAddress.flags = 0;
    nonAutoResolveKeywordAddress.addresses = L"10.0.0.5,20.0.0.0/24,30.0.0.0-40.0.0.0";

    error = addDynamicKeywordAddressFn(&nonAutoResolveKeywordAddress);
    if (error != ERROR_SUCCESS)
    {
        return error;
    }
    return error;
}

删除动态关键字 (keyword) 地址

此示例演示如何使用 FWDeleteDynamicKeywordAddress0 函数。

// main.cpp in a Console App project.
#include <windows.h>
#include <wil/resource.h>
#include <netfw.h>

// {26548e4f-d486-4a1d-8a1d-22b0837cd53b}
const GUID DYNAMIC_KEYWORD_ADDRESS_ID_1 =
{
    0x26548e4f,
    0xd486,
    0x4a1d,
    {0x8a,0x1d,0x22,0xb0,0x83,0x7c,0xd5,0x3b}
};


// {e9d5c993-9369-4a96-8228-9c5c37aac51a}
const GUID DYNAMIC_KEYWORD_ADDRESS_ID_2 =
{
    0xe9d5c993,
    0x9369,
    0x4a96,
    {0x82,0x28,0x9c,0x5c,0x37,0xaa,0xc5,0x1a}
};

int main()
{
    DWORD error = ERROR_SUCCESS;
    PFN_FWDELETEDYNAMICKEYWORDADDRESS0 deleteDynamicKeywordAddressFn = NULL;
    HMODULE moduleHandle = NULL;

    // Use LoadLibrary/GetProcAddress to invoke this function
    moduleHandle = LoadLibraryExW(L"firewallapi.dll", NULL, LOAD_LIBRARY_SEARCH_SYSTEM32);
    auto onExitFreeModuleHandle = wil::scope_exit([&]
        {
            if (moduleHandle)
            {
                FreeLibrary(moduleHandle);
            }
        });


    if (moduleHandle != NULL)
    {
        deleteDynamicKeywordAddressFn = (PFN_FWDELETEDYNAMICKEYWORDADDRESS0)GetProcAddress(
            moduleHandle,
            "FWDeleteDynamicKeywordAddress0"
        );
    }

    if (deleteDynamicKeywordAddressFn == NULL)
    {
        error = GetLastError();
        return error;
    }

    // Invoke the functions
    error = deleteDynamicKeywordAddressFn(DYNAMIC_KEYWORD_ADDRESS_ID_1);
    if (error != ERROR_SUCCESS)
    {
        wprintf(L"Failed to delete object with ID 1, err=[%d]", error);
    }

    error = deleteDynamicKeywordAddressFn(DYNAMIC_KEYWORD_ADDRESS_ID_2);
    if (error != ERROR_SUCCESS)
    {
        wprintf(L"Failed to delete object with ID 2, err=[%d]", error);
    }

    return error;
}

按 ID 枚举和释放动态关键字 (keyword) 地址

此示例演示如何使用 FWEnumDynamicKeywordAddressById0 和 FWFreeDynamicKeywordAddressData0 函数。

// main.cpp in a Console App project.
#include <windows.h>
#include <wil/resource.h>
#include <netfw.h>

// {26548e4f-d486-4a1d-8a1d-22b0837cd53b}
const GUID DYNAMIC_KEYWORD_ADDRESS_ID_1 =
{
    0x26548e4f,
    0xd486,
    0x4a1d,
    {0x8a,0x1d,0x22,0xb0,0x83,0x7c,0xd5,0x3b}
};

// {e9d5c993-9369-4a96-8228-9c5c37aac51a}
const GUID DYNAMIC_KEYWORD_ADDRESS_ID_2 =
{
    0xe9d5c993,
    0x9369,
    0x4a96,
    {0x82,0x28,0x9c,0x5c,0x37,0xaa,0xc5,0x1a}
};

int main()
{
    DWORD error = ERROR_SUCCESS;
    PFN_FWENUMDYNAMICKEYWORDADDRESSBYID0 enumDynamicKeywordAddressByIdFn = NULL;
    PFN_FWFREEDYNAMICKEYWORDADDRESSDATA0 freeDynamicKeywordAddressDataFn = NULL;
    HMODULE moduleHandle = NULL;
    PFW_DYNAMIC_KEYWORD_ADDRESS_DATA0 dynamicKeywordAddressData = NULL;

    // Use LoadLibrary/GetProcAddress to invoke this function
    moduleHandle = LoadLibraryExW(L"firewallapi.dll", NULL, LOAD_LIBRARY_SEARCH_SYSTEM32);
    auto onExitFreeModuleHandle = wil::scope_exit([&]
        {
            if (moduleHandle)
            {
                FreeLibrary(moduleHandle);
            }
        });

    if (moduleHandle != NULL)
    {
        enumDynamicKeywordAddressByIdFn = (PFN_FWENUMDYNAMICKEYWORDADDRESSBYID0)GetProcAddress(
            moduleHandle,
            "FWEnumDynamicKeywordAddressById0"
        );
        freeDynamicKeywordAddressDataFn = (PFN_FWFREEDYNAMICKEYWORDADDRESSDATA0)GetProcAddress(
            moduleHandle,
            "FWFreeDynamicKeywordAddressData0"
        );
    }

    if (enumDynamicKeywordAddressByIdFn == NULL ||
        freeDynamicKeywordAddressDataFn == NULL)
    {
        error = GetLastError();
        return error;
    }

    error = enumDynamicKeywordAddressByIdFn(
        DYNAMIC_KEYWORD_ADDRESS_ID_1,
        &dynamicKeywordAddressData
    );
    if (error != ERROR_SUCCESS)
    {
        return error;
    }

    if (dynamicKeywordAddressData != NULL)
    {
        // Process this dynamic keyword address
    }

    // Free the dynamic keyword address
    freeDynamicKeywordAddressDataFn(dynamicKeywordAddressData);
    return error;
}

按类型枚举和释放动态关键字 (keyword) 地址

此示例演示如何使用 FWEnumDynamicKeywordAddressesByType0 和 FWFreeDynamicKeywordAddressData0 函数。

// main.cpp in a Console App project.
#include <windows.h>
#include <wil/resource.h>
#include <netfw.h>

int main()
{
    DWORD error = ERROR_SUCCESS;
    PFN_FWENUMDYNAMICKEYWORDADDRESSESBYTYPE0 enumDynamicKeywordAddressesByTypeFn = NULL;
    PFN_FWFREEDYNAMICKEYWORDADDRESSDATA0 freeDynamicKeywordAddressDataFn = NULL;
    HMODULE moduleHandle = NULL;

    PFW_DYNAMIC_KEYWORD_ADDRESS_DATA0 dynamicKeywordAddressData = NULL;
    PFW_DYNAMIC_KEYWORD_ADDRESS_DATA0 currDynamicKeywordAddressData = NULL;

    // Use LoadLibrary/GetProcAddress to invoke this function
    moduleHandle = LoadLibraryExW(L"firewallapi.dll", NULL, LOAD_LIBRARY_SEARCH_SYSTEM32);
    auto onExitFreeModuleHandle = wil::scope_exit([&]
        {
            if (moduleHandle)
            {
                FreeLibrary(moduleHandle);
            }
        });

    if (moduleHandle != NULL)
    {
        enumDynamicKeywordAddressesByTypeFn = (PFN_FWENUMDYNAMICKEYWORDADDRESSESBYTYPE0)GetProcAddress(
            moduleHandle,
            "FWEnumDynamicKeywordAddressesByType0"
        );
        freeDynamicKeywordAddressDataFn = (PFN_FWFREEDYNAMICKEYWORDADDRESSDATA0)GetProcAddress(
            moduleHandle,
            "FWFreeDynamicKeywordAddressData0"
        );
    }

    if (enumDynamicKeywordAddressesByTypeFn == NULL ||
        freeDynamicKeywordAddressDataFn == NULL)
    {
        error = GetLastError();
        return error;
    }

    // Invoke enum for ALL dynamic keyword addresses
    error = enumDynamicKeywordAddressesByTypeFn(
        FW_DYNAMIC_KEYWORD_ADDRESS_ENUM_FLAGS_ALL,
        &dynamicKeywordAddressData
    );
    if (error != ERROR_SUCCESS)
    {
        return error;
    }

    currDynamicKeywordAddressData = dynamicKeywordAddressData;
    while (currDynamicKeywordAddressData != NULL)
    {
        // Process this dynamic keyword address

        // iterate to the next one in the list
        currDynamicKeywordAddressData = currDynamicKeywordAddressData->next;
    }

    // Free the dynamic keyword addresses
    freeDynamicKeywordAddressDataFn(dynamicKeywordAddressData);

    return error;
}

更新动态关键字 (keyword) 地址

此示例演示如何使用 FWUpdateDynamicKeywordAddress0 函数。

// main.cpp in a Console App project.
#include <windows.h>
#include <wil/resource.h>
#include <netfw.h>

// {26548e4f-d486-4a1d-8a1d-22b0837cd53b}
const GUID DYNAMIC_KEYWORD_ADDRESS_ID_1 =
{
    0x26548e4f,
    0xd486,
    0x4a1d,
    {0x8a,0x1d,0x22,0xb0,0x83,0x7c,0xd5,0x3b}
};

int main()
{
    DWORD error = ERROR_SUCCESS;
    PFN_FWUPDATEDYNAMICKEYWORDADDRESS0 updateDynamicKeywordAddressFn = NULL;
    HMODULE moduleHandle = NULL;
    BOOL appendToCurrentAddresses = TRUE;

    // Use LoadLibrary/GetProcAddress to invoke this function
    moduleHandle = LoadLibraryExW(L"firewallapi.dll", NULL, LOAD_LIBRARY_SEARCH_SYSTEM32);
    auto onExitFreeModuleHandle = wil::scope_exit([&]
        {
            if (moduleHandle)
            {
                FreeLibrary(moduleHandle);
            }
        });

    if (moduleHandle != NULL)
    {
        updateDynamicKeywordAddressFn = (PFN_FWUPDATEDYNAMICKEYWORDADDRESS0)GetProcAddress(
            moduleHandle,
            "FWUpdateDynamicKeywordAddress0"
        );
    }

    if (updateDynamicKeywordAddressFn == NULL)
    {
        error = GetLastError();
        return error;
    }

    // Invoke the function
    error = updateDynamicKeywordAddressFn(
        DYNAMIC_KEYWORD_ADDRESS_ID_1,
        L"20.0.0.5",
        appendToCurrentAddresses);
    return error;
}

此示例演示如何使用 FwpmDynamicKeywordSubscribe0 和 FwpmDynamicKeywordUnsubscribe0 函数，以及 FWPM_DYNAMIC_KEYWORD_CALLBACK0 回调。

// main.cpp in a Console App project.
#include <windows.h>
#include <netfw.h>
#include <fwpmu.h>
#pragma comment(lib, "Fwpuclnt")

void CALLBACK TestCallback(_Inout_ VOID* /*pNotification*/, _Inout_ VOID* pContext)
{
    DWORD error = ERROR_SUCCESS;
    PFN_FWENUMDYNAMICKEYWORDADDRESSESBYTYPE0 enumDynamicKeywordAddressesByTypeFn = NULL;
    PFN_FWFREEDYNAMICKEYWORDADDRESSDATA0 freeDynamicKeywordAddressDataFn = NULL;
    HMODULE moduleHandle = NULL;

    PFW_DYNAMIC_KEYWORD_ADDRESS_DATA0 dynamicKeywordAddressData = NULL;
    PFW_DYNAMIC_KEYWORD_ADDRESS_DATA0 currDynamicKeywordAddressData = NULL;
    HANDLE* waitHandle = (HANDLE*)pContext;

    // Use LoadLibrary/GetProcAddress to invoke this function
    moduleHandle = LoadLibraryW(L"firewallapi.dll");
    if (moduleHandle != NULL)
    {
        enumDynamicKeywordAddressesByTypeFn = (PFN_FWENUMDYNAMICKEYWORDADDRESSESBYTYPE0)GetProcAddress(
            moduleHandle,
            "FWEnumDynamicKeywordAddressesByType0"
        );
        freeDynamicKeywordAddressDataFn = (PFN_FWFREEDYNAMICKEYWORDADDRESSDATA0)GetProcAddress(
            moduleHandle,
            "FWFreeDynamicKeywordAddressData0"
        );
    }

    if (enumDynamicKeywordAddressesByTypeFn == NULL ||
        freeDynamicKeywordAddressDataFn == NULL)
    {
        return;
    }

    // Invoke enum for ALL AutoResolve dynamic keyword addresses
    error = enumDynamicKeywordAddressesByTypeFn(
        FW_DYNAMIC_KEYWORD_ADDRESS_ENUM_FLAGS_AUTO_RESOLVE,
        &dynamicKeywordAddressData
    );
    if (error != ERROR_SUCCESS)
    {
        return;
    }

    currDynamicKeywordAddressData = dynamicKeywordAddressData;
    while (currDynamicKeywordAddressData != NULL)
    {
        // Process this dynamic keyword address

        currDynamicKeywordAddressData = currDynamicKeywordAddressData->next;
    }

    // Free the dynamic keyword addresses
    freeDynamicKeywordAddressDataFn(dynamicKeywordAddressData);

    SetEvent(*waitHandle);
}

int main()
{
    DWORD error = ERROR_SUCCESS;
    HANDLE notifyHandle;
    HANDLE waitHandle;

    waitHandle = CreateEventW(
        NULL,
        TRUE,
        FALSE,
        L"subscriptionWaitEvent"
    );


    // Subscribe for change notifications
    error = FwpmDynamicKeywordSubscribe0(
        FWPM_NOTIFY_ADDRESSES_AUTO_RESOLVE,
        TestCallback,
        &waitHandle,
        &notifyHandle);
    if (error != ERROR_SUCCESS)
    {
        return error;
    }

    WaitForSingleObject(waitHandle, INFINITE);

    // When client is ready to unsubscribe
    error = FwpmDynamicKeywordUnsubscribe0(notifyHandle);

    return error;
}

防火墙动态关键字参考

防火墙动态关键字

对动态关键字 (keyword) 地址的操作

自动解决动态关键字 (keyword) 地址

非自动重新解决动态关键字 (keyword) 地址

有关动态关键字 (keyword) 地址的详细信息

代码示例

添加动态关键字 (keyword) 地址

删除动态关键字 (keyword) 地址

按 ID 枚举和释放动态关键字 (keyword) 地址

按类型枚举和释放动态关键字 (keyword) 地址

更新动态关键字 (keyword) 地址

反馈

反馈

其他资源

防火墙动态关键字

对动态关键字 (keyword) 地址的操作

自动解决动态关键字 (keyword) 地址

非自动重新解决动态关键字 (keyword) 地址

有关动态关键字 (keyword) 地址的详细信息

代码示例

添加动态关键字 (keyword) 地址

删除动态关键字 (keyword) 地址

按 ID 枚举和释放动态关键字 (keyword) 地址

按类型枚举和释放动态关键字 (keyword) 地址

更新动态关键字 (keyword) 地址

订阅和处理动态关键字 (keyword) 地址更改通知

相关主题

反馈

反馈

其他资源