WiFi Configuration and Security

How to set the SSID and use the security features of the WiFi Wildcard

WiFi Wildcard configuration
- - Using the Lantronix WiPort configuration webserver to configure security

The WiFi Wildcard™ is ideal for web-enabled instrumentation and automation applications. Based on the Lantronix WiPort WiFi server device, it implements a wireless interface that enables communications between your instrument and other computers or wireless access points via a Wireless Local Area Network (WLAN) using the standard 802.11b/g packet-based protocol. This page describes how to set the SSID and use the security features of the WiFi Wildcard.

WiFi Wildcard configuration

The WiFi Wildcard ships in a default configuration that specifies the "infrastructure" (access point) mode with reasonable values for transmit power level and rate. All WiFi security is disabled by default; this makes it simpler to verify proper WiFi operation when first installing the Wildcard in a network that attaches to a WAN (wide area network). The default case-sensitive SSID (Service Set ID) is

WIFI_WILDCARD

The SSID and the security settings must be shared by all nodes on the WLAN in order for mutual communications to be established.

There are two ways to modify the WiFi configuration and security settings:

by calling the functions listed in Table 1-5; or,
by using the Lantronix internal configuration webserver available on port 8000 at the Wildcard’s IP address.

Each of these methods is discussed in turn.

Table 1-5 WiFi configuration functions and constants.

WIFI_CCMP_GROUP_ENCRYPT	WIFI_TKIP_GROUP_ENCRYPT
WIFI_CCMP_PAIR_ENCRYPT	WIFI_TKIP_PAIR_ENCRYPT
WiFi_Check	WIFI_WEP128_PAIR_ENCRYPT
WiFi_Encryption_Key	WIFI_WEP64_PAIR_ENCRYPT
WIFI_NO_SECURITY	WIFI_WEP_GROUP_ENCRYPT
WiFi_Options	WIFI_WEP_SUITE
WiFi_Security	WIFI_WPA2_SUITE
WiFi_SSID	WIFI_WPA_SUITE

The WiFi_SSID Function

WiFi_SSID accepts a buffer specification (xaddress and count) and a modulenum. For the specified WiFi Wildcard module, it writes a reference to the specified WiFi SSID ("Service Set ID") buffer into the ether_info structure. Assuming that you have initialized the Ethernet task by calling WiFi_Task_Setup_Default, you can instantiate the string into the Lantronix WiPort flash after invoking this function by executing Ether_XPort_Update followed by Ether_Await_Response. The case-sensitive SSID is the name which must be shared among members of a WLAN (Wireless Local Area Network) in order for the members to associate with one another. The default SSID set by Mosaic at the factory, and restored by Ether_XPort_Defaults, is "WIFI_WILDCARD" (without the quotes).

The WiFi_Options Function

The WiFi_Options function configures the transmit power level and rate, and specifies infrastructure versus ad-hoc mode. The function writes the specified parameters into the ether_info struct for the specified WiFi module. These parameters do not take effect until Ether_Xport_Update is invoked as explained below. See the glossary entry of WiFi_Options for a detailed list of the parameters passed to this function and their meanings. Briefly, the transmit power can be set to 0, 6, 12, or 18 dBm. dBm is a measure of power in dB relative to 1 milliWatt of radiated power: 0 dBm is equivalent to 1 milliWatt, and each additional 3 dBm represents roughly a doubling of power. A power management flag enables transmitter power management if nonzero, and disables it if zero (the default). The transmit data rate can be set to one of 8 values in the range from 1 Mbps to 54 Mbps, with a default of 18 Mbps (Megabits per second). A flag enables automated control of transmission rate if nonzero (the default), and disables automated rate control if zero. An additional flag specifies the "ad hoc" mode if nonzero. In ad hoc mode, two wireless devices communicate directly with each other without the use of an access point. A zero adhoc_flag (the default) configures the Wildcard for "infrastructure mode" which is the standard Wireless Local Area Network configuration that uses an access point to enable communications among multiple wireless devices. If the adhoc_flag is true, then the ad hoc channel number can be set to a specified value. In the United States and Canada, allowed ad hoc channels are between 1 and 11 inclusive.

After executing the WiFi_Options function, assuming that you have initialized the Ethernet task by calling WiFi_Task_Setup_Default, you can instantiate the values into the WiPort flash by executing Ether_XPort_Update followed by Ether_Await_Response. To restore the values marked as defaults, execute Ether_XPort_Defaults followed by Ether_Await_Response.

The WiFi_Security Function

