OID_802_11_ADD_WEP

  • Article

When set, the OID_802_11_ADD_WEP OID requests that the miniport driver set an IEEE 802.11 Wired Equivalent Privacy (WEP) 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).

There are two types of WEP keys:

  • Per-Client key
    The device uses a per-client key to send packets to the access point. This includes unicast, multicast, and broadcast packets sent by the device to the access point.

    In the IEEE 802.11-1999 terminology, per-client keys are referred to as key mapping keys .

  • Global key
    The device uses a global key to receive broadcast and multicast packets from the access point. A global key can also be used for unicast packets sent to or received from the access point. The device must support at least four global keys.

    In the IEEE 802.11-1999 terminology, global keys are referred to as default keys.

The miniport driver returns NDIS_STATUS_INVALID_DATA if the key cannot be set for any reason.

A WEP key is described by the NDIS_802_11_WEP structure, which is defined as follows:

    typedef struct _NDIS_802_11_WEP {
         ULONG Length;
         ULONG KeyIndex;
         ULONG KeyLength;
         UCHAR KeyMaterial[1];
   
    } NDIS_802_11_WEP, *PNDIS_802_11_WEP;

The members of this structure contain the following information:

  • Length
    The length, in bytes, of the NDIS_802_11_WEP structure. Length is calculated as follows:

    FIELD_OFFSET(NDIS_802_11_WEP, KeyMaterial) + KeyLength

  • KeyIndex
    Specifies which key to add or replace. When bit 31 is set, it indicates that the key is used to for transmitting packets (transmit key).

    When bit 30 is set, it indicates that the key is a per-client key. A per-client key can only be set for infrastructure network mode.

  • KeyLength
    The length, in bytes, of the KeyMaterial character array.

  • KeyMaterial
    An array that contains the WEP key. The length of this array is variable and depends on the value of the KeyLength member.

If the device does not support the specified key length, the miniport driver must fail the OID request and return NDIS_STATUS_INVALID_DATA. For example, if the device supports only 40-bit keys, a request to add a 104-bit key must fail.

When this OID sets the same index twice, the miniport driver must overwrite the previous WEP key at that index.

Within the set of available unicast and broadcast keys, at most only one key can be designated as the transmit key. Similarly, within the set of broadcast keys, at most only one key can be designated as the transmit key. The miniport driver cannot have two transmit keys simultaneously. That is, it is invalid to have a unicast and a broadcast key set to transmit at the same time. Therefore, a valid transmit key set through this OID must be used and overrides the current transmit key.

The miniport driver must discard WEP keys 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 is unloaded.

  • The device is disabled or reset.

The miniport driver and the underlying NIC must not maintain WEP keys in permanent storage (disk, registry, flash, or anything else).

If the transmit key is set through this OID, the device must not encrypt 802.1X packets.

When setting a per-client key, the BSSID for the key is not specified and must be assumed to be used for the BSSID of the access point. As a result, per-client keys are only used for infrastructure network mode.

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 WEP keys dynamically added through this OID must be discarded.

 

 

Send comments about this topic to Microsoft