FwpmFilterAdd0 (fwpmu.h)
La fonction FwpmFilterAdd0 ajoute un nouvel objet de filtre au système.
Syntaxe
DWORD FwpmFilterAdd0(
[in] HANDLE engineHandle,
[in] const FWPM_FILTER0 *filter,
[in, optional] PSECURITY_DESCRIPTOR sd,
[out, optional] UINT64 *id
);
Paramètres
[in] engineHandle
Type : HANDLE
Gérer pour une session ouverte sur le moteur de filtre. Appelez FwpmEngineOpen0 pour ouvrir une session sur le moteur de filtre.
[in] filter
Type : FWPM_FILTER0*
Objet de filtre à ajouter.
[in, optional] sd
Type : SECURITY_DESCRIPTOR
Informations de sécurité sur l’objet de filtre.
[out, optional] id
Type : UINT64*
Identificateur d’exécution de ce filtre.
Valeur retournée
Type : DWORD
| Code/valeur de retour | Description |
|---|---|
| ERROR_SUCCESS 0 |
Le filtre a été ajouté avec succès. |
| ERROR_INVALID_SECURITY_DESCR 0x8007053A |
La structure du descripteur de sécurité n’est pas valide. Ou bien, une condition de filtre contient un descripteur de sécurité au format absolu. |
| FWP_E_CALLOUT_NOTIFICATION_FAILED 0x80320037 |
L’appelant a ajouté un filtre de légende et la légende a renvoyé une erreur à partir de sa routine de notification. |
| code d’erreur FWP_E_* 0x80320001 0x80320039 |
Erreur spécifique à la plateforme de filtrage Windows (PAM). Pour plus d’informations, consultez Codes d’erreur PAM . |
| code d’erreur RPC_* 0x80010001 — 0x80010122 |
Échec de la communication avec le moteur de pare-feu distant ou local. |
Remarques
FwpmFilterAdd0 ajoute le filtre à la sous-couche spécifiée à chaque couche de filtrage dans le système.
Certains champs de la structure FWPM_FILTER0 sont attribués par le système, et non par l’appelant, et sont ignorés dans l’appel à FwpmFilterAdd0.
Si l’appelant fournit un descripteur de sécurité NULL , le système affecte un descripteur de sécurité par défaut.
Pour bloquer les connexions à des emplacements particuliers, ajoutez un filtre FWP_ACTION_BLOCK spécifiant l’adresse locale au niveau de la couche FWPM_LAYER_ALE_AUTH_CONNECT_V* , ou ajoutez un filtre FWP_ACTION_BLOCK sans spécifier l’adresse locale au niveau de la couche FWPM_LAYER_ALE_RESOURCE_ASSIGNMENT_V*.
Notes
Si une adresse locale est spécifiée au niveau de la couche d’affectation de ressources, une liaison implicite réussit, car l’adresse, le type d’adresse et le port peuvent revenir en tant que FWP_EMPTY.
La structure FWPM_FILTER0 peut étiqueter un filtre en tant que filtre au démarrage ou persistant. Les filtres au démarrage sont ajoutés au moteur de filtrage de base (BFE) au démarrage du pilote TCP/IP et sont supprimés une fois que le BFE a terminé l’initialisation. Des objets persistants sont ajoutés lorsque le BFE démarre.
Cette fonction ne peut pas être appelée à partir d’une transaction en lecture seule. Elle échoue avec FWP_E_INCOMPATIBLE_TXN. Pour plus d’informations sur les transactions, consultez Gestion des objets.
L’appelant a besoin des droits d’accès suivants :
- FWPM_ACTRL_ADD accès au conteneur du filtre
- FWPM_ACTRL_ADD_LINK accès au fournisseur (le cas échéant)
- FWPM_ACTRL_ADD_LINK accès à la couche applicable
- FWPM_ACTRL_ADD_LINK accès à la sous-couche applicable
- FWPM_ACTRL_ADD_LINK accès à la légende (le cas échéant)
- FWPM_ACTRL_ADD_LINK accès au contexte du fournisseur (le cas échéant).
Pour plus d’informations, consultez Access Control.
Pour ajouter un filtre qui fait référence à une légende, appelez les fonctions dans l’ordre suivant.
- Appelez FwpsCalloutRegister0 (documenté dans le Kit de pilotes Windows (WDK)) pour inscrire la légende auprès du moteur de filtre.
- Appelez FwpmCalloutAdd0 pour ajouter la légende au système.
- Appelez FwpmFilterAdd0 pour ajouter le filtre qui référence la légende au système.
Par défaut, les filtres qui font référence à des légendes qui ont été ajoutées mais qui n’ont pas encore été inscrites auprès du moteur de filtre sont traités comme des filtres de blocage.
FwpmFilterAdd0 est une implémentation spécifique de FwpmFilterAdd. Pour plus d’informations , voir PAM Version-Independent noms et Ciblage de versions spécifiques de Windows .
Exemples
L’exemple C++ suivant montre comment initialiser et ajouter un filtre à l’aide de FwpmFilterAdd0 qui
bloque spécifiquement le trafic sur IP V4 pour toutes les applications.
// Add filter to block traffic on IP V4 for all applications.
//
FWPM_FILTER0 fwpFilter;
FWPM_SUBLAYER0 fwpFilterSubLayer;
RtlZeroMemory(&fwpFilter, sizeof(FWPM_FILTER0));
fwpFilter.layerKey = FWPM_LAYER_ALE_AUTH_RECV_ACCEPT_V4;
fwpFilter.action.type = FWP_ACTION_BLOCK;
if (&fwpFilterSubLayer.subLayerKey != NULL)
fwpFilter.subLayerKey = fwpFilterSubLayer.subLayerKey;
fwpFilter.weight.type = FWP_EMPTY; // auto-weight.
fwpFilter.numFilterConditions = 0; // this applies to all application traffic
fwpFilter.displayData.name = L"Receive/Accept Layer Block";
fwpFilter.displayData.description = L"Filter to block all inbound connections.";
printf("Adding filter to block all inbound connections.\n");
result = FwpmFilterAdd0(engineHandle, &fwpFilter, NULL, NULL);
if (result != ERROR_SUCCESS)
printf("FwpmFilterAdd0 failed. Return value: %d.\n", result);
else
printf("Filter added successfully.\n");
Configuration requise
| Condition requise | Valeur |
|---|---|
| Client minimal pris en charge | Windows Vista [applications de bureau uniquement] |
| Serveur minimal pris en charge | Windows Server 2008 [applications de bureau uniquement] |
| Plateforme cible | Windows |
| En-tête | fwpmu.h |
| Bibliothèque | Fwpuclnt.lib |
| DLL | Fwpuclnt.dll |