WiFi encryption prevents unauthorized parties from eavesdropping on communications that occur on the secured WLAN. The most common security methods are called WEP and WPA. WEP, or Wired Equivalent Privacy, is the oldest and simplest WiFi security suite. WEP64 uses a 40-bit encryption key with a 24-bit initialization vector, and WEP128 uses a 104-bit encryption key with a 24-bit initialization vector. WEP is not completely immune to attack, and the newer WPA (WiFi Protected Access) offers stronger encryption. TKIP (Temporal Key Integrity Protocol) pairwise encryption method is used in conjunction with WPA, and uses a 128 bit key. The still newer WPA2 is associated with the 802.11i protocol, and uses the CCMP pairwise encryption method.

Note that WiFi encryption is independent of and not related to the AES encryption described in the Ether_Encryption glossary entry.

The WiFi_Security function configures the security parameters for the WiFi Wildcard. Its C function prototype is as follows:

void WiFi_Security (int authenticate_flag, int suite_method,
int pairwise_encrypt_method, int group_encrypt_method,
int key_length, int passphrase_flag, int modulenum )

This function writes the specified parameters into the ether_info struct for the specified WiFi module. These parameters do not take effect until Ether_Xport_Update is invoked. The default upon shipment from Mosaic or after executing Ether_XPort_Defaults is "no security", equivalent to specifying zeros for all of the security parameters passed to the function.

A nonzero authenticate_flag parameter enables authentication, while a zero disables it. The suite_method parameter should be one of the constants WIFI_NO_SECURITY, WIFI_WEP_SUITE, WIFI_WPA_SUITE, or WIFI_WPA2_SUITE. WEP, or Wired Equivalent Privacy, is the oldest and simplest WiFi security suite. It is not completely immune to attack, and the newer WPA (WiFi Protected Access) offers stronger encryption. The still newer WPA2 is associated with the 802.11i protocol. The pairwise_encrypt_method parameter should be one of the constants WIFI_NO_SECURITY, WIFI_WEP64_PAIR_ENCRYPT, WIFI_WEP128_PAIR_ENCRYPT, WIFI_TKIP_PAIR_ENCRYPT, or WIFI_CCMP_PAIR_ENCRYPT. The pairwise method specifies the main encryption scheme for the security suite. WEP64 uses a 40-bit encryption key with a 24-bit initialization vector, and WEP128 uses a 104-bit encryption key with a 24-bit initialization vector. TKIP (Temporal Key Integrity Protocol) pairwise encryption method is used in conjunction with WPA, and uses a 128 bit key. CCMP pairwise encryption is used in conjunction with WPA2 on 802.11i networks.

The group_encrypt_method should be one of the constants WIFI_NO_SECURITY, WIFI_WEP_GROUP_ENCRYPT, WIFI_TKIP_GROUP_ENCRYPT, or WIFI_CCMP_GROUP_ENCRYPT. Group encryption is typically not used if the WEP security suite is specified. The standard group encryption for the WPA suite is TKIP, although the group encryption should be set to WIFI_WEP_GROUP_ENCRYPT if the WPA suite is specified with encryption called "TKIP plus WEP group keys".

The key_length parameter can be safely set to zero, or it can be set to the actual key length. Testing indicates that the current Lantronix firmware (V6.1.0.1) ignores the key length field and uses the encryption type to infer the length of a hex key, and uses a trailing zero to determine the length of a passphrase key.

The passphrase_flag parameter should be nonzero if an 8- to 63-byte passphrase is used to specify the encryption key, and should be zero if a hex key is specified. The key type should match the parameters passed to the WiFi_Encryption_Key function explained in the next section. Both WEP and WPA keys can be specified using hex digits, or using a passphrase of 8 to 63 bytes that is converted into a key using a hash function. See the next section for a function that sets the security key.

After executing the WiFi_Security function, assuming that you have initialized the Ethernet task by invoking WiFi_Task_Setup_Default, you can instantiate the values into the WiPort flash by executing Ether_XPort_Update followed by Ether_Await_Response. To restore the default "no security" values, execute Ether_XPort_Defaults followed by Ether_Await_Response.

The WiFi_Encryption_Key Function

WiFi_Encryption_Key accepts a buffer xaddress and count containing an encryption key (hex or passphrase), and installs the specified WiFi encryption key into the WiPort flash. The number of key bytes stored is clamped to a maximum of 63 bytes, which is the limit for a passphrase key as described below. If the number of key bytes is less than 63, the unspecified bytes are set to zero. The most significant byte of the key is the byte stored at the beginning of the buffer. All devices on a WiFi Local Area Network must have the same SSID, WiFi security settings, and key to be able to communicate with one another. Devices that do not know the security key will in theory not be able to eavesdrop on the secure communications.

