Mots clés dynamiques du pare-feu

2025-03-13

Vous utilisez les API de mots clés dynamiques du pare-feu pour gérer adresses de mots clés dynamiques dans Microsoft Defender Firewall. Une adresse de mot clé dynamique est utilisée pour créer un ensemble d’adresses IP auxquelles une ou plusieurs règles de pare-feu peuvent faire référence. Les adresses de mots clés dynamiques prennent en charge IPv4 et IPv6.

Note

Pour obtenir le contenu de référence d’API pour les API introduites dans cette rubrique, consultez informations de référence sur les mots clés dynamiques pare-feu.

Opérations sur des adresses de mots clés dynamiques

Avec les API de mots clés dynamiques du pare-feu, vous pouvez effectuer les opérations suivantes.

Ajouter des adresses de mot clé dynamiques
Supprimer des adresses de mots clés dynamiques
Énumérer les adresses de mot clé dynamiques par ID ou par type
Mettre à jour les adresses de mots clés dynamiques
S’abonner aux notifications de modification de l’adresse de mot clé dynamique et les gérer

Il existe des exemples de code pour toutes ces opérations plus loin dans cette rubrique.

Une fois que vous avez ajouté une adresse de mot clé dynamique, elle persiste entre les redémarrages. Vous devez supprimer une adresse de mot clé dynamique une fois l’objet terminé.

Il existe deux classes d’adresses de mots clés dynamiques, comme décrit dans les deux sections suivantes.

Adresses de mots clés dynamiques AutoResolve

Le premier type est résolution automatique, où le champ mot clé représente un nom résolvable et les adresses IP ne sont pas définies lors de la création.

Ces objets sont conçus pour que leurs adresses IP soient résolues automatiquement. Autrement dit, pas par le biais d’un administrateur au moment de la création de l’objet ; ni par le biais du système d’exploitation lui-même. Un composant en dehors du service de pare-feu doit effectuer la résolution d’adresses IP pour ces objets et les mettre à jour de manière appropriée. L’implémentation d’un tel composant est en dehors de l’étendue de ce contenu.

Une adresse de mot clé dynamique est indiquée comme étant AutoResolve en définissant l’indicateur FW_DYNAMIC_KEYWORD_ADDRESS_FLAGS_AUTO_RESOLVE dans l’objet lors de l’appel de la fonction FWAddDynamicKeywordAddress0. Le champ mot clé doit être utilisé pour représenter la valeur en cours de résolution, autrement dit, un nom de domaine complet (FQDN) ou un nom d’hôte. Les adresses champ doivent initialement avoir la valeur NULL pour ces objets. Ces objets n’ont pas leurs adresses IP persistantes au cours des cycles de démarrage, et vous devez réévaluer/réappliquer leurs adresses au cours du prochain cycle de démarrage.

Note

Les objets d’adresse de mot clé dynamique AutoResolve déclenchent des notifications sur FWAddDynamicKeywordAddress0 et FWDeleteDynamicKeywordAddress0, mais pas FWUpdateDynamicKeywordAddress0.

Adresses de mots clés dynamiques non AutoResolve

Le deuxième type est non-AutoResolve, où le champ mot clé est n’importe quelle chaîne et les adresses sont définies au moment de la création.

Ces objets sont utilisés pour stocker un ensemble d’adresses IP, de sous-réseaux ou de plages. Le mot clé champ ici est utilisé pour la commodité de gestion, et il peut être défini sur n’importe quelle chaîne. Les adresses champ doivent être non NULL lors de la création. Les adresses de ces objets sont conservées entre les redémarrages.

Note

Les objets d’adresse de mot clé dynamique non AutoResolve déclenchent des notifications sur FWAddDynamicKeywordAddress0, FWDeleteDynamicKeywordAddress0, ainsi que FWUpdateDynamicKeywordAddress0.

En savoir plus sur les adresses de mots clés dynamiques

Toutes les adresses de mot clé dynamique doivent avoir un GUID unique identificateur pour les représenter.

L’API FwpmDynamicKeywordSubscribe0 remet des notifications à un client lorsque les adresses de mot clé dynamiques changent. Il n’existe aucune charge utile fournie au client décrivant exactement ce qui a changé sur le système. Si vous avez besoin de savoir quels objets ont changé, vous devez interroger l’état actuel des objets sur le système à l’aide de la FWEnumDynamicKeywordAddressById0 ou FWEnumDynamicKeywordAddressesByType0 API. Vous pouvez utiliser les différents indicateurs pour demander des notifications uniquement pour un sous-ensemble d’objets. Si vous n’utilisez aucun indicateur, les notifications de modification sont remises pour tous les objets.

