OID_802_11_ADD_KEY
When set, the OID_802_11_ADD_KEY OID requests that the miniport driver set a key to a specified value. Keys are used for authentication or encryption or both. A key can be pre-shared (in other words, provided to the device before use).
Two types of keys exist, pairwise keys and group keys.
Pairwise key
The device also uses a pairwise key to do the following:Send unicast, multicast, and broadcast packets to the access point.
Send unicast packets to another IBSS station.
Receive unicast packets from the access point or IBSS station.
Group key
The device uses a group key to send broadcast and multicast packets to all stations that are communicating with an access point or communicating within an IBSS.If no pairwise keys have been set, a group key can also be used to send and receive unicast packets. The device must support four or more group keys.
This OID can be used to set keys for the WEP, TKIP, and AES cipher suites. However, the 802.11 miniport driver is responsible for verifying the keys set through this OID with the cipher suited enabled for the current association.
The data type for this OID is the NDIS_802_11_KEY structure, which is defined as follows:
typedef struct _NDIS_802_11_KEY {
ULONG Length;
ULONG KeyIndex;
ULONG KeyLength;
NDIS_802_11_MAC_ADDRESS BSSID;
NDIS_802_11_KEY_RSC KeyRSC;
UCHAR KeyMaterial[1];
} NDIS_802_11_KEY, *PNDIS_802_11_KEY;
This structure includes the following members:
Length
The length, in bytes, of the NDIS_802_11_KEY structure. Length is calculated as follows:FIELD_OFFSET(NDIS_802_11_KEY, KeyMaterial) + KeyLengthKeyIndex
Specifies the key type.If bit 31 is set, the key is a transmit key. For group keys, one transmit key is allowed for each BSSID. The last group key that is added with bit 31 set is the group transmit key. If a pairwise key was set for a BSSID, the transmit bit of all group keys must be cleared and ignored for unicast messages.
If bit 30 is set, the key is a pairwise key. Otherwise, the key is a group key.
It is invalid to clear bit 31 and set bit 30. If the miniport driver encounters this combination, it must fail the request and return NDIS_STATUS_INVALID_DATA.
The device can use a group key as the transmit key only when pairwise keys are unavailable.
If bit 29 is set, the device uses the value in the KeyRSC member to set the initial receive sequence counter (RSC) for the key. If bit 29 is cleared, the device determines the RSC.
If bit 28 is set, an 802.1X authenticator is setting the key. If bit 28 is cleared, an 802.1X supplicant is setting the key. Bit 28 must be cleared in authentication mode Ndis802_11AuthModeWPANone.
For TKIP, the device uses bit 28 to decide which part of the key material must be used for the transmit and receive Michael MIC integrity keys.
In IBSS WPA authentication mode, the system ensures that the authenticator transmit key and authenticator receive key are the same.
The lower 8 bits of KeyIndex specify a key-index value from 0 through 255. The value must be 0 for a pairwise key. If the value is not 0, the miniport driver must fail the request and return NDIS_STATUS_INVALID_DATA.
All other bits must be cleared. If they are not, the miniport driver must fail the request and return NDIS_STATUS_INVALID_DATA.
KeyLength
The length, in bytes, of the KeyMaterial array. The maximum value is 32.BSSID
The MAC address of the BSSID that the key applies to. The field is set to 0xFFFFFFFFFFFF if the BSSID is unknown.KeyRSC
If bit 29 of KeyIndex is set, KeyRSC contains the initial value of the key's receive sequence counter (RSC). If the encryption cipher requires fewer bytes than KeyRSC supplies, the miniport driver must use the least significant bytes. For example, if 6 bytes are required, the miniport driver uses KeyRSC[0-5].KeyMaterial
An array that contains the key. The KeyLength member contains the length of this array.
For WEP keys, the key length is either 40 or 104 bits.
For TKIP keys, the key length is 256 bits. The first 128 bits, starting with the least significant bit, must be used for the encryption key. The second 128 bits must be used for two MIC keys.
If bit 28 of KeyIndex is set, the first 64 bits of the MIC key are used in the direction from the authenticator to the supplicant, and the second 64 bits are used in the direction from the supplicant to authenticator. If bit 28 of KeyIndex is not set, these directions are reversed.
The following table summarizes the contents of the TKIP key for particular authentication modes and bit-28 values.
| WPA/WPA2 authentication mode | Bit 28 of KeyIndex | Bits 0-127 of the TKIP key | Bits 128-191 of the TKIP key | Bits 192-255 of the TKIP key |
|---|---|---|---|---|
WPA, WPA2, WPAPSK, or WPA2PSK |
0 (supplicant) |
Encryption key |
Receive MIC key |
Transmit MIC key |
WPA, WPA2, WPAPSK, or WPA2PSK |
1 (authenticator) |
Encryption key |
Transmit MIC key |
Receive MIC key |
WPANone |
Not applicable |
Encryption key |
Receive and transmit MIC key |
Not used |
For AES keys, the key length is 128 bits.
When set by this OID, the miniport driver's actions depend on the following factors:
Whether the device supports key mapping.
Whether the key type is pairwise or group.
Whether the BSSID for the key is known or unknown. An unknown BSSID would have a value of 0xFFFFFFFFFFFF.
Whether the driver's network mode is infrastructure (ESS) or ad hoc (IBSS) mode.
The following table specifies the possible combinations.
| Key type | BSSID | IBSS/ESS | Key mapping supported | What the miniport driver must do |
|---|---|---|---|---|
Pairwise |
Unknown |
Not applicable |
Yes |
Fail the request and return NDIS_STATUS_INVALID_DATA. |
Pairwise |
Known |
Not applicable |
Yes |
Immediately configure the key. If all the pairwise keys are configured, delete one that is not being used. The driver does not delete the pairwise key for the currently associated access point, but the driver can change this key. If all the pairwise keys are in use, the driver maps the key to group key at index 0. |
Pairwise |
Not applicable |
Not applicable |
No |
Map to group key at index 0. |
Group |
Unknown |
Not applicable |
Not applicable |
Immediately configure the key. |
Group |
Known |
IBSS |
Not applicable |
Fail the request and return NDIS_STATUS_INVALID_DATA. |
Group |
Equal to the currently associated BSSID |
ESS |
Not applicable |
Immediately configure the key. |
Group |
Known: either not equal to the currently associated BSSID, or device is not associated |
ESS |
Not applicable |
Save the key and configure it just before association or reassociation to the access point with the specified BSSID. After the key is configured, delete the saved copy. |
When this OID sets the same index twice for the same key type and the same BSSID, the miniport driver must overwrite the previous key at that index.
The miniport driver must discard keys set through this OID immediately after any of the following events:
The driver makes a media disconnect indication.
The driver's network mode is changed through a setting of OID_802_11_INFRASTRUCTURE_MODE.
Shared-key authentication that uses the key fails.
The driver receives a disassociate or deauthenticate request from an access point or IBSS station or sends an associate or reassociate request.
The driver is unloaded.
The device is disabled or reset.
If the device does not support the key length for the encryption modes that are currently enabled or in use, the miniport driver must fail the OID set request and return NDIS_STATUS_INVALID_DATA. For example, if the device supports 40-bit keys for the currently enabled encryption modes, a request to add a 104-bit key must fail. Also, if the device is associated with an access point, and TKIP has been negotiated, the miniport driver must fail any set requests for key lengths that are not valid.
If the card does not support key mapping, the miniport driver or NIC must use the group key at index 0 for the pairwise key. The device can use this key as if it were a pairwise key to encrypt packets. The group key at index 0 must be saved and not used if the BSSID member does not contain the current BSSID for the association.
If the device cannot support an additional pairwise key, it must delete a previous key that is not currently in use. For example, if the device supports ten pairwise keys and an eleventh pairwise key is added, the miniport driver must delete one of the earlier ten keys. However, a key that is currently in use (for example, the pairwise key that is assigned to the currently associated access point) must not be deleted. If no more pairwise keys can be supported and all pairwise keys are currently in use, the device must map the pairwise key to group key at index 0.
After a key is configured into the encryption-integrity engine, the saved copy must be deleted. The copy must not be later reconfigured into the encryption-integrity engine.
The miniport driver and the underlying NIC must not maintain keys in permanent storage (disk, registry, flash, or anything else).
If the driver's authentication mode is set to WPA or WPA2, the device must not encrypt 802.1X packets until the transmit key is set through this OID. After this OID is set, the device must encrypt all transmitted packets.
If the driver's MiniportResetfunction is called, the driver must save the current state of the NIC, reset the NIC, and reconfigure the original state. Legacy NICs that saved keys within permanent storage must reload those keys. However, any keys dynamically added through this OID must be discarded.
If the device is using TKIP, care must be taken to avoid integrity errors when the device changes the MIC keys. This could occur due to the overlap of packets being received while the key is changing.