There are two ways of specifying a key: as a hexadecimal (hex) sequence, or as a passphrase. Specifying a hex key is simple: just type in a hexadecimal number of the correct length. Each hex character (in the range 0 to 9, A to F ) specifies 4 bits of the key. A passphrase is 8 to 63 printable ASCII bytes that is automatically converted into 1 to 4 numeric keys by a built-in hash function. If you are offered a choice in a configuration screen, always select the first key (key index 0) as this is the one the Lantronix device uses. The WiFi_Encryption_Key routine ensures that a trailing zero (null delimiter) is stored after the passphrase, as required by the Lantronix firmware. A passphrase can be used with WEP or WPA.

A WEP64 hex key is 40 bits, corresponding to ten hex digits. An example 40-bit key is:

123456789A

A WEP128 hex key is 104 bits, corresponding to 26 hex digits. An example 104-bit key is:

123456789ABCDEF0123456789A

A WPA/TKIP key is 128 bits, corresponding to 32 hex digits, An example 128-bit key is:

123456789ABCDEF0123456789ABCDEF0

After a restart, initialize the WiFi Wildcard using WiFi_Setup or one of its calling functions listed in Table 1 3, and then invoke WiFi_Encryption_Key, passing it the base xaddress and size of the key that has been stored in memory. Make sure there are no active connections during the execution of this function, as they will be interfered with when monitor mode is entered. Double check the key values, as there is no way to read them back after they are set. At this point the key is present, but WiFi encryption is not enabled until you setup WiPort flash record 8 via the functions Wifi_Security, WiFi_SSID, and WiFi_Options, and then execute Ether_XPort_Update as described in the preceding sections. To undo the effect of these commands and return to non-encrypted operation of the WiFi Wildcard, make sure that the Ethernet task is running by invoking WiFi_Task_Setup_Default. Then execute Ether_XPort_Defaults (see its glossary entry; it works for both EtherSmart and WiFi Wildcards). Remember to adjust the security settings on your wireless access point, as all security parameters must match for communications to occur.

Using the Lantronix WiPort configuration webserver to configure security

An alternative method to customize the wireless and security settings of the WiFi Wildcard is to log into the configuration web site served out by the Lantronix WiPort. Assuming that you have established wireless communications (see the section titled "Verifying WiFi Wildcard Communications"), and you know its IP address, you can use your PC’s browser to access its internal configuration website on port 8000. For the WiFi Wildcard with IP address 192.168.0.2, you would type the following into the address bar of your web browser:

http://192.168.0.2:8000

The :8000 tells the browser to go to port 8000 instead of the standard web port 80. The WiFi Wildcard uses port 80 for all of its standard network traffic, and locates the built-in configuration webserver at port 8000.

When the login box comes up, just hit "Enter" (no password required), and you should see the Lantronix configuration web page. The column at the left allows you to select which settings are to be configured. Click on the "WLAN" item to bring up the screen shown in Figure 1-9.

Figure 1-9 Default WLAN settings page served out by the WiPort’s internal configuration webserver on port 8000.

A good rule is to use the WiPort configuration webserver to change ONLY the "WLAN" settings which include the SSID and the wireless security settings. Changing other settings could render the WiFi Wildcard inoperable. (It is permissible to use the "Network" screen if you want to hard code an IP address and subnet; these can also be configured as described in the section above titled "Configuring the Lantronix Device").

If by any chance any settings are corrupted, use the Ether_XPort_Defaults function described in this document to restore the Mosaic factory settings. Do not use the "Apply Factory Defaults" button in the configuration website. The "Apply Factory Defaults" button does NOT establish the correct Mosaic defaults; Mosaic’s defaults are different than those selected by Lantronix.

Figure 1-9 shows the WLAN configuration page of the Lantronix configuration site in its default state with security disabled and the SSID equal to "WIFI_WILDCARD". You can use this page to change the SSID, specify ad hoc (as opposed to infrastructure) mode, enable WiFi security, specify the encryption key, and change the transmit data rate and power settings. To instantiate the changed fields, click the "OK" button at the bottom of the screen, and then click "Apply Settings" from the left-hand menu. The Lantronix device will install the new settings in its flash memory and reboot; this takes over 10 seconds. Of course, once you change the SSID or enable security on any part of the WLAN, the same SSID, security key and security type must be setup on the other members of the WLAN to enable communications.

We examine each of the fields shown in Figure 1-9 in turn. The "Network name (SSID)" contains the default case-sensitive WIFI_WILDCARD Service Set ID. You can type any valid ASCII string up to 32 bytes long into this field. Make sure to configure the same SSID on any other devices on your WLAN, as matching SSID’s are required for wireless association to occur.