Une règle de pare-feu peut utiliser des adresses de mot clé dynamiques au lieu de définir explicitement des adresses IP pour sa condition d’adresse distante. Une règle de pare-feu peut utiliser des adresses de mots clés dynamiques et des plages d’adresses distantes définies statiquement. Un seul objet d’adresse de mot clé dynamique peut être réutilisé dans plusieurs règles de pare-feu. Si une règle de pare-feu n’a pas configuré d’adresses distantes (autrement dit, configurées uniquement avec des objets AutoResolve qui n’ont pas encore été résolus), la règle n’est pas appliquée. En outre, si une règle utilise plusieurs adresses de mots clés dynamiques, la règle est appliquée pour toutes les adresses actuellement résolues, même s’il existe d’autres objets qui ne sont pas encore résolus. Lorsqu’une adresse de mot clé dynamique est mise à jour, tous les objets de règle associés ont également leurs adresses distantes mises à jour.

Le système d’exploitation lui-même n’applique aucune dépendance entre une règle et une adresse de mot clé dynamique. Cela signifie que l’un ou l’autre objet peut être créé en premier : la règle peut référencer des ID d’adresse de mot clé dynamique qui n’existent pas encore (auquel cas, la règle n’est pas appliquée). En outre, vous pouvez supprimer une adresse de mot clé dynamique même si elle est utilisée par une règle de pare-feu. Cette rubrique décrit comment un administrateur peut configurer des règles pour utiliser l’adresse de mot clé dynamique.

Exemples de code

Pour essayer chacun de ces exemples de code, commencez par lancer Visual Studio et créez un projet basé sur le modèle de projet application console. Vous pouvez simplement remplacer le contenu de main.cpp par la liste de codes.

La plupart des exemples de code utilisent le bibliothèques d’implémentation Windows (WIL). Un moyen pratique d’installer WIL consiste à accéder à Visual Studio, cliquez sur Project>Gérer les packages NuGet...>Parcourir, tapez ou collez microsoft.Windows.ImplementationLibrary dans la zone de recherche, sélectionnez l’élément dans les résultats de recherche, puis cliquez sur Installer pour installer le package pour ce projet.

Note

Les types de pointeur pour les fonctions gratuites NetFw sont publiés via NetFw.h, mais une bibliothèque de liens statiques n’est pas publiée. Utilisez le modèle LoadLibraryExW/GetProcAddress pour appeler ces fonctions, comme illustré dans ces exemples de code.

Ajouter une adresse de mot clé dynamique

Cet exemple montre comment utiliser la fonction 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;
}

Supprimer une adresse de mot clé dynamique

Cet exemple montre comment utiliser la fonction 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;
}

Énumérer et libérer des adresses de mots clés dynamiques par ID

Cet exemple montre comment utiliser les fonctions FWEnumDynamicKeywordAddressById0 et fonctions 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;
}

Énumérer et libérer des adresses de mots clés dynamiques par type

Cet exemple montre comment utiliser les fonctions FWEnumDynamicKeywordAddressesByType0 et fonctions 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;
}

Mettre à jour les adresses de mots clés dynamiques

Cet exemple montre comment utiliser la fonction 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;
}

Cet exemple montre comment utiliser les fonctions FwpmDynamicKeywordSubscribe0 et FwpmDynamicKeywordUnsubscribe0 et le rappel 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;
}

informations de référence sur les mots clés dynamiques du pare-feu

Partager via

Mots clés dynamiques du pare-feu

Opérations sur des adresses de mots clés dynamiques

Adresses de mots clés dynamiques AutoResolve

Adresses de mots clés dynamiques non AutoResolve

En savoir plus sur les adresses de mots clés dynamiques

Exemples de code

Ajouter une adresse de mot clé dynamique

Supprimer une adresse de mot clé dynamique

Énumérer et libérer des adresses de mots clés dynamiques par ID

Énumérer et libérer des adresses de mots clés dynamiques par type

Mettre à jour les adresses de mots clés dynamiques

S’abonner aux notifications de modification de l’adresse de mot clé dynamique et les gérer

Rubriques connexes

Commentaires

Ressources supplémentaires