Edit

Managing Port Policies

  • Article

Hyper-V extensible switch filtering and forwarding extensions can be provisioned with the properties of standard and custom port properties. Once provisioned, these extensions enforce the policies when they filter packets obtained on the extensible switch ingress data path. For more information about these policies, see Port Policies.

The Hyper-V extensible switch interface uses the following object identifiers (OIDs) to provision filtering and forwarding extensions with the properties of standard and custom port policies:

OID_SWITCH_PORT_PROPERTY_ADD
This OID set request is issued by the protocol edge of the extensible switch to notify underlying extensions of the addition of a property at the WMI management layer. The InformationBuffer of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_SWITCH_PORT_PROPERTY_PARAMETERS structure.

Note  Custom port properties are specified by an NDIS_SWITCH_PORT_PROPERTY_TYPE enumeration value of NdisSwitchPortPropertyTypeCustom. Standard port properties are specified by an NDIS_SWITCH_PORT_PROPERTY_TYPE enumeration value of NdisSwitchPortPropertyTypeSecurity, NdisSwitchPortPropertyTypeVlan, and NdisSwitchPortPropertyTypeProfile.

OID_SWITCH_PORT_PROPERTY_UPDATE
This OID set request is issued by the protocol edge of the extensible switch to inform underlying extensions of the update of a property at the WMI management layer. The InformationBuffer of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_SWITCH_PORT_PROPERTY_PARAMETERS structure.

OID_SWITCH_PORT_PROPERTY_DELETE
This OID set request is issued by the protocol edge of the extensible switch to inform underlying extensions of the deletion of a property at the WMI management layer. The InformationBuffer of the NDIS_OID_REQUEST structure contains a pointer to an NDIS_SWITCH_PORT_PROPERTY_DELETE_PARAMETERS structure.

OID_SWITCH_PORT_PROPERTY_ENUM
This OID method request is sent by the extension to query the underlying miniport edge of the extensible switch about the currently configured properties for a specified port on the extensible switch. The InformationBuffer of the NDIS_OID_REQUEST structure contains a pointer to a buffer. This buffer contains the following data:

Note  The extension must not originate OID set requests of OID_SWITCH_PORT_PROPERTY_ADD. OID_SWITCH_PORT_PROPERTY_UPDATE, or OID_SWITCH_PORT_PROPERTY_DELETE.

The extensible switch extension must follow these guidelines when it handles an OID set request of OID_SWITCH_PORT_PROPERTY_ADD, OID_SWITCH_PORT_PROPERTY_UPDATE, or OID_SWITCH_PORT_PROPERTY_DELETE:

  • The extension must not modify the NDIS_SWITCH_PORT_PROPERTY_PARAMETERS or NDIS_SWITCH_PORT_PROPERTY_DELETE_PARAMETERS structure that is associated with the OID request.

  • The extension must handle these OID requests if the extension manages the property. Depending on the OID request, the extension must inspect the following members of the NDIS_SWITCH_PORT_PROPERTY_PARAMETERS or NDIS_SWITCH_PORT_PROPERTY_DELETE_PARAMETERS structures to determine whether it manages the port property:

    • The PropertyType member. This member specifies the type of the port property. Custom port properties have a PropertyType member value of NdisSwitchPortPropertyTypeCustom. Standard port properties have other property type values. For example, standard VLAN port policies have a property type value of NdisSwitchPortPropertyTypeVlan.

    • The PropertyId member. This member specifies a proprietary GUID value for a custom port property. This GUID value is created by the independent software vendor (ISV) who also defines the format of the custom extensible switch property.

      Note  The extension must ignore this member for standard port policies.

  • The extension must handle an OID_SWITCH_PORT_PROPERTY_UPDATE set request if the extension was previously provisioned with a port property that matches the following members of the NDIS_SWITCH_PROPERTY_PARAMETERS structure:

    • The PropertyType member.

    • The PropertyId member.

      Note  The extension must ignore this member for standard port policies.

    • The PropertyVersion member. This member specifies the version of the port property that the extension was provisioned with.

    • The PropertyInstanceId member. This member specifies the instance of the port property that the extension was provisioned with.

  • The filtering or forwarding extension can veto the addition or update of a port policy that it manages. The extension does this by completing the OID request with STATUS_DATA_NOT_ACCEPTED.

    Note  Capturing extensions must not veto the addition or update of a port policy. Instead, it must forward the OID request down the extensible switch control path.

  • A forwarding extension can fail the OID request for standard port properties that it does not support or if the property conflicts with its own policy configuration. In this case, the extension must complete the OID request and return the appropriate NDIS status code to report the failure.

  • If the extension successfully handles the OID set request for a standard port policy, it must not complete the OID request and must forward it down the extensible switch control path.

  • If the capturing or filtering extension successfully handles the OID set request for a custom port policy, it must not complete the OID request and must forward it down the extensible switch control path.

    If the forwarding extension successfully handles the OID set request for a custom port policy, it must complete the OID request and return the appropriate NDIS_STATUS_Xxx value.

  • If the extension does not complete the OID set request, it must call NdisFOidRequest to forward the OID request down the extensible switch driver stack. In this case, the extensions should monitor the completion status of the OID to detect whether an underlying extension has failed the OID request.