NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST

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.

A miniport driver uses the NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST indication to request pairwise master key identifiers (PMKIDs) for basic service set (BSS) identifiers (BSSIDs) that the 802.11 station can potentially roam to. When roaming, the 802.11 station uses the PMKID value to pre-authenticate with an access point (AP).

The data type for this indication is the DOT11_PMKID_CANDIDATE_LIST_PARAMETERS structure:

    typedef struct DOT11_PMKID_CANDIDATE_LIST_PARAMETERS {
         NDIS_OBJECT_HEADER Header;
         ULONG uCandidateListSize;
         ULONG uCandidateListOffset;
    } DOT11_PMKID_CANDIDATE_LIST_PARAMETERS,   *PDOT11_PMKID_CANDIDATE_LIST_PARAMETERS;
  

The DOT11_PMKID_CANDIDATE_LIST_PARAMETERS structure contains the following members:

Header
The type, revision, and size of the DOT11_PMKID_CANDIDATE_LIST_PARAMETERS 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_CANDIDATE_LIST_PARAMETERS_REVISION_1.

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

For more information about these members, see NDIS_OBJECT_HEADER.

uCandidateListSize
The size, in bytes, of the list of BSSID candidates for PMKIDs.

uCandidateListOffset
The offset of the BSSID candidate list.

This offset is relative to the start of the buffer that contains the DOT11_PMKID_CANDIDATE_LIST_PARAMETERS structure.

Each entry in the BSSID candidate list is formatted as a DOT11_BSSID_CANDIDATE structure:

typedef struct DOT11_BSSID_CANDIDATE {         
         DOT11_MAC_ADDRESS BSSID;
         ULONG uFlags;   
     } DOT11_BSSID_CANDIDATE, *PDOT11_BSSID_CANDIDATE;

The DOT11_BSSID_CANDIDATE structure contains the following members:

BSSID
The BSSID of the AP for which the miniport driver is requesting a PMKID.

BSSID candidates that are specified by the BSSID member must:

• Be in the service set identifier (SSID) that the 802.11 station is currently associated with.

• Match an entry in the desired BSSID list that is defined by the Extensible Station (ExtSTA) msDot11DesiredBSSIDList MIB object. For more information about this MIB object, see OID_DOT11_DESIRED_BSSID_LIST.

• Be a member of the SSID with which the 802.11 station is currently associated and authenticated with.

Note  The miniport can only request a PMKID for the AP with which the 802.11 station is currently associated.

uFlags
A bitmask that specifies pre-authentication attributes of the BSSID candidates. This bitmask is defined as follows:

DOT11_PMKID_CANDIDATE_PREAUTH_ENABLED
The BSSID candidate supports pre-authentication. The BSSID candidate advertises its support for pre-authentication by setting the Pre-authentication Subfield of the RSN Capabilities field to one in the 802.11 Beacon and Probe Response frames that the BSSID candidate transmits.

If the DOT11_PMKID_CANDIDATE_PREAUTH_ENABLED bit is set, the 802.1X supplicant will initiate the 802.1X pre-authentication with the specified BSSID candidate.

If the DOT11_PMKID_CANDIDATE_PREAUTH_ENABLED bit is not set, pre-authentication cannot be performed with the BSSID candidate. However, the 802.1X supplicant can update the driver's PMKID cache by using the PMK from a prior association with the BSSID candidate.

Pre-authentication applies to infrastructure networks that support Robust Security Network Association (RSNA) authentication. For more information about RSNA authentication, refer to Clause 8.4.6 of the IEEE 802.11i-2004 standard.

The miniport driver calls NdisMIndicateStatusEx to make an NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST indication, and must pass a pointer to an NDIS_STATUS_INDICATION structure through the StatusIndication parameter. When making this indication, the driver must set the following members of the NDIS_STATUS_INDICATION structure:

• StatusCode must be set to NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST.

• StatusBuffer must be set to the address of a DOT11_LINK_QUALITY_PARAMETERS structure.

• StatusBufferSize must be set to sizeof(DOT11_PMKID_CANDIDATE_LIST_PARAMETERS) plus the values of the uCandidateListSize and uCandidateListoffset members.

The miniport driver can make the NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST indication only if:

• The IEEE 802.11 dot11DesiredBSSType MIB object is set to dot11_BSS_type_infrastructure. For more information about this MIB object, see OID_DOT11_DESIRED_BSS_TYPE.

• The 802.11 station has associated with a BSS that supports RSNA authentication.

When it makes the NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST indication, the miniport driver must do the following:

• Order the PMKID candidate list from most preferred to least preferred.

  The miniport driver can use any criteria to define the preference order. For example, the miniport driver can order the PMKID candidate list based on RSSI strength.

• Set the number of entries in the PMKID candidate list to a value less than or equal to the value of uPMKIDCacheSize, which the driver returned when OID_DOT11_EXTSTA_CAPABILITY was previously queried.

• Be associated with an RSNA-capable AP and have transferred cipher keys to the 802.11 station through set requests of OID_DOT11_CIPHER_DEFAULT_KEY or OID_DOT11_CIPHER_KEY_MAPPING_KEY.

Note  The miniport must make an NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST indication within one minute after it has completed the association with the AP and the cipher keys have been transferred to the 802.11 station.

While the 802.11 station is associated with the AP, the miniport driver may generate additional NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST indications if the BSSID candidate list changes. The driver should keep the frequency of these indications to a minimum. For example, the driver should not make an NDIS_STATUS_DOT11_PMKID_CANDIDATE_LIST indication if only one new entry was added to its BSSID candidate list. Instead, it must make the indication after the number of new entries inserted into its BSSID candidate list reaches a driver-specific threshold.

Requirements