FwpmFilterAdd0 function (fwpmu.h)

  • Artigo

A função FwpmFilterAdd0 adiciona um novo objeto de filtro ao sistema.

Sintaxe

DWORD FwpmFilterAdd0(
  [in]            HANDLE               engineHandle,
  [in]            const FWPM_FILTER0   *filter,
  [in, optional]  PSECURITY_DESCRIPTOR sd,
  [out, optional] UINT64               *id
);

Parâmetros

[in] engineHandle

Tipo: HANDLE

Manipule para uma sessão aberta para o mecanismo de filtro. Chame FwpmEngineOpen0 para abrir uma sessão para o mecanismo de filtro.

[in] filter

Tipo: FWPM_FILTER0*

O objeto de filtro a ser adicionado.

[in, optional] sd

Tipo: SECURITY_DESCRIPTOR

Informações de segurança sobre o objeto de filtro.

[out, optional] id

Tipo: UINT64*

O identificador de runtime para esse filtro.

Retornar valor

Tipo: DWORD

Valor/código retornado Descrição
ERROR_SUCCESS
0		 O filtro foi adicionado com êxito.
ERROR_INVALID_SECURITY_DESCR
0x8007053A		 A estrutura do descritor de segurança é inválida. Ou uma condição de filtro contém um descritor de segurança em formato absoluto.
FWP_E_CALLOUT_NOTIFICATION_FAILED
0x80320037		 O chamador adicionou um filtro de texto explicativo e o texto explicativo retornou um erro de sua rotina de notificação.
código de erro FWP_E_*
0x80320001 — 0x80320039		 Um erro específico da Plataforma de Filtragem do Windows (WFP). Consulte Códigos de erro WFP para obter detalhes.
código de erro RPC_*
0x80010001 — 0x80010122		 Falha ao se comunicar com o mecanismo de firewall remoto ou local.

Comentários

FwpmFilterAdd0 adiciona o filtro à subcamada especificada em cada camada de filtragem no sistema.

Alguns campos na estrutura FWPM_FILTER0 são atribuídos pelo sistema, não pelo chamador e são ignorados na chamada para FwpmFilterAdd0.

Se o chamador fornecer um descritor de segurança NULL , o sistema atribuirá um descritor de segurança padrão.

Para bloquear conexões com locais específicos, adicione um filtro FWP_ACTION_BLOCK especificando o endereço local na camada FWPM_LAYER_ALE_AUTH_CONNECT_V* ou adicione um filtro FWP_ACTION_BLOCK sem especificar o endereço local na camada FWPM_LAYER_ALE_RESOURCE_ASSIGNMENT_V*.

Observação

Se um endereço local for especificado na camada de atribuição de recursos, uma associação implícita terá êxito porque o endereço, o tipo de endereço e a porta podem voltar como FWP_EMPTY.

A estrutura FWPM_FILTER0 pode rotular um filtro como um filtro persistente ou de tempo de inicialização. Os filtros de tempo de inicialização são adicionados ao BFE (Mecanismo de Filtragem Base) quando o driver TCP/IP é iniciado e removidos depois que o BFE conclui a inicialização. Objetos persistentes são adicionados quando o BFE é iniciado.

Essa função não pode ser chamada de dentro de uma transação somente leitura. Ele falhará com FWP_E_INCOMPATIBLE_TXN. Consulte Gerenciamento de Objetos para obter mais informações sobre transações.

O chamador precisa dos seguintes direitos de acesso:

Consulte Controle de Acesso para obter mais informações.

Para adicionar um filtro que faça referência a um texto explicativo, invoque as funções na ordem a seguir.

  • Chame FwpsCalloutRegister0 (documentado no WDK (Kit de Driver do Windows) para registrar o texto explicativo com o mecanismo de filtro.
  • Chame FwpmCalloutAdd0 para adicionar o texto explicativo ao sistema.
  • Chame FwpmFilterAdd0 para adicionar o filtro que faz referência ao texto explicativo ao sistema.

Por padrão, os filtros que fazem referência a textos explicativos que foram adicionados, mas que ainda não foram registrados com o mecanismo de filtro, são tratados como Filtros de bloco.

FwpmFilterAdd0 é uma implementação específica do FwpmFilterAdd. Consulte Nomes de Version-Independent WFP e Direcionamento de versões específicas do Windows para obter mais informações.

Exemplos

O exemplo C++ a seguir mostra como inicializar e adicionar um filtro usando FwpmFilterAdd0 que
bloqueia especificamente o tráfego no IP V4 para todos os aplicativos.


// 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");

Requisitos

Requisito Valor
Cliente mínimo com suporte Windows Vista [somente aplicativos da área de trabalho]
Servidor mínimo com suporte Windows Server 2008 [somente aplicativos da área de trabalho]
Plataforma de Destino Windows
Cabeçalho fwpmu.h
Biblioteca Fwpuclnt.lib
DLL Fwpuclnt.dll

Confira também

FWPM_FILTER0

Funções de gerenciamento

Funções WFP