Mots clés dynamiques de pare-feu
Vous utilisez les API de mots clés dynamiques du pare-feu pour gérer les adresses de mot clé dynamiques dans Microsoft Defender Pare-feu. Une adresse de mot clé dynamique permet de 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.
Notes
Pour obtenir du 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 du pare-feu.
Opérations sur les adresses mot clé dynamiques
Avec les API de mots clés dynamiques du pare-feu, vous pouvez effectuer les opérations suivantes.
- Ajouter des adresses mot clé dynamiques
- Supprimer des adresses de mot clé dynamiques
- Énumérer les adresses mot clé dynamiques par ID ou par type
- Mettre à jour les adresses mot clé dynamiques
- S’abonner et gérer les notifications de changement d’adresse dynamiques mot clé
Vous trouverez 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 mot clé dynamiques, comme décrit dans les deux sections suivantes.
Résolution automatique des adresses mot clé dynamiques
Le premier type est AutoResolve, où le champ mot clé représente un nom pouvant être résolu 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 via le 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, c’est-à-dire un nom de domaine complet (FQDN) ou un nom d’hôte. Le champ adresses doit initialement avoir la valeur NULL pour ces objets. Ces objets n’auront pas leurs adresses IP conservées entre les cycles de démarrage, et vous devez réévaluer/réinsérer leurs adresses au cours du prochain cycle de démarrage.
Notes
AutoResolve dynamique mot clé objets d’adresse déclenchent des notifications sur FWAddDynamicKeywordAddress0 et FWDeleteDynamicKeywordAddress0, mais pas sur FWUpdateDynamicKeywordAddress0.
Adresses mot clé dynamiques non résolues
Le deuxième type n’est pas 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 champ mot clé ici est utilisé à des fins de gestion et peut être défini sur n’importe quelle chaîne. Le champ adresses doit être non NULL lors de la création. Les adresses de ces objets sont conservées entre les redémarrages.
Notes
Non-AutoResolve dynamique mot clé les objets d’adresse déclenchent des notifications sur FWAddDynamicKeywordAddress0, FWDeleteDynamicKeywordAddress0 et également FWUpdateDynamicKeywordAddress0.
En savoir plus sur les adresses de mot clé dynamiques
Toutes les adresses mot clé dynamiques doivent avoir un identificateur GUID unique pour les représenter.
L’API FwpmDynamicKeywordSubscribe0 transmet des notifications à un client lorsque les adresses dynamiques mot clé changent. Aucune charge utile fournie au client ne décrit 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 des API FWEnumDynamicKeywordAddressById0 ou FWEnumDynamicKeywordAddressesByType0 . Vous pouvez utiliser les différents indicateurs pour demander des notifications uniquement pour un sous-ensemble d’objets. Si vous n’utilisez aucun indicateur, des notifications de modification sont remises pour tous les objets.
Une règle de pare-feu peut utiliser des adresses 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 à la fois des adresses mot clé dynamiques et des plages d’adresses distantes statiquement définies. Un seul objet d’adresse dynamique mot clé peut être réutilisé dans plusieurs règles de pare-feu. Si une règle de pare-feu n’a pas d’adresses distantes configurées (autrement dit, configurées avec uniquement les objets AutoResolve qui n’ont pas encore été résolus), la règle ne sera pas appliquée. En outre, si une règle utilise plusieurs adresses dynamiques mot clé, la règle est appliquée à toutes les adresses actuellement résolues, même s’il existe d’autres objets qui ne sont pas encore résolus. Lorsqu’une adresse mot clé dynamique est mise à jour, les adresses distantes de tous les objets de règle associés sont également mises à jour.
Le système d’exploitation lui-même n’applique aucune dépendance entre une règle et une adresse mot clé dynamique. Cela signifie que l’un ou l’autre des objets peut être créé en premier, la règle peut référencer des ID d’adresse dynamiques mot clé qui n’existent pas encore (auquel cas, la règle ne sera pas appliquée). En outre, vous pouvez supprimer une adresse 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 une adresse 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 par la liste de main.cpp
code.
La plupart des exemples de code utilisent les bibliothèques d’implémentation Windows (WIL). Un moyen pratique d’installer WIL consiste à accéder à Visual Studio, puis à cliquer sur Project>Manage NuGet Packages...>Parcourez, 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.
Notes
Les types de pointeurs 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èleGetProcAddressLoadLibraryExW/ pour appeler ces fonctions, comme indiqué dans ces exemples de code.
Ajouter une adresse 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 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 mot clé dynamiques par ID
Cet exemple montre comment utiliser les fonctions FWEnumDynamicKeywordAddressById0 et 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 mot clé dynamiques par type
Cet exemple montre comment utiliser les fonctions FWEnumDynamicKeywordAddressesByType0 et 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 mot clé 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;
}
S’abonner et gérer les notifications de changement d’adresse dynamiques mot clé
Cet exemple montre comment utiliser les fonctions FwpmDynamicKeywordSubscribe0 et FwpmDynamicKeywordUnsubscribe0 , ainsi que 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,
¬ifyHandle);
if (error != ERROR_SUCCESS)
{
return error;
}
WaitForSingleObject(waitHandle, INFINITE);
// When client is ready to unsubscribe
error = FwpmDynamicKeywordUnsubscribe0(notifyHandle);
return error;
}