OID_DOT11_PMKID_LIST

  • Article

Important  The Native 802.11 Wireless LAN interface is deprecated in Windows 10 and later. Please use the WLAN Device Driver Interface (WDI) instead. For more information about WDI, see WLAN Universal Windows driver model.

 

When set, the OID_DOT11_PMKID_LIST object identifier (OID) requests that the miniport driver flush its cache of pairwise master key identifiers (PMKIDs) and add the PMKID entries from the specified list to its cache.

When queried, this OID requests that the miniport driver return a list of the entries from its PMKID cache.

The 802.11 station uses the PMKID cache for preauthentication to access points that have enabled the Robust Security Network Association (RSNA) authentication algorithm. If the 802.11 station is associating or reassociating to a BSSID that matches an entry in its PMKID cache, the 802.11 station must use the PMKID data in the RSN information element (RSN IE) of its Association or Reassociation frame. For more information about the RSN IE, refer to Clause 7.3.2.25 of the 802.11i-2004 standard.

Note  Support for OID_DOT11_PMKID_LIST is mandatory if the 802.11 station supports PMKID caching for the DOT11_AUTH_ALGO_RSNA authentication algorithms. The miniport driver specifies its support for this authentication algorithm when OID_DOT11_SUPPORTED_UNICAST_ALGORITHM_PAIR or OID_DOT11_SUPPORTED_MULTICAST_ALGORITHM_PAIR are queried.

 

The data type for OID_DOT11_PMKID_LIST is the DOT11_PMKID_LIST structure.

    typedef struct DOT11_PMKID_LIST {
         NDIS_OBJECT_HEADER Header; 
         ULONG uNumOfEntries;
         ULONG uTotalNumOfEntries;
         DOT11_PMKID_ENTRY PMKIDs[1];
    } DOT11_PMKID_LIST, *PDOT11_PMKID_LIST;

This structure includes the following members:

Header
The type, revision, and size of the DOT11_PMKID_LIST structure. This member is formatted as an NDIS_OBJECT_HEADER structure.

The miniport driver must set the members of Header to the following values:

Type
This member must be set to NDIS_OBJECT_TYPE_DEFAULT.

Revision
This member must be set to DOT11_PMKID_LIST_REVISION_1.

Size
This member must be set to sizeof(DOT11_PMKID_LIST).

For more information about these members, see NDIS_OBJECT_HEADER.

uNumOfEntries
Number of entries in the PMKIDs array. A zero value for this member indicates an empty list of PMKID entries.

uTotalNumOfEntries
Maximum number of entries that the PMKIDs array can contain.

PMKIDs
The list of PMKID entries.

The data type for the elements of the PMKIDs array is the DOT11_PMKID_ENTRY structure.

typedef struct DOT11_PMKID_ENTRY {         
         DOT11_MAC_ADDRESS BSSID;
         DOT11_PMKID_VALUE PMKID; 
         ULONG uFlags;   
     } DOT11_PMKID_ENTRY, *PDOT11_PMKID_ENTRY;

This structure includes the following members:

BSSID
The BSSID of the target access point (AP) with which the 802.11 station associates. For more information about the data type of this member, see DOT11_MAC_ADDRESS.

PMKID
The PMKID value. For more information about the data type of this member, see DOT11_PMKID_VALUE.

The 802.11 station uses this value in the RSN information element (IE) of the 802.11 Association or Reassociation Request frames when connecting to the target BSSID.

Note  When OID_DOT11_PMKID_LIST is set, the entries in the PMKIDs array might be different than the entries in the list of PMKID candidates that the miniport driver specified when it made a previous NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST indication.

 

uFlags
This member is reserved and must be set to zero.

When OID_DOT11_PMKID_LIST is set, the miniport driver must do the following:

  • If the uNumOfEntries member has a value greater than the value of uPMKIDCacheSize that the driver previously returned through a query of OID_DOT11_EXTSTA_CAPABILITY, fail the set request by returning NDIS_STATUS_INVALID_LENGTH from its MiniportOidRequest function.

  • If the 802.11 station does not support the DOT11_AUTH_ALGO_RSNA authentication algorithm, fail the request by returning NDIS_STATUS_NOT_SUPPORTED from its MiniportOidRequest function.

  • If the 802.11 station has not enabled the DOT11_AUTH_ALGO_RSNA authentication algorithm, fail the request by returning NDIS_STATUS_INVALID_DATA from its MiniportOidRequest function.

  • Ignore any list entry that has a BSSID member that is not in the miniport driver's desired BSSID list. For more information about the desired BSSID list, see OID_DOT11_DESIRED_BSSID_LIST.

    If none of the entries in the list has a BSSID member that matches an entry in the miniport driver's desired BSSID list, the miniport driver must fail the request by returning NDIS_STATUS_INVALID_DATA from its MiniportOidRequest function.

  • Ensure that the value of the InformationBufferLength member of the MiniportOidRequest function's OidRequest parameter is at least the value returned by the following formula:

    FIELD_OFFSET(DOT11_PMKID_LIST, PMKIDs) + uNumOfEntries * sizeof(DOT11_PMKID_ENTRY))

When OID_DOT11_PMKID_LIST is queried, the miniport driver must verify that the InformationBuffer member of the MiniportOidRequest function's OidRequest parameter is large enough to return the entire DOT11_PMKID_LIST structure, including all entries in the PMKIDs array. The value of the InformationBufferLength member of the OidRequest parameter determines what the miniport driver must do, as the following list shows:

  • If the value of the InformationBufferLength member is less than the length, in bytes, of the entire DOT11_PMKID_LIST structure, the miniport driver must do the following:

    • Set the uNumOfEntries member to zero.

    • Set the uTotalNumOfEntries member to the number of entries in the PMKIDs array.

      For the OidRequest parameter, set the BytesWritten member to zero and the BytesNeeded member to the length, in bytes, of the entire DOT11_PMKID_LIST structure.

    • Fail the query request by returning NDIS_STATUS_BUFFER_OVERFLOW from its MiniportOidRequest function.

  • If the value of the InformationBufferLength member is greater than or equal to than the length, in bytes, of the entire DOT11_PMKID_LIST structure, the miniport driver must do the following to complete a successful query request:

    • For the DOT11_PMKID_LIST structure, set the uNumOfEntries and uTotalNumOfEntries members to the total number of entries in the PMKIDs array.

    • For the OidRequest parameter, set the BytesNeeded member to zero and the BytesWritten member to the length, in bytes, of the entire DOT11_PMKID_LIST structure. The miniport driver must also copy the entire DOT11_PMKID_LIST structure to the InformationBuffer member.

    • Return NDIS_STATUS_SUCCESS from its MiniportOidRequest function.

The default PMKID cache is an empty list with uNumEntries set to zero. The miniport driver must set this cache to its default if any of the following occurs:

  • The miniport driver's MiniportInitializeEx function is called.

  • A method request of OID_DOT11_RESET_REQUEST is made. The miniport driver must unconditionally set the PMKID cache to its default value whenever OID_DOT11_RESET_REQUEST is set.

Requirements

Version

Available in Windows Vista and later versions of the Windows operating systems.

Header

 Windot11.h (include Ndis.h)

See also

Native 802.11 Wireless LAN OIDs