The default "Network Type" is infrastructure, meaning a network that incorporates a wireless access point to coordinate communications among wireless nodes. The alternative is "ad hoc" mode, which is a point-to-point network between two wireless devices. For example, you could configure two WiFi Wildcards in ad hoc mode and set them up to communicate with one another. If the ad hoc mode is specified, the "Channel" box is enabled, allowing you to specify a WiFi channel number between 1 and 13, inclusive. Channels 1 through 11 are valid in the U.S. and Canada. Channel 11 is the default.

The "Security" field contains the default value "None"; when this option is selected, the remaining security fields are "greyed out" and cannot be modified. The alternative entries in the "Security" field are "WEP", "WPA", and "802.11i/WPA2". These are explained in detail in the section titled "The WiFi_Security Function". If you specify WEP, WPA, or WPA2 encryption, the remaining security fields are enabled.

Figure 1-10 shows the WLAN settings page when the WEP security suite is selected. The default "Authentication" for WEP is "open/none". The alternative is "shared". This field corresponds to the "authentication_flag" parameter passed to the WiFi_Security function described above, where "open/none" corresponds to a zero flag, and "shared" corresponds to a nonzero authentication flag.

Figure 1-10 WLAN settings page with WEP security selected.

The next "Encryption" field allows the selection of 64-bit or 128-bit WEP encryption. These respectively correspond to the WIFI_WEP64_PAIR_ENCRYPT and WIFI_WEP128_PAIR_ENCRYPT "pairwise_encryption" flag passed to the WiFi_Security function described above.

The "Key Type" field can be specified as either "hex" or "passphrase". The WEP encryption key can be entered as a hexadecimal value, or as a "passphrase". A passphrase is an 8 to 63 byte printable ASCII string that is processed by a "hash function" to create one or more numeric keys. If a passphrase is used, the WiFi Wildcard always uses key index 0 generated by the passphrase hash function. The configuration page asks for the key to be typed twice to help ensure that there is no entry error; keys cannot be read back from the Lantronix device once they are installed.

If "hex" key type is selected, note that a WEP64 hex key is 40 bits, corresponding to ten hex digits. An example 40-bit WEP key is:

123456789A

A WEP128 hex key is 104 bits, corresponding to 26 hex digits. An example 104-bit key is:

123456789ABCDEF0123456789A

Figure 1-10 shows the WLAN settings page when the WPA security suite is selected. The default (and only) "Authentication" option for WPA is "Pre-Shared Keys (WPA-PSK)". This field corresponds to the "authentication_flag" parameter passed to the WiFi_Security function described above, where a true (nonzero) authentication flag must always be passed if the WPA security suite is in use.

The next "Encryption" field allows the selection of "TKIP" or "TKIP+WEP group keys" encryption. In each case, the pairwise encryption method is TKIP (Temporal Key Integrity Protocol) pairwise encryption method which is used in conjunction with WPA. This corresponds to the WIFI_TKIP_PAIR_ENCRYPT "pairwise_encryption" flag passed to the WiFi_Security function described above. If WPA is in use, the encryption method also specifies a "group encryption" method. Choosing "TKIP" encryption is equivalent to specifying WIFI_TKIP_GROUP_ENCRYPT as the "group_encryption" flag passed to the WiFi_Security function described above. Choosing "TKIP+WEP group keys" encryption with the WPA security suite is equivalent to specifying WIFI_WEP_GROUP_ENCRYPT as the "group_encryption" flag passed to the WiFi_Security function described above.

The "Key Type" field can be specified as either "hex" or "passphrase". The passphrase can be 8 to 32 ASCII bytes. If the "hex" key type is selected, note that a WPA/TKIP key is 128 bits, corresponding to 32 hex digits, An example 128-bit WPA key is:

123456789ABCDEF0123456789ABCDEF0

The remaining settings in Figure 1-10 specify the data rate (with or without automated rate control), and whether automated radio power management is enabled.

To confirm any changes you have made in the WLAN configuration page, click "OK" at the bottom of the page, and then click "Apply Settings" to store the changes into flash in the Lantronix device. As stated earlier, do NOT click the "Apply Factory Defaults" button, as this will corrupt the WiFi Wildcard communications with the Mosaic controller. To recover from this or any other configuration problem and return to the Mosaic defaults, execute Ether_Xport_Defaults or the convenient interactive version Ether_Set_Defaults defined in the demonstration code (see the demo program excerpt in Listing 1-3).

Figure 1-11 WLAN settings page with WPA security selected