The method configures the secondary security key that will be used by the wireless Hosted Network.
- Parameters
-
| KeyLength | The number of valid data bytes in the key data array pointed to by the KeyData parameter. This key length should include the terminating 0 if the key is a passphrase. |
| KeyData | A pointer to a buffer that contains the key data. The number of valid data bytes in the buffer must be at least the value specified in KeyLength parameter. |
| IsPassPhrase | A Boolean value that indicates if the key data array pointed to by the KeyData parameter is in passphrase format. If this parameter is True, the key data array is in passphrase format. If this parameter is False, the key data array is not in passphrase format. |
| Persistent | A Boolean value that indicates if the key data array pointed to by the KeyData parameter is to be stored and reused later or is for one-time use only. If this parameter is True, the key data array is to be stored and reused later. If this parameter is False, the key data array is to be used for one session (either the current session or the next session if the Hosted Network is not started). |
A client application calls the SetKey method to configure the secondary security key that will be used by the wireless Hosted Network. Any Hosted Network change caused by this function would not be automatically undone if the calling application closes or if the process ends.
Once started, the wireless Hosted Network will allow wireless peers to associate with this secondary security key in addition to the primary security key. The secondary security key is always specified by the user as needed, while the primary security key is generated by the operating system with greater security strength.
The secondary security key passed in the buffer pointed to by the KeyData parameter is used with WPA2-Personal authentication and should be in one of the following formats:
-
A key passphrase that consists of an array of ASCII characters from 8 to 63 characters. The
KeyLength parameter should include the terminating 0 in the passphrase. The value of the KeyLength parameter should be in the range of 9 to 64.
-
A binary key that consists of 32 bytes of binary key data. The
KeyLength parameter should be 32 for binary key.
To configure a valid secondary security key, the KeyLength parameter should be in the correct range and the KeyData parameter should point to a valid memory buffer containing the specified bytes of data. To remove the currently configured secondary security key from the system, the application should call the SetKey method with zero in KeyLength parameter and NULL in the KeyData parameter.
The SetKey method will return WCL_E_WIFI_INVALID_ARGUMENT if the KeyData parameter is NULL, but the KeyLength parameter is not zero. The SetKey method will also return WCL_E_WIFI_INVALID_ARGUMENT if the KeyLength parameter is zero, but KeyData parameter is not NULL.
The secondary security key can be specified as persistent if the Persistent parameter is set to True. When specified as persistent, the secondary security key would be used immediately and also reused whenever Hosted Network is started in the future.
If secondary security key is not specified as persistent, it will be used immediately, or only for the next time when Hosted Network is started. After the Hosted Network is stopped, this secondary security key will never be used again and will be removed from the system.
